@relu-interactives/spatial-ecs 0.2.13 → 0.2.15

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

@@ -7203,6 +7203,8 @@ var _AudioSystem = class _AudioSystem {
     this.prevPlayingState = /* @__PURE__ */ new Map();
     /** Snapshot of options applied in the previous frame, for change detection. */
     this.prevOptions = /* @__PURE__ */ new Map();
+    /** Tracks entities that were stopped due to invisibility. */
+    this.stoppedDueToInvisibility = /* @__PURE__ */ new Set();
     this.isEditor = isEditor;
   }
   update(world, _deltaTime) {
@@ -7214,12 +7216,21 @@ var _AudioSystem = class _AudioSystem {
       if (!component?.audio) continue;
       const sound = component.audio;
       if (!world.isEntityVisible(entityId)) {
-        if (sound.isPlaying) sound.stop();
+        if (sound.isPlaying) {
+          sound.stop();
+          this.stoppedDueToInvisibility.add(entityId);
+        }
         continue;
       }
+      if (this.stoppedDueToInvisibility.has(entityId)) {
+        this.stoppedDueToInvisibility.delete(entityId);
+        if (component.isPlaying && !sound.isPlaying && sound.buffer) {
+          sound.play();
+        }
+      }
       this._syncOptions(entityId, component, sound);
       const prevWasPlaying = this.prevPlayingState.get(entityId) ?? false;
-      if (prevWasPlaying && !sound.isPlaying && component.isPlaying && !component.isPaused) {
+      if (prevWasPlaying && !sound.isPlaying && component.isPlaying && !component.isPaused && !this.stoppedDueToInvisibility.has(entityId)) {
         component.isPlaying = false;
       }
       if (component.isPlaying && !sound.isPlaying) {
@@ -7239,6 +7250,7 @@ var _AudioSystem = class _AudioSystem {
       if (!liveEntityIds.has(entityId)) {
         this.prevPlayingState.delete(entityId);
         this.prevOptions.delete(entityId);
+        this.stoppedDueToInvisibility.delete(entityId);
       }
     }
   }
@@ -7271,6 +7283,7 @@ var _AudioSystem = class _AudioSystem {
   dispose(_world) {
     this.prevPlayingState.clear();
     this.prevOptions.clear();
+    this.stoppedDueToInvisibility.clear();
   }
 };
 __name(_AudioSystem, "AudioSystem");
@@ -7298,6 +7311,8 @@ var _VideoSystem = class _VideoSystem {
     this.prevIntent = /* @__PURE__ */ new Map();
     /** Snapshot of options applied in the previous frame, for change detection. */
     this.prevOptions = /* @__PURE__ */ new Map();
+    /** Tracks entities that were manually paused due to invisibility. */
+    this.pausedDueToInvisibility = /* @__PURE__ */ new Set();
     this.isEditor = isEditor;
   }
   update(world, _deltaTime) {
@@ -7309,12 +7324,22 @@ var _VideoSystem = class _VideoSystem {
       if (!component?.videoElement) continue;
       const video = component.videoElement;
       if (!world.isEntityVisible(entityId)) {
-        if (!video.paused) video.pause();
+        if (!video.paused) {
+          video.pause();
+          this.pausedDueToInvisibility.add(entityId);
+        }
         continue;
       }
+      if (this.pausedDueToInvisibility.has(entityId)) {
+        this.pausedDueToInvisibility.delete(entityId);
+        if (component.isPlaying && video.paused) {
+          video.play().catch(() => {
+          });
+        }
+      }
       this._syncOptions(entityId, component, video);
       const prev = this.prevIntent.get(entityId) ?? { isPlaying: false, isPaused: false };
-      if (prev.isPlaying && video.paused && !video.seeking && component.isPlaying && !component.isPaused) {
+      if (prev.isPlaying && video.paused && !video.seeking && component.isPlaying && !component.isPaused && !this.pausedDueToInvisibility.has(entityId)) {
         component.isPlaying = false;
       }
       const isStoppedNow = !component.isPlaying && !component.isPaused;
@@ -7346,6 +7371,7 @@ var _VideoSystem = class _VideoSystem {
       if (!liveEntityIds.has(entityId)) {
         this.prevIntent.delete(entityId);
         this.prevOptions.delete(entityId);
+        this.pausedDueToInvisibility.delete(entityId);
       }
     }
   }
@@ -7398,6 +7424,7 @@ var _VideoSystem = class _VideoSystem {
   dispose(_world) {
     this.prevIntent.clear();
     this.prevOptions.clear();
+    this.pausedDueToInvisibility.clear();
   }
 };
 __name(_VideoSystem, "VideoSystem");
@@ -7948,6 +7975,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(