@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/components/material.md

@@ -0,0 +1,161 @@
+# Material
+
+Material catalog for an entity. Tracks the live three.js materials (`materials`, `material`) plus serialized authoring state (`values[]`) mirrored from the inspector. Supports `standard`, `basic`, `phong`, and `physical` PBR types with optional texture map slots.  Use `setMaterials`, `updateValue`, `setMaterialType`, `setTextureFiltering`, and `setUseMipmaps` to mutate state — these keep `values[]` and the live three.js materials in sync. Texture URLs use the `localasset://` protocol inside the editor.
+
+> **Managed by:** [`MaterialSyncSystem`](../systems/material-sync-system)
+
+## Editor inspector
+
+![Material inspector](/images/components/Material.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `materials` | `THREE.Material[]` | Live three.js materials currently bound to the entity's mesh (one per submesh). |
+| `material` | `THREE.Material \| null` | Convenience reference to `materials[0]`. `null` when no material is assigned. |
+| `values` | `MaterialValueState[]` | Serialized authoring state (one entry per material in `materials`). Saved with the project. |
+
+## API reference
+
+- Class: [`MaterialComponent`](../../api/components/classes/MaterialComponent.md)
+- Source: [`core/components/Material.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Material.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const mat = this.getComponent(MaterialComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Wall");
+if (other) {
+  const mat = this.world.getComponent(other.entityId, MaterialComponent);
+}
+```
+:::
+
+### Fade opacity with a sine wave
+
+Animate material transparency to create a pulsing ghost or reveal effect. Use `updateValue` so the state persists in the ECS snapshot — `MaterialSyncSystem` applies it to the live material each frame.
+
+```typescript
+import { Behaviour, MaterialComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class MaterialFade extends Behaviour {
+  data = {
+    speed: 1 as FloatInput,
+  };
+
+  private elapsed = 0;
+
+  protected onUpdate() {
+    this.elapsed += this.deltaTime;
+    const mat = this.getComponent(MaterialComponent);
+    if (!mat) return;
+
+    const opacity = (Math.sin(this.elapsed * this.data.speed) + 1) * 0.5;
+    mat.updateValue(0, 'transparent', true);
+    mat.updateValue(0, 'opacity', opacity);
+  }
+}
+```
+
+::: warning Transient vs persistent opacity
+`mat.updateValue(0, 'opacity', value)` keeps `values[]` in sync with the live material — changes survive a project reload.
+
+Mutating `mat.material?.opacity` directly can work for transient visual-only effects, but `MaterialSyncSystem` may overwrite it when other material properties change. Prefer `updateValue` for any state you want to persist.
+:::
+
+### Change material color at runtime
+
+Let the inspector drive the diffuse color live without restarting the scene.
+
+```typescript
+import { Behaviour, MaterialComponent } from "@relu-interactives/spatial-ecs";
+import type { ColorInput } from "@relu-interactives/spatial-ecs";
+
+export default class MaterialColorDriver extends Behaviour {
+  data = {
+    color: "#ff0000" as ColorInput,
+  };
+
+  private _prev: string | null = null;
+
+  protected onUpdate() {
+    // Guard — only call updateValue when the color actually changes
+    if (this.data.color === this._prev) return;
+    this._prev = this.data.color;
+
+    const mat = this.getComponent(MaterialComponent);
+    if (!mat) return;
+    mat.updateValue(0, 'color', this.data.color);
+  }
+}
+```
+
+::: tip Material sync
+`updateValue(index, key, value)` writes to `values[]` (persisted with the project) and lets `MaterialSyncSystem` apply the change to the live THREE.js material. Mutating `material.color` or other THREE.js properties directly is not saved with the project.
+:::
+
+### Via `ComponentInput` in the inspector
+
+You can also pick this component from the inspector using a `ComponentInput` field. Assign any entity in the inspector and the field resolves to the live `MaterialComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  MaterialComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetMaterial: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const mat = this.data.targetMaterial.value as MaterialComponent | null;
+    if (!mat) return;
+    // Use the live component instance.
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  MaterialComponent,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const mat = this.world.getComponent(
+      entity.entityId,
+      MaterialComponent,
+    ) as MaterialComponent | null;
+    if (!mat) return;
+    // Use the component on the picked entity.
+  }
+}
+```

package/dist/docs/guide/components/mesh-geometry.md

@@ -0,0 +1,153 @@
+# Mesh Geometry
+
+Editable geometry parameters for primitive meshes (cube, sphere, plane, capsule, cylinder) and the placeholder for `model` entities. Holds the authoring values plus shadow casting/receiving flags. The mesh-geometry system rebuilds the underlying `BufferGeometry` when parameters change.
+
+> **Managed by:** [`MeshGeometrySystem`](../systems/mesh-geometry-system)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `kind` | `EditableMeshObjectKind` | Primitive kind (`cube`, `sphere`, `plane`, `capsule`, `cylinder`) or `model` for loaded assets. |
+| `geometryType` | `string` | Three.js geometry class name (e.g. `"BoxGeometry"`, `"SphereGeometry"`). Derived from `kind`. |
+| `parameters` | `MeshGeometryParameters` | Editable parameters whose shape depends on `kind`. The mesh-geometry system rebuilds geometry when these change. |
+| `object` | `THREE.Object3D \| null` | Live three.js object whose geometry is being managed. `null` until the object is built. |
+| `modelName` | `string` | Human-readable model name shown in the inspector for `model` entities; empty for primitives. |
+| `castShadow` | `boolean` | Whether the mesh casts shadows in the renderer. |
+| `receiveShadow` | `boolean` | Whether the mesh receives shadows in the renderer. |
+
+## API reference
+
+- Class: [`MeshGeometryComponent`](../../api/components/classes/MeshGeometryComponent.md)
+- Source: [`core/components/MeshGeometry.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/MeshGeometry.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const geo = this.getComponent(MeshGeometryComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Floor");
+if (other) {
+  const geo = this.world.getComponent(other.entityId, MeshGeometryComponent);
+}
+```
+:::
+
+### Toggle shadow casting at runtime
+
+Let the inspector or game logic control whether the mesh casts and receives shadows.
+
+```typescript
+import { Behaviour, MeshGeometryComponent } from "@relu-interactives/spatial-ecs";
+import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class ShadowDriver extends Behaviour {
+  data = {
+    castShadow: true as BooleanInput,
+    receiveShadow: true as BooleanInput,
+  };
+
+  protected onUpdate() {
+    const geo = this.getComponent(MeshGeometryComponent);
+    if (!geo) return;
+    geo.castShadow = this.data.castShadow;
+    geo.receiveShadow = this.data.receiveShadow;
+  }
+}
+```
+
+### Animate sphere radius
+
+Pulse the radius of a sphere primitive by writing to its geometry `parameters` each frame. The mesh-geometry system rebuilds the `BufferGeometry` when parameters change.
+
+```typescript
+import { Behaviour, MeshGeometryComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class SphereGrow extends Behaviour {
+  data = {
+    speed: 1 as FloatInput,
+    minRadius: 0.3 as FloatInput,
+    maxRadius: 1 as FloatInput,
+  };
+
+  private elapsed = 0;
+
+  protected onUpdate() {
+    this.elapsed += this.deltaTime;
+    const geo = this.getComponent(MeshGeometryComponent);
+    if (!geo || geo.kind !== "sphere") return;
+
+    const t = (Math.sin(this.elapsed * this.data.speed) + 1) * 0.5;
+    const radius = this.data.minRadius + t * (this.data.maxRadius - this.data.minRadius);
+    (geo.parameters as { radius: number }).radius = radius;
+  }
+}
+```
+
+### Via `ComponentInput` in the inspector
+
+You can also pick this component from the inspector using a `ComponentInput` field. Assign any entity in the inspector and the field resolves to the live `MeshGeometryComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  MeshGeometryComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetGeometry: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const geo = this.data.targetGeometry.value as MeshGeometryComponent | null;
+    if (!geo) return;
+    // Use the live component instance.
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  MeshGeometryComponent,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const geo = this.world.getComponent(
+      entity.entityId,
+      MeshGeometryComponent,
+    ) as MeshGeometryComponent | null;
+    if (!geo) return;
+    // Use the component on the picked entity.
+  }
+}
+```
+
+::: tip Geometry rebuild cost
+The mesh-geometry system only rebuilds geometry when parameters actually change. Avoid writing the same value every frame unless the value is genuinely different, to prevent unnecessary geometry allocations.
+:::

package/dist/docs/guide/components/mesh.md

@@ -0,0 +1,151 @@
+# Mesh
+
+Holds the live three.js `Object3D` for an entity that renders as a primitive mesh (cube, sphere, plane, capsule, cylinder). For loaded GLTF/GLB models see `ModelComponent`; for the editable geometry parameters see `MeshGeometryComponent`.
+
+## Editor inspector
+
+![Mesh inspector](/images/components/Mesh.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `mesh` | `THREE.Object3D` | Underlying three.js mesh placed in the scene graph. |
+
+## API reference
+
+- Class: [`MeshComponent`](../../api/components/classes/MeshComponent.md)
+- Source: [`core/components/Mesh.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Mesh.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const mesh = this.getComponent(MeshComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Terrain");
+if (other) {
+  const mesh = this.world.getComponent(other.entityId, MeshComponent);
+}
+```
+:::
+
+### Toggle shadow casting on all sub-meshes
+
+Walk the mesh hierarchy and enable or disable shadow casting based on a boolean inspector field.
+
+```typescript
+import { Behaviour, MeshComponent } from "@relu-interactives/spatial-ecs";
+import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class ShadowToggle extends Behaviour {
+  data = {
+    castShadow: true as BooleanInput,
+    receiveShadow: true as BooleanInput,
+  };
+
+  protected onUpdate() {
+    const mesh = this.getComponent(MeshComponent);
+    if (!mesh?.mesh) return;
+
+    mesh.mesh.traverse((child: any) => {
+      if (child.isMesh) {
+        child.castShadow = this.data.castShadow;
+        child.receiveShadow = this.data.receiveShadow;
+      }
+    });
+  }
+}
+```
+
+### Change vertex color or material on the raw mesh
+
+Access the underlying `THREE.Object3D` directly for low-level material mutations that are not exposed through `MaterialComponent`.
+
+```typescript
+import { Behaviour, MeshComponent } from "@relu-interactives/spatial-ecs";
+import type { ColorInput } from "@relu-interactives/spatial-ecs";
+
+export default class MeshColorDriver extends Behaviour {
+  data = {
+    color: "#ffffff" as ColorInput,
+  };
+
+  protected onUpdate() {
+    const mesh = this.getComponent(MeshComponent);
+    if (!mesh?.mesh) return;
+
+    mesh.mesh.traverse((child: any) => {
+      if (child.isMesh && child.material?.color) {
+        child.material.color.set(this.data.color);
+      }
+    });
+  }
+}
+```
+
+::: tip Prefer MaterialComponent for authored changes
+For changes that should persist across save/reload, prefer `MaterialComponent.updateValue()` which keeps the serialised `values[]` in sync. Use `MeshComponent.mesh` for frame-by-frame visual effects only.
+:::
+
+### Via `ComponentInput` in the inspector
+
+You can also pick this component from the inspector using a `ComponentInput` field. Assign any entity in the inspector and the field resolves to the live `MeshComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  MeshComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetMesh: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const mesh = this.data.targetMesh.value as MeshComponent | null;
+    if (!mesh) return;
+    // Use the live component instance.
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  MeshComponent,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const mesh = this.world.getComponent(
+      entity.entityId,
+      MeshComponent,
+    ) as MeshComponent | null;
+    if (!mesh) return;
+    // Use the component on the picked entity.
+  }
+}
+```

package/dist/docs/guide/components/model.md

@@ -0,0 +1,96 @@
+# Model
+
+References a GLTF/GLB asset loaded from `path`. The model loading system resolves the asset asynchronously and populates `ModelComponent.object` once available; loading is deferred-tolerant so the entity exists before the model finishes loading.
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Source URL or `localasset://` path of the GLTF/GLB asset. |
+| `object` | `THREE.Object3D \| null` | Loaded model object, populated asynchronously by the model loader. `null` until loaded. |
+
+## API reference
+
+- Class: [`ModelComponent`](../../api/components/classes/ModelComponent.md)
+- Source: [`core/components/Model.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Model.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const model = this.getComponent(ModelComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Robot");
+if (other) {
+  const model = this.world.getComponent(other.entityId, ModelComponent);
+}
+```
+:::
+
+### Fade the model in after it loads
+
+Wait for the async model load to complete, then animate opacity to 1 over one second.
+
+```typescript
+import { Behaviour, ModelComponent } from "@relu-interactives/spatial-ecs";
+
+export default class ModelFadeIn extends Behaviour {
+  private fadeProgress = 0;
+  private started = false;
+
+  protected onUpdate() {
+    const model = this.getComponent(ModelComponent);
+    if (!model?.object) return; // wait for async load to complete
+
+    if (!this.started) {
+      this.started = true;
+      // Initialise all sub-mesh materials to transparent before fading in
+      model.object.traverse((child: any) => {
+        if (child.isMesh && child.material) {
+          child.material.transparent = true;
+          child.material.opacity = 0;
+        }
+      });
+    }
+
+    this.fadeProgress = Math.min(1, this.fadeProgress + this.deltaTime);
+    model.object.traverse((child: any) => {
+      if (child.isMesh && child.material) {
+        child.material.opacity = this.fadeProgress;
+      }
+    });
+  }
+}
+```
+
+### Toggle model visibility
+
+Show or hide the loaded model at runtime using the `Object3DRef` visibility flag.
+
+```typescript
+import { Behaviour, ModelComponent, Object3DRef } from "@relu-interactives/spatial-ecs";
+import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class ModelVisibility extends Behaviour {
+  data = {
+    visible: true as BooleanInput,
+  };
+
+  protected onUpdate() {
+    const model = this.getComponent(ModelComponent);
+    if (!model?.object) return; // still loading
+
+    const ref = this.getComponent(Object3DRef);
+    if (ref) ref.visibility = this.data.visible;
+  }
+}
+```
+
+::: tip Async loading
+Always guard with `model?.object` before traversing or mutating sub-meshes. The `object` property is `null` until the GLTF/GLB asset finishes loading.
+:::
+

package/dist/docs/guide/components/name.md

@@ -0,0 +1,121 @@
+# Name
+
+Human-readable name for an entity. Shown in the editor hierarchy panel and preserved across save/reload.
+
+## Editor inspector
+
+![Name inspector](/images/components/Name.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Display name for the entity. Shown in the editor hierarchy. |
+
+## API reference
+
+- Class: [`Name`](../../api/components/classes/Name.md)
+- Source: [`core/components/Name.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Name.ts)
+
+## Scripting examples
+
+::: tip Component access patterns
+Use `this.getComponent(X)` to access a component on the **entity this script is attached to**. Use `this.world.getEntityByName` to find another entity by name, then `this.world.getComponent` to read its component:
+
+```typescript
+// Component on the entity this script is on
+const name = this.getComponent(Name);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Player");
+if (other) {
+  const name = this.world.getComponent(other.entityId, Name);
+}
+```
+:::
+
+### Drive the display name from the inspector
+
+Rename the entity at runtime from an inspector string field. Useful for dynamic labels or debug output.
+
+```typescript
+import { Behaviour, Name } from "@relu-interactives/spatial-ecs";
+import type { StringInput } from "@relu-interactives/spatial-ecs";
+
+export default class EntityRenamer extends Behaviour {
+  data = {
+    displayName: "My Entity" as StringInput,
+  };
+
+  protected onUpdate() {
+    const name = this.getComponent(Name);
+    if (name && name.value !== this.data.displayName) {
+      name.value = this.data.displayName;
+    }
+  }
+}
+```
+
+### Find another entity by name
+
+Query all `Name` components to locate a sibling entity and read its position.
+
+```typescript
+import { Behaviour, Name, TransformComponent } from "@relu-interactives/spatial-ecs";
+import type { StringInput } from "@relu-interactives/spatial-ecs";
+
+export default class LookAtTarget extends Behaviour {
+  data = {
+    targetName: "Target" as StringInput,
+  };
+
+  protected onUpdate() {
+    let targetTransform: TransformComponent | null = null;
+
+    for (const [id, nameComp] of this.world.query([Name])) {
+      if (nameComp.value === this.data.targetName) {
+        targetTransform = this.world.getComponent(id, TransformComponent);
+        break;
+      }
+    }
+
+    if (!targetTransform) return;
+
+    // Rotate to face the target on the Y axis
+    const dx = targetTransform.position.x - this.transform.position.x;
+    const dz = targetTransform.position.z - this.transform.position.z;
+    this.transform.rotation.y = Math.atan2(dx, dz);
+  }
+}
+```
+
+### Via `EntityInput` in the inspector
+
+Alternatively, pick an entity from the inspector using an `EntityInput` field and then read the component off that entity via `world.getComponent`:
+
+```typescript
+import {
+  Behaviour,
+  Name,
+  type EntityInput,
+  type WorldEntityView,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntity: { type: "entity", value: null } as unknown as EntityInput,
+  };
+
+  protected onUpdate() {
+    const entity = this.data.targetEntity.value as WorldEntityView | null;
+    if (!entity) return;
+
+    const nameComp = this.world.getComponent(
+      entity.entityId,
+      Name,
+    ) as Name | null;
+    if (!nameComp) return;
+    // Use the component on the picked entity.
+  }
+}
+```