@codehz/ecs 0.8.1 → 0.9.0

package/src/archetype/store.ts

@@ -10,46 +10,49 @@ type RelationEntry =
   | { type: "multi"; targets: Map<EntityId, { relationType: EntityId<any>; data: any }> };
 
 /**
- * Interface for storing dontFragment relation data.
+ * Interface for the sparse side store used by components declared with `sparse: true`
+ * (or the legacy `dontFragment: true` alias).
  *
- * Storage is now primarily keyed by relation ComponentId (the "kind" of relation)
- * rather than by entity. This provides O(1) or near-O(1) answers for the hot
- * wildcard-related paths (hasRelationWithComponentId, wildcard materialization
- * during iteration, hook matching, etc.).
+ * Relation data for these components lives here instead of in archetype columns,
+ * preventing fragmentation for high-cardinality or frequently-changing relations.
  *
- * A lightweight reverse index (entity -> Set of base ComponentIds) is maintained
- * to efficiently support the infrequent "get all dontFragment data for this entity"
- * operations (removeEntity, dump, getEntity, serialization).
- *
- * The interface no longer leaks internal Map structures. Callers work with
- * semantic operations only.
+ * Storage is primarily keyed by base relation ComponentId. This enables efficient
+ * per-component lookups required by wildcard queries (relation(Comp, "*")) and
+ * archetype filtering, while still supporting full-entity enumeration when needed.
  */
-export interface DontFragmentStore {
-  // High-frequency operations (used by get/set/getOptional and structural changes)
+export interface SparseStore {
+  // High-frequency per-(entity, relation) operations (get/set/has/remove, structural changes)
   getValue(entityId: EntityId, relationType: EntityId<any>): any | undefined;
   setValue(entityId: EntityId, relationType: EntityId<any>, data: any): void;
   deleteValue(entityId: EntityId, relationType: EntityId<any>): boolean;
 
-  // Wildcard / filtering hot paths (X-class priority)
+  // Hot paths for wildcard queries and archetype filtering (per-component lookups)
   hasAnyForComponent(componentId: EntityId<any>): boolean;
   getRelationsForComponent(entityId: EntityId, componentId: EntityId<any>): [target: EntityId, data: any][];
 
-  // Low-frequency "get everything for entity" paths (Y-class, acceptable cost)
+  // Entity-wide enumeration paths (used for snapshots, serialization, forEach, and rare presence checks)
   getAllForEntity(entityId: EntityId): Array<[relationType: EntityId<any>, data: any]>;
   deleteEntity(entityId: EntityId): void;
+
+  /**
+   * @internal Bulk helper for serialization of many entities.
+   * Default implementation simply loops getAllForEntity; subclasses / future
+   * implementations can provide a more efficient fused walk.
+   */
+  getAllForEntities(entityIds: readonly EntityId[]): Map<EntityId, Array<[EntityId<any>, any]>>;
 }
 
 /**
- * Production implementation of DontFragmentStore.
+ * Production implementation of SparseStore.
  *
  * Internal layout (optimized):
  * - byComponent: baseComponentId → (entityId → RelationEntry)
  *   RelationEntry uses a single-value form for the common exclusive case (1 target),
- *   avoiding Map allocation entirely for the vast majority of dontFragment usage.
+ *   avoiding Map allocation for the vast majority of usage.
  * - entityIndex: entityId → Set<baseComponentId>
  *   Lightweight reverse index.
  */
-export class DontFragmentStoreImpl implements DontFragmentStore {
+export class SparseStoreImpl implements SparseStore {
   /**
    * Primary storage, keyed by the base relation component ID.
    */
@@ -60,7 +63,8 @@ export class DontFragmentStoreImpl implements DontFragmentStore {
 
   /**
    * Reverse index: which base component kinds an entity participates in.
-   * Used only by the infrequent getAllForEntity / deleteEntity paths.
+   * Only required to support getAllForEntity and deleteEntity efficiently.
+   * The primary storage (byComponent) is deliberately not optimized for these operations.
    */
   private entityIndex = new Map<EntityId, Set<EntityId<any>>>();
 
@@ -87,7 +91,7 @@ export class DontFragmentStoreImpl implements DontFragmentStore {
   setValue(entityId: EntityId, relationType: EntityId<any>, data: any): void {
     const componentId = getComponentIdFromRelationId(relationType);
     if (componentId === undefined) {
-      throw new Error("setValue called with a non-relation type on DontFragmentStore");
+      throw new Error("setValue called with a non-relation type on SparseStore");
     }
 
     let entities = this.byComponent.get(componentId);
@@ -237,4 +241,15 @@ export class DontFragmentStoreImpl implements DontFragmentStore {
 
     this.entityIndex.delete(entityId);
   }
+
+  getAllForEntities(entityIds: readonly EntityId[]): Map<EntityId, Array<[EntityId<any>, any]>> {
+    const result = new Map<EntityId, Array<[EntityId<any>, any]>>();
+    for (const eid of entityIds) {
+      const data = this.getAllForEntity(eid);
+      if (data.length > 0) {
+        result.set(eid, data);
+      }
+    }
+    return result;
+  }
 }

package/src/commands/buffer.ts

@@ -55,9 +55,10 @@ export class CommandBuffer {
   }
 
   /**
-   * Execute all commands and clear the buffer
+   * Execute all commands and clear the buffer.
+   * Returns the number of iterations performed (for debug stats).
    */
-  execute(): void {
+  execute(): number {
     let iterations = 0;
 
     while (this.commands.length > 0) {
@@ -92,6 +93,8 @@ export class CommandBuffer {
       }
       entityCommands.clear();
     }
+
+    return iterations;
   }
 
   /**

package/src/commands/changeset.ts

@@ -70,35 +70,4 @@ export class ComponentChangeset {
 
     return existingComponents;
   }
-
-  /**
-   * Get the final component types after applying the changeset
-   * @param existingComponentTypes - The current component types on the entity
-   * @returns The final component types or undefined if no changes
-   */
-  getFinalComponentTypes(existingComponentTypes: EntityId<any>[]): EntityId<any>[] | undefined {
-    const finalComponentTypes = new Set<EntityId<any>>(existingComponentTypes);
-    let changed = false;
-
-    // Apply removals
-    for (const componentType of this.removes) {
-      if (!finalComponentTypes.has(componentType)) {
-        this.removes.delete(componentType);
-        continue; // Component not present, skip
-      }
-      changed = true;
-      finalComponentTypes.delete(componentType);
-    }
-
-    // Apply additions
-    for (const componentType of this.adds.keys()) {
-      if (finalComponentTypes.has(componentType)) {
-        continue; // Component already present, skip
-      }
-      changed = true;
-      finalComponentTypes.add(componentType);
-    }
-
-    return changed ? Array.from(finalComponentTypes) : undefined;
-  }
 }

package/src/component/registry.ts

@@ -138,7 +138,7 @@ export interface ComponentOptions<T = any> {
    *   `cascadeDelete`, deleting the target entity will both (a) delete the
    *   referencing entity, and (b) the exclusivity constraint prevents the
    *   entity from having multiple cascade-delete relations of the same type.
-   * - **`dontFragment`**: Compatible. Exclusivity is enforced at the data level
+   * - **`sparse`**: Compatible. Exclusivity is enforced at the data level
    *   regardless of whether the archetype is fragmented.
    *
    * @example
@@ -196,7 +196,8 @@ export interface ComponentOptions<T = any> {
    */
   cascadeDelete?: boolean;
   /**
-   * If true, relations with this component will not cause archetype fragmentation.
+   * If true, relations with this component use sparse storage and will not cause
+   * archetype fragmentation.
    *
    * **Problem it solves**: By default, each unique relation pair `(component, target)`
    * creates a **separate archetype**. If 100 entities each have a `ChildOf` relation
@@ -204,28 +205,28 @@ export interface ComponentOptions<T = any> {
    * Queries that iterate over all entities with a `ChildOf` relation must check all
    * 100 archetypes, which degrades iteration performance and increases memory overhead.
    *
-   * **How it works**: When `dontFragment` is enabled, the relation's target does **not**
-   * contribute to the archetype signature. Entities with different targets for the same
-   * relation component share a **single archetype**, and the per-entity target data is
-   * stored in a separate `DontFragmentStore` (a `Map<EntityId, Map<EntityId, any>>`).
-   * A wildcard relation marker (`relation(Comp, "*")`) is placed in the archetype
-   * component list so queries can still discover matching archetypes.
+   * **How it works (sparse storage)**: When `sparse` is enabled, the relation's target
+   * does **not** contribute to the archetype signature. Entities with different targets
+   * for the same relation component share a **single archetype**, and the per-entity
+   * target data is stored in a separate side store (historically called
+   * `DontFragmentStore`, now `SparseStore`). A wildcard relation marker (`relation(Comp, "*")`) is placed
+   * in the archetype component list so queries can still discover matching archetypes.
    *
    * **Use cases**:
    * - **Hierarchy/ownership**: `ChildOf` relations where thousands of entities each
    *   point to different parent entities.
    * - **Dynamic targeting**: Relations where targets change frequently (e.g., AI
-   *   targeting, inventory slots) — without `dontFragment`, each target change would
-   *   cause an archetype migration, which is expensive.
+   *   targeting, inventory slots) — without `sparse`, each target change would cause
+   *   an archetype migration, which is expensive.
    * - **High-cardinality relations**: Any relation where the number of unique targets
    *   is large compared to the number of entities.
    *
    * **Performance implications**:
-   * - **Without `dontFragment`**: Archetype count grows linearly with unique targets.
+   * - **Without `sparse`**: Archetype count grows linearly with unique targets.
    *   Each archetype migration (changing a relation target) requires moving the entity's
    *   data between component arrays.
-   * - **With `dontFragment`**: Archetype count stays constant regardless of target
-   *   diversity. Changing a relation target is an O(1) update in the `DontFragmentStore`.
+   * - **With `sparse`**: Archetype count stays constant regardless of target diversity.
+   *   Changing a relation target is an O(1) update in the sparse side store.
    *   The trade-off is an extra map lookup when accessing the relation data.
    *
    * **Constraints**:
@@ -234,13 +235,16 @@ export interface ComponentOptions<T = any> {
    *   archetype carries a wildcard marker so queries can discover it.
    * - Works with `exclusive` and `cascadeDelete` simultaneously.
    *
+   * **Backward compatibility**: The legacy key `dontFragment` is still accepted and
+   * behaves identically. Prefer `sparse` in new code.
+   *
    * @example
    * ```ts
-   * // Without dontFragment: 100 entities with different parents = 100 archetypes
+   * // Without sparse: 100 entities with different parents = 100 archetypes
    * const ChildOf = component(); // default: fragmentation happens
    *
-   * // With dontFragment: 100 entities with different parents = 1 archetype
-   * const ChildOf = component({ dontFragment: true });
+   * // With sparse: 100 entities with different parents = 1 archetype
+   * const ChildOf = component({ sparse: true });
    *
    * for (let i = 0; i < 100; i++) {
    *   const parent = world.new();
@@ -249,11 +253,17 @@ export interface ComponentOptions<T = any> {
    *   world.set(child, relation(ChildOf, parent));
    * }
    * world.sync();
-   * // dontFragment: 1 archetype for all 100 entities
+   * // sparse: 1 archetype for all 100 entities
    * // without: 100 archetypes, one per unique parent
    * ```
    *
-   * Inspired by Flecs' `DontFragment` trait.
+   * Inspired by Flecs' `DontFragment` trait (now exposed as the clearer `sparse` option).
+   */
+  sparse?: boolean;
+  /**
+   * @deprecated Use `sparse: true` instead. This key is kept solely for backward
+   * compatibility; `component({ dontFragment: true })` continues to work exactly
+   * as before and is equivalent to `sparse: true`.
    */
   dontFragment?: boolean;
   /**
@@ -324,7 +334,7 @@ const componentNames: (string | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
 // BitSets for fast component option checks (Component ID range: 1-1023)
 const exclusiveFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const cascadeDeleteFlags = new BitSet(COMPONENT_ID_MAX + 1);
-const dontFragmentFlags = new BitSet(COMPONENT_ID_MAX + 1);
+const sparseFlags = new BitSet(COMPONENT_ID_MAX + 1);
 const componentMerges: (ComponentMerge<any> | undefined)[] = new Array(COMPONENT_ID_MAX + 1);
 
 /**
@@ -370,7 +380,8 @@ export function component<T = void>(nameOrOptions?: string | ComponentOptions<T>
     // Set bitset flags for fast lookup
     if (options.exclusive) exclusiveFlags.set(id);
     if (options.cascadeDelete) cascadeDeleteFlags.set(id);
-    if (options.dontFragment) dontFragmentFlags.set(id);
+    // Support both `sparse` (preferred) and the legacy `dontFragment` alias for BC
+    if (options.sparse || options.dontFragment) sparseFlags.set(id);
     if (options.merge) componentMerges[id] = options.merge;
   }
 
@@ -406,12 +417,14 @@ export function getComponentOptions<T = any>(id: ComponentId<T>): ComponentOptio
   const hasName = componentNames[id] !== undefined;
   const hasExclusive = exclusiveFlags.has(id);
   const hasCascadeDelete = cascadeDeleteFlags.has(id);
-  const hasDontFragment = dontFragmentFlags.has(id);
+  const hasSparse = sparseFlags.has(id);
   return {
     name: hasName ? componentNames[id] : undefined,
     exclusive: hasExclusive ? true : undefined,
     cascadeDelete: hasCascadeDelete ? true : undefined,
-    dontFragment: hasDontFragment ? true : undefined,
+    sparse: hasSparse ? true : undefined,
+    // For full backward compatibility with code that inspects options.dontFragment
+    dontFragment: hasSparse ? true : undefined,
     merge: componentMerges[id] as ComponentMerge<T> | undefined,
   };
 }
@@ -487,20 +500,21 @@ export function isCascadeDeleteComponent(id: ComponentId<any>): boolean {
 }
 
 /**
- * Check if a component is marked as `dontFragment`.
+ * Check if a component is marked as `sparse` (sparse storage for relations).
  *
- * When a component has `dontFragment: true`, relations using it do not cause
- * archetype fragmentation — entities with different relation targets can share
- * the same archetype. This is a fast O(1) bitset lookup.
+ * When a component has `sparse: true`, relations using it do not cause archetype
+ * fragmentation — entities with different relation targets can share the same
+ * archetype. This is a fast O(1) bitset lookup. The legacy `dontFragment` key
+ * is still accepted and sets the same internal flag.
  *
  * @param id - The component ID to check.
- * @returns `true` if the component was created with `dontFragment: true`.
+ * @returns `true` if the component was created with `sparse: true` (or the
+ *   legacy `dontFragment: true`).
  *
- * @see {@link ComponentOptions.dontFragment} for the full explanation of how
- *   `dontFragment` prevents archetype fragmentation.
+ * @see {@link ComponentOptions.sparse} for the full explanation of sparse storage.
  */
-export function isDontFragmentComponent(id: ComponentId<any>): boolean {
-  return dontFragmentFlags.has(id);
+export function isSparseComponent(id: ComponentId<any>): boolean {
+  return sparseFlags.has(id);
 }
 
 /**
@@ -511,9 +525,8 @@ export function isDontFragmentComponent(id: ComponentId<any>): boolean {
  * ID and checking: (1) the ID is a valid relation, (2) the component ID is in the
  * valid range, (3) the target satisfies the condition, and (4) the flag bit is set.
  *
- * Used as the fast-path implementation for `isDontFragmentRelation`,
- * `isDontFragmentWildcard`, `isExclusiveRelation`, `isExclusiveWildcard`,
- * and `isCascadeDeleteRelation`.
+ * Used as the fast-path implementation for `isSparseRelation`, `isSparseWildcard`,
+ * `isExclusiveRelation`, `isExclusiveWildcard`, and `isCascadeDeleteRelation`.
  *
  * @param id - The entity/relation ID to check.
  * @param flagBitSet - The bitset tracking which component IDs have the flag.
@@ -534,53 +547,41 @@ function checkRelationFlag(
 }
 
 /**
- * Check if an ID is a specific (non-wildcard) relation backed by a `dontFragment`
- * component.
+ * Check if an ID is a specific (non-wildcard) relation backed by a `sparse`
+ * component (i.e. stored in the side sparse store rather than the archetype).
  *
  * This is used in hot paths (archetype resolution, command processing) to determine
- * whether a relation should be excluded from the archetype signature. Relations with
- * `dontFragment` components are stored in the shared {@link DontFragmentStore} instead
- * of being part of the archetype's component type list.
- *
- * This is an optimized function that avoids the overhead of `getDetailedIdType`
- * by directly decoding and checking the relation's component ID against the
- * `dontFragment` bitset.
+ * whether a relation should be excluded from the archetype signature.
  *
  * @param id - The entity/relation ID to check (must be a relation ID, not a plain
  *   component ID).
  * @returns `true` if this is a specific-target relation (not wildcard) whose base
- *   component was created with `dontFragment: true`.
+ *   component was created with `sparse: true` (or legacy `dontFragment: true`).
  *
- * @see {@link isDontFragmentWildcard} for the wildcard variant.
- * @see {@link ComponentOptions.dontFragment} for the full explanation.
+ * @see {@link isSparseWildcard} for the wildcard variant.
+ * @see {@link ComponentOptions.sparse} for the full explanation.
  */
-export function isDontFragmentRelation(id: EntityId<any>): boolean {
-  return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
+export function isSparseRelation(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, sparseFlags, (targetId) => targetId !== WILDCARD_TARGET_ID);
 }
 
 /**
  * Check if an ID is a wildcard relation (`relation(Comp, "*")`) backed by a
- * `dontFragment` component.
- *
- * Wildcard markers for `dontFragment` components are placed in the archetype
- * component list so that queries can discover archetypes containing entities
- * with that relation type. This function is used in `filterRegularComponentTypes`
- * to **keep** these wildcard markers in the archetype signature while stripping
- * out specific-target `dontFragment` relations.
+ * `sparse` component.
  *
- * This is an optimized function that avoids the overhead of `getDetailedIdType`
- * by directly decoding and checking the relation's component ID against the
- * `dontFragment` bitset.
+ * Wildcard markers for sparse components are placed in the archetype component
+ * list so that queries can discover archetypes containing entities with that
+ * relation type.
  *
  * @param id - The entity/relation ID to check.
  * @returns `true` if this is a wildcard relation (`"*"` target) whose base
- *   component was created with `dontFragment: true`.
+ *   component was created with `sparse: true` (or legacy `dontFragment: true`).
  *
- * @see {@link isDontFragmentRelation} for the specific-target variant.
- * @see {@link ComponentOptions.dontFragment} for the full explanation.
+ * @see {@link isSparseRelation} for the specific-target variant.
+ * @see {@link ComponentOptions.sparse} for the full explanation.
  */
-export function isDontFragmentWildcard(id: EntityId<any>): boolean {
-  return checkRelationFlag(id, dontFragmentFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
+export function isSparseWildcard(id: EntityId<any>): boolean {
+  return checkRelationFlag(id, sparseFlags, (targetId) => targetId === WILDCARD_TARGET_ID);
 }
 
 /**

package/src/entity/index.ts

@@ -54,10 +54,13 @@ export {
   getComponentOptions,
   isCascadeDeleteComponent,
   isCascadeDeleteRelation,
-  isDontFragmentComponent,
-  isDontFragmentRelation,
-  isDontFragmentWildcard,
+  isSparseComponent as isDontFragmentComponent,
+  isSparseRelation as isDontFragmentRelation,
+  isSparseWildcard as isDontFragmentWildcard,
   isExclusiveComponent,
   isExclusiveRelation,
   isExclusiveWildcard,
+  isSparseComponent,
+  isSparseRelation,
+  isSparseWildcard,
 } from "../component/registry";

package/src/index.ts

@@ -39,3 +39,16 @@ export { Query } from "./query/query";
 
 // Type utilities
 export type { ComponentTuple, ComponentType, LifecycleCallback, LifecycleHook } from "./types";
+
+// Debug / observability types
+export type { DebugStatsCollector, SyncDebugStats } from "./types";
+
+// Sparse / dontFragment flag checks (preferred + legacy aliases for BC)
+export {
+  isSparseComponent as isDontFragmentComponent,
+  isSparseRelation as isDontFragmentRelation,
+  isSparseWildcard as isDontFragmentWildcard,
+  isSparseComponent,
+  isSparseRelation,
+  isSparseWildcard,
+} from "./component/registry";

package/src/query/filter.ts

@@ -1,12 +1,6 @@
 import type { Archetype } from "../archetype/archetype";
 import type { EntityId } from "../entity";
-import {
-  getComponentIdFromRelationId,
-  getDetailedIdType,
-  isDontFragmentComponent,
-  isRelationId,
-  relation,
-} from "../entity";
+import { getComponentIdFromRelationId, getDetailedIdType, isRelationId, isSparseComponent, relation } from "../entity";
 
 /**
  * Filter options for queries
@@ -41,13 +35,13 @@ export function matchesComponentTypes(archetype: Archetype, componentTypes: Enti
     } else if (
       (detailedType.type === "entity-relation" || detailedType.type === "component-relation") &&
       detailedType.componentId !== undefined &&
-      isDontFragmentComponent(detailedType.componentId)
+      isSparseComponent(detailedType.componentId)
     ) {
-      // For specific dontFragment relations, check if archetype has the wildcard marker
+      // For specific sparse relations, check if archetype has the wildcard marker
       const wildcardMarker = relation(detailedType.componentId, "*");
       return archetype.componentTypeSet.has(wildcardMarker);
     } else {
-      // For regular components and non-dontFragment relations, check direct inclusion
+      // For regular components and non-sparse relations, check direct inclusion
       return archetype.componentTypeSet.has(type);
     }
   });

package/src/query/query.ts

@@ -1,7 +1,7 @@
 import type { Archetype } from "../archetype/archetype";
 import { normalizeComponentTypes } from "../component/type-utils";
 import type { EntityId, WildcardRelationId } from "../entity";
-import { getDetailedIdType, isDontFragmentComponent } from "../entity";
+import { getDetailedIdType, isSparseComponent } from "../entity";
 import type { ComponentTuple, ComponentType } from "../types";
 import type { World } from "../world/world";
 import { matchesComponentTypes, matchesFilter, type QueryFilter } from "./filter";
@@ -33,8 +33,8 @@ export class Query {
   _cacheKey: string | undefined;
   /** Cached wildcard component types for faster entity filtering */
   private wildcardTypes: WildcardRelationId<any>[];
-  /** Cached specific dontFragment relation types that need entity-level filtering */
-  private specificDontFragmentTypes: EntityId<any>[];
+  /** Cached specific sparse relation types that need entity-level filtering */
+  private specificSparseRelationTypes: EntityId<any>[];
 
   /**
    * @internal Queries should be created via {@link World.createQuery}, not instantiated directly.
@@ -47,13 +47,13 @@ export class Query {
     this.wildcardTypes = this.componentTypes.filter(
       (ct) => getDetailedIdType(ct).type === "wildcard-relation",
     ) as WildcardRelationId<any>[];
-    // Pre-compute specific dontFragment relation types that need entity-level filtering
-    this.specificDontFragmentTypes = this.componentTypes.filter((ct) => {
+    // Pre-compute specific sparse relation types that need entity-level filtering
+    this.specificSparseRelationTypes = this.componentTypes.filter((ct) => {
       const detailedType = getDetailedIdType(ct);
       return (
         (detailedType.type === "entity-relation" || detailedType.type === "component-relation") &&
         detailedType.componentId !== undefined &&
-        isDontFragmentComponent(detailedType.componentId)
+        isSparseComponent(detailedType.componentId)
       );
     });
     this.updateCache();
@@ -86,8 +86,8 @@ export class Query {
   getEntities(): EntityId[] {
     this.ensureNotDisposed();
 
-    // Fast path: no wildcard relations and no specific dontFragment relations
-    if (this.wildcardTypes.length === 0 && this.specificDontFragmentTypes.length === 0) {
+    // Fast path: no wildcard relations and no specific sparse relations
+    if (this.wildcardTypes.length === 0 && this.specificSparseRelationTypes.length === 0) {
       const result: EntityId[] = [];
       for (const archetype of this.cachedArchetypes) {
         for (const entity of archetype.getEntities()) {
@@ -100,7 +100,7 @@ export class Query {
     // Slow path: need to filter entities that actually have the required relations
     // This is necessary for:
     // 1. Wildcard relations where an archetype can contain entities with/without the relation
-    // 2. Specific dontFragment relations where the archetype only has the wildcard marker
+    // 2. Specific sparse relations where the archetype only has the wildcard marker
     const result: EntityId[] = [];
     for (const archetype of this.cachedArchetypes) {
       for (const entity of archetype.getEntities()) {
@@ -113,7 +113,7 @@ export class Query {
   }
 
   /**
-   * Check if entity matches all query requirements (wildcards and specific dontFragment relations)
+   * Check if entity matches all query requirements (wildcards and specific sparse relations)
    */
   private entityMatchesQuery(archetype: Archetype, entity: EntityId): boolean {
     // Check wildcard relations
@@ -124,8 +124,8 @@ export class Query {
       }
     }
 
-    // Check specific dontFragment relations
-    for (const specificType of this.specificDontFragmentTypes) {
+    // Check specific sparse relations
+    for (const specificType of this.specificSparseRelationTypes) {
       const result = archetype.getOptional(entity, specificType);
       if (result === undefined) {
         return false;

package/src/storage/serialization.ts

@@ -33,9 +33,9 @@ export type SerializedComponent = {
 };
 
 /**
- * Encode an internal EntityId into a SerializedEntityId for snapshots
+ * Core encoding logic (no cache). Extracted so cached wrapper can reuse it without duplication.
  */
-export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
+function encodeEntityIdCore(id: EntityId<any>): SerializedEntityId {
   const detailed = getDetailedIdType(id);
   switch (detailed.type) {
     case "component": {
@@ -81,6 +81,33 @@ export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
   }
 }
 
+/**
+ * Encode an internal EntityId into a SerializedEntityId for snapshots.
+ * Use encodeEntityIdCached when serializing many entities to benefit from memoization
+ * of repeated component/relation type IDs.
+ */
+export function encodeEntityId(id: EntityId<any>): SerializedEntityId {
+  return encodeEntityIdCore(id);
+}
+
+/**
+ * Encode an EntityId, using an optional cache Map to avoid repeated getDetailedIdType
+ * + name lookup work for IDs that appear many times (typical during full world snapshot).
+ */
+export function encodeEntityIdCached(
+  id: EntityId<any>,
+  cache?: Map<EntityId<any>, SerializedEntityId>,
+): SerializedEntityId {
+  if (cache) {
+    const cached = cache.get(id);
+    if (cached !== undefined) return cached;
+    const result = encodeEntityIdCore(id);
+    cache.set(id, result);
+    return result;
+  }
+  return encodeEntityIdCore(id);
+}
+
 /**
  * Decode a SerializedEntityId back into an internal EntityId
  */