Instantiating scenes

Once you have a scene (.prefab file), you can instantiate it into other scenes. An instance is a linked copy: changes to the source scene propagate to every instance, except for properties the instance has deliberately overridden.

Terminology

  • Source — the .prefab file on disk that defines the object tree.
  • Instance — a linked copy of that tree inside an open scene.
  • Override — a property changed on a specific instance, which is preserved when the source is updated.

Instantiating at edit time

In the Asset Browser, locate a scene or prefab. Two ways to instantiate:

  • Drag it from the Asset Browser into the Scene Viewport or the Scene Hierarchy panel.
  • Right-click it and choose Instantiate into Scene.

A fresh instance appears under the scene root with a blue tint and a box icon on its root node — the editor's way of showing you it is a linked copy.

Creating a prefab from a scene object

To turn any node in your scene into a reusable prefab:

  1. Right-click the node in the Scene Hierarchy.
  2. Choose Create Prefab.
  3. A .prefab asset is written into the current Asset Browser folder and the object becomes the first instance of that prefab.

You can also drag a node from the Hierarchy and drop it onto the Asset Browser.

Editing a prefab

Double-click a .prefab in the Asset Browser to open it for editing. The Scene Hierarchy shows the prefab's tree. Make your changes and save — the next time a scene containing an instance is loaded, the instance reflects your edits (preserving any overrides).

Overrides

Once a prefab is instantiated, you can tweak any property on the instance — name, transform, component fields. Each changed property is recorded as an override and listed in the Prefab Instance banner at the top of the Inspector.

The banner has two actions:

  • Revert — discards all overrides on this instance and snaps it back to the source prefab.
  • Apply — pushes the instance's current values up into the source prefab, propagating to every other instance (each keeping its own overrides).

Spawning at runtime

Gameplay code spawns and destroys linked instances via the Frame context:

const engine = @import("engine");

pub const Spawner = struct {
    pub const is_component = true;

    prefab: engine.TypedAssetRef(.scene) = .{},

    pub fn update(self: *@This(), frame: engine.Frame) void {
        if (frame.input.wasPressed("fire")) {
            frame.instantiate(self.prefab.slice(), .{ .x = 0, .y = 1, .z = 0 }, null);
        }
    }
};
  • frame.instantiate(guid, position, rotation) queues a new linked instance of the prefab. position and rotation are optional overrides for the root's transform.
  • frame.destroy(node) queues removal of a node and its descendants.

Both are deferred: they apply after the current update, so a script can spawn or destroy while iterating scene objects without iteration bugs.

Performance and workflow

Instancing is not a performance optimisation — it is a workflow optimisation. You author one enemy prefab and stamp fifty instances into the level. Later, tweak the prefab's mesh or health and all fifty update. The runtime cost of an instance is the same as a hand-placed object.

← All docs Edit this page