Prefabs

A prefab is a reusable template for a scene object and its children — Turian's equivalent of a Unity prefab or a Godot scene-instance. You author an object once, save it as a .prefab asset, then stamp as many instances as you like into your scenes. Instances stay linked to the source: edits to the prefab flow back into every instance, except for the fields an instance has deliberately overridden.

Terminology. The thing you edit in the Scene Hierarchy is the Scene — the live, open node tree. When you serialize it to disk you get a Prefab: a .prefab asset with its own stable GUID/.meta. They share the exact same on-disk structure; a prefab is just a scene saved as a reusable, instantiable template. So a prefab opens in the Scene Hierarchy for editing exactly like any scene, and any scene can be instantiated into another. Its first object is the root; children are nested beneath it.

Creating a prefab

Two ways, both in the editor:

  • In the Scene Hierarchy, right-click an object and choose Create Prefab.
  • Drag an object from the Scene Hierarchy and drop it onto the Asset Browser.

Either way the editor writes a <Name>.prefab asset into the folder the Asset Browser is currently showing, and converts the selected object (and its children) into the first instance of that new prefab. The Inspector then shows a Prefab Instance banner for it.

Editing a prefab

Double-click a .prefab in the Asset Browser to open it in the Scene Hierarchy and edit it like any scene. Saving the prefab updates its instances the next time a scene containing them is opened (overrides are preserved).

Instantiating

Drop a fresh, linked copy into the active scene by:

  • Dragging a .prefab (or any scene) from the Asset Browser into the Scene Viewport, or
  • right-clicking it and choosing Instantiate into Scene.

Each instance gets its own object GUIDs but remembers which prefab it came from.

Spotting instances

In the Scene Hierarchy, a prefab instance is tinted blue and its root uses a box icon, so a linked instance stands out from plain objects at a glance. Select any node in the instance to see the Prefab Instance banner in the Inspector.

Overrides

Once instantiated, you can tweak an instance freely in the Inspector. Any group you change — name, active state, transform, or components — is recorded as an override and listed in the Prefab Instance banner. Overrides are what make each instance distinct, and they are preserved when the source prefab changes.

Revert and Apply

The Prefab Instance banner offers two actions:

  • Revert — discard the instance's overrides and snap every field back to the source prefab.
  • Apply — push this instance's current values up into the source prefab, then propagate the change to every other instance in the scene (each keeping its own overrides).

This is the core prefab loop: edit one instance, Apply to update the template, and all sibling instances inherit the change except where they've overridden it.

Spawning at runtime

Prefabs are also the runtime building block — the equivalent of Unity's Instantiate / Destroy. Gameplay scripts spawn and despawn through the Frame context:

const std = @import("std");
const engine = @import("engine");

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

    /// Drop a `.prefab` here in the Inspector.
    prefab: engine.TypedAssetRef(.scene) = .{},

    pub fn update(self: *@This(), frame: engine.Frame) void {
        // Instantiate(prefab, position, rotation) — position/rotation are optional.
        if (frame.input.wasPressed("fire")) {
            frame.instantiate(self.prefab.slice(), .{ .x = 0, .y = 1, .z = 0 }, null);
        }

        // Destroy(node) — removes the node and its children.
        for (frame.objects) |*obj| {
            if (std.mem.eql(u8, obj.nameSlice(), "Doomed")) frame.destroy(obj);
        }
    }
};
  • frame.instantiate(prefab_guid, position, rotation) — queues a new linked instance of the prefab (identified by its asset GUID, e.g. a TypedAssetRef(.scene) field's .slice()). position and rotation are optional overrides of the prefab root's transform.
  • frame.destroy(node) — queues removal of a node and its descendants.

Both are deferred: they apply at the end of the current update, never mid-iteration, so a script can safely spawn/destroy while looping over frame.objects. Spawned instances stay linked to their prefab just like editor-placed ones. See examples/basic-project/assets/PrefabSpawner.zig for a runnable demo that logs each spawn and destroy.

Nested prefabs

A prefab can contain instances of other prefabs, so you compose big templates from small ones. To build one:

  1. Instantiate prefab A into your scene (drag it in, or right-click → Instantiate).
  2. Add a parent object and put that instance under it (plus whatever else you want).
  3. Select the parent and Create Prefab → the new prefab B contains a linked instance of A.

Instantiating B brings its nested A along, and each instance still tracks its own source independently — editing A and Apply-ing it flows into the A nested inside every B.

Variants (not yet)

Prefab variants — a prefab that inherits from another prefab and layers its own permanent overrides on top — are not a distinct feature yet. The nearest thing today: instantiate a prefab, tweak it, then Create Prefab from that instance to get a new, independent prefab. It will not stay linked to the original as a true variant; that inheritance chain is planned future work.

← All docs Edit this page