✨ instantiateObject

What is it?

The instantiateObject function allows you to create a completely new object during gameplay. This method is similar to instantiating a prefab in Unity, but generating the object from a configuration object instead of a prefab file.

Unlike previous versions of the engine, instantiateObject now includes:

• Full normalization of transforms and properties.
• Automatic loading of the associated script.
• Internal registration in the behaviour system (scriptBehaviours).
• Immediate Start() execution if the script defines it.

This ensures that the instantiated object behaves exactly like any object loaded from the scene or from a prefab.

📖 Syntax

await instantiateObject(config, optionalScript);

• config → Configuration object with initial properties.
• optionalScript → Script filename to load (if not included in config).
• Returns a reference to the created object.

📦 Allowed properties in config

• type: type/nature of the object.
• name: visible name in debug (auto-generated if not provided).
• x, y: initial position (auto-normalized).
• scaleX, scaleY: scale.
• rotation: rotation in degrees.
• w, h: dimensions; if omitted, they are calculated based on scale.
• color: object color (if no image is used).
• image: image file name (path applied automatically).
• opacity: opacity (0–1).
• pixelPerfect: smoothing on/off.
• collision: enable collision.
• trigger: if acts as a trigger.
• collisionType: "square" or "circle".
• gravity: local gravity for the object.
• components: array of components (AudioSource, Animator, etc.).
• script: associated script (if not passed as second parameter).

🚀 What happens automatically?

When calling instantiateObject, the engine performs:

• ✔ Creates a unique ID.
• ✔ Normalizes numbers (prevents NaN).
• ✔ Loads the appropriate image.
• ✔ Initializes components.
• ✔ Adds the object to the global objects array.
• ✔ Loads and evaluates the object's script.
• ✔ Registers its methods (Start, Update, etc.) in scriptBehaviours.
• ✔ Executes Start(obj) immediately.

📘 Simple example

// Create a red enemy at position (300, 200)
const enemy = await instantiateObject({
  type: "enemy",
  name: "Enemy1",
  x: 300,
  y: 200,
  color: "#f00"
}, "EnemyAI.js");

📘 Example with image and components

const bullet = await instantiateObject({
  type: "bullet",
  x: player.x,
  y: player.y,
  image: "bullet.png",
  scaleX: 1,
  scaleY: 1,
  components: [
    { type: "AudioSource", clip: "shoot.wav", playOnStart: true }
  ]
}, "BulletController.js");