@forgeax/engine-scene 0.0.0-dev.8d955ade1c79

package/src/__tests__/hierarchy-projection-contract.unit.test.ts

@@ -0,0 +1,45 @@
+import { World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Transform } from '../index';
+import { projectHierarchy, type SceneHierarchyDiagnostic } from '../systems';
+import { setMalformedParentEdge } from './fixtures/malformed-hierarchy-edge';
+
+describe('scene hierarchy projection contract', () => {
+  it('exposes stable parent edges and diagnostic detail without throwing', () => {
+    const world = new World();
+    const parent = world.spawn({ component: Transform, data: {} }).unwrap();
+    const child = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+      .unwrap();
+
+    const snapshot = projectHierarchy(world);
+
+    expect(snapshot.parentOf.get(child)).toBe(parent);
+    expect(snapshot.diagnostics).toEqual([]);
+  });
+
+  it('keeps every diagnostic machine-readable and deterministically ordered', () => {
+    const world = new World();
+    const first = world.spawn({ component: Transform, data: {} }).unwrap();
+    const second = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: first } })
+      .unwrap();
+    const third = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent: second } })
+      .unwrap();
+    setMalformedParentEdge(world, second, third);
+
+    const diagnostics: readonly SceneHierarchyDiagnostic[] = projectHierarchy(world).diagnostics;
+
+    expect(diagnostics.map((item) => item.detail.entity)).toEqual(
+      [...diagnostics.map((item) => item.detail.entity)].sort((a, b) => a - b),
+    );
+    for (const diagnostic of diagnostics) {
+      expect(['hierarchy-cycle', 'hierarchy-broken']).toContain(diagnostic.code);
+      expect(diagnostic.expected).toEqual(expect.any(String));
+      expect(diagnostic.hint).toEqual(expect.any(String));
+      expect(diagnostic.detail.entity).toEqual(expect.any(Number));
+      expect(diagnostic.detail.parent).toEqual(expect.any(Number));
+    }
+  });
+});

package/src/__tests__/hierarchy-projection.unit.test.ts

@@ -0,0 +1,92 @@
+import { type EntityHandle, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, Transform } from '../index';
+import { projectHierarchy } from '../systems';
+import { setMalformedParentEdge } from './fixtures/malformed-hierarchy-edge';
+
+function childOf(world: World, parent: EntityHandle): EntityHandle {
+  return world
+    .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+    .unwrap();
+}
+
+describe('scene hierarchy projection', () => {
+  it('keeps a live parent edge even when the parent has no Transform', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = childOf(world, parent);
+
+    const snapshot = projectHierarchy(world);
+
+    expect(snapshot.getParent(child)).toBe(parent);
+    expect(snapshot.diagnostics).toEqual([]);
+  });
+
+  it('cuts a stale parent edge and reports a machine-readable diagnostic', () => {
+    const world = new World();
+    const parent = world.spawn().unwrap();
+    const child = childOf(world, parent);
+    const staleParent = world.spawn().unwrap();
+    world.despawn(staleParent).unwrap();
+    setMalformedParentEdge(world, child, staleParent);
+
+    const snapshot = projectHierarchy(world);
+    const diagnostic = snapshot.diagnostics[0];
+
+    expect(snapshot.getParent(child)).toBeUndefined();
+    expect(diagnostic?.code).toBe('hierarchy-broken');
+    expect(diagnostic?.detail.entity).toBe(child);
+    expect(diagnostic?.detail.parent).toBe(staleParent);
+    expect(diagnostic?.expected).toContain('live entity');
+    expect(diagnostic?.hint.length).toBeGreaterThan(0);
+  });
+
+  it('terminates self and multi-member cycles and sorts diagnostics by entity', () => {
+    const world = new World();
+    const self = childOf(world, world.spawn().unwrap());
+    const a = childOf(world, world.spawn().unwrap());
+    const b = childOf(world, world.spawn().unwrap());
+    const c = childOf(world, world.spawn().unwrap());
+    setMalformedParentEdge(world, self, self);
+    setMalformedParentEdge(world, a, b);
+    setMalformedParentEdge(world, b, c);
+    setMalformedParentEdge(world, c, a);
+
+    const snapshot = projectHierarchy(world);
+    const cycleDiagnostics = snapshot.diagnostics.filter((item) => item.code === 'hierarchy-cycle');
+    const diagnosticEntities = cycleDiagnostics.map((item) => item.detail.entity);
+
+    expect(snapshot.getParent(self)).toBeUndefined();
+    expect(snapshot.getParent(a)).toBeUndefined();
+    expect(snapshot.getParent(b)).toBeUndefined();
+    expect(snapshot.getParent(c)).toBeUndefined();
+    expect(cycleDiagnostics).toHaveLength(4);
+    expect(diagnosticEntities).toEqual([...diagnosticEntities].sort((x, y) => x - y));
+    expect(cycleDiagnostics.every((item) => item.detail.parent !== undefined)).toBe(true);
+  });
+
+  it('does not invent a parent edge for a root entity', () => {
+    const world = new World();
+    const root = world.spawn().unwrap();
+
+    expect(projectHierarchy(world).getParent(root)).toBeUndefined();
+  });
+
+  it('reuses a stable World projection and invalidates it after a hierarchy mutation', () => {
+    const world = new World();
+    const firstParent = world.spawn().unwrap();
+    const secondParent = world.spawn().unwrap();
+    const child = childOf(world, firstParent);
+
+    const first = projectHierarchy(world);
+    expect(projectHierarchy(world)).toBe(first);
+    expect(first.getParent(child)).toBe(firstParent);
+
+    world.set(child, ChildOf, { parent: secondParent }).unwrap();
+
+    const second = projectHierarchy(world);
+    expect(second).not.toBe(first);
+    expect(second.getParent(child)).toBe(secondParent);
+    expect(projectHierarchy(world)).toBe(second);
+  });
+});

package/src/__tests__/plugin.integration.test.ts

@@ -0,0 +1,23 @@
+import { createWorldContext, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, scenePlugin, Transform } from '../index';
+
+describe('scenePlugin', () => {
+  it('installs propagation without render or animation capabilities', async () => {
+    const world = new World();
+    const ctx = await createWorldContext(world, [scenePlugin()]);
+    const root = world.spawn({ component: Transform, data: { pos: [4, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [1, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    world.update(1 / 60).unwrap();
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+    await ctx.fiber.dispose();
+    expect(world.inspect().systems.some((system) => system.name === 'propagateTransforms')).toBe(
+      false,
+    );
+  });
+});

package/src/__tests__/propagation.unit.test.ts

@@ -0,0 +1,163 @@
+import { FixedUpdate, Update, World } from '@forgeax/engine-ecs';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, propagateTransforms, Transform } from '../index';
+import { registerPropagateTransforms } from '../systems';
+
+describe('scene propagation', () => {
+  it('registers ordinary transform owners without exposing terminal publication as a schedule', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+
+    expect(
+      world
+        .inspect()
+        .schedules.find((entry) => entry.schedule === Update)
+        ?.systems.map((system) => system.name),
+    ).toContain('propagateTransforms');
+    expect(
+      world
+        .inspect()
+        .schedules.find((entry) => entry.schedule === FixedUpdate)
+        ?.systems.map((system) => system.name),
+    ).toContain('propagateTransformsFixed');
+    expect(world.inspect().schedules.map((entry) => entry.schedule.name)).not.toContain(
+      'FramePublish',
+    );
+  });
+  it('propagates a root and child in a headless world', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    expect(world.update(1 / 60).ok).toBe(true);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+  });
+
+  it('cascades linked children when a parent is despawned', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const parent = world.spawn({ component: Transform, data: {} }).unwrap();
+    const child = world
+      .spawn({ component: Transform, data: {} }, { component: ChildOf, data: { parent } })
+      .unwrap();
+    world.despawn(parent);
+    const result = world.update(1 / 60);
+    expect(result.ok).toBe(true);
+    expect(world.get(child, Transform).ok).toBe(false);
+  });
+
+  it('keeps equal entity handles isolated across Worlds', () => {
+    const first = new World();
+    const second = new World();
+    const firstRoot = first.spawn({ component: Transform, data: { pos: [3, 0, 0] } }).unwrap();
+    const secondRoot = second.spawn({ component: Transform, data: { pos: [7, 0, 0] } }).unwrap();
+
+    expect(firstRoot).toBe(secondRoot);
+    expect(propagateTransforms(first).ok).toBe(true);
+    expect(propagateTransforms(second).ok).toBe(true);
+    expect(first.get(firstRoot, Transform).unwrap().world[12]).toBeCloseTo(3);
+    expect(second.get(secondRoot, Transform).unwrap().world[12]).toBeCloseTo(7);
+  });
+
+  it('reuses a stable propagation result and invalidates it after a local edit', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+
+    const first = propagateTransforms(world);
+    const second = propagateTransforms(world);
+    expect(first).toBe(second);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(5);
+
+    world.set(root, Transform, { pos: [7, 0, 0] }).unwrap();
+    const third = propagateTransforms(world);
+    expect(third).not.toBe(second);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+  });
+
+  it('incrementally recomputes an edited transform and its descendants', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const grandchild = world
+      .spawn(
+        { component: Transform, data: { pos: [4, 0, 0] } },
+        { component: ChildOf, data: { parent: child } },
+      )
+      .unwrap();
+    const sibling = world.spawn({ component: Transform, data: { pos: [20, 0, 0] } }).unwrap();
+
+    propagateTransforms(world).unwrap();
+    world.set(child, Transform, { pos: [8, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+
+    expect(world.get(root, Transform).unwrap().world[12]).toBeCloseTo(2);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+    expect(world.get(grandchild, Transform).unwrap().world[12]).toBeCloseTo(14);
+    expect(world.get(sibling, Transform).unwrap().world[12]).toBeCloseTo(20);
+  });
+
+  it('expands a generic ChildOf mutation from the validated hierarchy snapshot', () => {
+    const world = new World();
+    const firstParent = world.spawn({ component: Transform, data: { pos: [10, 0, 0] } }).unwrap();
+    const secondParent = world.spawn({ component: Transform, data: { pos: [100, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [1, 0, 0] } },
+        { component: ChildOf, data: { parent: firstParent } },
+      )
+      .unwrap();
+    const grandchild = world
+      .spawn(
+        { component: Transform, data: { pos: [2, 0, 0] } },
+        { component: ChildOf, data: { parent: child } },
+      )
+      .unwrap();
+
+    propagateTransforms(world).unwrap();
+    world.set(child, ChildOf, { parent: secondParent }).unwrap();
+    propagateTransforms(world).unwrap();
+
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(101);
+    expect(world.get(grandchild, Transform).unwrap().world[12]).toBeCloseTo(103);
+  });
+
+  it('publishes transform writes when propagation is explicitly ordered after gameplay', () => {
+    const world = new World();
+    registerPropagateTransforms(world);
+    const root = world.spawn({ component: Transform, data: { pos: [2, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    world
+      .addSystem(Update, {
+        name: 'late-pose',
+        before: ['propagateTransforms'],
+        queries: [],
+        fn: () => world.set(child, Transform, { pos: [8, 0, 0] }),
+      })
+      .unwrap();
+
+    world.update(0).unwrap();
+
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(10);
+  });
+});

package/src/__tests__/transform-change-journal.unit.test.ts

@@ -0,0 +1,105 @@
+import { World } from '@forgeax/engine-ecs';
+import { createWorldProjection } from '@forgeax/engine-ecs/projection';
+import { describe, expect, it } from 'vitest';
+import { ChildOf, propagateTransforms, Transform } from '../index';
+
+describe('transform change journal', () => {
+  it('drains a large derived publication without rebuilding on the next pass', () => {
+    const world = new World();
+    for (let index = 0; index <= 65_536; index += 1) {
+      world.spawn({ component: Transform, data: {} }).unwrap();
+    }
+
+    const first = propagateTransforms(world);
+    const second = propagateTransforms(world);
+
+    expect(second).toBe(first);
+  });
+
+  it('publishes exactly the recomputed subtree and stays empty on no-change propagation', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: { pos: [1, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [2, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+    const grandchild = world
+      .spawn(
+        { component: Transform, data: { pos: [3, 0, 0] } },
+        { component: ChildOf, data: { parent: child } },
+      )
+      .unwrap();
+    const sibling = world.spawn({ component: Transform, data: { pos: [4, 0, 0] } }).unwrap();
+
+    propagateTransforms(world).unwrap();
+    const projection = createWorldProjection(world, { components: [Transform] });
+    projection.poll();
+    propagateTransforms(world).unwrap();
+    expect(projection.poll()).toEqual({ status: 'delta', cursor: projection.cursor, changes: [] });
+
+    world.set(child, Transform, { pos: [8, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+    const changed = projection.poll();
+    expect(changed.status).toBe('delta');
+    if (changed.status !== 'delta') return;
+    expect(
+      changed.changes
+        .filter(
+          (record) => record.kind === 'derived-component-changed' && record.component === Transform,
+        )
+        .map((record) => record.entity),
+    ).toEqual([child, grandchild]);
+    expect(changed.changes.some((record) => record.entity === sibling)).toBe(false);
+  });
+
+  it('does not propagate again from derived Transform records', () => {
+    const world = new World();
+    world.spawn({ component: Transform, data: { pos: [1, 0, 0] } }).unwrap();
+
+    propagateTransforms(world).unwrap();
+    const projection = createWorldProjection(world, { components: [Transform] });
+    projection.poll();
+
+    propagateTransforms(world).unwrap();
+
+    expect(projection.poll()).toEqual({ status: 'delta', cursor: projection.cursor, changes: [] });
+  });
+
+  it('uses the final authored Transform state and skips an unchanged final state', () => {
+    const world = new World();
+    const root = world.spawn({ component: Transform, data: { pos: [1, 0, 0] } }).unwrap();
+    const child = world
+      .spawn(
+        { component: Transform, data: { pos: [2, 0, 0] } },
+        { component: ChildOf, data: { parent: root } },
+      )
+      .unwrap();
+
+    propagateTransforms(world).unwrap();
+    const projection = createWorldProjection(world, { components: [Transform] });
+    projection.poll();
+
+    world.set(root, Transform, { pos: [5, 0, 0] }).unwrap();
+    world.set(root, Transform, { pos: [1, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+    const unchanged = projection.poll();
+    expect(unchanged.status).toBe('delta');
+    if (unchanged.status !== 'delta') return;
+    expect(
+      unchanged.changes.filter((record) => record.kind === 'derived-component-changed'),
+    ).toEqual([]);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(3);
+
+    world.set(root, Transform, { pos: [5, 0, 0] }).unwrap();
+    world.set(root, Transform, { pos: [7, 0, 0] }).unwrap();
+    propagateTransforms(world).unwrap();
+    const changed = projection.poll();
+    expect(changed.status).toBe('delta');
+    if (changed.status !== 'delta') return;
+    const derived = changed.changes.filter((record) => record.kind === 'derived-component-changed');
+    expect(derived.map((record) => record.entity)).toEqual([root, child]);
+    expect(world.get(child, Transform).unwrap().world[12]).toBeCloseTo(9);
+  });
+});

package/src/assets/scene-decoder.ts

@@ -0,0 +1,153 @@
+import {
+  type AssetDecoder,
+  type AssetDecoderContribution,
+  type AssetKind,
+  type AssetLoadError,
+  err,
+  ok,
+  type Result,
+  type SceneAsset,
+  type SceneEntity,
+  type SceneInstanceMount,
+} from '@forgeax/engine-types';
+
+export const sceneAssetKind: AssetKind<SceneAsset, 'scene'> = {
+  kind: 'scene',
+} as AssetKind<SceneAsset, 'scene'>;
+
+function invalidScene(guid: string, reason: string): Result<SceneAsset, AssetLoadError> {
+  return err({
+    code: 'asset-package-invalid',
+    expected: 'a scene payload with an entities array',
+    hint: 'recook the SceneAsset and publish its complete envelope',
+    detail: { guid, reason },
+  });
+}
+
+type SceneWireRefResult =
+  | { readonly ok: true; readonly value: SceneAsset }
+  | { readonly ok: false; readonly reason: string };
+
+// The Pack envelope owns refs[] while the decoded SceneAsset remains the
+// portable payload. Keep that wire-only fact beside the decoded object so the
+// World-local projection can interpret shared-field indices without putting a
+// component registry or World into the decoder contract.
+const sceneWireRefs = new WeakMap<object, readonly string[]>();
+
+/** @internal Read the Pack refs[] retained for a decoded SceneAsset payload. */
+export function sceneAssetWireRefs(asset: SceneAsset): readonly string[] | undefined {
+  return sceneWireRefs.get(asset);
+}
+
+function resolveWireRef(
+  refs: readonly string[],
+  value: number,
+  location: string,
+): { readonly ok: true; readonly value: string } | { readonly ok: false; readonly reason: string } {
+  const guid = refs[value];
+  if (!Number.isInteger(value) || value < 0 || guid === undefined) {
+    return {
+      ok: false,
+      reason: `${location} references refs[${value}], but refs contains ${refs.length} entries`,
+    };
+  }
+  return { ok: true, value: guid };
+}
+
+function resolveMounts(
+  mounts: readonly SceneInstanceMount[] | undefined,
+  refs: readonly string[],
+):
+  | { readonly ok: true; readonly value: readonly SceneInstanceMount[] | undefined }
+  | { readonly ok: false; readonly reason: string } {
+  if (mounts === undefined) return { ok: true, value: undefined };
+  const resolved: SceneInstanceMount[] = [];
+  for (const mount of mounts) {
+    if (typeof mount.source !== 'number' || !Number.isInteger(mount.source)) {
+      resolved.push(mount);
+      continue;
+    }
+    const ref = resolveWireRef(refs, mount.source, `mount ${mount.localId} source`);
+    if (!ref.ok) return ref;
+    resolved.push({ ...mount, source: ref.value });
+  }
+  return { ok: true, value: resolved };
+}
+
+function resolveSkinGuids(
+  skinGuids: readonly (number | string)[] | undefined,
+  refs: readonly string[],
+):
+  | { readonly ok: true; readonly value: readonly string[] | undefined }
+  | { readonly ok: false; readonly reason: string } {
+  if (skinGuids === undefined) return { ok: true, value: undefined };
+  const resolved: string[] = [];
+  for (let index = 0; index < skinGuids.length; index += 1) {
+    const value = skinGuids[index];
+    if (typeof value === 'string') {
+      resolved.push(value);
+      continue;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value)) {
+      return { ok: false, reason: `skinGuids[${index}] is not a GUID or refs index` };
+    }
+    const ref = resolveWireRef(refs, value, `skinGuids[${index}]`);
+    if (!ref.ok) return ref;
+    resolved.push(ref.value);
+  }
+  return { ok: true, value: resolved };
+}
+
+function resolveSceneWireRefs(payload: SceneAsset, refs: readonly string[]): SceneWireRefResult {
+  const entities: SceneEntity[] = [];
+  for (const entity of payload.entities) {
+    const components: Record<string, Record<string, unknown>> = {};
+    for (const [componentName, rawFields] of Object.entries(entity.components)) {
+      // Component schema lookup is World-local after the ECS core reduction.
+      // The runtime projection owns the World-local schema and converts
+      // authored GUID fields into World.sharedRefs handles. Keep this loader
+      // boundary POD-only instead of consulting a removed process-global ECS
+      // component registry.
+      components[componentName] = { ...(rawFields as Record<string, unknown>) };
+    }
+    entities.push({ localId: entity.localId, components });
+  }
+
+  const mounts = resolveMounts(payload.mounts, refs);
+  if (!mounts.ok) return mounts;
+  const skinGuids = resolveSkinGuids(
+    payload.skinGuids as readonly (number | string)[] | undefined,
+    refs,
+  );
+  if (!skinGuids.ok) return skinGuids;
+
+  return {
+    ok: true,
+    value: {
+      kind: 'scene',
+      entities,
+      ...(mounts.value === undefined ? {} : { mounts: mounts.value }),
+      ...(skinGuids.value === undefined ? {} : { skinGuids: skinGuids.value }),
+    },
+  };
+}
+
+/** Scene owns structural validation; World-local projection resolves shared refs. */
+export const sceneAssetDecoder: AssetDecoder<SceneAsset> = {
+  async decode({ envelope }): Promise<Result<SceneAsset, AssetLoadError>> {
+    const payload = envelope.payload;
+    if (payload.kind !== 'scene' || !Array.isArray(payload.entities)) {
+      return invalidScene(envelope.guid, 'scene payload is missing entities');
+    }
+    const resolved = resolveSceneWireRefs(payload, envelope.refs);
+    if (!resolved.ok) return invalidScene(envelope.guid, resolved.reason);
+    sceneWireRefs.set(resolved.value, Object.freeze([...envelope.refs]));
+    return ok(resolved.value);
+  },
+};
+
+export const sceneAssetContribution: AssetDecoderContribution<SceneAsset, 'scene'> = {
+  kind: sceneAssetKind,
+  decoder: sceneAssetDecoder,
+  consumer: 'Scene',
+};

package/src/collect-subtree.ts

@@ -0,0 +1,30 @@
+// Scene-owned hierarchy traversal shared by scene collection and render hooks.
+
+import type { EntityHandle, World } from '@forgeax/engine-ecs';
+
+import { Children } from './components/children';
+
+/** Walk a Children hierarchy breadth-first, reusing an optional visited set. */
+export function collectSubtree(
+  world: World,
+  spawnRoot: EntityHandle,
+  visited?: Set<number>,
+): Set<number> {
+  if (visited === undefined) visited = new Set<number>();
+  if (visited.has(spawnRoot as number)) return visited;
+  const queue: number[] = [spawnRoot as number];
+  visited.add(spawnRoot as number);
+  while (queue.length > 0) {
+    const current = queue.shift() as number;
+    const children = world.get(current as EntityHandle, Children);
+    if (!children.ok) continue;
+    const entities = children.value.entities as ArrayLike<number>;
+    for (let index = 0; index < entities.length; index += 1) {
+      const child = entities[index] as number;
+      if (visited.has(child)) continue;
+      visited.add(child);
+      queue.push(child);
+    }
+  }
+  return visited;
+}