@relu-interactives/spatial-ecs 0.2.21 → 0.2.22

package/dist/components/index.d.cts

@@ -1,5 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-U9hAnf9y.cjs';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-me3iAcMF.cjs';
-export { P as PrefabInstance, a as PrefabNode } from '../index-CZo5I5Gs.cjs';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as ScriptObjectComponent, X as ScriptObjectComponentInput, Y as ScriptObjectRuntimeState, Z as Selectable, _ as SelectionTransformState, $ as SpriteComponent, a0 as TextureFilteringValue, a1 as TransformModeValue, a2 as TransformSpaceValue, a3 as VideoComponent, a4 as defaultMaterialValue, a5 as normalizePhysicsState } from '../Video-ppAXaKt0.cjs';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-CYWZ_Zx5.cjs';
+export { P as PrefabInstance, a as PrefabNode } from '../index-Cu2Pt7wN.cjs';
 import 'three';
 import '@dimforge/rapier3d-compat';

package/dist/components/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as defaultMaterialValue, a2 as normalizePhysicsState } from '../Video-DHnxjGhW.js';
-export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-me3iAcMF.js';
-export { P as PrefabInstance, a as PrefabNode } from '../index-D7FSg0Au.js';
+export { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as ScriptObjectComponent, X as ScriptObjectComponentInput, Y as ScriptObjectRuntimeState, Z as Selectable, _ as SelectionTransformState, $ as SpriteComponent, a0 as TextureFilteringValue, a1 as TransformModeValue, a2 as TransformSpaceValue, a3 as VideoComponent, a4 as defaultMaterialValue, a5 as normalizePhysicsState } from '../Video-C1IOat7L.js';
+export { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from '../System-CYWZ_Zx5.js';
+export { P as PrefabInstance, a as PrefabNode } from '../index-DdiWu1b6.js';
 import 'three';
 import '@dimforge/rapier3d-compat';

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, Selectable, SelectionTransformState, SpriteComponent, TransformComponent, VideoComponent, defaultMaterialValue, normalizePhysicsState } from '../chunk-V7BNVTJW.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 } from '../chunk-JHCPRVBC.js';
 import '../chunk-OY7ZODZP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/docs/guide/authoring-a-behaviour.md

@@ -122,45 +122,8 @@ See [Accessing Components](./accessing-components) to read and mutate built-in c
 
 See [Reading Input](./reading-input) for the full keyboard and mouse input API, `KeyboardKeys` reference, and scripting examples.
 
-## Running scripts in the editor
+## Behaviours run at preview/runtime only
 
-By default, `Behaviour` scripts only execute at preview or runtime. Setting **Execute in editor** to `true` on a script entry (via the inspector toggle) enables the full lifecycle (`init` → `onUpdate`) while the editor is open.
+`Behaviour` scripts execute **only** at preview and runtime — never inside the editor. Gameplay logic, input handling, physics, and anything that should not run while authoring belongs in a Behaviour.
 
-This is useful for Three.js functionality the editor's object palette does not expose — custom shaders, procedural geometry, grass, post-processing passes, and similar.
-
-```ts
-import { Behaviour } from "@relu-interactives/spatial-ecs";
-import * as THREE from "three";
-
-export default class GrassPlane extends Behaviour {
-  private mesh: THREE.Mesh | null = null;
-
-  protected init() {
-    // Access the live Three.js scene directly.
-    const scene = this.world.getScene();
-
-    const geo = new THREE.PlaneGeometry(10, 10, 32, 32);
-    const mat = new THREE.MeshStandardMaterial({ color: 0x228b22 });
-    this.mesh = new THREE.Mesh(geo, mat);
-    scene.add(this.mesh);
-  }
-
-  protected dispose() {
-    if (this.mesh) {
-      this.world.getScene().remove(this.mesh);
-      this.mesh = null;
-    }
-  }
-}
-```
-
-> [!WARNING]
-> **Undo-history churn** — avoid writing to ECS components (e.g. `TransformComponent`) on every frame when `executeInEditor` is `true`. The editor's change-detection system records a new undo entry each time a component snapshot differs, which will flood the undo stack and cause performance degradation. Keep per-frame mutations in local Three.js state (objects, materials, uniforms) rather than in ECS component fields.
-
-Available world accessors in editor mode:
-
-| Accessor | Returns |
-| --- | --- |
-| `this.world.getScene()` | `THREE.Scene` |
-| `this.world.getCamera()` | `THREE.PerspectiveCamera` |
-| `this.world.getRenderer()` | `THREE.WebGLRenderer` |
+For a visual that must render and animate **inside the editor** (custom shaders, procedural geometry, grass, particle systems — anything the object palette can't produce), use a [Script Object](./authoring-a-script-object) instead. A `ScriptObject` builds a `THREE.Object3D` that renders in the editor AND at runtime.

package/dist/docs/guide/authoring-a-script-object.md

@@ -0,0 +1,102 @@
+# Authoring a Script Object
+
+A **Script Object** is an entity whose THREE.js visual is built entirely by your code — custom shaders, procedural geometry, particle systems, anything the editor's object palette can't produce. Unlike a [Behaviour](./authoring-a-behaviour), a Script Object runs in the **editor AND at runtime**: `build()` and `update()` execute identically in both, so what you see while authoring is exactly what ships.
+
+> [!IMPORTANT]
+> **Do NOT gate anything on `world.isEditorMode()`.** Running everywhere is the whole point of a Script Object. Use a [Behaviour](./authoring-a-behaviour) for gameplay logic that must NOT run in the editor.
+
+## The contract
+
+Subclass `ScriptObject` and export it (named export matching the class, or default export):
+
+```ts
+import { ScriptObject, type ColorInput } from "@relu-interactives/spatial-ecs";
+import * as THREE from "three";
+
+export default class WavePlane extends ScriptObject {
+  // Typed data → inspector fields (same envelopes as Behaviours).
+  declare data: { color: ColorInput };
+
+  private mat!: THREE.ShaderMaterial;
+
+  // REQUIRED — build and return the visual root.
+  build(): THREE.Object3D {
+    this.data.color ??= { type: "color", value: "#3aa0ff" };
+    this.mat = new THREE.ShaderMaterial({
+      uniforms: {
+        uTime: { value: 0 },
+        uColor: { value: new THREE.Color(this.data.color.value) },
+      },
+      vertexShader: /* glsl */ `
+        uniform float uTime;
+        varying float vH;
+        void main() {
+          vec3 p = position;
+          p.z += sin(p.x * 4.0 + uTime) * 0.1;
+          vH = p.z;
+          gl_Position = projectionMatrix * modelViewMatrix * vec4(p, 1.0);
+        }`,
+      fragmentShader: /* glsl */ `
+        uniform vec3 uColor;
+        varying float vH;
+        void main() { gl_FragColor = vec4(uColor * (0.6 + vH), 1.0); }`,
+    });
+    const geo = new THREE.PlaneGeometry(2, 2, 64, 64);
+    geo.rotateX(-Math.PI / 2);
+    return new THREE.Mesh(geo, this.mat);
+  }
+
+  // OPTIONAL — per-frame, runs in editor AND runtime.
+  update(deltaTime: number): void {
+    this.mat.uniforms.uTime.value += deltaTime;
+  }
+
+  // OPTIONAL — free GPU resources you created.
+  dispose(): void {
+    this.mat.dispose();
+  }
+}
+```
+
+`ScriptObjectSystem` calls `build()` once, attaches the returned object under the entity's Object3D (so it inherits the entity's transform, selection, and visibility), then calls `update(deltaTime)` every frame. `dispose()` runs on removal, disable, or hot-reload.
+
+## Members available
+
+| Member | Type | Notes |
+| --- | --- | --- |
+| `this.world` | `World` | The owning ECS world. |
+| `this.entityId` | `number` | The entity this script is bound to. |
+| `this.data` | `Record<string, unknown>` | Inspector-bound payload. Declare a shape with `declare data: MyShape`. |
+| `this.root` | `THREE.Object3D \| null` | The object `build()` returned (set after build). |
+
+## Data fields (inspector)
+
+Type `data` fields with the same input envelopes as Behaviours to get inspector controls:
+
+```ts
+declare data: {
+  color: ColorInput;      // color swatch
+  amplitude: SliderInput; // slider
+  target: EntityInput;    // entity picker
+};
+```
+
+Read a field's value as `this.data.color.value`. See [Data binding](./behaviour-data-binding/) for the full envelope catalog. Edits made in the inspector are pushed to the live instance's `this.data` between frames.
+
+## Rules
+
+- **`build()` must return a `THREE.Object3D`** — a `Group`, `Mesh`, `Points`, etc. Returning anything else marks the object as errored.
+- **Do NOT gate on `world.isEditorMode()`.** Build and animate unconditionally.
+- **`dispose()` must free what you allocated** — geometries, materials, textures, render targets. THREE `dispose()` is idempotent, so it's safe to over-dispose. The engine removes the built subtree from the scene for you; freeing GPU memory is yours.
+- **Keep per-frame work in local THREE state / uniforms.** Do NOT write ECS components every frame from `update()` — that churns the editor's undo history.
+- **Pivot at the origin, meters for scale.** The built object rides the entity's transform, so build it centered on `(0,0,0)` at real-world scale.
+- **Imports**: only `three` (and `three/examples/jsm/*`) and `@relu-interactives/spatial-ecs`. Other bare imports won't resolve.
+
+## Behaviour vs Script Object
+
+| | Behaviour | Script Object |
+| --- | --- | --- |
+| Runs in editor | ❌ preview/runtime only | ✅ editor AND runtime |
+| Purpose | gameplay logic, input, physics | visuals: shaders, procedural geometry, particles |
+| Produces | side effects on the world | a `THREE.Object3D` (the entity's visual) |
+| Hooks | `init` / `onUpdate` / `dispose` | `build` / `update` / `dispose` |

package/dist/docs/guide/behaviour-lifecycle.md

@@ -28,13 +28,13 @@ This ordering means:
 
 | Hook | Override? | Frequency | Runs in editor? | Purpose |
 | --- | --- | --- | --- | --- |
-| `init()` | Yes (protected) | Once before first `onUpdate` | Only when `executeInEditor: true` | Default and validate `data`, cache references |
-| `onUpdate()` | Yes (protected) | Every frame | Only when `executeInEditor: true` | Per-frame logic |
-| `dispose()` | Yes | Once on detach/destroy | Only when `executeInEditor: true` | Release timers, listeners, resources |
+| `init()` | Yes (protected) | Once before first `onUpdate` | No | Default and validate `data`, cache references |
+| `onUpdate()` | Yes (protected) | Every frame | No | Per-frame logic |
+| `dispose()` | Yes | Once on detach/destroy | No | Release timers, listeners, resources |
 | `onSelect()` / `onDeselect()` | Optional | Editor selection toggles | Yes | UX-only hooks |
 | `onTargetFound()` / `onTargetLost()` | Optional | Image tracking | No | React to AR target visibility |
 
-Set `executeInEditor: true` on a script entry in the inspector to opt a script into the full lifecycle in editor mode. See [Running scripts in the editor](./authoring-a-behaviour#running-scripts-in-the-editor).
+Behaviours never run in the editor. For a visual that must render and animate in the editor, use a [Script Object](./authoring-a-script-object).
 
 <!-- ## Tips
 

package/dist/docs/guide/spawning/script-object.md

@@ -0,0 +1,36 @@
+# Script Object
+
+An entity whose visual is built by a user [`ScriptObject`](../authoring-a-script-object) script (custom shaders, procedural geometry, particles). Renders and animates in the editor AND at runtime. Starts as an empty `THREE.Group`; `ScriptObjectSystem` builds the visual once a script is linked.
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class Spawner extends Behaviour {
+  init() {
+    const objects = this.world.getObjectManagementSystem();
+    objects?.requestCreate("scriptObject", {
+      name: "Wave",
+      transform: { position: { x: 0, y: 0, z: -3 } },
+      options: {
+        scriptUrl: "localasset://.../scripts/WavePlane.js",
+        className: "WavePlane",
+      },
+    });
+  }
+}
+```
+
+## Payload
+
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `"Script Object"` | Display name. |
+| `transform` | `TransformData` | identity | Position / rotation (radians) / scale. |
+| `options.scriptUrl` | `string \| null` | `null` | Compiled script URL. Optional — can be assigned later in the inspector. |
+| `options.className` | `string \| null` | `null` | Exported `ScriptObject` class name. |
+| `options.enabled` | `boolean` | `true` | When `false`, the visual isn't built/ticked. |
+| `options.data` | `Record<string, unknown>` | `{}` | Initial inspector data. |
+
+## Components attached
+
+`Transform`, `Object3DRef`, `Name`, `EntityType`, `ParentId`, `Selectable`, `ScriptObjectComponent`.

package/dist/docs/guide/systems/_sidebar.json

@@ -59,6 +59,10 @@
     "text": "ScriptBehaviourSystem",
     "link": "/guide/systems/script-behaviour-system"
   },
+  {
+    "text": "ScriptObjectSystem",
+    "link": "/guide/systems/script-object-system"
+  },
   {
     "text": "TransformSyncSystem",
     "link": "/guide/systems/transform-sync-system"

package/dist/docs/guide/systems/script-behaviour-system.md

@@ -34,23 +34,7 @@ If no valid `Behaviour` subclass is found the entry is skipped and an error is w
 - **Instance keying** — each script instance is keyed by `entityId + scriptUrl + className`. A new instance is created only when any of these three values changes.
 - **Error isolation** — errors thrown inside `init()` or `onUpdate()` are caught per-instance and logged to the console. A failing script does not crash the frame loop or affect other scripts.
 - **Destroyed entity cleanup** — when an entity is removed from the world, all of its script instances are destroyed and removed from the registry on the next update.
-- **Editor vs preview** — the system is used in both the editor and preview. By default, scripts are **not** executed in the editor. Set `executeInEditor: true` on a `ScriptEntry` to opt a script into full lifecycle execution (including `init()`) while the editor is open. Scripts without this flag stay in `idle` state in editor mode and never call `init()` or `onUpdate()`.
-
-## Editor mode execution
-
-When `ScriptEntry.executeInEditor` is `true`:
-
-1. The script module is loaded and the class is instantiated as normal.
-2. `init()` is called once (same as preview).
-3. `onUpdate()` is called every frame while the script is enabled.
-4. Direct Three.js scene access is available via `this.world.getScene()`, `getCamera()`, and `getRenderer()`.
-
-This allows scripts to create geometry, shaders, materials, and any other Three.js construct that the editor's object palette does not expose.
-
-> [!WARNING]
-> Writing to ECS components (e.g. `TransformComponent`) every frame in editor mode will generate an undo history entry on every tick. Keep per-frame mutations in local Three.js state to avoid flooding the undo stack.
-
-See [Running scripts in the editor](../authoring-a-behaviour#running-scripts-in-the-editor) for usage examples.
+- **Editor vs preview** — Behaviours execute **only** at preview/runtime. In an editor world (`isEditorMode()`), every `ScriptComponent` entry stays in `idle` state and `init()`/`onUpdate()` never run. For visuals that must render in the editor, use [`ScriptObjectSystem`](./script-object-system) + [`ScriptObject`](../authoring-a-script-object).
 
 ## API reference
 

package/dist/docs/guide/systems/script-object-system.md

@@ -0,0 +1,44 @@
+# ScriptObjectSystem
+
+Loads, builds, ticks, and disposes [`ScriptObject`](../authoring-a-script-object) scripts attached via `ScriptObjectComponent`. Unlike [`ScriptBehaviourSystem`](./script-behaviour-system), it runs in the **editor AND at runtime** — there is no `isEditorMode()` gating.
+
+## Lifecycle
+
+For each entity with an enabled `ScriptObjectComponent` that has a `scriptUrl` + `className`:
+
+1. **Load** — the module is fetched via the `moduleLoader`, the class resolved (named export → `default` → `__reluScriptObjectClass` marker), and instantiated. `runtimeState` transitions `idle → loading`.
+2. **Build** — `build()` runs; the returned `THREE.Object3D` is tagged (`userData.__scriptObjectRoot`) and attached under the entity's `Object3DRef.object`. `runtimeState → ready`.
+3. **Update** — every frame while enabled and visible, `update(deltaTime)` is called. Inspector data edits are pushed to `this.data` between frames (dirty-checked, not per-frame).
+4. **Dispose** — on removal, disable, script change, or `invalidate*()`, `dispose()` is called and the built subtree is removed and its geometries/materials/textures freed (shared model-cache resources are skipped).
+
+`runtimeState` is written **only on transitions** (never every frame). A `build()`/`update()` error sets `runtimeState: "error"` with a sanitized message and tombstones the record so a broken script doesn't reload every frame (cleared by a script/enabled change or `invalidate*()`).
+
+## Keying
+
+Instances are keyed by **entity id** — a duplicated entity gets its own fresh instance, and two entities sharing one `scriptUrl` get independent instances.
+
+## Hot reload
+
+- `invalidateAll()` — disposes every live instance so the next `update()` reloads with freshly compiled modules. The editor calls this on its asset-changed epoch.
+- `invalidate(scriptUrl)` — same, scoped to one script.
+
+The `moduleLoader` owns cache-busting: with the default dynamic-import loader the URL must change for fresh code to load; `invalidate*()` guarantees re-instantiation.
+
+## Wiring
+
+Construct it and pass it to `World.setup`:
+
+```ts
+import { ScriptObjectSystem } from "@relu-interactives/spatial-ecs";
+
+world.setup({
+  systems: [new ScriptObjectSystem(myModuleLoader)],
+  isEditor: false,
+});
+```
+
+## API reference
+
+- Class: [`ScriptObjectComponent`](../../api/components/classes/ScriptObjectComponent.md)
+- Base class: [`ScriptObject`](../../api/classes/ScriptObject.md)
+- Source: [`core/systems/ScriptObjectSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ScriptObjectSystem.ts)