@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/guide/components/entity-type.md

@@ -0,0 +1,141 @@
+# Entity Type
+
+Tags an entity with the kind it was created from (`cube`, `sphere`, `model`, `directionalLight`, etc.). Factories use this to drive kind-specific behavior; the editor inspector uses it to select component editors.
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `value` | `EcsEntityKind \| EcsEntityEditorKind` | Kind tag identifying which factory created this entity (e.g. `cube`, `directionalLight`, `model`). |
+
+## API reference
+
+- Class: [`EntityType`](../../api/components/classes/EntityType.md)
+- Source: [`core/components/EntityType.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/EntityType.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 type = this.getComponent(EntityType);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Enemy");
+if (other) {
+  const type = this.world.getComponent(other.entityId, EntityType);
+}
+```
+:::
+
+### Read the entity's own type tag
+
+Branch behaviour based on what kind of entity this script is attached to.
+
+```typescript
+import { Behaviour, EntityType } from "@relu-interactives/spatial-ecs";
+
+export default class TypeAwareSetup extends Behaviour {
+  protected init() {
+    const entityType = this.getComponent(EntityType);
+    if (!entityType) return;
+
+    if (entityType.value === "cube") {
+      // Run cube-specific logic
+      this.transform.scale.x = 2;
+    } else if (entityType.value === "sphere") {
+      // Run sphere-specific logic
+      this.transform.scale.x = 1.5;
+    }
+  }
+}
+```
+
+### Filter a world query by entity kind
+
+Iterate all entities in the scene and apply logic only to those of a specific type.
+
+```typescript
+import { Behaviour, EntityType, TransformComponent } from "@relu-interactives/spatial-ecs";
+import type { StringInput, FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class TypeFilter extends Behaviour {
+  data = {
+    targetKind: "cube" as StringInput,
+    spinSpeed: 1 as FloatInput,
+  };
+
+  protected onUpdate() {
+    for (const [id, entityType] of this.world.query([EntityType])) {
+      if (entityType.value !== this.data.targetKind) continue;
+
+      const t = this.world.getComponent(id, TransformComponent);
+      if (t) t.rotation.y += this.data.spinSpeed * this.deltaTime;
+    }
+  }
+}
+```
+
+::: tip Read-only tag
+`EntityType.value` is set by the factory that created the entity and should be treated as read-only. Do not mutate it at runtime — it is used by the editor inspector and by hydration to select the correct component editors and restore the correct factory state.
+:::
+
+### 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 `EntityType` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  EntityType,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetEntityType: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const entityType = this.data.targetEntityType.value as EntityType | null;
+    if (!entityType) 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,
+  EntityType,
+  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 entityType = this.world.getComponent(
+      entity.entityId,
+      EntityType,
+    ) as EntityType | null;
+    if (!entityType) return;
+    // Use the component on the picked entity.
+  }
+}
+```

package/dist/docs/guide/components/image-target-anchor.md

@@ -0,0 +1,103 @@
+# Image Target Anchor
+
+Marks an entity as an anchor for an image-tracking target. The image tracking system reveals the entity when the referenced target is found and hides it when the target is lost.
+
+## Editor inspector
+
+![Image Target Anchor inspector](/images/components/ImageTargetAnchor.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `targetId` | `number \| null` | Tracked target id this anchor follows. `null` when unbound. |
+| `targetUrl` | `string` | Canonical target image URL, retained as a fallback identifier. |
+
+## API reference
+
+- Class: [`ImageTargetAnchor`](../../api/components/classes/ImageTargetAnchor.md)
+- Source: [`core/components/ImageTargetAnchor.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/ImageTargetAnchor.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 anchor = this.getComponent(ImageTargetAnchor);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("CardTarget");
+if (other) {
+  const anchor = this.world.getComponent(other.entityId, ImageTargetAnchor);
+}
+```
+:::
+
+### Run logic when the anchor becomes visible or hidden
+
+The image-tracking system sets `Object3DRef.visibility` on anchor entities when a target is found or lost. Use that flag as an event edge detector to trigger game logic.
+
+
+::: tip Anchor vs. target entity
+Attach this script to the **anchor child entity** (the one with `ImageTargetAnchor`), not to the root entity that has `ImageTarget`. The tracking system operates on the anchor and its `Object3DRef.visibility`, not on the target root.
+:::
+
+### 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 `ImageTargetAnchor` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  ImageTargetAnchor,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetAnchor: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const anchor = this.data.targetAnchor.value as ImageTargetAnchor | null;
+    if (!anchor) 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,
+  ImageTargetAnchor,
+  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 anchor = this.world.getComponent(
+      entity.entityId,
+      ImageTargetAnchor,
+    ) as ImageTargetAnchor | null;
+    if (!anchor) return;
+    // Use the component on the picked entity.
+  }
+}
+```

package/dist/docs/guide/components/image-target.md

@@ -0,0 +1,122 @@
+# Image Target
+
+Image-tracking target metadata used by AR projects. Holds the source images users uploaded plus the URL of the compiled `.mind` target file produced by the image-target compiler. Pair with `ImageTargetAnchor` on child entities that should appear when the target is detected.
+
+## Editor inspector
+
+![Image Target inspector](/images/components/ImageTarget.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `targets` | `ImageTargetReference[]` | Source images that were combined into the compiled `.mind` target. |
+| `compiledTargetUrl` | `string` | URL of the compiled `.mind` target file. Set after the image-target compiler finishes. |
+| `compiledTargetDir` | `string` | Directory containing the compiled `.mind` file (desktop projects). |
+| `texture` | `THREE.Texture \| null` | Optional preview texture used in the editor viewport. `null` when not assigned. |
+| `object` | `THREE.Object3D \| null` | Optional preview object placed in the editor viewport. `null` when not assigned. |
+
+## API reference
+
+- Class: [`ImageTarget`](../../api/components/classes/ImageTarget.md)
+- Source: [`core/components/ImageTarget.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/ImageTarget.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 target = this.getComponent(ImageTarget);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("CardMarker");
+if (other) {
+  const target = this.world.getComponent(other.entityId, ImageTarget);
+}
+```
+:::
+
+### React to target found / lost events
+
+The image-tracking system reveals the entity when its target is detected and hides it when lost. Attach this script to a child entity that has `ImageTargetAnchor` to run logic on those transitions.
+
+```typescript
+import { Behaviour, Object3DRef, AudioComponent } from "@relu-interactives/spatial-ecs";
+
+export default class TargetFoundReactor extends Behaviour {
+  private onTargetFound() {
+    // Play audio, trigger animation, spawn objects, etc.
+    const audio = this.getComponent(AudioComponent);
+    audio?.play();
+  }
+
+  private onTargetLost() {
+    const audio = this.getComponent(AudioComponent);
+    audio?.stop();
+  }
+}
+```
+
+::: tip AR-only component
+`ImageTarget` and `ImageTargetAnchor` are specific to **image-tracking** AR projects. The tracking system only runs in preview; behaviour scripts attached to anchor entities will still initialise in the editor, but `Object3DRef.visibility` will remain as authored until a real target is detected at runtime.
+:::
+
+### 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 `ImageTarget` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  ImageTarget,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetImageTarget: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const imageTarget = this.data.targetImageTarget.value as ImageTarget | null;
+    if (!imageTarget) 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,
+  ImageTarget,
+  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 imageTarget = this.world.getComponent(
+      entity.entityId,
+      ImageTarget,
+    ) as ImageTarget | null;
+    if (!imageTarget) return;
+    // Use the component on the picked entity.
+  }
+}
+```

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

@@ -0,0 +1,146 @@
+# Image
+
+Renders a 2D image as a textured quad in the scene. Width/height are in world units. Texture loading is handled by the image system, which populates `ImageComponent.texture` and `ImageComponent.object` asynchronously.
+
+## Editor inspector
+
+![Image inspector](/images/components/Image.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `path` | `string` | Source URL or `localasset://` path of the image file. |
+| `width` | `number` | Width of the rendered quad in world units. |
+| `height` | `number` | Height of the rendered quad in world units. |
+| `texture` | `THREE.Texture \| null` | Loaded texture, populated asynchronously by the image system. `null` until loaded. |
+| `object` | `THREE.Object3D \| null` | Live three.js object representing the textured quad. `null` until built. |
+
+## API reference
+
+- Class: [`ImageComponent`](../../api/components/classes/ImageComponent.md)
+- Source: [`core/components/Image.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Image.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 image = this.getComponent(ImageComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("Banner");
+if (other) {
+  const image = this.world.getComponent(other.entityId, ImageComponent);
+}
+```
+:::
+
+### Smooth resize toward a target size
+
+Lerp the image quad's dimensions toward inspector-defined target values, useful for animated UI reveals or zoom effects.
+
+```typescript
+import { Behaviour, ImageComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class ImageResizer extends Behaviour {
+  data = {
+    targetWidth: 2 as FloatInput,
+    targetHeight: 2 as FloatInput,
+    speed: 3 as FloatInput,
+  };
+
+  protected onUpdate() {
+    const image = this.getComponent(ImageComponent);
+    if (!image) return;
+
+    const k = this.data.speed * this.deltaTime;
+    image.width  += (this.data.targetWidth  - image.width)  * k;
+    image.height += (this.data.targetHeight - image.height) * k;
+  }
+}
+```
+
+### Show or hide based on a flag
+
+Drive the quad's visibility from the inspector or from game logic via `Object3DRef`.
+
+```typescript
+import { Behaviour, ImageComponent, Object3DRef } from "@relu-interactives/spatial-ecs";
+import type { BooleanInput } from "@relu-interactives/spatial-ecs";
+
+export default class ImageVisibility extends Behaviour {
+  data = {
+    visible: true as BooleanInput,
+  };
+
+  protected onUpdate() {
+    const image = this.getComponent(ImageComponent);
+    if (!image?.object) return; // wait for texture load
+
+    const ref = this.getComponent(Object3DRef);
+    if (ref) ref.visibility = this.data.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 `ImageComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  ImageComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetImage: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const image = this.data.targetImage.value as ImageComponent | null;
+    if (!image) 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,
+  ImageComponent,
+  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 image = this.world.getComponent(
+      entity.entityId,
+      ImageComponent,
+    ) as ImageComponent | null;
+    if (!image) return;
+    // Use the component on the picked entity.
+  }
+}
+```

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

@@ -0,0 +1,157 @@
+# Light
+
+Light source attached to an entity. `type` selects the underlying three.js light class (directional, point, spot, ambient, hemisphere, rect-area). `values` carries authoring state including color, intensity, and type-specific fields (distance, decay, angle, penumbra, width, height).
+
+> **Managed by:** [`LightSyncSystem`](../systems/light-sync-system)
+
+## Editor inspector
+
+![Light inspector](/images/components/Light.png)
+
+## Properties
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `light` | `THREE.Light` | Live three.js light placed in the scene. Recreated when the project loads. |
+| `type` | `string` | Three.js class name of the light (e.g. `"DirectionalLight"`, `"PointLight"`, `"SpotLight"`). |
+| `values` | `LightValueState` | Serialized authoring state. Saved with the project. |
+
+## API reference
+
+- Class: [`LightComponent`](../../api/components/classes/LightComponent.md)
+- Source: [`core/components/Light.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/components/Light.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 light = this.getComponent(LightComponent);
+
+// Component on another entity, found by its scene name
+const other = this.world.getEntityByName("SpotLight");
+if (other) {
+  const light = this.world.getComponent(other.entityId, LightComponent);
+}
+```
+:::
+
+### Pulse intensity
+
+Animate the light's intensity between a min and max value using a sine wave — useful for flickering flames or heartbeat effects.
+
+```typescript
+import { Behaviour, LightComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class LightPulse extends Behaviour {
+  data = {
+    speed: 2 as FloatInput,
+    minIntensity: 0.5 as FloatInput,
+    maxIntensity: 3 as FloatInput,
+  };
+
+  private elapsed = 0;
+
+  protected onUpdate() {
+    this.elapsed += this.deltaTime;
+    const light = this.getComponent(LightComponent);
+    if (!light?.light) return;
+
+    const t = (Math.sin(this.elapsed * this.data.speed) + 1) * 0.5;
+    light.light.intensity =
+      this.data.minIntensity + t * (this.data.maxIntensity - this.data.minIntensity);
+  }
+}
+```
+
+### Timed color shift
+
+Cycle the light's color through the RGB spectrum over a configurable period.
+
+```typescript
+import { Behaviour, LightComponent } from "@relu-interactives/spatial-ecs";
+import type { FloatInput } from "@relu-interactives/spatial-ecs";
+
+export default class LightColorCycle extends Behaviour {
+  data = {
+    period: 4 as FloatInput,
+  };
+
+  private elapsed = 0;
+
+  protected onUpdate() {
+    this.elapsed += this.deltaTime;
+    const light = this.getComponent(LightComponent);
+    if (!light?.light) return;
+
+    const hue = (this.elapsed / this.data.period) % 1;
+    (light.light.color as { setHSL(h: number, s: number, l: number): void })
+      .setHSL(hue, 1, 0.5);
+  }
+}
+```
+
+::: tip Live light access
+Mutate `light.light.intensity` and `light.light.color` directly for immediate per-frame changes. For changes that should survive a save/reload cycle, also update `light.values.intensity` / `light.values.color` so the authoring state stays in sync.
+:::
+
+### 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 `LightComponent` instance at runtime.
+
+```typescript
+import {
+  Behaviour,
+  LightComponent,
+  type ComponentInput,
+} from "@relu-interactives/spatial-ecs";
+
+export default class Example extends Behaviour {
+  data = {
+    targetLight: {
+      type: "component",
+      value: null,
+    } as unknown as ComponentInput,
+  };
+
+  protected onUpdate() {
+    const light = this.data.targetLight.value as LightComponent | null;
+    if (!light) 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,
+  LightComponent,
+  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 light = this.world.getComponent(
+      entity.entityId,
+      LightComponent,
+    ) as LightComponent | null;
+    if (!light) return;
+    // Use the component on the picked entity.
+  }
+}
+```