@modoki/engine / index / spawnPrefabInstance

Function: spawnPrefabInstance()

spawnPrefabInstance(world, prefab, opts?): number

Spawn a prefab instance into a world at RUNTIME (gameplay) — as opposed to scene-load instantiation, which is driven by loadSceneFile + onInstantiatePrefab.

A scene-authored instance carries a serialized root guid (stable across reloads). A runtime instance has none, so this mints a FRESH unique root guid: multiple live instances of the same prefab must never share a guid (the guid is now the entity's identity in the index + cross-entity refs). Members get deterministic guids derived off that unique root, so they're unique per instance too. Root + members are added to the guid index, so they're immediately addressable by guid.

opts.guidSeed makes the root guid DETERMINISTIC — deriveGuid(seed) instead of the random newGuid(). A caller on a deterministic sim path (e.g. a Timeline control track spawning on an exact tick) MUST pass a stable seed built from stable ids (the Director's guid + track/clip index — never a runtime entity id), so two identical-seed replays mint the same guid and the event journal stays byte-reproducible. Omit it for genuinely ad-hoc runtime spawns, which want a fresh random identity each time.

Returns the root entity's koota id (0 on failure).

Parameters

world

World

prefab

entities

PrefabFileEntry[]

id?

string

rootLocalId?

number

opts?

forceTransient?

boolean

guidSeed?

string

parentId?

number

rootTransform?

Record<string, unknown>

source?

string

Returns

number