@relu-interactives/spatial-ecs 0.2.2

package/dist/docs/api/Behaviour/classes/Behaviour.md

@@ -0,0 +1,554 @@
+[**@relu-interactives/spatial-ecs**](../../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../../index.md) / [Behaviour](../index.md) / Behaviour
+
+# Class: Behaviour
+
+Defined in: [Behaviour.ts:62](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L62)
+
+Base class for all user-authored scripts attached to an entity through a
+`ScriptComponent`. Subclass `Behaviour` to drive per-frame logic on a single
+entity with full access to the [World](../../index/classes/World.md), the entity's
+[TransformComponent](../../components/classes/TransformComponent.md), and its three.js [Object3DRef](../../components/classes/Object3DRef.md).
+
+## Remarks
+
+Scripts are dispatched by `ScriptBehaviourSystem` once per frame in this
+order: [Behaviour.init](#init) (first frame only) → [Behaviour.onUpdate](#onupdate).
+Override [Behaviour.onUpdate](#onupdate) for per-frame logic — never override
+[Behaviour.update](#update), which is the engine-managed entry point.
+
+**Editor scripts**: By default, `Behaviour` subclasses do not run inside the
+editor. Set `executeInEditor: true` on the script entry in the inspector to
+enable the full lifecycle (`init` → `onUpdate` → `dispose`) while the editor
+is open. This gives direct access to the Three.js scene, camera, and renderer
+via [World.getScene](../../index/classes/World.md#getscene), [World.getCamera](../../index/classes/World.md#getcamera), and
+[World.getRenderer](../../index/classes/World.md#getrenderer) — useful for custom shaders, procedural geometry,
+grass, and any Three.js feature the editor's object palette does not expose.
+Avoid mutating ECS component state every frame in editor mode, as it creates
+undo history entries on every tick.
+
+The runtime recognizes a script by its **default export** plus the
+inherited static marker `__reluBehaviourClass`. Do not override the marker.
+
+## Example
+
+```ts
+import { Behaviour, type Component } from "@relu-interactives/spatial-ecs";
+
+export default class Spinner extends Behaviour {
+  data: {
+   speed: number;
+   axis: "x" | "y" | "z";
+ };
+
+  init() {
+    this.data.speed ??= 1;
+    this.data.axis ??= "y";
+  }
+
+  onUpdate() {
+    this.transform.rotation[this.data.axis] += this.data.speed * this.deltaTime;
+  }
+}
+```
+
+## See
+
+ - [World](../../index/classes/World.md)
+ - [TransformComponent](../../components/classes/TransformComponent.md)
+ - [Object3DRef](../../components/classes/Object3DRef.md)
+
+## Implements
+
+- `CustomEcsSystem`
+
+## Constructors
+
+### Constructor
+
+```ts
+new Behaviour(
+   world, 
+   entityId, 
+   component): Behaviour;
+```
+
+Defined in: [Behaviour.ts:120](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L120)
+
+Engine-managed constructor. Hosts (`ScriptBehaviourSystem`) instantiate
+subclasses with the owning world, the entity id, and the script's `data`
+payload. User code should not call this directly.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `world` | [`World`](../../index/classes/World.md) | The owning ECS world. |
+| `entityId` | `number` | The entity this script is bound to. |
+| `component` | \| [`Component`](../../Component/classes/Component.md) \| `Record`\<`string`, `unknown`\> | The `ScriptComponent.data` payload, or any object that should be exposed to the script as `this.data`. |
+
+#### Returns
+
+`Behaviour`
+
+## Properties
+
+| Property | Type | Default value | Description | Defined in |
+| ------ | ------ | ------ | ------ | ------ |
+| <a id="data"></a> `data` | \| [`Component`](../../Component/classes/Component.md) \| `Record`\<`string`, `unknown`\> | `undefined` | Inspector-bound payload from the entity's `ScriptComponent`. Override the type on subclasses with `declare data: MyDataShape` to get type safety inside hooks. Saved with the project so values persist across reloads. | [Behaviour.ts:78](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L78) |
+| <a id="entityid"></a> `entityId` | `number` | `undefined` | Numeric id of the entity this script is attached to. | [Behaviour.ts:81](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L81) |
+| <a id="entity"></a> `entity` | `WorldEntityView` | `undefined` | View of the owning entity (id + components) at construction time. | [Behaviour.ts:84](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L84) |
+| <a id="threeref"></a> `threeRef` | [`Object3DRef`](../../components/classes/Object3DRef.md) | `undefined` | Live three.js object wrapper for the entity. May be `null` for entities with no scene presence; helpers on this class return `null` in that case. | [Behaviour.ts:90](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L90) |
+| <a id="transform"></a> `transform` | [`TransformComponent`](../../components/classes/TransformComponent.md) | `undefined` | The entity's [TransformComponent](../../components/classes/TransformComponent.md). Mutating `position`, `rotation`, or `scale` here is picked up the same frame by `TransformSyncSystem`. | [Behaviour.ts:96](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L96) |
+| <a id="world"></a> `world` | [`World`](../../index/classes/World.md) | `undefined` | The owning [World](../../index/classes/World.md). Refreshed each frame in [Behaviour.update](#update). Use it to query other entities or components. | [Behaviour.ts:102](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L102) |
+| <a id="deltatime"></a> `deltaTime` | `number` | `0` | Seconds elapsed since the last frame. Set by the engine before each [Behaviour.onUpdate](#onupdate). | [Behaviour.ts:108](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L108) |
+
+## Methods
+
+### update()
+
+```ts
+update(world, deltaTime): void;
+```
+
+Defined in: [Behaviour.ts:144](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L144)
+
+Engine-managed per-frame entry point. Refreshes [Behaviour.deltaTime](#deltatime)
+and delegates to [Behaviour.onUpdate](#onupdate).
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `world` | [`World`](../../index/classes/World.md) | The owning world (may differ from the constructor world after hot reload). |
+| `deltaTime` | `number` | Seconds since the last frame. |
+
+#### Returns
+
+`void`
+
+#### Remarks
+
+Do **not** override this method — override
+[Behaviour.onUpdate](#onupdate) instead.
+
+#### Implementation of
+
+```ts
+CustomEcsSystem.update
+```
+
+***
+
+### dispose()?
+
+```ts
+optional dispose(world): void;
+```
+
+Defined in: [Behaviour.ts:156](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L156)
+
+Optional cleanup hook invoked when the script is detached or the entity
+is destroyed. Override to release timers, listeners, or other resources.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `world` | [`World`](../../index/classes/World.md) | The owning world at disposal time. |
+
+#### Returns
+
+`void`
+
+#### Implementation of
+
+```ts
+CustomEcsSystem.dispose
+```
+
+***
+
+### getWorldPosition()
+
+```ts
+getWorldPosition(): Vector3 | null;
+```
+
+Defined in: [Behaviour.ts:164](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L164)
+
+Returns the entity's world-space position as a new `THREE.Vector3`, or
+`null` if the entity has no scene presence.
+
+#### Returns
+
+`Vector3` \| `null`
+
+***
+
+### getWorldDirection()
+
+```ts
+getWorldDirection(): Vector3 | null;
+```
+
+Defined in: [Behaviour.ts:179](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L179)
+
+Returns the entity's forward direction in world space (the +Z axis of its
+world matrix), or `null` if the entity has no scene presence.
+
+#### Returns
+
+`Vector3` \| `null`
+
+***
+
+### directionTo()
+
+```ts
+directionTo(targetPosition): Vector3 | null;
+```
+
+Defined in: [Behaviour.ts:196](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L196)
+
+Returns a unit vector pointing from this entity toward the given world
+position, or `null` if the entity has no scene presence.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `targetPosition` | `Vector3` | Destination point in world space. |
+
+#### Returns
+
+`Vector3` \| `null`
+
+***
+
+### distanceTo()
+
+```ts
+distanceTo(targetPosition): number | null;
+```
+
+Defined in: [Behaviour.ts:211](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L211)
+
+Returns the world-space distance from this entity to the given position,
+or `null` if the entity has no scene presence.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `targetPosition` | `Vector3` | Destination point in world space. |
+
+#### Returns
+
+`number` \| `null`
+
+***
+
+### lerpTo()
+
+```ts
+lerpTo(targetPosition, alpha): void;
+```
+
+Defined in: [Behaviour.ts:229](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L229)
+
+Linearly interpolates the entity's position toward `targetPosition` and
+writes the result back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if the
+entity has no scene presence.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `targetPosition` | `Vector3` | Destination point in world space. |
+| `alpha` | `number` | Interpolation factor in [0, 1]. Multiply by `deltaTime` for frame-rate-independent smoothing. |
+
+#### Returns
+
+`void`
+
+***
+
+### slerpTo()
+
+```ts
+slerpTo(targetRotation, alpha): void;
+```
+
+Defined in: [Behaviour.ts:251](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L251)
+
+Spherically interpolates the entity's rotation toward `targetRotation`
+and writes the result back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if
+the entity has no scene presence.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `targetRotation` | `Quaternion` | Destination orientation as a quaternion. |
+| `alpha` | `number` | Interpolation factor in [0, 1]. |
+
+#### Returns
+
+`void`
+
+***
+
+### lookAt()
+
+```ts
+lookAt(targetPosition): void;
+```
+
+Defined in: [Behaviour.ts:270](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L270)
+
+Rotates the entity to face `targetPosition` in world space and writes the
+resulting orientation back through [TransformComponent](../../components/classes/TransformComponent.md). No-op if
+the entity has no scene presence.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `targetPosition` | `Vector3` | Point in world space to face. |
+
+#### Returns
+
+`void`
+
+***
+
+### getComponents()
+
+```ts
+getComponents(): Component[];
+```
+
+Defined in: [Behaviour.ts:284](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L284)
+
+Returns every component currently attached to this entity.
+
+#### Returns
+
+[`Component`](../../Component/classes/Component.md)[]
+
+***
+
+### getComponent()
+
+```ts
+getComponent<T>(componentClass): T | null;
+```
+
+Defined in: [Behaviour.ts:301](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L301)
+
+Returns the entity's component of the given class, or `null` if it has
+no such component.
+
+#### Type Parameters
+
+| Type Parameter | Description |
+| ------ | ------ |
+| `T` *extends* [`Component`](../../Component/classes/Component.md) | Concrete component type. |
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `componentClass` | `ComponentClass`\<`T`\> | Component class constructor to look up. |
+
+#### Returns
+
+`T` \| `null`
+
+#### Example
+
+```ts
+const mesh = this.getComponent(MeshComponent);
+if (mesh) console.log(mesh.geometryRef);
+```
+
+***
+
+### getEntity()
+
+```ts
+getEntity(): WorldEntityView | null;
+```
+
+Defined in: [Behaviour.ts:311](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L311)
+
+Returns the latest [WorldEntityView](../../types/type-aliases/WorldEntityView.md) snapshot for this entity, or
+`null` if it was destroyed.
+
+#### Returns
+
+`WorldEntityView` \| `null`
+
+***
+
+### getParent()
+
+```ts
+getParent(): ParentLookup;
+```
+
+Defined in: [Behaviour.ts:321](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L321)
+
+Resolves the entity's parent from the [ParentId](../../components/classes/ParentId.md) component, if any.
+
+#### Returns
+
+[`ParentLookup`](../../types/type-aliases/ParentLookup.md)
+
+A [ParentLookup](../../types/type-aliases/ParentLookup.md) with the parent component reference and
+  the parent entity view (or `null` if the entity is at the root).
+
+***
+
+### getChildren()
+
+```ts
+getChildren(): WorldEntityView[];
+```
+
+Defined in: [Behaviour.ts:342](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L342)
+
+Returns every direct child entity of this one (entities whose
+[ParentId](../../components/classes/ParentId.md) matches `entityId`).
+
+#### Returns
+
+`WorldEntityView`[]
+
+***
+
+### init()
+
+```ts
+protected init(): void;
+```
+
+Defined in: [Behaviour.ts:361](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L361)
+
+Called once before the first [Behaviour.onUpdate](#onupdate). Override to
+default and validate [Behaviour.data](#data), cache references, or set
+initial state.
+
+#### Returns
+
+`void`
+
+#### Remarks
+
+Also called in editor mode when `executeInEditor` is `true` on the script
+entry.
+
+***
+
+### onUpdate()
+
+```ts
+protected onUpdate(): void;
+```
+
+Defined in: [Behaviour.ts:374](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L374)
+
+Called every frame while the script is enabled. Override with the
+script's main per-frame logic.
+
+#### Returns
+
+`void`
+
+#### Remarks
+
+Also called every frame in editor mode when `executeInEditor` is `true`.
+Access the Three.js scene with `this.world.getScene()` for editor-only
+rendering work such as custom shaders or procedural geometry.
+
+***
+
+### onSelect()
+
+```ts
+onSelect(): void;
+```
+
+Defined in: [Behaviour.ts:379](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L379)
+
+Called when the editor selects this entity. Optional UX hook.
+
+#### Returns
+
+`void`
+
+***
+
+### onDeselect()
+
+```ts
+onDeselect(): void;
+```
+
+Defined in: [Behaviour.ts:384](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L384)
+
+Called when the editor deselects this entity. Optional UX hook.
+
+#### Returns
+
+`void`
+
+***
+
+### onTargetFound()
+
+```ts
+onTargetFound(target): void;
+```
+
+Defined in: [Behaviour.ts:394](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L394)
+
+Called when an image-tracking target this entity depends on becomes
+visible. Optional AR hook.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `target` | `WorldEntityView` | The newly-visible target entity view. |
+
+#### Returns
+
+`void`
+
+***
+
+### onTargetLost()
+
+```ts
+onTargetLost(target): void;
+```
+
+Defined in: [Behaviour.ts:404](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Behaviour.ts#L404)
+
+Called when an image-tracking target this entity depends on is lost.
+Optional AR hook.
+
+#### Parameters
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `target` | `WorldEntityView` | The target entity view that became invisible. |
+
+#### Returns
+
+`void`

package/dist/docs/api/Behaviour/index.md

@@ -0,0 +1,15 @@
+[**@relu-interactives/spatial-ecs**](../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../index.md) / Behaviour
+
+# Behaviour
+
+## Classes
+
+### Scripting
+
+| Class | Description |
+| ------ | ------ |
+| [Behaviour](classes/Behaviour.md) | Base class for all user-authored scripts attached to an entity through a `ScriptComponent`. Subclass `Behaviour` to drive per-frame logic on a single entity with full access to the [World](../index/classes/World.md), the entity's [TransformComponent](../components/classes/TransformComponent.md), and its three.js [Object3DRef](../components/classes/Object3DRef.md). |

package/dist/docs/api/Component/classes/Component.md

@@ -0,0 +1,57 @@
+[**@relu-interactives/spatial-ecs**](../../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../../index.md) / [Component](../index.md) / Component
+
+# Class: Component
+
+Defined in: [Component.ts:12](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/d7abe871a8dd71d2e6e1dff3235da21d5376bd8f/core/Component.ts#L12)
+
+Marker base class for every ECS component. Subclass `Component` to declare
+a typed data container that systems can query.
+
+## Remarks
+
+Components own state only — runtime behaviour belongs in [Behaviour](../../Behaviour/index.md)
+subclasses for user scripts. Keep fields plain (numbers, strings, vectors,
+asset URLs).
+
+## Extended by
+
+- [`AnimationComponent`](../../components/classes/AnimationComponent.md)
+- [`CameraComponent`](../../components/classes/CameraComponent.md)
+- [`AudioComponent`](../../components/classes/AudioComponent.md)
+- [`Environment`](../../components/classes/Environment.md)
+- [`Postprocessing`](../../components/classes/Postprocessing.md)
+- [`PhysicsComponent`](../../components/classes/PhysicsComponent.md)
+- [`EntityType`](../../components/classes/EntityType.md)
+- [`ImageComponent`](../../components/classes/ImageComponent.md)
+- [`ImageTarget`](../../components/classes/ImageTarget.md)
+- [`ImageTargetAnchor`](../../components/classes/ImageTargetAnchor.md)
+- [`LightComponent`](../../components/classes/LightComponent.md)
+- [`MaterialComponent`](../../components/classes/MaterialComponent.md)
+- [`MeshComponent`](../../components/classes/MeshComponent.md)
+- [`MeshGeometryComponent`](../../components/classes/MeshGeometryComponent.md)
+- [`ModelComponent`](../../components/classes/ModelComponent.md)
+- [`Name`](../../components/classes/Name.md)
+- [`Object3DRef`](../../components/classes/Object3DRef.md)
+- [`ParentId`](../../components/classes/ParentId.md)
+- [`ScriptComponent`](../../components/classes/ScriptComponent.md)
+- [`Selectable`](../../components/classes/Selectable.md)
+- [`SpriteComponent`](../../components/classes/SpriteComponent.md)
+- [`SelectionTransformState`](../../components/classes/SelectionTransformState.md)
+- [`TransformComponent`](../../components/classes/TransformComponent.md)
+- [`VideoComponent`](../../components/classes/VideoComponent.md)
+
+## Constructors
+
+### Constructor
+
+```ts
+new Component(): Component;
+```
+
+#### Returns
+
+`Component`

package/dist/docs/api/Component/index.md

@@ -0,0 +1,15 @@
+[**@relu-interactives/spatial-ecs**](../index.md)
+
+***
+
+[@relu-interactives/spatial-ecs](../index.md) / Component
+
+# Component
+
+## Classes
+
+### Components
+
+| Class | Description |
+| ------ | ------ |
+| [Component](classes/Component.md) | Marker base class for every ECS component. Subclass `Component` to declare a typed data container that systems can query. |