@codehz/ecs 0.8.2 → 0.10.0

package/src/world/archetype-manager.ts

@@ -0,0 +1,283 @@
+import { Archetype } from "../archetype/archetype";
+import type { SparseStore } from "../archetype/store";
+import { normalizeComponentTypes } from "../component/type-utils";
+import type { EntityId } from "../entity";
+import {
+  getComponentIdFromRelationId,
+  getDetailedIdType,
+  isSparseRelation,
+  isSparseWildcard,
+  isWildcardRelationId,
+} from "../entity";
+import { matchesFilter } from "../query/filter";
+import type { QueryRegistry } from "../query/registry";
+import type { LifecycleHookEntry } from "../types";
+import { getOrCompute } from "../utils/utils";
+import { filterRegularComponentTypes } from "./commands";
+
+/**
+ * Context provided to ArchetypeManager for notifying dependent systems
+ * (query caching and lifecycle hooks) without creating tight coupling or cycles.
+ * Follows the same callback/context injection pattern used by CommandProcessorContext,
+ * HooksContext, and WorldDeserializationContext.
+ */
+export interface ArchetypeManagerContext {
+  queryRegistry: QueryRegistry;
+  hooks: Set<LifecycleHookEntry>;
+  /** Called only when debug collectors are active (mirrors original guard in World) */
+  recordArchetypeCreated?: () => void;
+  recordArchetypeRemoved?: () => void;
+}
+
+/**
+ * Encapsulates all archetype storage, indexing, creation, removal, and reverse
+ * referencing logic that was previously scattered as private methods + maps
+ * directly on the World class.
+ *
+ * Responsibilities:
+ * - Archetype memoization by signature
+ * - Component-type reverse index (archetypesByComponent)
+ * - Entity → current Archetype map
+ * - Reverse "who references this entity via component/relation" index
+ * - Creation + removal with proper notifications to QueryRegistry + hook matching
+ * - Cleanup of empty archetypes after entity cascades
+ *
+ * This extraction shrinks World while keeping the same behavior and hot-path characteristics.
+ */
+export class ArchetypeManager {
+  // Public for performance (hot paths access these maps frequently).
+  // This intentionally breaks encapsulation a bit for speed, as requested.
+  readonly archetypes: Archetype[] = [];
+  readonly archetypeBySignature = new Map<string, Archetype>();
+  readonly entityToArchetype = new Map<EntityId, Archetype>();
+  readonly archetypesByComponent = new Map<EntityId<any>, Set<Archetype>>();
+  readonly entityToReferencingArchetypes = new Map<EntityId, Set<Archetype>>();
+
+  private readonly sparseStore: SparseStore;
+  private readonly ctx: ArchetypeManagerContext;
+
+  constructor(ctx: ArchetypeManagerContext, sparseStore: SparseStore) {
+    this.ctx = ctx;
+    this.sparseStore = sparseStore;
+  }
+
+  // ------------------------------------------------------------------
+  // Public / package-internal surface used by World and its close collaborators
+  // (commands.ts applyChangeset, serialization deserialization context, etc.)
+  // ------------------------------------------------------------------
+
+  /** Primary entry point — memoized archetype creation/lookup. */
+  ensureArchetype(componentTypes: Iterable<EntityId<any>>): Archetype {
+    const regularTypes = filterRegularComponentTypes(componentTypes);
+    const sortedTypes = normalizeComponentTypes(regularTypes);
+    const hashKey = this.createArchetypeSignature(sortedTypes);
+
+    return getOrCompute(this.archetypeBySignature, hashKey, () => this.createNewArchetype(sortedTypes));
+  }
+
+  getArchetypeForEntity(entityId: EntityId): Archetype | undefined {
+    return this.entityToArchetype.get(entityId);
+  }
+
+  setEntityToArchetype(entityId: EntityId, archetype: Archetype): void {
+    this.entityToArchetype.set(entityId, archetype);
+  }
+
+  // Query helpers (moved from World for cohesion)
+  getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[] {
+    if (componentTypes.length === 0) {
+      return [...this.archetypes];
+    }
+
+    const regularComponents: EntityId<any>[] = [];
+    const wildcardRelations: { componentId: EntityId<any>; relationId: EntityId<any> }[] = [];
+
+    for (const componentType of componentTypes) {
+      if (isWildcardRelationId(componentType)) {
+        const componentId = getComponentIdFromRelationId(componentType);
+        if (componentId !== undefined) {
+          wildcardRelations.push({ componentId, relationId: componentType });
+        }
+      } else {
+        regularComponents.push(componentType);
+      }
+    }
+
+    let matchingArchetypes = this.getArchetypesWithComponents(regularComponents);
+
+    for (const { componentId, relationId } of wildcardRelations) {
+      const markerSet = this.archetypesByComponent.get(relationId);
+      const archetypesWithMarker = markerSet ? Array.from(markerSet) : [];
+      matchingArchetypes =
+        matchingArchetypes.length === 0
+          ? archetypesWithMarker
+          : matchingArchetypes.filter((a) => markerSet?.has(a) || a.hasRelationWithComponentId(componentId));
+    }
+
+    return matchingArchetypes;
+  }
+
+  getArchetypesWithComponents(componentTypes: EntityId<any>[]): Archetype[] {
+    if (componentTypes.length === 0) return [...this.archetypes];
+    if (componentTypes.length === 1) {
+      const set = this.archetypesByComponent.get(componentTypes[0]!);
+      return set ? Array.from(set) : [];
+    }
+
+    // Sort by Set size, intersect starting from the smallest
+    const sets = componentTypes
+      .map((type) => this.archetypesByComponent.get(type))
+      .filter((s): s is Set<Archetype> => s !== undefined && s.size > 0)
+      .sort((a, b) => a.size - b.size);
+
+    if (sets.length === 0) return [];
+    if (sets.length < componentTypes.length) return []; // One component has no matching archetypes
+
+    const smallest = sets[0]!;
+
+    // 2-component fast path
+    if (sets.length === 2) {
+      const other = sets[1]!;
+      return Array.from(smallest).filter((a) => other.has(a));
+    }
+
+    // Multi-component intersection
+    let result = new Set(smallest);
+    for (let i = 1; i < sets.length; i++) {
+      for (const item of result) {
+        if (!sets[i]!.has(item)) result.delete(item);
+      }
+      if (result.size === 0) return [];
+    }
+    return Array.from(result);
+  }
+
+  // ------------------------------------------------------------------
+  // Internal creation / removal (core of the original cluster)
+  // ------------------------------------------------------------------
+
+  private createArchetypeSignature(componentTypes: EntityId<any>[]): string {
+    return componentTypes.join(",");
+  }
+
+  /** Deduplicated version of the original pair of methods. */
+  private updateReferencingIndex(componentType: EntityId<any>, archetype: Archetype, isAdd: boolean): void {
+    const detailedType = getDetailedIdType(componentType);
+    let entityId: EntityId | undefined;
+
+    if (detailedType.type === "entity") {
+      entityId = componentType as EntityId;
+    } else if (detailedType.type === "entity-relation") {
+      entityId = detailedType.targetId;
+    }
+
+    if (entityId !== undefined) {
+      let refs = this.entityToReferencingArchetypes.get(entityId);
+      if (isAdd) {
+        if (!refs) {
+          refs = new Set();
+          this.entityToReferencingArchetypes.set(entityId, refs);
+        }
+        refs.add(archetype);
+      } else {
+        if (refs) {
+          refs.delete(archetype);
+          if (refs.size === 0) {
+            this.entityToReferencingArchetypes.delete(entityId);
+          }
+        }
+      }
+    }
+  }
+
+  private createNewArchetype(componentTypes: EntityId<any>[]): Archetype {
+    const newArchetype = new Archetype(componentTypes, this.sparseStore);
+    this.archetypes.push(newArchetype);
+
+    this.ctx.recordArchetypeCreated?.();
+
+    for (const componentType of componentTypes) {
+      let archetypes = this.archetypesByComponent.get(componentType);
+      if (!archetypes) {
+        archetypes = new Set();
+        this.archetypesByComponent.set(componentType, archetypes);
+      }
+      archetypes.add(newArchetype);
+
+      // Update reverse index (deduped)
+      this.updateReferencingIndex(componentType, newArchetype, true);
+    }
+
+    this.ctx.queryRegistry.onNewArchetype(newArchetype);
+    this.updateArchetypeHookMatches(newArchetype);
+
+    return newArchetype;
+  }
+
+  private updateArchetypeHookMatches(archetype: Archetype): void {
+    for (const entry of this.ctx.hooks) {
+      if (this.archetypeMatchesHook(archetype, entry)) {
+        archetype.matchingMultiHooks.add(entry);
+        if (entry.matchedArchetypes) {
+          entry.matchedArchetypes.add(archetype);
+        }
+      }
+    }
+  }
+
+  public archetypeMatchesHook(archetype: Archetype, entry: LifecycleHookEntry): boolean {
+    return (
+      entry.requiredComponents.every((c: EntityId<any>) => {
+        if (isWildcardRelationId(c)) {
+          if (isSparseWildcard(c)) return true;
+          const componentId = getComponentIdFromRelationId(c);
+          return componentId !== undefined && archetype.hasRelationWithComponentId(componentId);
+        }
+        return archetype.componentTypeSet.has(c) || isSparseRelation(c);
+      }) && matchesFilter(archetype, entry.filter)
+    );
+  }
+
+  /** Called during cascade deletion cleanup. */
+  cleanupArchetypesReferencingEntity(entityId: EntityId): void {
+    const refs = this.entityToReferencingArchetypes.get(entityId);
+    if (!refs) return;
+
+    for (const archetype of refs) {
+      if (archetype.getEntities().length === 0) {
+        this.removeArchetype(archetype);
+      }
+    }
+    // removeArchetype already cleans up the reverse index entries for the archetypes themselves
+    this.entityToReferencingArchetypes.delete(entityId);
+  }
+
+  private removeArchetype(archetype: Archetype): void {
+    const index = this.archetypes.indexOf(archetype);
+    if (index !== -1) {
+      // swap-and-pop: O(1) removal
+      const last = this.archetypes[this.archetypes.length - 1]!;
+      this.archetypes[index] = last;
+      this.archetypes.pop();
+    }
+
+    this.ctx.recordArchetypeRemoved?.();
+
+    this.archetypeBySignature.delete(this.createArchetypeSignature(archetype.componentTypes));
+
+    for (const componentType of archetype.componentTypes) {
+      const archetypes = this.archetypesByComponent.get(componentType);
+      if (archetypes) {
+        archetypes.delete(archetype);
+        if (archetypes.size === 0) {
+          this.archetypesByComponent.delete(componentType);
+        }
+      }
+
+      // Clean up reverse index (deduped)
+      this.updateReferencingIndex(componentType, archetype, false);
+    }
+
+    this.ctx.queryRegistry.onArchetypeRemoved(archetype);
+  }
+}

package/src/world/command-executor.ts

@@ -0,0 +1,258 @@
+import type { Archetype } from "../archetype/archetype";
+import type { SparseStore } from "../archetype/store";
+import type { Command } from "../commands/buffer";
+import { ComponentChangeset } from "../commands/changeset";
+import type { ComponentEntityStore } from "../component/entity-store";
+import {
+  getComponentIdFromRelationId,
+  getTargetIdFromRelationId,
+  isEntityRelation,
+  isExclusiveComponent,
+  type EntityId,
+} from "../entity";
+import type { LifecycleHookEntry } from "../types";
+import {
+  applyChangeset,
+  maybeRemoveWildcardMarker,
+  processCommands,
+  removeMatchingRelations,
+  type CommandProcessorContext,
+} from "./commands";
+import type { triggerLifecycleHooks } from "./hooks";
+import { type HooksContext } from "./hooks";
+import { trackEntityReference, untrackEntityReference, type EntityReferencesMap } from "./references";
+
+/**
+ * Dependencies provided by World to the CommandExecutor.
+ * Keeps the executor decoupled while allowing efficient hot-path access
+ * (maps passed by reference where hot code already expects them).
+ */
+export interface CommandExecutorContext {
+  /** For component-entity (singleton) fast path in execute */
+  componentEntities: ComponentEntityStore;
+
+  /** Reverse reference index for cascades and entity-valued components */
+  entityReferences: EntityReferencesMap;
+
+  /** For the no-hooks fast path guard */
+  hooks: Set<LifecycleHookEntry>;
+
+  /** Direct map access (hot path in applyChangeset and various places) */
+  entityToArchetype: Map<EntityId, Archetype>;
+
+  /** Archetype creation/lookup (passed through CommandProcessorContext) */
+  ensureArchetype: (componentTypes: Iterable<EntityId<any>>) => Archetype;
+
+  /** Sparse store (needed for CommandProcessorContext) */
+  sparseStore: SparseStore;
+
+  /** Factories for the HooksContext (used by triggerLifecycleHooks) */
+  has: (entityId: EntityId, componentType: EntityId<any>) => boolean;
+  get: <T>(entityId: EntityId, componentType: EntityId<T>) => T;
+  getOptional: <T>(entityId: EntityId, componentType: EntityId<T>) => { value: T } | undefined;
+
+  /** Destroy fast-path delegation (BFS + cascade logic stays in World) */
+  destroyEntityImmediate: (entityId: EntityId) => void;
+
+  /** Debug migration counter (now routed through DebugStatsManager) */
+  incrementMigrations: () => void;
+
+  /** Hook triggering (the function from hooks.ts) */
+  triggerLifecycleHooks: typeof triggerLifecycleHooks;
+
+  /** Remove hook fast path for full entity deletion (used by destroy paths in World) */
+  triggerRemoveHooksForEntityDeletion: (
+    entityId: EntityId,
+    removedComponents: Map<EntityId<any>, any>,
+    oldArchetype: Archetype,
+  ) => void;
+}
+
+/**
+ * Encapsulates the command execution pipeline, reusable changesets,
+ * and related orchestration that was previously private methods + fields on World.
+ *
+ * Responsibilities:
+ * - executeEntityCommands (routing for singletons / destroy / structural changes)
+ * - applyEntityCommands (changeset processing + exclusive relations + apply + refs + hooks)
+ * - removeComponentImmediate (used by cascade deletion)
+ * - updateEntityReferences (keeps the reverse index in sync)
+ *
+ * This extraction significantly reduces World line count while preserving
+ * every fast-path branch and allocation-avoidance characteristic.
+ */
+export class CommandExecutor {
+  private readonly _changeset = new ComponentChangeset();
+  private readonly _removeChangeset = new ComponentChangeset();
+
+  private readonly _commandCtx: CommandProcessorContext;
+  private readonly _hooksCtx: HooksContext;
+
+  constructor(private readonly ctx: CommandExecutorContext) {
+    this._commandCtx = {
+      sparseStore: ctx.sparseStore,
+      ensureArchetype: ctx.ensureArchetype,
+    };
+
+    this._hooksCtx = {
+      multiHooks: ctx.hooks,
+      has: ctx.has,
+      get: ctx.get,
+      getOptional: ctx.getOptional,
+    };
+  }
+
+  /**
+   * Entry point used by the CommandBuffer.
+   * Routes to singleton handling, destroy fast path, or structural apply.
+   */
+  executeEntityCommands(entityId: EntityId, commands: Command[]): void {
+    this._changeset.clear();
+
+    // 1. Route: component entities use flat-map storage
+    if (this.ctx.componentEntities.exists(entityId)) {
+      this.ctx.componentEntities.executeCommands(entityId, commands);
+      return;
+    }
+
+    // 2. Route: destroy uses fast path (BFS/cascade stays in World)
+    if (commands.some((cmd) => cmd.type === "destroy")) {
+      this.ctx.destroyEntityImmediate(entityId);
+      return;
+    }
+
+    // 3. Apply structural changes
+    this.applyEntityCommands(entityId, commands);
+  }
+
+  private applyEntityCommands(entityId: EntityId, commands: Command[]): void {
+    const currentArchetype = this.ctx.entityToArchetype.get(entityId);
+    if (!currentArchetype) return;
+
+    const changeset = this._changeset;
+    processCommands(entityId, currentArchetype, commands, changeset, (eid, arch, compId) => {
+      if (isExclusiveComponent(compId)) {
+        removeMatchingRelations(eid, arch, compId, changeset);
+      }
+    });
+
+    const hasStructuralChange = changeset.removes.size > 0 || changeset.adds.size > 0;
+
+    if (this.ctx.hooks.size === 0) {
+      // Fast path: no hooks, skip removedComponents map allocation and hook triggering
+      const newArchetype = applyChangeset(
+        this._commandCtx,
+        entityId,
+        currentArchetype,
+        changeset,
+        this.ctx.entityToArchetype,
+        null,
+      );
+      if (hasStructuralChange) {
+        this.updateEntityReferences(entityId, changeset);
+      }
+      if (newArchetype !== currentArchetype) {
+        this.ctx.incrementMigrations();
+      }
+      return;
+    }
+
+    const removedComponents = new Map<EntityId<any>, any>();
+    const newArchetype = applyChangeset(
+      this._commandCtx,
+      entityId,
+      currentArchetype,
+      changeset,
+      this.ctx.entityToArchetype,
+      removedComponents,
+    );
+
+    if (hasStructuralChange) {
+      this.updateEntityReferences(entityId, changeset);
+    }
+
+    if (newArchetype !== currentArchetype) {
+      this.ctx.incrementMigrations();
+    }
+
+    this.ctx.triggerLifecycleHooks(
+      this._hooksCtx,
+      entityId,
+      changeset.adds,
+      removedComponents,
+      currentArchetype,
+      newArchetype,
+    );
+  }
+
+  /**
+   * Immediate (non-buffered) component removal used during cascade deletion.
+   * Called from destroy* paths (which remain in World).
+   */
+  removeComponentImmediate(entityId: EntityId, componentType: EntityId<any>, targetEntityId: EntityId): void {
+    const sourceArchetype = this.ctx.entityToArchetype.get(entityId);
+    if (!sourceArchetype) return;
+
+    const changeset = this._removeChangeset;
+    changeset.clear();
+    changeset.delete(componentType);
+    maybeRemoveWildcardMarker(
+      entityId,
+      sourceArchetype,
+      componentType,
+      getComponentIdFromRelationId(componentType),
+      changeset,
+    );
+
+    const removedComponent = sourceArchetype.get(entityId, componentType);
+    const newArchetype = applyChangeset(
+      this._commandCtx,
+      entityId,
+      sourceArchetype,
+      changeset,
+      this.ctx.entityToArchetype,
+      null,
+    );
+    untrackEntityReference(this.ctx.entityReferences, entityId, componentType, targetEntityId);
+
+    this.ctx.triggerLifecycleHooks(
+      this._hooksCtx,
+      entityId,
+      new Map(),
+      new Map([[componentType, removedComponent]]),
+      sourceArchetype,
+      newArchetype,
+    );
+  }
+
+  /**
+   * Keeps the entity reference reverse index in sync after structural changes.
+   * Called from apply paths.
+   */
+  updateEntityReferences(entityId: EntityId, changeset: ComponentChangeset): void {
+    for (const componentType of changeset.removes) {
+      if (isEntityRelation(componentType)) {
+        const targetId = getTargetIdFromRelationId(componentType)!;
+        untrackEntityReference(this.ctx.entityReferences, entityId, componentType, targetId);
+      } else if (componentType >= 1024) {
+        untrackEntityReference(this.ctx.entityReferences, entityId, componentType, componentType);
+      }
+    }
+
+    for (const [componentType] of changeset.adds) {
+      if (isEntityRelation(componentType)) {
+        const targetId = getTargetIdFromRelationId(componentType)!;
+        trackEntityReference(this.ctx.entityReferences, entityId, componentType, targetId);
+      } else if (componentType >= 1024) {
+        trackEntityReference(this.ctx.entityReferences, entityId, componentType, componentType);
+      }
+    }
+  }
+
+  /**
+   * Exposed for any future direct needs (currently not required outside the executor).
+   */
+  getHooksContext(): HooksContext {
+    return this._hooksCtx;
+  }
+}