✨ instantiatePrefab

What is it?

instantiatePrefab allows you to instantiate a copy of a Prefab stored in the project into the game at runtime.

A Prefab is a JSON file located in the project's prefab list:

prefabs/NAME.json

The engine loads that JSON, reconstructs the object, normalizes all its values, loads its script, registers it internally, and immediately executes Start().

📖 Syntax

await instantiatePrefab(prefabName, x, y);

• prefabName: file name without extension (e.g. "EnemyBasic").
• x, y: initial position where the prefab will spawn.

🔧 What does a Prefab contain?

Each prefab is a JSON file containing all object data:

• type
• name (optional)
• position (x, y)
• scaleX, scaleY
• rotation
• image
• components (Animator, AudioSource, ParticleSystem, etc.)
• script
• children (if it has an internal hierarchy)

🚀 What does instantiatePrefab do automatically?

• ✔ Loads the prefab JSON.
• ✔ Clones the object without modifying the original.
• ✔ Generates a new unique ID.
• ✔ Normalizes values.
• ✔ Rebuilds image and animation paths.
• ✔ Initializes ParticleSystem.
• ✔ Adds the object to the scene.
• ✔ Loads its associated script.
• ✔ Immediately executes Start().

📘 Basic example

// Instantiate the "EnemyBasic" prefab at position (200, 150)
const enemy = await instantiatePrefab("EnemyBasic", 200, 150);

This creates a fully functional copy of the prefab, with its script active if it has one.

📘 Example with logic from a script

function Start(obj) {
  // Create an enemy next to the player when the game starts
  instantiatePrefab("ENEMY_FOLLOW", obj.x + 50, obj.y);
}

📘 Example: projectile using a prefab

function Shoot(obj) {
  const bullet = await instantiatePrefab("BulletPrefab", obj.x, obj.y);
  bullet.vx = 400;
}

📌 Important notes

🆚 instantiatePrefab vs instantiateObject