@relu-interactives/spatial-ecs 0.2.12 → 0.2.14

package/dist/docs/guide/scene/environment.md

@@ -12,15 +12,14 @@ It is a **singleton** there is exactly one `Environment` entity per scene, owned
 
 ## Get the component from the world
 
+Use `world.getEnvironmentComponent()` — a convenience method that handles the entity lookup for you:
+
 ```ts
-import { Behaviour, Environment } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
 
 export default class ReadEnvironment extends Behaviour {
   init() {
-    const [entityId] = this.world.query(Environment);
-    if (entityId === undefined) return;
-
-    const env = this.world.getComponent(entityId, Environment);
+    const env = this.world.getEnvironmentComponent();
     if (!env) return;
 
     console.log("skybox type", env.values.skybox.type);
@@ -29,7 +28,7 @@ export default class ReadEnvironment extends Behaviour {
 }
 ```
 
-`env.values` is the live state object. Mutating fields on it is enough, the `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
+`env.values` is the live state object. Mutating fields on it is enough — `EnvironmentSyncSystem` reads it every frame and pushes changes into the three.js scene.
 
 ## Change values at runtime
 

package/dist/docs/guide/scene/index.md

@@ -9,22 +9,17 @@ Some settings live on the **scene** rather than on a single object the skybox, f
 
 ## Pattern
 
-Both components follow the same access pattern from a script:
+Both components expose a convenience method on `world` — no manual entity lookup needed:
 
 ```ts
-import { Behaviour, Environment, Postprocessing } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
 
 export default class TweakScene extends Behaviour {
   init() {
-    // 1. Find the singleton entity that owns the component.
-    const [entityId] = this.world.query(Environment);
-    if (entityId === undefined) return;
-
-    // 2. Read the component instance.
-    const env = this.world.getComponent(entityId, Environment);
+    const env = this.world.getEnvironmentComponent();
     if (!env) return;
 
-    // 3. Mutate `env.values` — sync systems pick the change up next frame.
+    // Mutate `env.values` — sync systems pick the change up next frame.
     env.values.fog.type = "linear";
     env.values.fog.color = "#88aaff";
     env.values.fog.linear.near = 5;
@@ -33,4 +28,4 @@ export default class TweakScene extends Behaviour {
 }
 ```
 
-The same shape works for `Postprocessing` — see each page for the full set of authorable values.
+The same pattern works for `Postprocessing` via `this.world.getPostprocessingComponent()` — see each page for the full set of authorable values.

package/dist/docs/guide/scene/postprocessing.md

@@ -11,15 +11,14 @@ It is a **singleton** there is exactly one `Postprocessing` entity per scene, ow
 
 ## Get the component from the world
 
+Use `world.getPostprocessingComponent()` — a convenience method that handles the entity lookup for you:
+
 ```ts
-import { Behaviour, Postprocessing } from "@relu-interactives/spatial-ecs";
+import { Behaviour } from "@relu-interactives/spatial-ecs";
 
 export default class ReadPostprocessing extends Behaviour {
   init() {
-    const [entityId] = this.world.query(Postprocessing);
-    if (entityId === undefined) return;
-
-    const post = this.world.getComponent(entityId, Postprocessing);
+    const post = this.world.getPostprocessingComponent();
     if (!post) return;
 
     console.log("post enabled?", post.values.postEnabled);
@@ -27,7 +26,7 @@ export default class ReadPostprocessing extends Behaviour {
 }
 ```
 
-`post.values` is the live state object mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the composer pipeline as effects are toggled.
+`post.values` is the live state object — mutate fields on it directly. The `PostprocessingSyncSystem` reads it every frame and rebuilds the composer pipeline as effects are toggled.
 
 ## Change values at runtime
 

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

@@ -44,4 +44,65 @@ Component kinds (e.g. `"animation"`, `"physics"`) are registered with `registerC
 
 ## API reference
 
+### `requestCreate(kind, payload?, onCreated?)`
+
+Queue a new entity creation request. The factory for the given `kind` runs on the next frame; the optional `onCreated` callback fires with the new `entityId`:
+
+```ts
+const oms = this.world.getObjectManagementSystem();
+
+oms?.requestCreate("cube", {
+  name: "DynamicCube",
+  transform: { position: { x: 0, y: 2, z: 0 } },
+}, (entityId) => {
+  // entityId is ready — add more components here
+});
+```
+
+### `createComponentNow(kind, world, entityId, ...args)`
+
+Synchronously call the registered component factory for `kind` on an existing entity. Use this instead of `world.addComponent` when the component needs runtime setup (Rapier bodies, Web Audio nodes, Three.js material instances):
+
+```ts
+// Add physics with full Rapier body + collider setup
+oms.createComponentNow("physics", world, entityId, {
+  rigidbody: { type: "dynamic", mass: 1, gravityScale: 1 },
+  collider: { shape: "box" },
+});
+
+// Add a material with a Three.js material instance
+oms.createComponentNow("material", world, entityId, { color: "#ff0000" });
+```
+
+Registered factory kinds: `"animation"`, `"audio"`, `"camera"`, `"physics"`, `"environment"`, `"entityType"`, `"image"`, `"imageTarget"`, `"imageTargetAnchor"`, `"light"`, `"material"`, `"mesh"`, `"meshGeometry"`, `"model"`, `"name"`, `"object3DRef"`, `"parentId"`, `"postprocessing"`, `"script"`, `"sprite"`, `"transform"`, `"video"`, `"instancedMesh"`.
+
+### `deleteEntity(world, entityId, dispose?)`
+
+Remove an entity from the ECS world and its `Object3D` from the Three.js scene graph. Pass `dispose = true` to also free GPU memory by calling `.dispose()` on all `BufferGeometry` and `Material` instances in the subtree:
+
+```ts
+// Remove from scene, keep GPU resources (safe if geometry is shared)
+oms.deleteEntity(world, entityId);
+
+// Remove from scene and free GPU memory (use for dynamically spawned objects)
+oms.deleteEntity(world, entityId, true);
+```
+
+### `setParent(world, entityId, parentId, options?)`
+
+Re-parent an entity at runtime. Updates the `ParentId` component and reconciles the Three.js scene graph on the same frame. By default (`preserveWorldTransform: true`), world-space position and rotation are preserved by adjusting the local transform:
+
+```ts
+// Attach child to a parent entity (preserves world position)
+oms.setParent(world, childEntityId, parentEntityId);
+
+// Detach from parent — make direct child of scene root
+oms.setParent(world, childEntityId, null);
+
+// Reparent without preserving world position (local transform reset)
+oms.setParent(world, childEntityId, parentEntityId, { preserveWorldTransform: false });
+```
+
+`setParent` guards against cycles and returns `false` if the operation would create a loop or if either entity does not exist.
+
 - Source: [`core/systems/ObjectManagementSystem.ts`](https://github.com/Relu-Interactives/relu-spatial-ecs-engine/blob/main/core/systems/ObjectManagementSystem.ts)

package/dist/docs/guide/world-api.md

@@ -55,6 +55,8 @@ export default class Spinner extends Behaviour {
 | `getEntityByName(name)` | First entity whose `Name` matches, or `null`. |
 | `getEntitiesByName(name)` | All entities sharing a `Name`. |
 | `getEntitiesByComponent(component)` | All entities that own a component of the same class. |
+| `getEntitiesChildren(entityId)` | All child entities of the given entity (entities whose `ParentId` component points to this entity). |
+| `getEntitiesParent(entityId)` | The parent entity of the given entity, or `null` if the entity has no parent or is at the world root. |
 
 ### Scripts
 
@@ -102,6 +104,8 @@ Both methods accept `Vec3` (`THREE.Vector3` or `{ x, y, z }`) and return `Inters
 | `getSystem(SystemClass)` | Resolve a registered system instance. |
 | `hasSystem(SystemClass)` | `true` if the system is registered. |
 | `getObjectManagementSystem()` | Shorthand for the built-in `ObjectManagementSystem`. Use this to spawn or destroy entities at runtime (`requestCreate`, `createNow`, `deleteEntity`). |
+| `getEnvironmentComponent()` | Returns the singleton [`Environment`](./scene/environment) component, or `undefined` if not yet initialized. Mutate `values` to change skybox, fog, or gravity at runtime. |
+| `getPostprocessingComponent()` | Returns the singleton [`Postprocessing`](./scene/postprocessing) component, or `undefined` if not yet initialized. Mutate `values` to toggle effects or adjust parameters at runtime. |
 
 ### World lifecycle
 
@@ -148,6 +152,38 @@ export default class FlickerAllLights extends Behaviour {
 }
 ```
 
+### Navigate the entity hierarchy
+
+Use `getEntitiesParent` and `getEntitiesChildren` to traverse parent-child relationships in the scene graph. This is useful for group operations, finding related entities, or building custom hierarchy traversal logic.
+
+```ts
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class HierarchyWalker extends Behaviour {
+  init() {
+    // Get the parent of this entity
+    const parent = this.world.getEntitiesParent(this.entityId);
+    if (parent) {
+      console.log(`Parent: ${parent.name} (ID: ${parent.entityId})`);
+    }
+
+    // Get all children of this entity
+    const children = this.world.getEntitiesChildren(this.entityId);
+    console.log(`Children count: ${children.length}`);
+    for (const child of children) {
+      console.log(`  - ${child.name} (ID: ${child.entityId})`);
+    }
+
+    // Recursively walk up to the root
+    let current = this.world.getEntityById(this.entityId);
+    while (current) {
+      console.log(`Ancestor: ${current.name}`);
+      current = this.world.getEntitiesParent(current.entityId);
+    }
+  }
+}
+```
+
 ### Talk to another script on a different entity
 
 ```ts
@@ -398,6 +434,6 @@ export default class PauseOnHit extends Behaviour {
 ## See also
 
 - [Custom Behaviours](./authoring-a-behaviour) — `init`, `onUpdate`, `dispose`, `data`, lifecycle.
-- [Inspector Data Binding](./inspector-data-binding) — exposing fields to the inspector through `data`.
+- [Behaviour Data Binding](./behaviour-data-binding/) — exposing fields to the inspector through `data`.
 - [Behaviour Lifecycle & Events](./behaviour-lifecycle) — when each hook fires.
 - [Component Catalog](./component-catalog) — the components you'll read and mutate from scripts.