@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/components/object3d-ref.md

@@ -0,0 +1,115 @@
+# Object3D Reference
+
+Wraps the live `THREE.Object3D` for an entity. Almost every entity that renders to the scene carries an `Object3DRef` so transform sync, selection, and parenting systems can manipulate the underlying object.  The `object` reference may be replaced when assets finish loading. Read it fresh inside system/script hooks rather than caching it across frames.
+
+> **Managed by:** [`ObjectManagementSystem`](../systems/object-management-system) (hierarchy), [`ObjectVisibilitySystem`](../systems/object-visibility-system) (visibility)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `object` | `THREE.Object3D` | Live three.js object placed in the scene graph. May be replaced when assets finish loading. |
+| `visibility` | `boolean` | Whether the object is currently visible. Mirrors `object.visible` and is preserved across reloads. |
+
+## API reference
+
+- Class: [`Object3DRef`](../../api/components/classes/Object3DRef.md)
+- Source: [`core/components/Object3DRef.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Object3DRef.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 ref = this.getComponent(Object3DRef);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Obstacle");
+if (other) {
+  const ref = this.world.getComponent(other.entityId, Object3DRef);
+}
+```
+:::
+
+### Toggle visibility from the inspector
+
+Expose a boolean that shows or hides the entity's scene object at runtime.
+
+```typescript
+import { Behaviour, Object3DRef } from "@relu-interactives/spatial-ecs";
+import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class VisibilityDriver extends Behaviour {
+  data = {
+    visible: true as BooleanInput,
+  };
+
+  protected onUpdate() {
+    const ref = this.getComponent(Object3DRef);
+    if (ref) ref.visibility = this.data.visible;
+  }
+}
+```
+
+### Flash the object on and off
+
+Alternate visibility every half-second, useful for damage flashes or blinking pickups.
+
+```typescript
+import { Behaviour, Object3DRef } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class ObjectFlash extends Behaviour {
+  data = {
+    flashRate: 2 as FloatInput, // flashes per second
+  };
+
+  private elapsed = 0;
+
+  protected onUpdate() {
+    this.elapsed += this.deltaTime;
+    const ref = this.getComponent(Object3DRef);
+    if (!ref) return;
+
+    // Alternate visibility based on sine wave sign
+    ref.visibility = Math.sin(this.elapsed * this.data.flashRate * Math.PI) >= 0;
+  }
+}
+```
+
+### 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,
+  Object3DRef,
+  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 ref = this.world.getComponent(
+      entity.entityId,
+      Object3DRef,
+    ) as Object3DRef | null;
+    if (!ref) return;
+    // Use the component on the picked entity.
+  }
+}
+```
+
+::: tip Do not cache the object reference
+The underlying `object` on `Object3DRef` may be replaced when assets finish loading. Always read `ref.object` fresh inside system/script hooks rather than caching it in a class field.
+:::

package/dist/docs/guide/components/parent-id.md

@@ -0,0 +1,108 @@
+# Parent
+
+Records the parent entity id for hierarchical scene graphs. `null` means the entity is at the world root. The `ObjectManagementSystem` reconciles scene-graph parenting from this component each frame.
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `EntityId \| null` | Parent entity id, or `null` for root-level entities. |
+
+## API reference
+
+- Class: [`ParentId`](../../api/components/classes/ParentId.md)
+- Source: [`core/components/ParentId.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/ParentId.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 parentId = this.getComponent(ParentId);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Prop");
+if (other) {
+  const parentId = this.world.getComponent(other.entityId, ParentId);
+}
+```
+
+:::
+
+### Detach an entity to the world root on key press
+
+Set `ParentId.value` to `null` to reparent the entity to the scene root. The `ObjectManagementSystem` reconciles the actual scene-graph hierarchy every frame.
+
+```typescript
+import { Behaviour, ParentId, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export default class DetachOnKey extends Behaviour {
+  protected onUpdate() {
+    if (this.world.getKeyDown(KeyboardKeys.D)) {
+      const parent = this.getComponent(ParentId);
+      if (parent) parent.value = null;
+    }
+  }
+}
+```
+
+### Reparent to a specific entity
+
+Assign a new parent entity ID to move the entity (and its children) under a different part of the hierarchy at runtime.
+
+```typescript
+import { Behaviour, ParentId, Name, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { StringInput } from "@relu-interactives/spatial-ecs";
+
+export default class Reparenter extends Behaviour {
+  data = {
+    newParentName: "Holder" as StringInput,
+  };
+
+  protected onUpdate() {
+    if (!this.world.getKeyDown(KeyboardKeys.R)) return;
+
+ // Find the target parent entity by name
+    const parentEntity = this.world.getEntityByName(this.data.newParentName);
+    const parent = this.getComponent(ParentId);
+    if (parent) parent.value = id;
+  }
+}
+```
+
+### 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,
+  ParentId,
+  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 parentId = this.world.getComponent(
+      entity.entityId,
+      ParentId,
+    ) as ParentId | null;
+    if (!parentId) return;
+    // Use the component on the picked entity.
+  }
+}
+```
+
+::: tip ObjectManagementSystem
+Do not call `THREE.Object3D.add` / `remove` directly to reparent. Write to `ParentId.value` instead — the `ObjectManagementSystem` reads this every frame and reconciles the scene graph. This keeps the ECS hierarchy state consistent with the three.js scene graph.
+:::

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

@@ -0,0 +1,163 @@
+# Physics
+
+Combined rigid body and collider component backed by Rapier. `values.rigidbody.type` is one of `dynamic`, `fixed`, `kinematicPosition`, or `kinematicVelocity`. Per-axis translation/rotation locks constrain motion (e.g. lock Y rotation for top-down characters). Supported collider shapes: `cuboid`, `ball`, `capsule`, `cylinder`, `trimesh`. Set `values.collider.isSensor` to receive collision events without producing a physical response.
+
+> **Managed by:** [`PhysicsSyncSystem`](../systems/physics-sync-system)
+
+## Editor inspector
+
+![Physics inspector](/images/components/Physics.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `values` | `PhysicsState` | Authoring state containing `rigidbody` and `collider` sub-states. Saved with the project. |
+| `values.rigidbody` | `RigidbodyState` | Rigid body authoring state (type, gravity scale, locks, etc.). |
+| `values.collider` | `ColliderState` | Collider authoring state (shape, size, sensor flag, etc.). |
+| `rigidBody` | `RapierRigidBody \| null` | Live Rapier rigid body. Recreated when the project loads; `null` until physics is initialized. |
+| `collider` | `RapierCollider \| null` | Live Rapier collider. Recreated when the project loads; `null` until physics is initialized. |
+
+## API reference
+
+- Class: [`PhysicsComponent`](../../api/components/classes/PhysicsComponent.md)
+- Source: [`core/components/Physics.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Physics.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 physics = this.getComponent(PhysicsComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Crate");
+if (other) {
+  const physics = this.world.getComponent(other.entityId, PhysicsComponent);
+}
+```
+:::
+
+### Apply a jump impulse
+
+Apply a one-shot upward impulse to a dynamic rigid body when the player presses Space.
+
+```typescript
+import { Behaviour, PhysicsComponent, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class Jumper extends Behaviour {
+  data = {
+    jumpForce: 5 as FloatInput,
+  };
+
+  protected onUpdate() {
+    const physics = this.getComponent(PhysicsComponent);
+    if (!physics?.rigidBody) return;
+
+    if (this.world.getKeyDown(KeyboardKeys.Space)) {
+      physics.rigidBody.applyImpulse({ x: 0, y: this.data.jumpForce, z: 0 }, true);
+    }
+  }
+}
+```
+
+### Move a kinematic body with arrow keys
+
+Displace a `kinematicPosition` body each frame using the Rapier `setNextKinematicTranslation` API.
+
+```typescript
+import { Behaviour, PhysicsComponent, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class KinematicMover extends Behaviour {
+  data = {
+    speed: 3 as FloatInput,
+  };
+
+  protected onUpdate() {
+    const physics = this.getComponent(PhysicsComponent);
+    if (!physics?.rigidBody) return;
+
+    const pos = physics.rigidBody.translation();
+    let dx = 0;
+    let dz = 0;
+
+    if (this.world.getKey(KeyboardKeys.ArrowLeft))  dx -= this.data.speed * this.deltaTime;
+    if (this.world.getKey(KeyboardKeys.ArrowRight)) dx += this.data.speed * this.deltaTime;
+    if (this.world.getKey(KeyboardKeys.ArrowUp))    dz -= this.data.speed * this.deltaTime;
+    if (this.world.getKey(KeyboardKeys.ArrowDown))  dz += this.data.speed * this.deltaTime;
+
+    physics.rigidBody.setNextKinematicTranslation({
+      x: pos.x + dx,
+      y: pos.y,
+      z: pos.z + dz,
+    });
+  }
+}
+```
+
+### 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 `PhysicsComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  PhysicsComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetPhysics: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const physics = this.data.targetPhysics.value as PhysicsComponent | null;
+    if (!physics) 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,
+  PhysicsComponent,
+  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 physics = this.world.getComponent(
+      entity.entityId,
+      PhysicsComponent,
+    ) as PhysicsComponent | null;
+    if (!physics) return;
+    // Use the component on the picked entity.
+  }
+}
+```
+
+
+::: tip Rigid body type
+Set `values.rigidbody.type` to `"kinematicPosition"` in the inspector for the second example. Applying impulses requires a `"dynamic"` rigid body.
+:::

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

@@ -0,0 +1,142 @@
+# Script
+
+Component holding the list of `scripts` attached to an entity. Loaded from the saved project; the runtime-side fields (`scriptInstance`, `scriptInstances`) are non-enumerable so they never leak into save data or undo history.  Authored scripts subclass `Behaviour`.
+
+> **Managed by:** [`ScriptBehaviourSystem`](../systems/script-behaviour-system)
+
+## Editor inspector
+
+![Script inspector](/images/components/Script.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `entries` | `ScriptEntry[]` | Authored script entries attached to the entity. Each entry references a class by name plus its inspector field overrides. Saved with the project. |
+| `scriptInstance` | `unknown \| null` | First live behaviour instance after compile/load. Non-enumerable, so it does not appear in save data. `null` when no script is loaded. |
+| `scriptInstances` | `Map<number, unknown>` | Map of `entityId` to its compiled behaviour instance (one entry per script bound to the entity). Non-enumerable, so it does not appear in save data. |
+
+## API reference
+
+- Class: [`ScriptComponent`](../../api/components/classes/ScriptComponent.md)
+- Source: [`core/components/ScriptComponent.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/ScriptComponent.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 scriptComp = this.getComponent(ScriptComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Manager");
+if (other) {
+  const scriptComp = this.world.getComponent(other.entityId, ScriptComponent);
+}
+```
+:::
+
+### Call a method on another script attached to the same entity
+
+`ScriptComponent.scriptInstances` maps entity IDs to their compiled behaviour instances. You can cast an instance to a known shape and call public methods on it, enabling script-to-script communication.
+
+```typescript
+import { Behaviour, ScriptComponent } from "@relu-interactives/spatial-ecs";
+
+// Assumes another script on this entity exposes a `reset()` method.
+export default class ScriptBridge extends Behaviour {
+  protected init() {
+    const scriptComp = this.getComponent(ScriptComponent);
+    if (!scriptComp) return;
+
+    // scriptInstance is the first compiled behaviour on this entity
+    const other = scriptComp.scriptInstance as { reset?(): void } | null;
+    if (other?.reset) {
+      other.reset();
+    }
+  }
+}
+```
+
+### Inspect script entries
+
+Read the authored `entries` array to find which scripts are attached and inspect their saved field overrides.
+
+```typescript
+import { Behaviour, ScriptComponent } from "@relu-interactives/spatial-ecs";
+
+export default class ScriptInspector extends Behaviour {
+  protected init() {
+    const scriptComp = this.getComponent(ScriptComponent);
+    if (!scriptComp) return;
+
+    for (const entry of scriptComp.entries) {
+      console.log(`Script: ${entry.className}`, entry.data);
+    }
+  }
+}
+```
+
+### 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 `ScriptComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  ScriptComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetScript: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const scriptComp = this.data.targetScript.value as ScriptComponent | null;
+    if (!scriptComp) 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,
+  ScriptComponent,
+  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 scriptComp = this.world.getComponent(
+      entity.entityId,
+      ScriptComponent,
+    ) as ScriptComponent | null;
+    if (!scriptComp) return;
+    // Use the component on the picked entity.
+  }
+}
+```
+
+::: tip Runtime vs. authored data
+`entries` is the persisted array of script definitions (class name + inspector overrides). `scriptInstance` and `scriptInstances` are non-enumerable runtime references that are never saved to snapshots. Do not store references to `scriptInstance` across frames — re-read from `ScriptComponent` each time if needed.
+:::

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

@@ -0,0 +1,155 @@
+# Sprite
+
+Camera-facing 2D sprite. Unlike `ImageComponent`, sprites use `THREE.Sprite` and always render as billboards.
+
+## Editor inspector
+
+![Sprite inspector](/images/components/Sprite.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Source URL or `localasset://` path of the sprite image. |
+| `width` | `number` | Width of the sprite in world units. |
+| `height` | `number` | Height of the sprite in world units. |
+| `texture` | `THREE.Texture \| null` | Loaded texture, populated asynchronously. `null` until loaded. |
+| `object` | `THREE.Sprite \| null` | Live `THREE.Sprite` placed in the scene. `null` until built. |
+
+## API reference
+
+- Class: [`SpriteComponent`](../../api/components/classes/SpriteComponent.md)
+- Source: [`core/components/Sprite.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Sprite.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 sprite = this.getComponent(SpriteComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Coin");
+if (other) {
+  const sprite = this.world.getComponent(other.entityId, SpriteComponent);
+}
+```
+:::
+
+### Pulse sprite size
+
+Animate the sprite's width and height to create a breathing or highlight effect. The initial dimensions are captured on `init` so the pulse is relative to the authored size.
+
+```typescript
+import { Behaviour, SpriteComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class SpritePulse extends Behaviour {
+  data = {
+    speed: 2 as FloatInput,
+    amplitude: 0.2 as FloatInput,
+  };
+
+  private elapsed = 0;
+  private baseWidth = 1;
+  private baseHeight = 1;
+
+  protected init() {
+    const sprite = this.getComponent(SpriteComponent);
+    if (sprite) {
+      this.baseWidth = sprite.width;
+      this.baseHeight = sprite.height;
+    }
+  }
+
+  protected onUpdate() {
+    this.elapsed += this.deltaTime;
+    const sprite = this.getComponent(SpriteComponent);
+    if (!sprite) return;
+
+    const factor = 1 + this.data.amplitude * Math.sin(this.elapsed * this.data.speed);
+    sprite.width = this.baseWidth * factor;
+    sprite.height = this.baseHeight * factor;
+  }
+}
+```
+
+### Toggle visibility on key press
+
+Show or hide the sprite by toggling `Object3DRef.visibility`.
+
+```typescript
+import { Behaviour, Object3DRef, KeyboardKeys } from "@relu-interactives/spatial-ecs";
+
+export default class SpriteToggle extends Behaviour {
+  private visible = true;
+
+  protected onUpdate() {
+    if (this.world.getKeyDown(KeyboardKeys.V)) {
+      this.visible = !this.visible;
+      const ref = this.getComponent(Object3DRef);
+      if (ref) ref.visibility = this.visible;
+    }
+  }
+}
+```
+
+### 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 `SpriteComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  SpriteComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetSprite: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const sprite = this.data.targetSprite.value as SpriteComponent | null;
+    if (!sprite) 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,
+  SpriteComponent,
+  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 sprite = this.world.getComponent(
+      entity.entityId,
+      SpriteComponent,
+    ) as SpriteComponent | null;
+    if (!sprite) return;
+    // Use the component on the picked entity.
+  }
+}
+```