@relu-interactives/spatial-ecs

---

@relu-interactives/spatial-ecs / components / PrefabInstance

Class: PrefabInstance

Defined in: components/PrefabInstance.ts:45

Marks the ROOT entity of a prefab instance and records its link to the source .prefab asset plus the instance's per-property overrides.

Instances may appear in a scene OR nested inside another prefab's file (nested prefabs): the nested root keeps the child prefab's PrefabNode identity AND this link. instanceId is a per-placement uuid that scopes node identity across nesting — two nested instances of the same prefab share nodeIds but never instanceIds, so override keys stay unambiguous.

overrides is a flat list of encoded strings so it survives snapshot serialization at any depth:

"<nodeKey>|<ComponentName>|<slash/separated/path>"
"<nodeKey>|<ComponentName>|"   // empty path = whole component overridden
"<nodeKey>|+node|"             // marker: node added by the HOST document
                               // inside a nested region (never deleted by
                               // file patching)

where <nodeKey> is the entity's PrefabNode.nodeId prefixed by the instanceId chain of any nested instance roots between the scope root and the entity (e.g. "9f2c…" for direct children, "<iB>/<bNode>" inside a nested instance). Overridden paths keep their per-instance values when the prefab asset is re-applied; everything else syncs from the file. The instance root's Transform, Name, and ParentId are implicitly per-instance and never appear here. Overrides are an editor-side concern — the runtime never resolves them (scene-placed instances are fully materialized; runtime spawns are fresh copies of the file).

Extends

• Component

Constructors

Constructor

new PrefabInstance(
   url, 
   overrides?, 
   instanceId?): PrefabInstance;

Defined in: components/PrefabInstance.ts:57

Parameters

Parameter	Type	Default value
url	string	undefined
overrides	string[]	[]
instanceId?	string	undefined

Returns

PrefabInstance

Overrides

Component.constructor

Properties

Property	Type	Description	Defined in
url	string	URL of the source .prefab asset (localasset://… inside the editor).	components/PrefabInstance.ts:47
overrides	string[]	Encoded override paths — see class docs for the format.	components/PrefabInstance.ts:49
instanceId	string	Per-placement uuid scoping node identity across nesting. Stable for the lifetime of the placement (persisted; survives applies) so override keys referencing nested content stay valid.	components/PrefabInstance.ts:55