@relu-interactives/spatial-ecs 0.2.13 → 0.2.14

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

@@ -103,6 +103,31 @@ export default class Example extends Behaviour {
 }
 ```
 
+### Navigate the hierarchy with World methods
+
+Instead of querying the `ParentId` component directly, use `world.getEntitiesParent` and `world.getEntitiesChildren` for convenient hierarchy traversal:
+
+```typescript
+import { Behaviour } from "@relu-interactives/spatial-ecs";
+
+export default class HierarchyLogger extends Behaviour {
+  protected init() {
+    // Get parent entity
+    const parent = this.world.getEntitiesParent(this.entityId);
+    if (parent) {
+      console.log(`Parent: ${parent.name} (ID: ${parent.entityId})`);
+    }
+
+    // Get all children
+    const children = this.world.getEntitiesChildren(this.entityId);
+    console.log(`${children.length} child(ren):`);
+    for (const child of children) {
+      console.log(`  - ${child.name} (ID: ${child.entityId})`);
+    }
+  }
+}
+```
+
 ::: 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/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
 
@@ -150,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

package/dist/factories/index.d.cts

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-BMWPYc3q.cjs';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-CTTwEGn1.cjs';
+import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-D4B-z74P.cjs';
+import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-BeuJ1xt5.cjs';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 

package/dist/factories/index.d.ts

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-CV1-u6hL.js';
-import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-CTTwEGn1.js';
+import { A as AnimationComponent, b as AudioComponent, c as CameraComponentOptions, C as CameraComponent, S as RigidbodyState, g as ColliderState, P as PhysicsComponent, n as EntityType, I as ImageComponent, p as ImageTargetAnchor, o as ImageTarget, L as LightComponent, M as MaterialComponent, z as MeshComponent, B as MeshGeometryComponent, H as ModelComponent, N as Name, O as Object3DRef, V as ScriptEntry, U as ScriptComponent, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, v as InstancedMeshKind, F as MeshGeometryParameters, u as InstancedMeshComponent, s as InstanceSlotComponent, a0 as VideoComponent } from '../Video-Cym2C52L.js';
+import { l as World, g as EnvironmentState, E as Environment, P as ParentId, i as PostprocessingState, h as Postprocessing, T as TransformComponent, O as ObjectManagementSystem } from '../System-BeuJ1xt5.js';
 import * as THREE from 'three';
 import '@dimforge/rapier3d-compat';
 

package/dist/{index-D7q4SRCp.d.cts → index-BfoOC2CG.d.cts}

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from './Video-BMWPYc3q.cjs';
-import { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-CTTwEGn1.cjs';
+import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from './Video-D4B-z74P.cjs';
+import { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-BeuJ1xt5.cjs';
 
 declare const index_AnimationComponent: typeof AnimationComponent;
 declare const index_AnimationComponentOptions: typeof AnimationComponentOptions;

package/dist/{index-ByX7502C.d.ts → index-BoJ3_6a3.d.ts}

@@ -1,5 +1,5 @@
-import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from './Video-CV1-u6hL.js';
-import { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-CTTwEGn1.js';
+import { A as AnimationComponent, a as AnimationComponentOptions, b as AudioComponent, C as CameraComponent, c as CameraComponentOptions, d as CameraProjection, e as CameraRuntimeType, f as ColliderShape, g as ColliderState, h as CubeMeshParameters, D as DEFAULT_COLLIDER_STATE, i as DEFAULT_INSTANCED_MESH_PARAMETERS, j as DEFAULT_INSTANCE_TRANSFORM, k as DEFAULT_MESH_GEOMETRY_PARAMETERS, l as DEFAULT_PHYSICS_STATE, m as DEFAULT_RIGIDBODY_STATE, E as EditableMeshObjectKind, n as EntityType, I as ImageComponent, o as ImageTarget, p as ImageTargetAnchor, q as ImageTargetAnchorOptions, r as ImageTargetReference, s as InstanceSlotComponent, t as InstanceTransform, u as InstancedMeshComponent, v as InstancedMeshKind, L as LightComponent, w as LightValueState, M as MaterialComponent, x as MaterialTypeValue, y as MaterialValueState, z as MeshComponent, B as MeshGeometryComponent, F as MeshGeometryParameters, G as MeshGeometryParametersByKind, H as ModelComponent, N as Name, O as Object3DRef, P as PhysicsComponent, J as PhysicsState, K as PlaneMeshParameters, R as RadiusHeightMeshParameters, Q as RadiusMeshParameters, S as RigidbodyState, T as RigidbodyType, U as ScriptComponent, V as ScriptEntry, W as Selectable, X as SelectionTransformState, Y as SpriteComponent, Z as TextureFilteringValue, _ as TransformModeValue, $ as TransformSpaceValue, a0 as VideoComponent, a1 as normalizePhysicsState } from './Video-Cym2C52L.js';
+import { D as DEFAULT_ENVIRONMENT_STATE, a as DEFAULT_POSTPROCESSING_STATE, E as Environment, b as EnvironmentFogState, c as EnvironmentFogType, d as EnvironmentGradientEffect, e as EnvironmentSkyboxState, f as EnvironmentSkyboxType, g as EnvironmentState, P as ParentId, h as Postprocessing, i as PostprocessingState, T as TransformComponent, j as TransformData, V as Vec3 } from './System-BeuJ1xt5.js';
 
 declare const index_AnimationComponent: typeof AnimationComponent;
 declare const index_AnimationComponentOptions: typeof AnimationComponentOptions;

package/dist/index.cjs

@@ -7948,6 +7948,24 @@ var _World = class _World {
     }
     return this.toEntityView(entityId);
   }
+  getEntitiesChildren(entityId) {
+    const children = [];
+    const entitiesWithParent = this.query(ParentId);
+    for (const childId of entitiesWithParent) {
+      const parentIdComponent = this.getComponent(childId, ParentId);
+      if (parentIdComponent?.value === entityId) {
+        children.push(this.toEntityView(childId));
+      }
+    }
+    return children;
+  }
+  getEntitiesParent(entityId) {
+    const parentIdComponent = this.getComponent(entityId, ParentId);
+    if (!parentIdComponent || parentIdComponent.value === null) {
+      return null;
+    }
+    return this.getEntityById(parentIdComponent.value);
+  }
   getObjectManagementSystem() {
     if (this.objectManagementSystem) return this.objectManagementSystem;
     const objectManagementSystem = this.systems.find(