@modoki/engine / index / LoadSceneOptions

Interface: LoadSceneOptions

Scene & Prefabs

clearMarks?

optional clearMarks?: boolean

Drop EVERY override mark before spawning (default true).

The global clear defends against ecs-id reuse ACROSS WORLDS — a world-scoped concern that was attached to a call back when one loadSceneFile call WAS one world. Phase 5 (base scenes) broke that equivalence: a chain loads N scene files into ONE world, bases first and the primary last, so the primary's call wiped the marks the base's call had just seeded and every carried/chained prefab instance serialized with EMPTY overrides (finding "A9" — docs/reviews/a9-carried-instance-overrides-investigation.md, defect 1).

SceneManager therefore clears ONCE per staging world and passes false for every chain + carry call. Left true by default so every other caller (tests, and any future single-scene caller) keeps byte-identical behaviour — per-entity hygiene against id reuse is independent of this flag and always runs (clearOverrideMarks(entity.id()) on each fresh spawn, below).

---

fetchPrefab

fetchPrefab: (path) => Promise<object | null>

Fetch a prefab JSON file given its path. Returns null if not found.

Parameters

path

string

Returns

Promise<object | null>

---

loadModels?

optional loadModels?: boolean

Whether to preload model templates from ModelSource entities

---

onDeletePlaceholder?

optional onDeletePlaceholder?: (entityId) => void

Called before deleting a placeholder entity during prefab re-instantiation

Parameters

entityId

number

Returns

void

---

onEntitySpawned?

optional onEntitySpawned?: (entity, oldId) => void

Called after all entities are spawned (runtime: registerEntity, editor: undo tracking)

Parameters

entity

any

oldId

number

Returns

void

---

onInstantiatePrefab?

optional onInstantiatePrefab?: (source, parentId, rootTransform, oldEntityId, rootExtraTraits?, overrides?, structure?, nestedOverrides?, rootGuid?, rootEditorFolder?) => void

Called to re-instantiate a prefab instance. The caller handles prefab fetch + entity creation. rootExtraTraits are traits the scene file added on the prefab-instance root beyond what the prefab itself defines (e.g. user-added Rotate3D, AnimatePosition). overrides carries per-localId field-level edits captured at save time so children's local edits survive reload.

Parameters

source

string

parentId

number

rootTransform

Record<string, unknown> | undefined

oldEntityId

number

rootExtraTraits?

Record<string, unknown>

overrides?

Record<number, Record<string, Record<string, unknown>>>

structure?

InstanceStructureData

nestedOverrides?

Record<number, Record<number, Record<string, Record<string, unknown>>>>

rootGuid?

string

The scene-authored stable guid for the instance root (SceneEntityEntry.guid), applied to the spawned root so it's addressable and anchors member derivation.

rootEditorFolder?

string

The editor Hierarchy folder tag (EntityAttributes.editorFolder) captured on the instance root, re-applied so a foldered prefab instance stays in its folder across reload. Empty/undefined = ungrouped.

Returns

void

---

world?

optional world?: World

Target world for entity spawning. Defaults to getCurrentWorld(). SceneManager passes the staging nextWorld so entities are isolated until the swap.