@relu-interactives/spatial-ecs 0.2.25 → 0.3.0

package/dist/components/index.js

@@ -1,4 +1,4 @@
-export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-J6736FFO.js';
+export { AnimationComponent, AudioComponent, CameraComponent, DEFAULT_COLLIDER_STATE, DEFAULT_ENVIRONMENT_STATE, DEFAULT_INSTANCED_MESH_PARAMETERS, DEFAULT_INSTANCE_TRANSFORM, DEFAULT_MESH_GEOMETRY_PARAMETERS, DEFAULT_PHYSICS_STATE, DEFAULT_POSTPROCESSING_STATE, DEFAULT_RIGIDBODY_STATE, EntityType, Environment, ImageComponent, ImageTarget, ImageTargetAnchor, InstanceSlotComponent, InstancedMeshComponent, LightComponent, MaterialComponent, MeshComponent, MeshGeometryComponent, ModelComponent, Name, Object3DRef, ParentId, PhysicsComponent, Postprocessing, PrefabInstance, PrefabNode, ScriptComponent, ScriptObjectComponent, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState, setPhysicsLiveRef } from '../chunk-7BPHZWQ6.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/docs/api/Behaviour/classes/Behaviour.md

@@ -6,7 +6,7 @@
 
 # Class: Behaviour
 
-Defined in: [Behaviour.ts:62](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L62)
+Defined in: [Behaviour.ts:64](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L64)
 
 Base class for all user-authored scripts attached to an entity through a
 `ScriptComponent`. Subclass `Behaviour` to drive per-frame logic on a single
@@ -20,15 +20,10 @@ order: [Behaviour.init](#init) (first frame only) → [Behaviour.onUpdate](#onup
 Override [Behaviour.onUpdate](#onupdate) for per-frame logic — never override
 [Behaviour.update](#update), which is the engine-managed entry point.
 
-**Editor scripts**: By default, `Behaviour` subclasses do not run inside the
-editor. Set `executeInEditor: true` on the script entry in the inspector to
-enable the full lifecycle (`init` → `onUpdate` → `dispose`) while the editor
-is open. This gives direct access to the Three.js scene, camera, and renderer
-via [World.getScene](../../index/classes/World.md#getscene), [World.getCamera](../../index/classes/World.md#getcamera), and
-[World.getRenderer](../../index/classes/World.md#getrenderer) — useful for custom shaders, procedural geometry,
-grass, and any Three.js feature the editor's object palette does not expose.
-Avoid mutating ECS component state every frame in editor mode, as it creates
-undo history entries on every tick.
+**Editor vs runtime**: `Behaviour` subclasses run ONLY at preview/runtime —
+they never execute in the editor. For a visual that must render and animate
+inside the editor (custom shaders, procedural geometry, grass, anything the
+object palette can't produce), use [ScriptObject](../../index/classes/ScriptObject.md) instead.
 
 The runtime recognizes a script by its **default export** plus the
 inherited static marker `__reluBehaviourClass`. Do not override the marker.
@@ -76,7 +71,7 @@ new Behaviour(
    component): Behaviour;
 ```
 
-Defined in: [Behaviour.ts:120](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L120)
+Defined in: [Behaviour.ts:122](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L122)
 
 Engine-managed constructor. Hosts (`ScriptBehaviourSystem`) instantiate
 subclasses with the owning world, the entity id, and the script's `data`
@@ -98,13 +93,13 @@ payload. User code should not call this directly.
 
 | Property | Type | Default value | Description | Defined in |
 | ------ | ------ | ------ | ------ | ------ |
-| <a id="data"></a> `data` | \| [`Component`](../../Component/classes/Component.md) \| `Record`\<`string`, `unknown`\> | `undefined` | Inspector-bound payload from the entity's `ScriptComponent`. Override the type on subclasses with `declare data: MyDataShape` to get type safety inside hooks. Saved with the project so values persist across reloads. | [Behaviour.ts:78](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L78) |
-| <a id="entityid"></a> `entityId` | `number` | `undefined` | Numeric id of the entity this script is attached to. | [Behaviour.ts:81](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L81) |
-| <a id="entity"></a> `entity` | `WorldEntityView` | `undefined` | View of the owning entity (id + components) at construction time. | [Behaviour.ts:84](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L84) |
-| <a id="threeref"></a> `threeRef` | [`Object3DRef`](../../components/classes/Object3DRef.md) | `undefined` | Live three.js object wrapper for the entity. May be `null` for entities with no scene presence; helpers on this class return `null` in that case. | [Behaviour.ts:90](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L90) |
-| <a id="transform"></a> `transform` | [`TransformComponent`](../../components/classes/TransformComponent.md) | `undefined` | The entity's [TransformComponent](../../components/classes/TransformComponent.md). Mutating `position`, `rotation`, or `scale` here is picked up the same frame by `TransformSyncSystem`. | [Behaviour.ts:96](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L96) |
-| <a id="world"></a> `world` | [`World`](../../index/classes/World.md) | `undefined` | The owning [World](../../index/classes/World.md). Refreshed each frame in [Behaviour.update](#update). Use it to query other entities or components. | [Behaviour.ts:102](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L102) |
-| <a id="deltatime"></a> `deltaTime` | `number` | `0` | Seconds elapsed since the last frame. Set by the engine before each [Behaviour.onUpdate](#onupdate). | [Behaviour.ts:108](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L108) |
+| <a id="data"></a> `data` | \| [`Component`](../../Component/classes/Component.md) \| `Record`\<`string`, `unknown`\> | `undefined` | Inspector-bound payload from the entity's `ScriptComponent`. Override the type on subclasses with `declare data: MyDataShape` to get type safety inside hooks. Saved with the project so values persist across reloads. | [Behaviour.ts:80](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L80) |
+| <a id="entityid"></a> `entityId` | `number` | `undefined` | Numeric id of the entity this script is attached to. | [Behaviour.ts:83](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L83) |
+| <a id="entity"></a> `entity` | `WorldEntityView` | `undefined` | View of the owning entity (id + components) at construction time. | [Behaviour.ts:86](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L86) |
+| <a id="threeref"></a> `threeRef` | [`Object3DRef`](../../components/classes/Object3DRef.md) | `undefined` | Live three.js object wrapper for the entity. May be `null` for entities with no scene presence; helpers on this class return `null` in that case. | [Behaviour.ts:92](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L92) |
+| <a id="transform"></a> `transform` | [`TransformComponent`](../../components/classes/TransformComponent.md) | `undefined` | The entity's [TransformComponent](../../components/classes/TransformComponent.md). Mutating `position`, `rotation`, or `scale` here is picked up the same frame by `TransformSyncSystem`. | [Behaviour.ts:98](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L98) |
+| <a id="world"></a> `world` | [`World`](../../index/classes/World.md) | `undefined` | The owning [World](../../index/classes/World.md). Refreshed each frame in [Behaviour.update](#update). Use it to query other entities or components. | [Behaviour.ts:104](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L104) |
+| <a id="deltatime"></a> `deltaTime` | `number` | `0` | Seconds elapsed since the last frame. Set by the engine before each [Behaviour.onUpdate](#onupdate). | [Behaviour.ts:110](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L110) |
 
 ## Methods
 
@@ -114,7 +109,7 @@ payload. User code should not call this directly.
 update(world, deltaTime): void;
 ```
 
-Defined in: [Behaviour.ts:144](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L144)
+Defined in: [Behaviour.ts:146](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L146)
 
 Engine-managed per-frame entry point. Refreshes [Behaviour.deltaTime](#deltatime)
 and delegates to [Behaviour.onUpdate](#onupdate).
@@ -149,7 +144,7 @@ CustomEcsSystem.update
 optional dispose(world): void;
 ```
 
-Defined in: [Behaviour.ts:156](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L156)
+Defined in: [Behaviour.ts:158](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L158)
 
 Optional cleanup hook invoked when the script is detached or the entity
 is destroyed. Override to release timers, listeners, or other resources.
@@ -172,13 +167,75 @@ CustomEcsSystem.dispose
 
 ***
 
+### spawnPrefab()
+
+```ts
+spawnPrefab(source, options?): Promise<number>;
+```
+
+Defined in: [Behaviour.ts:181](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L181)
+
+Instantiate a prefab asset into the world at runtime.
+
+`source` is typically an `AssetInput` field from this script's `data`
+(drag a `.prefab` from the asset browser onto the field in the editor),
+a URL string, or a pre-loaded `PrefabAsset`. Resolves with the new root
+entity id.
+
+```ts
+data = { enemyPrefab: { path: "", type: "prefab" } };
+async onUpdate() {
+  if (shouldSpawn) {
+    const id = await this.spawnPrefab(this.data.enemyPrefab, {
+      position: { x: 0, y: 0, z: -5 },
+    });
+  }
+}
+```
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `source` | [`SpawnPrefabSource`](../../index/type-aliases/SpawnPrefabSource.md) |
+| `options?` | [`SpawnPrefabOptions`](../../index/type-aliases/SpawnPrefabOptions.md) |
+
+#### Returns
+
+`Promise`\<`number`\>
+
+***
+
+### despawn()
+
+```ts
+despawn(rootEntityId): number;
+```
+
+Defined in: [Behaviour.ts:192](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L192)
+
+Remove a spawned prefab instance (the root entity and all descendants).
+Returns the number of entities removed.
+
+#### Parameters
+
+| Parameter | Type |
+| ------ | ------ |
+| `rootEntityId` | `number` |
+
+#### Returns
+
+`number`
+
+***
+
 ### getWorldPosition()
 
 ```ts
 getWorldPosition(): Vector3 | null;
 ```
 
-Defined in: [Behaviour.ts:164](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L164)
+Defined in: [Behaviour.ts:200](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L200)
 
 Returns the entity's world-space position as a new `THREE.Vector3`, or
 `null` if the entity has no scene presence.
@@ -195,7 +252,7 @@ Returns the entity's world-space position as a new `THREE.Vector3`, or
 getWorldDirection(): Vector3 | null;
 ```
 
-Defined in: [Behaviour.ts:179](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L179)
+Defined in: [Behaviour.ts:215](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L215)
 
 Returns the entity's forward direction in world space (the +Z axis of its
 world matrix), or `null` if the entity has no scene presence.
@@ -212,7 +269,7 @@ world matrix), or `null` if the entity has no scene presence.
 directionTo(targetPosition): Vector3 | null;
 ```
 
-Defined in: [Behaviour.ts:196](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L196)
+Defined in: [Behaviour.ts:232](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L232)
 
 Returns a unit vector pointing from this entity toward the given world
 position, or `null` if the entity has no scene presence.
@@ -235,7 +292,7 @@ position, or `null` if the entity has no scene presence.
 distanceTo(targetPosition): number | null;
 ```
 
-Defined in: [Behaviour.ts:211](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L211)
+Defined in: [Behaviour.ts:247](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L247)
 
 Returns the world-space distance from this entity to the given position,
 or `null` if the entity has no scene presence.
@@ -258,7 +315,7 @@ or `null` if the entity has no scene presence.
 lerpTo(targetPosition, alpha): void;
 ```
 
-Defined in: [Behaviour.ts:229](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L229)
+Defined in: [Behaviour.ts:265](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L265)
 
 Linearly interpolates the entity's position toward `targetPosition` and
 writes the result back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if the
@@ -283,7 +340,7 @@ entity has no scene presence.
 slerpTo(targetRotation, alpha): void;
 ```
 
-Defined in: [Behaviour.ts:251](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L251)
+Defined in: [Behaviour.ts:287](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L287)
 
 Spherically interpolates the entity's rotation toward `targetRotation`
 and writes the result back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if
@@ -308,7 +365,7 @@ the entity has no scene presence.
 lookAt(targetPosition): void;
 ```
 
-Defined in: [Behaviour.ts:270](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L270)
+Defined in: [Behaviour.ts:306](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L306)
 
 Rotates the entity to face `targetPosition` in world space and writes the
 resulting orientation back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if
@@ -332,7 +389,7 @@ the entity has no scene presence.
 getComponents(): Component[];
 ```
 
-Defined in: [Behaviour.ts:284](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L284)
+Defined in: [Behaviour.ts:320](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L320)
 
 Returns every component currently attached to this entity.
 
@@ -348,7 +405,7 @@ Returns every component currently attached to this entity.
 getComponent<T>(componentClass): T | null;
 ```
 
-Defined in: [Behaviour.ts:301](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L301)
+Defined in: [Behaviour.ts:337](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L337)
 
 Returns the entity's component of the given class, or `null` if it has
 no such component.
@@ -384,7 +441,7 @@ if (mesh) console.log(mesh.geometryRef);
 getEntity(): WorldEntityView | null;
 ```
 
-Defined in: [Behaviour.ts:311](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L311)
+Defined in: [Behaviour.ts:347](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L347)
 
 Returns the latest [WorldEntityView](../../types/type-aliases/WorldEntityView.md) snapshot for this entity, or
 `null` if it was destroyed.
@@ -401,7 +458,7 @@ Returns the latest [WorldEntityView](../../types/type-aliases/WorldEntityView.md
 getParent(): ParentLookup;
 ```
 
-Defined in: [Behaviour.ts:321](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L321)
+Defined in: [Behaviour.ts:357](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L357)
 
 Resolves the entity's parent from the [ParentId](../../components/classes/ParentId.md) component, if any.
 
@@ -420,7 +477,7 @@ A [ParentLookup](../../types/type-aliases/ParentLookup.md) with the parent compo
 getChildren(): WorldEntityView[];
 ```
 
-Defined in: [Behaviour.ts:342](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L342)
+Defined in: [Behaviour.ts:378](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L378)
 
 Returns every direct child entity of this one (entities whose
 [ParentId](../../components/classes/ParentId.md) matches `entityId`).
@@ -437,21 +494,16 @@ Returns every direct child entity of this one (entities whose
 protected init(): void;
 ```
 
-Defined in: [Behaviour.ts:361](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L361)
+Defined in: [Behaviour.ts:393](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L393)
 
 Called once before the first [Behaviour.onUpdate](#onupdate). Override to
 default and validate [Behaviour.data](#data), cache references, or set
-initial state.
+initial state. Runs at preview/runtime only — never in the editor.
 
 #### Returns
 
 `void`
 
-#### Remarks
-
-Also called in editor mode when `executeInEditor` is `true` on the script
-entry.
-
 ***
 
 ### onUpdate()
@@ -460,21 +512,16 @@ entry.
 protected onUpdate(): void;
 ```
 
-Defined in: [Behaviour.ts:374](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L374)
+Defined in: [Behaviour.ts:402](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L402)
 
 Called every frame while the script is enabled. Override with the
-script's main per-frame logic.
+script's main per-frame logic. Runs at preview/runtime only — never in the
+editor (use [ScriptObject](../../index/classes/ScriptObject.md) for editor-visible visuals).
 
 #### Returns
 
 `void`
 
-#### Remarks
-
-Also called every frame in editor mode when `executeInEditor` is `true`.
-Access the Three.js scene with `this.world.getScene()` for editor-only
-rendering work such as custom shaders or procedural geometry.
-
 ***
 
 ### onSelect()
@@ -483,7 +530,7 @@ rendering work such as custom shaders or procedural geometry.
 onSelect(): void;
 ```
 
-Defined in: [Behaviour.ts:379](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L379)
+Defined in: [Behaviour.ts:407](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L407)
 
 Called when the editor selects this entity. Optional UX hook.
 
@@ -499,7 +546,7 @@ Called when the editor selects this entity. Optional UX hook.
 onDeselect(): void;
 ```
 
-Defined in: [Behaviour.ts:384](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L384)
+Defined in: [Behaviour.ts:412](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L412)
 
 Called when the editor deselects this entity. Optional UX hook.
 
@@ -515,7 +562,7 @@ Called when the editor deselects this entity. Optional UX hook.
 onTargetFound(target): void;
 ```
 
-Defined in: [Behaviour.ts:394](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L394)
+Defined in: [Behaviour.ts:422](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L422)
 
 Called when an image-tracking target this entity depends on becomes
 visible. Optional AR hook.
@@ -538,7 +585,7 @@ visible. Optional AR hook.
 onTargetLost(target): void;
 ```
 
-Defined in: [Behaviour.ts:404](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Behaviour.ts#L404)
+Defined in: [Behaviour.ts:432](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Behaviour.ts#L432)
 
 Called when an image-tracking target this entity depends on is lost.
 Optional AR hook.

package/dist/docs/api/Component/classes/Component.md

@@ -6,7 +6,7 @@
 
 # Class: Component
 
-Defined in: [Component.ts:12](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/Component.ts#L12)
+Defined in: [Component.ts:12](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/Component.ts#L12)
 
 Marker base class for every ECS component. Subclass `Component` to declare
 a typed data container that systems can query.
@@ -39,7 +39,10 @@ asset URLs).
 - [`Name`](../../components/classes/Name.md)
 - [`Object3DRef`](../../components/classes/Object3DRef.md)
 - [`ParentId`](../../components/classes/ParentId.md)
+- [`PrefabInstance`](../../components/classes/PrefabInstance.md)
+- [`PrefabNode`](../../components/classes/PrefabNode.md)
 - [`ScriptComponent`](../../components/classes/ScriptComponent.md)
+- [`ScriptObjectComponent`](../../components/classes/ScriptObjectComponent.md)
 - [`Selectable`](../../components/classes/Selectable.md)
 - [`SpriteComponent`](../../components/classes/SpriteComponent.md)
 - [`SelectionTransformState`](../../components/classes/SelectionTransformState.md)

package/dist/docs/api/components/classes/AnimationComponent.md

@@ -6,7 +6,7 @@
 
 # Class: AnimationComponent
 
-Defined in: [components/Animation.ts:71](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L71)
+Defined in: [components/Animation.ts:71](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L71)
 
 Animation catalog and runtime state for an entity. Combines clips imported
 from a model with externally added clips, exposes a state machine for
@@ -30,7 +30,7 @@ machine directly so the animation system observes transitions.
 new AnimationComponent(options?): AnimationComponent;
 ```
 
-Defined in: [components/Animation.ts:102](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L102)
+Defined in: [components/Animation.ts:102](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L102)
 
 #### Parameters
 
@@ -50,18 +50,18 @@ Defined in: [components/Animation.ts:102](https://github.com/Relu-Interactives/r
 
 | Property | Type | Description | Defined in |
 | ------ | ------ | ------ | ------ |
-| <a id="clips"></a> `clips` | `AnimationClip`[] | Combined ordered list of clips (model + external) currently loaded. | [components/Animation.ts:78](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L78) |
-| <a id="clipcatalog"></a> `clipCatalog` | `AnimationClipCatalogEntry`[] | Per-clip metadata used by the inspector. | [components/Animation.ts:80](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L80) |
-| <a id="availableclips"></a> `availableClips` | `string`[] | Display names of clips available for state-machine bindings. | [components/Animation.ts:82](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L82) |
-| <a id="externalclipsources"></a> `externalClipSources` | `string`[] | URLs/paths of external clip sources (saved with the project). | [components/Animation.ts:84](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L84) |
-| <a id="paused"></a> `paused` | `boolean` | Whether playback is currently paused. | [components/Animation.ts:86](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L86) |
-| <a id="reverse"></a> `reverse` | `boolean` | Play the active clip in reverse. | [components/Animation.ts:88](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L88) |
-| <a id="timescale"></a> `timeScale` | `number` | Playback speed multiplier (`1` = real-time). | [components/Animation.ts:90](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L90) |
-| <a id="crossfadeduration"></a> `crossFadeDuration` | `number` | Default cross-fade duration in seconds when switching states. | [components/Animation.ts:92](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L92) |
-| <a id="states"></a> `states` | [`AnimationStateMachine`](../../index/classes/AnimationStateMachine.md)[] | All state-machine entries authored on this entity. | [components/Animation.ts:94](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L94) |
-| <a id="active"></a> `active` | \| [`AnimationStateMachine`](../../index/classes/AnimationStateMachine.md) \| `null` | State currently being played, or `null` if none. | [components/Animation.ts:96](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L96) |
-| <a id="activestatename"></a> `activeStateName` | `string` \| `null` | Name of the [active](#active) state, or `null` if none. | [components/Animation.ts:98](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L98) |
-| <a id="statemanager"></a> `stateManager` | [`AnimationStateManager`](../../index/classes/AnimationStateManager.md) | Manager that drives state transitions; mutate via [addState](#addstate)/[switchState](#switchstate). | [components/Animation.ts:100](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L100) |
+| <a id="clips"></a> `clips` | `AnimationClip`[] | Combined ordered list of clips (model + external) currently loaded. | [components/Animation.ts:78](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L78) |
+| <a id="clipcatalog"></a> `clipCatalog` | `AnimationClipCatalogEntry`[] | Per-clip metadata used by the inspector. | [components/Animation.ts:80](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L80) |
+| <a id="availableclips"></a> `availableClips` | `string`[] | Display names of clips available for state-machine bindings. | [components/Animation.ts:82](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L82) |
+| <a id="externalclipsources"></a> `externalClipSources` | `string`[] | URLs/paths of external clip sources (saved with the project). | [components/Animation.ts:84](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L84) |
+| <a id="paused"></a> `paused` | `boolean` | Whether playback is currently paused. | [components/Animation.ts:86](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L86) |
+| <a id="reverse"></a> `reverse` | `boolean` | Play the active clip in reverse. | [components/Animation.ts:88](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L88) |
+| <a id="timescale"></a> `timeScale` | `number` | Playback speed multiplier (`1` = real-time). | [components/Animation.ts:90](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L90) |
+| <a id="crossfadeduration"></a> `crossFadeDuration` | `number` | Default cross-fade duration in seconds when switching states. | [components/Animation.ts:92](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L92) |
+| <a id="states"></a> `states` | [`AnimationStateMachine`](../../index/classes/AnimationStateMachine.md)[] | All state-machine entries authored on this entity. | [components/Animation.ts:94](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L94) |
+| <a id="active"></a> `active` | \| [`AnimationStateMachine`](../../index/classes/AnimationStateMachine.md) \| `null` | State currently being played, or `null` if none. | [components/Animation.ts:96](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L96) |
+| <a id="activestatename"></a> `activeStateName` | `string` \| `null` | Name of the [active](#active) state, or `null` if none. | [components/Animation.ts:98](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L98) |
+| <a id="statemanager"></a> `stateManager` | [`AnimationStateManager`](../../index/classes/AnimationStateManager.md) | Manager that drives state transitions; mutate via [addState](#addstate)/[switchState](#switchstate). | [components/Animation.ts:100](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L100) |
 
 ## Methods
 
@@ -71,7 +71,7 @@ Defined in: [components/Animation.ts:102](https://github.com/Relu-Interactives/r
 setModelClips(clips): void;
 ```
 
-Defined in: [components/Animation.ts:234](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L234)
+Defined in: [components/Animation.ts:234](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L234)
 
 #### Parameters
 
@@ -91,7 +91,7 @@ Defined in: [components/Animation.ts:234](https://github.com/Relu-Interactives/r
 setImportedClips(clips): void;
 ```
 
-Defined in: [components/Animation.ts:239](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L239)
+Defined in: [components/Animation.ts:239](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L239)
 
 #### Parameters
 
@@ -111,7 +111,7 @@ Defined in: [components/Animation.ts:239](https://github.com/Relu-Interactives/r
 setExternalClipSources(sources): void;
 ```
 
-Defined in: [components/Animation.ts:276](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L276)
+Defined in: [components/Animation.ts:276](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L276)
 
 #### Parameters
 
@@ -136,7 +136,7 @@ addState(
   | null;
 ```
 
-Defined in: [components/Animation.ts:301](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L301)
+Defined in: [components/Animation.ts:301](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L301)
 
 #### Parameters
 
@@ -159,7 +159,7 @@ Defined in: [components/Animation.ts:301](https://github.com/Relu-Interactives/r
 setStates(states): void;
 ```
 
-Defined in: [components/Animation.ts:316](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L316)
+Defined in: [components/Animation.ts:316](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L316)
 
 #### Parameters
 
@@ -184,7 +184,7 @@ getStateConfigs(): {
 }[];
 ```
 
-Defined in: [components/Animation.ts:343](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L343)
+Defined in: [components/Animation.ts:343](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L343)
 
 #### Returns
 
@@ -203,7 +203,7 @@ Defined in: [components/Animation.ts:343](https://github.com/Relu-Interactives/r
 setActiveState(name, autoPlay?): boolean;
 ```
 
-Defined in: [components/Animation.ts:352](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L352)
+Defined in: [components/Animation.ts:352](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L352)
 
 #### Parameters
 
@@ -224,7 +224,7 @@ Defined in: [components/Animation.ts:352](https://github.com/Relu-Interactives/r
 removeState(name): boolean;
 ```
 
-Defined in: [components/Animation.ts:363](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L363)
+Defined in: [components/Animation.ts:363](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L363)
 
 #### Parameters
 
@@ -244,7 +244,7 @@ Defined in: [components/Animation.ts:363](https://github.com/Relu-Interactives/r
 switchState(name, autoPlay?): boolean;
 ```
 
-Defined in: [components/Animation.ts:371](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L371)
+Defined in: [components/Animation.ts:371](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L371)
 
 #### Parameters
 
@@ -265,7 +265,7 @@ Defined in: [components/Animation.ts:371](https://github.com/Relu-Interactives/r
 playState(name?): boolean;
 ```
 
-Defined in: [components/Animation.ts:382](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L382)
+Defined in: [components/Animation.ts:382](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L382)
 
 #### Parameters
 
@@ -285,7 +285,7 @@ Defined in: [components/Animation.ts:382](https://github.com/Relu-Interactives/r
 pauseState(name?): boolean;
 ```
 
-Defined in: [components/Animation.ts:393](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L393)
+Defined in: [components/Animation.ts:393](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L393)
 
 #### Parameters
 
@@ -305,7 +305,7 @@ Defined in: [components/Animation.ts:393](https://github.com/Relu-Interactives/r
 stopState(name?): boolean;
 ```
 
-Defined in: [components/Animation.ts:404](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/f4080487315dc2ea88332b3160fc071e7828b385/core/components/Animation.ts#L404)
+Defined in: [components/Animation.ts:404](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/020795472520adb990c488982ca8572cbf8580db/core/components/Animation.ts#L404)
 
 #### Parameters