@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/systems/material-sync-system.md

@@ -0,0 +1,32 @@
+# MaterialSyncSystem
+
+Applies `MaterialComponent` authoring values to the THREE.js materials on an entity's mesh objects each frame, including material type switching, PBR properties, and texture slot management.
+
+## Overview
+
+`MaterialSyncSystem` runs every frame and is responsible for:
+
+- Creating or replacing THREE.js materials (`MeshStandardMaterial`, `MeshBasicMaterial`, `MeshPhongMaterial`, `MeshPhysicalMaterial`) when the `type` field changes.
+- Applying scalar and vector properties (color, roughness, metalness, opacity, emissive, etc.) from the `values` array to the matching material slots.
+- Loading textures from URLs and assigning them to the correct texture slot (`map`, `alphaMap`, `normalMap`, `roughnessMap`, `metalnessMap`, `aoMap`, `emissiveMap`, `bumpMap`, `displacementMap`, `lightMap`, `envMap`).
+- Disposing stale textures and materials when they are replaced to prevent GPU memory leaks.
+- Propagating material changes across multi-material meshes (i.e. objects with a `materials` array).
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`MaterialComponent`](../components/material) | Read (`type`, `values` array) |
+| [`Object3DRef`](../components/object3d-ref) | Read (the live THREE.js mesh) |
+
+## Behavior notes
+
+- **Per-slot values** — `MaterialComponent.values` is an array where each entry maps to one material slot. Entities with multiple materials (e.g. a model with distinct material groups) are handled by index.
+- **Texture loading** — textures are loaded via `THREE.TextureLoader` and cached internally. A changed URL triggers a fresh load and the old texture is disposed on replacement.
+- **Change detection** — property values are compared to a previous-frame snapshot before being written to the material, so inspector edits during runtime take effect on the next frame without redundant assignments.
+- **Material type switch** — when `MaterialComponent.type` changes (e.g. from `standard` to `physical`), the old material is disposed and a new one is created and assigned to the mesh.
+
+## API reference
+
+- Class: [`MaterialComponent`](../../api/components/classes/MaterialComponent.md)
+- Source: [`core/systems/MaterialSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/MaterialSyncSystem.ts)

package/dist/docs/guide/systems/mesh-geometry-system.md

@@ -0,0 +1,40 @@
+# MeshGeometrySystem
+
+Creates and updates the THREE.js `BufferGeometry` on primitive mesh entities based on their `MeshGeometryComponent` kind and parameter values.
+
+## Overview
+
+`MeshGeometrySystem` runs every frame and is responsible for:
+
+- Creating `THREE.BoxGeometry`, `THREE.SphereGeometry`, `THREE.PlaneGeometry`, `THREE.CylinderGeometry`, or `THREE.CapsuleGeometry` when an entity's `MeshGeometryComponent` is first seen or its kind changes.
+- Recreating the geometry when parameter values (dimensions, radius, height) change.
+- Assigning the geometry to the `THREE.Mesh` found via `Object3DRef`.
+- Disposing the previous geometry before replacing it to free GPU memory.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`MeshGeometryComponent`](../components/mesh-geometry) | Read (`kind`, `parameters`) |
+| [`Object3DRef`](../components/object3d-ref) | Read (the live THREE.js mesh) |
+
+## Supported geometry kinds
+
+| Kind | Parameters |
+| --- | --- |
+| `cube` | `width`, `height`, `depth` |
+| `plane` | `width`, `height` |
+| `sphere` | `radius` |
+| `cylinder` | `radiusTop`, `radiusBottom`, `height` |
+| `capsule` | `radius`, `height` |
+
+## Behavior notes
+
+- **Parameter sanitization** — all dimension values are clamped to a minimum (`0.01` for dimensions, `0.001` for radii). Non-finite values fall back to component defaults so an invalid inspector input never creates a degenerate geometry.
+- **Signature-based change detection** — per-entity signatures are compared each frame; the geometry is only rebuilt when the signature changes.
+- **Geometry disposal** — the previous `BufferGeometry` is disposed before the new one is assigned, preventing accumulated GPU memory usage when parameters change frequently.
+
+## API reference
+
+- Class: [`MeshGeometryComponent`](../../api/components/classes/MeshGeometryComponent.md)
+- Source: [`core/systems/MeshGeometrySystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/MeshGeometrySystem.ts)

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

@@ -0,0 +1,38 @@
+# ObjectManagementSystem
+
+Core entity lifecycle system. Manages the entity creation queue, the scene graph parent-child hierarchy, and the registries for entity and component factories.
+
+## Overview
+
+`ObjectManagementSystem` runs at the **start of each frame** (before all other systems) and is responsible for:
+
+- Flushing the entity creation queue — calling the registered `EntityFactory` for each queued `create` request and invoking the optional `onCreated` callback with the new entity ID.
+- Reconciling parent-child relationships in the THREE.js scene graph each frame by reading `ParentId` components and reparenting `Object3DRef` objects when the hierarchy changes.
+- Maintaining the entity factory registry (`register`) and component factory registry (`registerComponentFactory`) used by higher-level spawn helpers.
+
+## Entity factory registry
+
+Object kinds (e.g. `"model"`, `"cube"`, `"image"`) are registered with `register(kind, factory)`. When `world.create(kind, payload)` is called, the system enqueues the request and the factory is invoked on the next frame.
+
+## Component factory registry
+
+Component kinds (e.g. `"animation"`, `"physics"`) are registered with `registerComponentFactory(kind, factory)`. These are called by save/hydration flows to restore component state onto existing entities.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`ParentId`](../components/parent-id) | Read (desired parent entity ID) |
+| [`Object3DRef`](../components/object3d-ref) | Read + mutate (scene graph reparenting) |
+| [`TransformComponent`](../components/transform) | Read (applied to object after reparenting) |
+
+## Behavior notes
+
+- **Ordering** — this system must run first in the world's update loop. All other systems assume entities and parent relationships are already resolved when they run.
+- **Parent reconciliation** — if a `ParentId` refers to an entity that does not yet have an `Object3DRef` (e.g. the parent is still loading), reparenting is deferred to the next frame.
+- **Scene root** — entities without a `ParentId` (or with `ParentId.parentId === null`) are kept as direct children of the THREE.js scene root.
+- **Audio listener** — `getOrCreateAudioListener()` lazily creates a single `THREE.AudioListener` on the world camera and is used by audio object factories.
+
+## API reference
+
+- Source: [`core/systems/ObjectManagementSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ObjectManagementSystem.ts)

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

@@ -0,0 +1,26 @@
+# ObjectVisibilitySystem
+
+Synchronizes the `visibility` flag on `Object3DRef` to the `visible` property of the underlying THREE.js `Object3D` each frame.
+
+## Overview
+
+`ObjectVisibilitySystem` runs every frame and is responsible for:
+
+- Reading `Object3DRef.visibility` for every entity that has an `Object3DRef` component.
+- Setting `object.visible` to `Boolean(visibility)` whenever it differs from the current THREE.js value.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`Object3DRef`](../components/object3d-ref) | Read + mutate (`visibility` → `object.visible`) |
+
+## Behavior notes
+
+- **Change-only writes** — the system only assigns `object.visible` when the value differs from the current state, preventing unnecessary scene graph dirty flags.
+- **Hierarchy inheritance** — THREE.js propagates `visible = false` to all children automatically, so hiding a parent entity hides its entire subtree without additional logic here.
+
+## API reference
+
+- Class: [`Object3DRef`](../../api/components/classes/Object3DRef.md)
+- Source: [`core/systems/ObjectVisibilitySystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ObjectVisibilitySystem.ts)

package/dist/docs/guide/systems/physics-sync-system.md

@@ -0,0 +1,56 @@
+# PhysicsSyncSystem
+
+Initializes and manages the Rapier physics world, creates rigid bodies and colliders from `PhysicsComponent` authoring state, steps the simulation each frame, and writes the results back to entity transforms.
+
+## Overview
+
+`PhysicsSyncSystem` runs every frame and is responsible for:
+
+- Lazy-initializing the Rapier physics engine (loaded asynchronously via `@dimforge/rapier3d-compat`) the first time the system updates.
+- Creating a Rapier `RigidBody` and `Collider` for each entity that has a `PhysicsComponent` and `Object3DRef`.
+- Recreating bodies and colliders when their type, shape, or size changes (detected by per-entity signatures).
+- Stepping the Rapier world each frame with the clamped delta time.
+- Writing the simulation's output (body translation + rotation) back into the entity's `TransformComponent` and THREE.js `Object3D` for dynamic and kinematic bodies.
+- Applying per-axis translation/rotation locks from `PhysicsComponent.values.rigidbody`.
+- Handling `isSensor` colliders that fire collision events without generating a physical response.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`PhysicsComponent`](../components/physics) | Read + mutate (`rigidBody`, `collider` live refs; `values` for authoring state) |
+| [`Object3DRef`](../components/object3d-ref) | Read (initial world position for body placement) |
+| [`TransformComponent`](../components/transform) | Mutate (position, rotation written from simulation output) |
+| [`Environment`](../scene/environment) | Read (global gravity vector) |
+
+## Supported rigid body types
+
+| Type | Description |
+| --- | --- |
+| `dynamic` | Fully simulated; affected by gravity and forces. |
+| `fixed` | Immovable; acts as a static collider. |
+| `kinematicPosition` | Moved by setting position directly; not affected by physics. |
+| `kinematicVelocity` | Moved by setting velocity; interacts with dynamics. |
+
+## Supported collider shapes
+
+| Shape | Parameters |
+| --- | --- |
+| `cuboid` | `width`, `height`, `depth` |
+| `ball` | `radius` |
+| `capsule` | `radius`, `height` |
+| `cylinder` | `radius`, `height` |
+| `trimesh` | Auto-extracted from the entity's THREE.js geometry |
+
+## Behavior notes
+
+- **Async init** — the Rapier WASM module is loaded once on the first `update()` call. Physics simulation does not start until the module is ready; entities created before init are processed on the first frame after init completes.
+- **Trimesh** — `trimesh` colliders extract vertex/index data from the entity's `THREE.BufferGeometry`. The extracted data is cached per entity by a geometry signature.
+- **Sensor colliders** — setting `values.collider.isSensor = true` creates a Rapier sensor collider. Sensor contacts do not generate forces but can be used for overlap/trigger queries.
+- **Gravity** — the global gravity vector is read from the `Environment` component (`gravity` field, default `{ x: 0, y: -9.81, z: 0 }`) and applied to the Rapier world gravity setting each frame.
+- **Preview only** — the system is typically constructed with `{ isEditor: false }` for preview. In the editor the physics world step is skipped so objects don't fall during authoring.
+
+## API reference
+
+- Class: [`PhysicsComponent`](../../api/components/classes/PhysicsComponent.md)
+- Source: [`core/systems/PhysicsSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/PhysicsSyncSystem.ts)

package/dist/docs/guide/systems/postprocessing-sync-system.md

@@ -0,0 +1,43 @@
+# PostprocessingSyncSystem
+
+Builds and manages a THREE.js `EffectComposer` pipeline from the `Postprocessing` component's state, enabling full-screen visual effects in the rendered scene.
+
+## Overview
+
+`PostprocessingSyncSystem` runs every frame and is responsible for:
+
+- Building an `EffectComposer` with a `RenderPass` base and adding post-process passes derived from the enabled effects in `Postprocessing`.
+- Rebuilding the composer pipeline when the effect configuration changes (detected by signature).
+- Handing off the composer to `RenderSystem` via `scene.userData.ecsPostprocessingComposer` so the render pass uses it instead of the default `renderer.render()`.
+- Disposing old composers and passes when the configuration changes or the component is removed.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`Postprocessing`](../scene/postprocessing) | Read (`effects` array and each effect's enabled/parameter state) |
+
+## Supported effects
+
+| Effect | THREE.js pass |
+| --- | --- |
+| `bloom` | `UnrealBloomPass` |
+| `dotScreen` | `DotScreenPass` |
+| `glitch` | `GlitchPass` |
+| `film` | `FilmPass` |
+| `bokeh` | `BokehPass` |
+| `ssao` | `SSAOPass` |
+| `hueSaturation` | `ShaderPass` (HueSaturationShader) |
+| `sepia` | `ShaderPass` (SepiaShader) |
+| `vignette` | `ShaderPass` (VignetteShader) |
+
+## Behavior notes
+
+- **Composer handoff** — when the composer is active, `scene.userData.ecsPostprocessingComposerActive` is set to `true` and `scene.userData.ecsPostprocessingComposer` holds the composer reference. `RenderSystem` checks this flag and delegates rendering to the composer instead of calling `renderer.render()` directly.
+- **Signature-based rebuild** — the full effect configuration is serialized each frame. The composer is only rebuilt when the signature changes, so parameter tweaks during runtime (e.g. adjusting bloom strength from the inspector) are applied efficiently.
+- **Cleanup** — when the `Postprocessing` component is removed from the scene, or when the composer is rebuilt, all existing passes are disposed and the composer is torn down.
+
+## API reference
+
+- Class: [`Postprocessing`](../../api/components/classes/Postprocessing.md)
+- Source: [`core/systems/PostprocessingSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/PostprocessingSyncSystem.ts)

package/dist/docs/guide/systems/render-system.md

@@ -0,0 +1,22 @@
+# RenderSystem
+
+The final system in the update loop. Submits the frame to the WebGL renderer, delegating to an `EffectComposer` when postprocessing is active.
+
+## Overview
+
+`RenderSystem` runs **last** in the world update loop and is responsible for:
+
+- Calling `renderer.render(scene, camera)` to produce the final frame.
+- Detecting whether `PostprocessingSyncSystem` has placed an active `EffectComposer` on `scene.userData.ecsPostprocessingComposer`.
+- When a composer is active: resizing it to the current renderer element dimensions and calling `composer.render()` instead of the default render path.
+- Invoking an optional `afterRender` callback after every frame (used by editor overlays or custom render hooks).
+
+## Behavior notes
+
+- **Composer precedence** — the system checks `scene.userData.ecsPostprocessingComposerActive` each frame. If `true`, the `EffectComposer` path is used; otherwise the standard `renderer.render()` path is used. This coupling with `PostprocessingSyncSystem` means both systems must be present for postprocessing to work.
+- **Dynamic resize** — before calling `composer.render()`, the system reads `renderer.domElement.clientWidth/Height` (clamped to `≥ 1`) and updates the composer size to match. This ensures the effect pipeline stays correct after window resizes without an explicit resize event handler.
+- **Ordering** — `RenderSystem` must be registered last in `World.setup`. All scene mutations (transform sync, visibility, etc.) must have already run.
+
+## API reference
+
+- Source: [`core/systems/RenderSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/RenderSystem.ts)

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

@@ -0,0 +1,59 @@
+# ScriptBehaviourSystem
+
+Loads user-authored Behaviour scripts via dynamic `import()`, instantiates their classes, and drives the full Behaviour lifecycle (`init`, `onUpdate`, `onDestroy`) each frame.
+
+## Overview
+
+`ScriptBehaviourSystem` runs every frame and is responsible for:
+
+- Discovering entities with a `ScriptComponent` and iterating their `entries` array.
+- Dynamically importing each script's compiled URL the first time it is seen (or when the URL changes).
+- Resolving the exported `Behaviour` subclass by name (or falling back to the default export).
+- Instantiating the class and calling `init()` once.
+- Calling `onUpdate(deltaTime)` on every active script instance each frame.
+- Detecting stale instances (removed entries, changed URLs, destroyed entities) and calling `onDestroy()` before discarding them.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`ScriptComponent`](../components/script) | Read (`entries`, `defaultData`, `runtimeData`) |
+
+## Behaviour resolution
+
+The system resolves the `Behaviour` constructor from the imported module using:
+
+1. Named export matching `ScriptEntry.className`.
+2. `default` export as a fallback.
+3. A `__reluBehaviourClass` static marker check to handle cases where esbuild bundles a second copy of `@relu-interactives/spatial-ecs` into the script blob (breaking the `instanceof` identity check).
+
+If no valid `Behaviour` subclass is found the entry is skipped and an error is written to the console.
+
+## Behavior notes
+
+- **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.
+
+## API reference
+
+- Class: [`ScriptComponent`](../../api/components/classes/ScriptComponent.md)
+- Base class: [`Behaviour`](../../api/Behaviour/classes/Behaviour.md)
+- Source: [`core/systems/ScriptBehaviourSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ScriptBehaviourSystem.ts)

package/dist/docs/guide/systems/transform-sync-system.md

@@ -0,0 +1,29 @@
+# TransformSyncSystem
+
+Applies `TransformComponent` position, rotation, and scale values to the linked THREE.js `Object3D` every frame.
+
+## Overview
+
+`TransformSyncSystem` runs every frame (just before `RenderSystem`) and is responsible for:
+
+- Querying all entities that have both a `TransformComponent` and an `Object3DRef`.
+- Calling `object.position.set(...)`, `object.rotation.set(...)`, and `object.scale.set(...)` from the component values.
+- Calling `object.updateMatrixWorld(true)` after applying the transform to propagate changes to child objects.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`TransformComponent`](../components/transform) | Read (`position`, `rotation`, `scale`) |
+| [`Object3DRef`](../components/object3d-ref) | Read (the live THREE.js object) |
+
+## Behavior notes
+
+- **Every frame** — transforms are applied unconditionally every frame. Scripts and inspector edits can mutate `TransformComponent` at any point and the result will be visible on the next render.
+- **World matrix propagation** — `updateMatrixWorld(true)` is called with `force = true` so that child objects in the hierarchy receive updated world matrices even if the parent did not mark itself dirty.
+- **Ordering** — `TransformSyncSystem` runs after all custom systems and before `RenderSystem`. This guarantees that script-driven position changes (from `onUpdate`) are reflected in the same frame they are written.
+
+## API reference
+
+- Class: [`TransformComponent`](../../api/components/classes/TransformComponent.md)
+- Source: [`core/systems/TransformSyncSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/TransformSyncSystem.ts)

package/dist/docs/guide/systems/video-system.md

@@ -0,0 +1,30 @@
+# VideoSystem
+
+Reconciles `VideoComponent` state with the underlying HTML `<video>` element and THREE.js mesh/material each frame. Only active in **preview** mode — editor viewports are unaffected.
+
+## Overview
+
+`VideoSystem` runs every frame in preview and is responsible for:
+
+- Driving `play()`, `pause()`, and stop (pause + seek to 0) on the HTML `<video>` element based on the intent flags set by `VideoComponent.play()`, `.pause()`, and `.stop()`.
+- Detecting when a non-looping video ends naturally and resetting the component flags.
+- Syncing `loop`, `volume`, `width`, `height`, `positional`, `refDistance`, `distanceModel`, and `rolloffFactor` to the video element and THREE.js mesh material.
+- Updating the green-screen chroma key shader uniforms (`backgroundColor`, `similarity`, `smoothness`, `spill`) live when they change.
+
+## Queried components
+
+| Component | Access |
+| --- | --- |
+| [`VideoComponent`](../components/video) | Read + mutate (`isPlaying`, `isPaused` flags; option properties) |
+
+## Behavior notes
+
+- **Editor skip** — when constructed with `{ isEditor: true }` the `update` method returns immediately so no video state is applied in the editor.
+- **Natural end detection** — the system compares `HTMLVideoElement.paused` and `ended` state between frames. If the video ended on its own while the component still believed it was playing, the component flags are reset.
+- **Change detection** — option sync uses a per-entity snapshot from the previous frame. Chroma key shader uniforms and other options are only written when they change, avoiding redundant material updates every frame.
+- **Positional audio** — videos with `options.positional = true` use a `THREE.PositionalAudio` node attached to the mesh; non-positional videos use a standard `THREE.Audio` node. The system respects `refDistance`, `distanceModel`, and `rolloffFactor` for spatial audio falloff.
+
+## API reference
+
+- Class: [`VideoComponent`](../../api/components/classes/VideoComponent.md)
+- Source: [`core/systems/VideoSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/VideoSystem.ts)