@codehz/ecs 0.8.1 → 0.9.0

package/src/types/index.ts

@@ -97,3 +97,74 @@ export interface LifecycleHookEntry {
   /** Archetypes that match this hook, used for precise cleanup on unsubscription */
   matchedArchetypes?: Set<any>;
 }
+
+/**
+ * Statistics payload delivered to callbacks registered via `World.createDebugStatsCollector`.
+ *
+ * All structural counts are snapshots taken after the sync that triggered delivery.
+ * `activity` always reflects work performed during that specific sync.
+ *
+ * Timestamps are raw `performance.now()` values suitable for `performance.measure`.
+ */
+export interface SyncDebugStats {
+  readonly timestamps: {
+    readonly syncStart: number;
+    readonly syncEnd: number;
+    readonly commandBufferStart: number;
+    readonly commandBufferEnd: number;
+  };
+
+  /** Number of iterations the internal command buffer loop performed during this sync. */
+  readonly commandIterations: number;
+
+  readonly entities: {
+    readonly total: number;
+    readonly freelistSize: number;
+    readonly nextId: number;
+  };
+
+  readonly archetypes: {
+    readonly total: number;
+    readonly empty: number;
+  };
+
+  readonly queries: {
+    readonly cached: number;
+    readonly registered: number;
+  };
+
+  readonly hooks: {
+    readonly total: number;
+  };
+
+  /** Sizes of stable internal reverse indices (conservative set). */
+  readonly indices: {
+    readonly entityReferences: number;
+    readonly entityToReferencingArchetypes: number;
+    readonly archetypesByComponent: number;
+  };
+
+  /**
+   * Activity that occurred as a direct result of this sync.
+   * All fields are always present (never optional).
+   */
+  readonly activity: {
+    /** Number of entities that performed an archetype migration (hasArchetypeStructuralChange was true). */
+    readonly migrations: number;
+    /** Total number of individual hook callback invocations (invokeHook calls). */
+    readonly hooksExecuted: number;
+    /** Number of new archetypes created during this sync. */
+    readonly archetypesCreated: number;
+    /** Number of archetypes removed during this sync. */
+    readonly archetypesRemoved: number;
+  };
+}
+
+/**
+ * Handle returned by `World.createDebugStatsCollector`.
+ * The object itself carries no data — its only responsibility is lifetime management.
+ * Use with `using` or call `[Symbol.dispose]()` when you no longer need collection.
+ */
+export interface DebugStatsCollector {
+  [Symbol.dispose](): void;
+}

package/src/world/commands.ts

@@ -1,14 +1,14 @@
 import type { Archetype } from "../archetype/archetype";
-import type { DontFragmentStore } from "../archetype/store";
+import type { SparseStore } from "../archetype/store";
 import type { Command } from "../commands/buffer";
 import type { ComponentChangeset } from "../commands/changeset";
 import { normalizeComponentTypes } from "../component/type-utils";
 import {
   getComponentIdFromRelationId,
   getComponentMerge,
-  isDontFragmentComponent,
-  isDontFragmentRelation,
-  isDontFragmentWildcard,
+  isSparseComponent,
+  isSparseRelation,
+  isSparseWildcard,
   isWildcardRelationId,
   relation,
   type ComponentId,
@@ -16,7 +16,7 @@ import {
 } from "../entity";
 
 export interface CommandProcessorContext {
-  dontFragmentStore: DontFragmentStore;
+  sparseStore: SparseStore;
   ensureArchetype: (componentTypes: Iterable<EntityId<any>>) => Archetype;
 }
 
@@ -59,8 +59,8 @@ function processSetCommand(
     // Handle exclusive relations by removing existing relations with the same base component
     handleExclusiveRelation(entityId, currentArchetype, componentId);
 
-    // For dontFragment relations, ensure wildcard marker is in archetype signature
-    if (isDontFragmentComponent(componentId)) {
+    // For sparse relations, ensure wildcard marker is in archetype signature
+    if (isSparseComponent(componentId)) {
       const wildcardMarker = relation(componentId, "*");
       // Add wildcard marker to changeset if not already in archetype
       if (!currentArchetype.componentTypeSet.has(wildcardMarker)) {
@@ -111,10 +111,10 @@ export function removeMatchingRelations(
     }
   }
 
-  // Check dontFragment relations stored on entity
-  const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-  if (dontFragmentData) {
-    for (const componentType of dontFragmentData.keys()) {
+  // Check sparse relations stored on entity
+  const sparseData = archetype.getEntitySparseRelations(entityId);
+  if (sparseData) {
+    for (const componentType of sparseData.keys()) {
       if (getComponentIdFromRelationId(componentType) === baseComponentId) {
         changeset.delete(componentType);
       }
@@ -130,8 +130,8 @@ function removeWildcardRelations(
 ): void {
   removeMatchingRelations(entityId, currentArchetype, baseComponentId, changeset);
 
-  // If removing dontFragment relations, also remove the wildcard marker
-  if (isDontFragmentComponent(baseComponentId)) {
+  // If removing sparse relations, also remove the wildcard marker
+  if (isSparseComponent(baseComponentId)) {
     changeset.delete(relation(baseComponentId, "*"));
   }
 }
@@ -143,7 +143,7 @@ export function maybeRemoveWildcardMarker(
   componentId: ComponentId<any> | undefined,
   changeset: ComponentChangeset,
 ): void {
-  if (componentId === undefined || !isDontFragmentComponent(componentId)) {
+  if (componentId === undefined || !isSparseComponent(componentId)) {
     return;
   }
 
@@ -160,9 +160,9 @@ export function maybeRemoveWildcardMarker(
     }
   }
 
-  const dontFragmentData = archetype.getEntityDontFragmentRelations(entityId);
-  if (dontFragmentData) {
-    for (const otherComponentType of dontFragmentData.keys()) {
+  const sparseData = archetype.getEntitySparseRelations(entityId);
+  if (sparseData) {
+    for (const otherComponentType of sparseData.keys()) {
       if (otherComponentType === removedComponentType) continue;
       if (changeset.removes.has(otherComponentType)) continue;
 
@@ -173,7 +173,7 @@ export function maybeRemoveWildcardMarker(
   }
 
   // Also check if this changeset itself is adding another relation of the same kind
-  // (common in exclusive dontFragment flips: remove old target + add new target in one batch)
+  // (common in exclusive sparse flips: remove old target + add new target in one batch)
   for (const addedType of changeset.adds.keys()) {
     if (addedType === removedComponentType) continue;
     if (getComponentIdFromRelationId(addedType) === componentId) {
@@ -189,7 +189,7 @@ function hasEntityComponent(archetype: Archetype, entityId: EntityId, componentT
     return true;
   }
 
-  return archetype.getEntityDontFragmentRelations(entityId)?.has(componentType) ?? false;
+  return archetype.getEntitySparseRelations(entityId)?.has(componentType) ?? false;
 }
 
 function pruneMissingRemovals(changeset: ComponentChangeset, archetype: Archetype, entityId: EntityId): void {
@@ -210,13 +210,13 @@ function pruneMissingRemovals(changeset: ComponentChangeset, archetype: Archetyp
 
 function hasArchetypeStructuralChange(changeset: ComponentChangeset, currentArchetype: Archetype): boolean {
   for (const componentType of changeset.removes) {
-    if (!isDontFragmentRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) {
+    if (!isSparseRelation(componentType) && currentArchetype.componentTypeSet.has(componentType)) {
       return true;
     }
   }
 
   for (const componentType of changeset.adds.keys()) {
-    if (!isDontFragmentRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) {
+    if (!isSparseRelation(componentType) && !currentArchetype.componentTypeSet.has(componentType)) {
       return true;
     }
   }
@@ -228,13 +228,13 @@ function buildFinalRegularComponentTypes(currentArchetype: Archetype, changeset:
   const finalRegularTypes = new Set(currentArchetype.componentTypes);
 
   for (const componentType of changeset.removes) {
-    if (!isDontFragmentRelation(componentType)) {
+    if (!isSparseRelation(componentType)) {
       finalRegularTypes.delete(componentType);
     }
   }
 
   for (const [componentType] of changeset.adds) {
-    if (!isDontFragmentRelation(componentType)) {
+    if (!isSparseRelation(componentType)) {
       finalRegularTypes.add(componentType);
     }
   }
@@ -269,16 +269,16 @@ export function applyChangeset(
     return newArchetype;
   }
 
-  // No archetype move needed: only component payload updates and/or dontFragment relation updates.
+  // No archetype move needed: only component payload updates and/or sparse relation updates.
   if (removedComponents !== null) {
-    applyDontFragmentChanges(ctx.dontFragmentStore, entityId, changeset, removedComponents);
+    applySparseChanges(ctx.sparseStore, entityId, changeset, removedComponents);
   } else {
-    applyDontFragmentChangesNoHooks(ctx.dontFragmentStore, entityId, changeset);
+    applySparseChangesNoHooks(ctx.sparseStore, entityId, changeset);
   }
 
   // Direct update for regular components in archetype
   for (const [componentType, component] of changeset.adds) {
-    if (isDontFragmentRelation(componentType)) {
+    if (isSparseRelation(componentType)) {
       continue;
     }
     currentArchetype.set(entityId, componentType, component);
@@ -287,52 +287,40 @@ export function applyChangeset(
   return currentArchetype;
 }
 
-/**
- * No-hooks variant of applyDontFragmentChanges that skips tracking removed component data.
- *
- * Rewritten for the new DontFragmentStore interface (ComponentId-primary storage).
- */
-function applyDontFragmentChanges(
-  dontFragmentRelations: DontFragmentStore,
+function applySparseChanges(
+  sparseStore: SparseStore,
   entityId: EntityId,
   changeset: ComponentChangeset,
   removedComponents: Map<EntityId<any>, any>,
 ): void {
   for (const componentType of changeset.removes) {
-    if (isDontFragmentRelation(componentType)) {
-      const removedValue = dontFragmentRelations.getValue(entityId, componentType);
+    if (isSparseRelation(componentType)) {
+      const removedValue = sparseStore.getValue(entityId, componentType);
       // Record for hooks if we are actually removing something
-      if (
-        removedValue !== undefined ||
-        dontFragmentRelations.getAllForEntity(entityId).some(([t]) => t === componentType)
-      ) {
+      if (removedValue !== undefined || sparseStore.getAllForEntity(entityId).some(([t]) => t === componentType)) {
         removedComponents.set(componentType, removedValue);
       }
-      dontFragmentRelations.deleteValue(entityId, componentType);
+      sparseStore.deleteValue(entityId, componentType);
     }
   }
 
   for (const [componentType, component] of changeset.adds) {
-    if (isDontFragmentRelation(componentType)) {
-      dontFragmentRelations.setValue(entityId, componentType, component);
+    if (isSparseRelation(componentType)) {
+      sparseStore.setValue(entityId, componentType, component);
     }
   }
 }
 
-function applyDontFragmentChangesNoHooks(
-  dontFragmentRelations: DontFragmentStore,
-  entityId: EntityId,
-  changeset: ComponentChangeset,
-): void {
+function applySparseChangesNoHooks(sparseStore: SparseStore, entityId: EntityId, changeset: ComponentChangeset): void {
   for (const componentType of changeset.removes) {
-    if (isDontFragmentRelation(componentType)) {
-      dontFragmentRelations.deleteValue(entityId, componentType);
+    if (isSparseRelation(componentType)) {
+      sparseStore.deleteValue(entityId, componentType);
     }
   }
 
   for (const [componentType, component] of changeset.adds) {
-    if (isDontFragmentRelation(componentType)) {
-      dontFragmentRelations.setValue(entityId, componentType, component);
+    if (isSparseRelation(componentType)) {
+      sparseStore.setValue(entityId, componentType, component);
     }
   }
 }
@@ -341,14 +329,14 @@ export function filterRegularComponentTypes(componentTypes: Iterable<EntityId<an
   const regularTypes: EntityId<any>[] = [];
 
   for (const componentType of componentTypes) {
-    // Keep wildcard markers for dontFragment components (they mark the archetype)
-    if (isDontFragmentWildcard(componentType)) {
+    // Keep wildcard markers for sparse components (they mark the archetype)
+    if (isSparseWildcard(componentType)) {
       regularTypes.push(componentType);
       continue;
     }
 
-    // Skip specific dontFragment relations from archetype signature
-    if (isDontFragmentRelation(componentType)) {
+    // Skip specific sparse relations from archetype signature
+    if (isSparseRelation(componentType)) {
       continue;
     }
 

package/src/world/hooks.ts

@@ -7,6 +7,12 @@ import {
 } from "../entity";
 import { isOptionalEntityId, type ComponentType, type LifecycleHookEntry } from "../types";
 
+/**
+ * Debug-only counter incremented on every invokeHook call when armed.
+ * World reads and resets this during armed syncs.
+ */
+export const debugHookExecutionCounter = { value: 0 };
+
 /**
  * Unified hook invocation: prefers entry.callback (callback style) over hook.on_* (object style).
  */
@@ -16,6 +22,8 @@ function invokeHook(
   entityId: EntityId,
   components: any[],
 ): void {
+  debugHookExecutionCounter.value++;
+
   if (entry.callback) {
     entry.callback(event as any, entityId, ...components);
     return;

package/src/world/serialization.ts

@@ -3,7 +3,7 @@ import type { ComponentEntityStore } from "../component/entity-store";
 import { getDetailedIdType, type EntityId, type EntityIdManager } from "../entity";
 import {
   decodeSerializedId,
-  encodeEntityId,
+  encodeEntityIdCached,
   type SerializedComponent,
   type SerializedEntity,
   type SerializedWorld,
@@ -18,29 +18,25 @@ export function serializeWorld(
   componentEntities: ComponentEntityStore,
   entityIdManager: EntityIdManager,
 ): SerializedWorld {
+  // ID cache turns repeated encode work (especially component type IDs) into O(#unique IDs)
+  const idCache = new Map<any, any>();
+
   const entities: SerializedEntity[] = [];
 
   for (const archetype of archetypes) {
-    const dumpedEntities = archetype.dump();
-    for (const { entity, components } of dumpedEntities) {
-      entities.push({
-        id: encodeEntityId(entity),
-        components: Array.from(components.entries()).map(([rawType, value]) => ({
-          type: encodeEntityId(rawType),
-          value: value === MISSING_COMPONENT ? undefined : value,
-        })),
-      });
-    }
+    // Pre-encode this archetype's component type IDs exactly once (big win when many entities share the archetype)
+    const encodedComponentTypes = archetype.componentTypes.map((t) => encodeEntityIdCached(t, idCache));
+
+    // The append method will use the bulk helper internally when a pre-fetched map is supplied.
+    // For now we rely on the per-entity fallback inside the archetype (already much cheaper than old dump path).
+    archetype.appendSerializedEntities(entities, (id) => encodeEntityIdCached(id, idCache), encodedComponentTypes);
   }
 
   const componentEntitiesArr: SerializedEntity[] = [];
   for (const [entityId, components] of componentEntities.entries()) {
     componentEntitiesArr.push({
-      id: encodeEntityId(entityId),
-      components: Array.from(components.entries()).map(([rawType, value]) => ({
-        type: encodeEntityId(rawType),
-        value: value === MISSING_COMPONENT ? undefined : value,
-      })),
+      id: encodeEntityIdCached(entityId, idCache),
+      components: serializeComponentsFromMap(components, idCache),
     });
   }
 
@@ -52,6 +48,21 @@ export function serializeWorld(
   };
 }
 
+/** Small helper to avoid duplicating the "Map → SerializedComponent[] with cache" pattern. */
+function serializeComponentsFromMap(
+  components: Map<EntityId<any>, any>,
+  idCache: Map<any, any>,
+): SerializedComponent[] {
+  const result: SerializedComponent[] = [];
+  for (const [rawType, value] of components) {
+    result.push({
+      type: encodeEntityIdCached(rawType, idCache),
+      value: value === MISSING_COMPONENT ? undefined : value,
+    });
+  }
+  return result;
+}
+
 /**
  * Context needed by `deserializeWorld` to populate world-internal state.
  * Defined as an interface to avoid a circular import between world.ts and this module.
@@ -96,14 +107,17 @@ export function deserializeWorld(ctx: WorldDeserializationContext, snapshot: Ser
       const componentsArray: SerializedComponent[] = entry.components || [];
 
       const componentMap = new Map<EntityId<any>, any>();
-      const componentTypes: EntityId<any>[] = [];
 
       for (const componentEntry of componentsArray) {
         const componentType = decodeSerializedId(componentEntry.type);
         componentMap.set(componentType, componentEntry.value);
-        componentTypes.push(componentType);
       }
 
+      // Build the list of component types from the map we just populated (no redundant push loop)
+      const componentTypes = Array.from(componentMap.keys());
+
+      // ensureArchetype is internally memoized (getOrCompute on signature), so repeated calls
+      // for the same component set are cheap after the first archetype is created.
       const archetype = ctx.ensureArchetype(componentTypes);
       archetype.addEntity(entityId, componentMap);
       ctx.setEntityToArchetype(entityId, archetype);