@codehz/ecs 0.8.1 → 0.9.0

package/src/world/world.ts

@@ -1,5 +1,5 @@
 import { Archetype } from "../archetype/archetype";
-import { DontFragmentStoreImpl } from "../archetype/store";
+import { SparseStoreImpl } from "../archetype/store";
 import { CommandBuffer, type Command } from "../commands/buffer";
 import { ComponentChangeset } from "../commands/changeset";
 import { ComponentEntityStore } from "../component/entity-store";
@@ -13,17 +13,26 @@ import {
   getDetailedIdType,
   getTargetIdFromRelationId,
   isCascadeDeleteRelation,
-  isDontFragmentRelation,
-  isDontFragmentWildcard,
   isEntityRelation,
   isExclusiveComponent,
+  isSparseRelation,
+  isSparseWildcard,
   isWildcardRelationId,
+  relation,
 } from "../entity";
 import { matchesFilter, serializeQueryFilter, type QueryFilter } from "../query/filter";
 import type { Query } from "../query/query";
 import { QueryRegistry } from "../query/registry";
 import type { SerializedWorld } from "../storage/serialization";
-import type { ComponentTuple, ComponentType, LifecycleCallback, LifecycleHook, LifecycleHookEntry } from "../types";
+import type {
+  ComponentTuple,
+  ComponentType,
+  DebugStatsCollector,
+  LifecycleCallback,
+  LifecycleHook,
+  LifecycleHookEntry,
+  SyncDebugStats,
+} from "../types";
 import { isOptionalEntityId } from "../types";
 import { getOrCompute } from "../utils/utils";
 import { EntityBuilder } from "./builder";
@@ -37,6 +46,7 @@ import {
 } from "./commands";
 import {
   collectMultiHookComponents,
+  debugHookExecutionCounter,
   triggerLifecycleHooks,
   triggerRemoveHooksForEntityDeletion,
   type HooksContext,
@@ -63,8 +73,8 @@ export class World {
   private entityReferences: EntityReferencesMap = new Map();
   /** Reverse index: entity ID → set of archetypes whose componentTypes include that entity ID */
   private entityToReferencingArchetypes = new Map<EntityId, Set<Archetype>>();
-  /** DontFragment relation storage, shared with all Archetype instances */
-  private readonly dontFragmentStore = new DontFragmentStoreImpl();
+  /** Sparse relation storage (for components created with `sparse: true`), shared with all Archetype instances */
+  private readonly sparseStore = new SparseStoreImpl();
   /** Component entity (singleton) storage */
   private readonly componentEntities = new ComponentEntityStore();
 
@@ -74,6 +84,14 @@ export class World {
   // Lifecycle hooks (declared before cached contexts that reference them)
   private hooks: Set<LifecycleHookEntry> = new Set();
 
+  // Debug observability collectors (armed only when non-empty)
+  private readonly _debugCollectors = new Set<(stats: SyncDebugStats) => void>();
+
+  // Transient counters for the current armed sync (reset each time)
+  private _debugMigrations = 0;
+  private _debugArchetypesCreated = 0;
+  private _debugArchetypesRemoved = 0;
+
   // Command execution
   private commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
 
@@ -82,7 +100,7 @@ export class World {
   private readonly _removeChangeset = new ComponentChangeset();
   /** Cached command processor context to avoid per-entity object allocation */
   private readonly _commandCtx: CommandProcessorContext = {
-    dontFragmentStore: this.dontFragmentStore,
+    sparseStore: this.sparseStore,
     ensureArchetype: (ct) => this.ensureArchetype(ct),
   };
   /** Cached hooks context to avoid per-entity object allocation */
@@ -198,7 +216,7 @@ export class World {
         }
       }
 
-      // Remove entity from archetype - this also cleans up dontFragment relations
+      // Remove entity from archetype - this also cleans up sparse relations
       // and returns all removed component data
       this.entityReferences.delete(cur);
       const removedComponents = archetype.removeEntity(cur)!;
@@ -443,11 +461,11 @@ export class World {
 
     if (archetype.componentTypeSet.has(componentType)) return true;
 
-    if (isDontFragmentRelation(componentType)) {
+    if (isSparseRelation(componentType)) {
       // Use getValue; presence check via getAllForEntity only if value can legitimately be undefined
-      const val = this.dontFragmentStore.getValue(entityId, componentType);
+      const val = this.sparseStore.getValue(entityId, componentType);
       if (val !== undefined) return true;
-      return this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType);
+      return this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType);
     }
 
     return false;
@@ -495,12 +513,12 @@ export class World {
 
     if (componentType >= 0 || componentType % RELATION_SHIFT !== 0) {
       const inArchetype = archetype.componentTypeSet.has(componentType);
-      const hasDontFragment = isDontFragmentRelation(componentType);
+      const hasSparse = isSparseRelation(componentType);
       const hasComponent =
         inArchetype ||
-        (hasDontFragment &&
-          (this.dontFragmentStore.getValue(entityId, componentType) !== undefined ||
-            this.dontFragmentStore.getAllForEntity(entityId).some(([t]) => t === componentType)));
+        (hasSparse &&
+          (this.sparseStore.getValue(entityId, componentType) !== undefined ||
+            this.sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)));
 
       if (!hasComponent) {
         throw new Error(
@@ -571,6 +589,213 @@ export class World {
     return archetype.getOptional(entityId, componentType);
   }
 
+  // ==========================================================================
+  // Relation & Hierarchy Companion Tools (public API)
+  // ==========================================================================
+
+  /**
+   * Retrieves all targets (and their associated data) for relations of a given
+   * base component on an entity.
+   *
+   * This is the ergonomic replacement for the common pattern:
+   *   world.get(entity, relation(Comp, "*"))
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const children = world.getRelationTargets(parent, ChildOf); // usually []
+   * const items = world.getRelationTargets(player, InInventory);
+   *
+   * // For common hierarchy use cases, prefer the higher-level helpers:
+   * // world.getChildren(parent, ChildOf), world.getParent(child, ChildOf)
+   */
+  getRelationTargets<T = void>(
+    entityId: EntityId,
+    relationComp: ComponentId<T>,
+  ): [target: EntityId<unknown>, data: T | undefined][] {
+    this.assertEntityExists(entityId, "Entity");
+
+    const wildcard = relation(relationComp, "*") as WildcardRelationId<T>;
+
+    // For component entities (singletons) the path is different; they rarely host relations
+    if (this.componentEntities.exists(entityId)) {
+      return this.componentEntities.getWildcard(entityId, wildcard);
+    }
+
+    // Regular entity path — archetype.get for wildcard always materializes the array
+    // (even if empty for a sparse relation that only has the marker)
+    const data = this.get(entityId, wildcard);
+    return data as [EntityId<unknown>, T | undefined][];
+  }
+
+  /**
+   * Returns every entity that currently holds a relation of the given base
+   * component pointing at `targetId`.
+   *
+   * This is the efficient **reverse** lookup. For common hierarchy cases,
+   * prefer the higher-level `world.getChildren(parent, ChildOf)` instead.
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const directChildren = world.getRelationSources(ship, ChildOf);
+   */
+  getRelationSources(targetId: EntityId, relationComp: ComponentId<any>): EntityId[] {
+    const refs = getEntityReferences(this.entityReferences, targetId);
+    const result: EntityId[] = [];
+
+    for (const [source, relType] of refs) {
+      // Only consider still-living sources
+      if (!this.entityToArchetype.has(source) && !this.componentEntities.exists(source)) continue;
+
+      const decodedComp = getComponentIdFromRelationId(relType);
+      if (decodedComp === relationComp) {
+        result.push(source);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Returns true if the entity has any (or a specific-target) relation of the
+   * given base component.
+   */
+  hasRelation(entityId: EntityId, relationComp: ComponentId<any>, targetId?: EntityId): boolean {
+    this.assertEntityExists(entityId, "Entity");
+
+    if (targetId !== undefined) {
+      const specific = relation(relationComp, targetId);
+      return this.has(entityId, specific);
+    }
+
+    // Any target of this relation kind?
+    const targets = this.getRelationTargets(entityId, relationComp);
+    return targets.length > 0;
+  }
+
+  /**
+   * Returns the number of relations of the given base component held by the entity.
+   */
+  countRelations(entityId: EntityId, relationComp: ComponentId<any>): number {
+    this.assertEntityExists(entityId, "Entity");
+    const targets = this.getRelationTargets(entityId, relationComp);
+    return targets.length;
+  }
+
+  /**
+   * For an *exclusive* relation (e.g. ChildOf, Owner), returns the single
+   * target entity (or undefined if none).
+   *
+   * When the component was declared `exclusive: true`, this is the preferred
+   * accessor (clearer intent than array destructuring).
+   */
+  getSingleRelationTarget<T = void>(entityId: EntityId, relationComp: ComponentId<T>): EntityId | undefined {
+    const targets = this.getRelationTargets(entityId, relationComp);
+    return targets.length > 0 ? (targets[0]![0] as EntityId) : undefined;
+  }
+
+  // --------------------------------------------------------------------------
+  // High-level hierarchy helpers (convenience methods on World)
+  // --------------------------------------------------------------------------
+
+  /**
+   * Returns the direct children of `parent` for the given relationship component
+   * (typically a `ChildOf` or similar exclusive `sparse` relation).
+   *
+   * This is the recommended high-level API for hierarchy traversal.
+   * It uses the internal reverse reference index for efficiency.
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const kids = world.getChildren(ship, ChildOf);
+   */
+  getChildren(parent: EntityId, childOf: ComponentId<any>): EntityId[] {
+    return this.getRelationSources(parent, childOf);
+  }
+
+  /**
+   * Returns the parent of `child` for the given relationship component
+   * (typically an exclusive `ChildOf` relation).
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const parent = world.getParent(turret, ChildOf);
+   */
+  getParent(child: EntityId, childOf: ComponentId<any>): EntityId | undefined {
+    return this.getSingleRelationTarget(child, childOf);
+  }
+
+  /**
+   * Returns the ancestor chain from the immediate parent up to (but not
+   * including) the root for the given relationship component.
+   *
+   * @example
+   * const ChildOf = component({ exclusive: true, sparse: true });
+   * const ancestors = world.getAncestors(muzzle, ChildOf); // [turret, ship]
+   */
+  getAncestors(entity: EntityId, childOf: ComponentId<any>): EntityId[] {
+    const ancestors: EntityId[] = [];
+    let cur = this.getParent(entity, childOf);
+    while (cur !== undefined) {
+      ancestors.push(cur);
+      cur = this.getParent(cur, childOf);
+    }
+    return ancestors;
+  }
+
+  /**
+   * Iteratively traverses all descendants of `root` in DFS pre-order.
+   * This is a generator and is safe for very deep hierarchies.
+   *
+   * @example
+   * for (const { entity, depth, parent } of world.iterateDescendants(root, ChildOf)) {
+   *   console.log(depth, entity);
+   * }
+   */
+  *iterateDescendants(
+    root: EntityId,
+    childOf: ComponentId<any>,
+    opts: { includeSelf?: boolean; maxDepth?: number } = {},
+  ): IterableIterator<{ entity: EntityId; depth: number; parent: EntityId | null }> {
+    const { includeSelf = false, maxDepth } = opts;
+    const stack: Array<{ entity: EntityId; depth: number; parent: EntityId | null }> = [];
+
+    if (includeSelf) {
+      stack.push({ entity: root, depth: 0, parent: null });
+    } else {
+      for (const child of this.getChildren(root, childOf)) {
+        stack.push({ entity: child, depth: 1, parent: root });
+      }
+    }
+
+    while (stack.length > 0) {
+      const current = stack.pop()!;
+      if (maxDepth !== undefined && current.depth > maxDepth) continue;
+
+      yield current;
+
+      const kids = this.getChildren(current.entity, childOf);
+      for (let i = kids.length - 1; i >= 0; i--) {
+        const k = kids[i]!;
+        stack.push({ entity: k, depth: current.depth + 1, parent: current.entity });
+      }
+    }
+  }
+
+  /**
+   * Callback-based descendant traversal (hot path friendly).
+   * Return `false` from the visitor to stop early.
+   */
+  traverseDescendants(
+    root: EntityId,
+    childOf: ComponentId<any>,
+    visitor: (entity: EntityId, depth: number, parent: EntityId | null) => void | boolean,
+    opts: { includeSelf?: boolean; maxDepth?: number } = {},
+  ): void {
+    for (const { entity, depth, parent } of this.iterateDescendants(root, childOf, opts)) {
+      const res = visitor(entity, depth, parent);
+      if (res === false) return;
+    }
+  }
+
   /**
    * Registers a lifecycle hook that responds to component changes.
    * The hook callback is invoked when components matching the specified types are added, updated, or removed.
@@ -684,6 +909,103 @@ export class World {
     };
   }
 
+  /**
+   * Creates a debug stats collector that will receive a `SyncDebugStats` payload
+   * after every subsequent `sync()`.
+   *
+   * The returned object is a pure lifecycle handle. It does not store data.
+   * Collection stops when you call `[Symbol.dispose]()` (or use a `using` declaration).
+   *
+   * All active collectors receive the exact same stats object for a given sync.
+   * Exceptions thrown by callbacks are ignored.
+   *
+   * This is intended for development/debugging and leak detection.
+   */
+  createDebugStatsCollector(callback: (stats: SyncDebugStats) => void): DebugStatsCollector {
+    this._debugCollectors.add(callback);
+
+    return {
+      [Symbol.dispose]: () => {
+        this._debugCollectors.delete(callback);
+      },
+    };
+  }
+
+  private _resetDebugActivityCounters(): void {
+    this._debugMigrations = 0;
+    this._debugArchetypesCreated = 0;
+    this._debugArchetypesRemoved = 0;
+    debugHookExecutionCounter.value = 0;
+  }
+
+  private _deliverDebugStats(timings: {
+    syncStart: number;
+    syncEnd: number;
+    commandBufferStart: number;
+    commandBufferEnd: number;
+    commandIterations: number;
+  }): void {
+    // Build structural counts (post-sync)
+    // Note: singletons (component-as-entity) are not included in the main archetype map.
+    // For debug purposes the dominant number is regular entities; we keep it simple here.
+    const entityCount = this.entityToArchetype.size;
+    let emptyArchetypes = 0;
+    for (const arch of this.archetypes) {
+      if (arch.size === 0) emptyArchetypes++;
+    }
+
+    let archetypesByComponentSize = 0;
+    for (const set of this.archetypesByComponent.values()) {
+      archetypesByComponentSize += set.size;
+    }
+
+    const stats: SyncDebugStats = {
+      timestamps: {
+        syncStart: timings.syncStart,
+        syncEnd: timings.syncEnd,
+        commandBufferStart: timings.commandBufferStart,
+        commandBufferEnd: timings.commandBufferEnd,
+      },
+      commandIterations: timings.commandIterations,
+
+      entities: {
+        total: entityCount,
+        freelistSize: this.entityIdManager.getFreelistSize(),
+        nextId: this.entityIdManager.getNextId(),
+      },
+      archetypes: {
+        total: this.archetypes.length,
+        empty: emptyArchetypes,
+      },
+      queries: {
+        cached: (this.queryRegistry as any).cache?.size ?? 0,
+        registered: (this.queryRegistry as any).queries?.size ?? 0,
+      },
+      hooks: {
+        total: this.hooks.size,
+      },
+      indices: {
+        entityReferences: this.entityReferences.size,
+        entityToReferencingArchetypes: this.entityToReferencingArchetypes.size,
+        archetypesByComponent: archetypesByComponentSize,
+      },
+      activity: {
+        migrations: this._debugMigrations,
+        hooksExecuted: debugHookExecutionCounter.value,
+        archetypesCreated: this._debugArchetypesCreated,
+        archetypesRemoved: this._debugArchetypesRemoved,
+      },
+    };
+
+    for (const cb of this._debugCollectors) {
+      try {
+        cb(stats);
+      } catch {
+        // Intentionally ignore user callback errors
+      }
+    }
+  }
+
   /**
    * Synchronizes all buffered commands (set/remove/delete) to the world.
    * This method must be called after making changes via `set()`, `remove()`, or `delete()` for them to take effect.
@@ -695,7 +1017,29 @@ export class World {
    * world.sync(); // Apply all buffered changes
    */
   sync(): void {
-    this.commandBuffer.execute();
+    const hasCollectors = this._debugCollectors.size > 0;
+
+    const syncStart = hasCollectors ? performance.now() : 0;
+
+    if (hasCollectors) {
+      this._resetDebugActivityCounters();
+    }
+
+    const commandBufferStart = hasCollectors ? performance.now() : 0;
+    const commandIterations = this.commandBuffer.execute();
+    const commandBufferEnd = hasCollectors ? performance.now() : 0;
+
+    const syncEnd = hasCollectors ? performance.now() : 0;
+
+    if (hasCollectors) {
+      this._deliverDebugStats({
+        syncStart,
+        syncEnd,
+        commandBufferStart,
+        commandBufferEnd,
+        commandIterations,
+      });
+    }
   }
 
   /**
@@ -958,10 +1302,20 @@ export class World {
 
     if (this.hooks.size === 0) {
       // Fast path: no hooks, skip removedComponents map allocation and hook triggering
-      applyChangeset(this._commandCtx, entityId, currentArchetype, changeset, this.entityToArchetype, null);
+      const newArchetype = applyChangeset(
+        this._commandCtx,
+        entityId,
+        currentArchetype,
+        changeset,
+        this.entityToArchetype,
+        null,
+      );
       if (hasStructuralChange) {
         this.updateEntityReferences(entityId, changeset);
       }
+      if (this._debugCollectors.size > 0 && newArchetype !== currentArchetype) {
+        this._debugMigrations++;
+      }
       return;
     }
 
@@ -978,6 +1332,11 @@ export class World {
     if (hasStructuralChange) {
       this.updateEntityReferences(entityId, changeset);
     }
+
+    if (this._debugCollectors.size > 0 && newArchetype !== currentArchetype) {
+      this._debugMigrations++;
+    }
+
     triggerLifecycleHooks(
       this.createHooksContext(),
       entityId,
@@ -1099,9 +1458,13 @@ export class World {
   }
 
   private createNewArchetype(componentTypes: EntityId<any>[]): Archetype {
-    const newArchetype = new Archetype(componentTypes, this.dontFragmentStore);
+    const newArchetype = new Archetype(componentTypes, this.sparseStore);
     this.archetypes.push(newArchetype);
 
+    if (this._debugCollectors.size > 0) {
+      this._debugArchetypesCreated++;
+    }
+
     for (const componentType of componentTypes) {
       let archetypes = this.archetypesByComponent.get(componentType);
       if (!archetypes) {
@@ -1135,11 +1498,11 @@ export class World {
     return (
       entry.requiredComponents.every((c: EntityId<any>) => {
         if (isWildcardRelationId(c)) {
-          if (isDontFragmentWildcard(c)) return true;
+          if (isSparseWildcard(c)) return true;
           const componentId = getComponentIdFromRelationId(c);
           return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
         }
-        return archetype.componentTypeSet.has(c) || isDontFragmentRelation(c);
+        return archetype.componentTypeSet.has(c) || isSparseRelation(c);
       }) && matchesFilter(archetype, entry.filter)
     );
   }
@@ -1166,6 +1529,10 @@ export class World {
       this.archetypes.pop();
     }
 
+    if (this._debugCollectors.size > 0) {
+      this._debugArchetypesRemoved++;
+    }
+
     this.archetypeBySignature.delete(this.createArchetypeSignature(archetype.componentTypes));
 
     for (const componentType of archetype.componentTypes) {