@codehz/ecs 0.1.1 → 0.1.3

package/README.md

@@ -180,6 +180,80 @@ bun run examples/simple/demo.ts
 - `update(...params)`: 更新世界（参数取决于泛型配置）
 - `sync()`: 应用命令缓冲区
 
+### 序列化（快照）
+
+库提供了对世界状态的「内存快照」序列化接口，用于保存/恢复实体与组件的数据。注意关键点：
+
+- `World.serialize()` 返回一个内存中的快照对象（snapshot），快照会按引用保存组件的实际值；它不会对数据做 JSON.stringify 操作，也不会尝试把组件值转换为可序列化格式。
+- `World.deserialize(snapshot)` 接受由 `World.serialize()` 生成的快照对象并重建世界状态。它期望一个内存对象（非 JSON 字符串）。
+
+为什么采用这种设计？很多情况下组件值可能包含函数、类实例、循环引用或其他无法用 JSON 表示的值。库不对组件值强行进行序列化/字符串化，以避免数据丢失或不可信的自动转换。
+
+示例：内存回环（component 值可为任意对象）
+
+```ts
+// 获取快照（内存对象）
+const snapshot = world.serialize();
+
+// 在同一进程内直接恢复
+const restored = World.deserialize(snapshot);
+```
+
+持久化到磁盘或跨进程传输
+
+如果你需要把世界保存到文件或通过网络传输，需要自己实现组件值的编码/解码策略：
+
+1. 使用 `World.serialize()` 得到 snapshot。
+2. 对 snapshot 中的组件值逐项进行可自定义的编码（例如将类实例转成纯数据、把函数替换为标识符，或使用自定义二进制编码）。
+3. 将编码后的对象字符串化并持久化。恢复时执行相反的解码步骤，得到与 `World.serialize()` 兼容的快照对象，然后调用 `World.deserialize(decodedSnapshot)`。
+
+简单示例：当组件值都是 JSON-友好时
+
+```ts
+const snapshot = world.serialize();
+// 如果组件值都可 JSON 化，可以直接 stringify
+const text = JSON.stringify(snapshot);
+// 写入文件或发送到网络
+
+// 恢复：parse -> deserialize
+const parsed = JSON.parse(text);
+const restored = World.deserialize(parsed);
+```
+
+示例：带自定义编码的持久化（伪代码）
+
+```ts
+const snapshot = world.serialize();
+
+// 将组件值编码为可持久化格式
+const encoded = {
+  ...snapshot,
+  entities: snapshot.entities.map((e) => ({
+    id: e.id,
+    components: e.components.map((c) => ({ type: c.type, value: myEncode(c.value) })),
+  })),
+};
+
+// 持久化 encoded（JSON.stringify / 二进制写入等）
+
+// 恢复时解码回原始组件值
+const decoded = /* parse file and decode */ encoded;
+const readySnapshot = {
+  ...decoded,
+  entities: decoded.entities.map((e) => ({
+    id: e.id,
+    components: e.components.map((c) => ({ type: c.type, value: myDecode(c.value) })),
+  })),
+};
+
+const restored = World.deserialize(readySnapshot);
+```
+
+注意事项
+
+- 快照只包含实体、组件、以及 `EntityIdManager` 的分配器状态（用于保留下一次分配的 ID）；并不会自动恢复已注册的系统、查询缓存或生命周期钩子。恢复后应由应用负责重新注册系统与钩子。
+- 若需要跨版本兼容，建议在持久化格式中包含 `version` 字段，并在恢复时进行格式兼容性检查与迁移。
+
 ### Entity
 
 - `component<T>(id)`: 分配类型安全的组件ID（上限：1022个）

package/entity.d.ts

@@ -129,6 +129,22 @@ export declare class EntityIdManager {
      * Get the next ID that would be allocated (for debugging)
      */
     getNextId(): number;
+    /**
+     * Serialize internal state for persistence.
+     * Returns a plain object representing allocator state. Values may be non-JSON-serializable.
+     */
+    serializeState(): {
+        nextId: number;
+        freelist: number[];
+    };
+    /**
+     * Restore internal state from a previously-serialized object.
+     * Overwrites the current nextId and freelist.
+     */
+    deserializeState(state: {
+        nextId: number;
+        freelist?: number[];
+    }): void;
 }
 /**
  * Component ID Manager for automatic allocation

package/index.js

@@ -184,6 +184,16 @@ class EntityIdManager {
   getNextId() {
     return this.nextId;
   }
+  serializeState() {
+    return { nextId: this.nextId, freelist: Array.from(this.freelist) };
+  }
+  deserializeState(state) {
+    if (typeof state.nextId !== "number") {
+      throw new Error("Invalid state for EntityIdManager.deserializeState");
+    }
+    this.nextId = state.nextId;
+    this.freelist = new Set(state.freelist || []);
+  }
 }
 
 class ComponentIdAllocator {
@@ -650,63 +660,94 @@ class SystemScheduler {
 class World {
   entityIdManager = new EntityIdManager;
   archetypes = [];
-  archetypeMap = new Map;
+  archetypeBySignature = new Map;
   entityToArchetype = new Map;
-  systemScheduler = new SystemScheduler;
+  archetypesByComponent = new Map;
+  entityReferences = new Map;
   queries = [];
   queryCache = new Map;
-  commandBuffer;
-  componentToArchetypes = new Map;
+  systemScheduler = new SystemScheduler;
+  commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
   lifecycleHooks = new Map;
-  entityReverseIndex = new Map;
   exclusiveComponents = new Set;
-  constructor() {
-    this.commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
+  constructor(snapshot) {
+    if (snapshot && typeof snapshot === "object") {
+      if (snapshot.entityManager) {
+        this.entityIdManager.deserializeState(snapshot.entityManager);
+      }
+      if (Array.isArray(snapshot.exclusiveComponents)) {
+        for (const id of snapshot.exclusiveComponents) {
+          this.exclusiveComponents.add(id);
+        }
+      }
+      if (Array.isArray(snapshot.entities)) {
+        for (const entry of snapshot.entities) {
+          const entityId = entry.id;
+          const componentsArray = entry.components || [];
+          const componentMap = new Map;
+          const componentTypes = [];
+          for (const componentEntry of componentsArray) {
+            componentMap.set(componentEntry.type, componentEntry.value);
+            componentTypes.push(componentEntry.type);
+          }
+          const archetype = this.ensureArchetype(componentTypes);
+          archetype.addEntity(entityId, componentMap);
+          this.entityToArchetype.set(entityId, archetype);
+          for (const compType of componentTypes) {
+            const detailedType = getDetailedIdType(compType);
+            if (detailedType.type === "entity-relation") {
+              const targetEntityId = detailedType.targetId;
+              this.trackEntityReference(entityId, compType, targetEntityId);
+            } else if (detailedType.type === "entity") {
+              this.trackEntityReference(entityId, compType, compType);
+            }
+          }
+        }
+      }
+    }
   }
-  getComponentTypesHash(componentTypes) {
+  createArchetypeSignature(componentTypes) {
     return componentTypes.join(",");
   }
   new() {
     const entityId = this.entityIdManager.allocate();
-    let emptyArchetype = this.getOrCreateArchetype([]);
+    let emptyArchetype = this.ensureArchetype([]);
     emptyArchetype.addEntity(entityId, new Map);
     this.entityToArchetype.set(entityId, emptyArchetype);
     return entityId;
   }
-  _destroyEntity(entityId) {
+  destroyEntityImmediate(entityId) {
     const archetype = this.entityToArchetype.get(entityId);
     if (!archetype) {
       return;
     }
-    const componentReferences = this.getComponentReferences(entityId);
+    const componentReferences = this.getEntityReferences(entityId);
     for (const { sourceEntityId, componentType } of componentReferences) {
       const sourceArchetype = this.entityToArchetype.get(sourceEntityId);
       if (sourceArchetype) {
         const currentComponents = new Map;
-        for (const compType of sourceArchetype.componentTypes) {
-          if (compType !== componentType) {
-            const data = sourceArchetype.get(sourceEntityId, compType);
-            if (data !== undefined) {
-              currentComponents.set(compType, data);
-            }
+        for (const archetypeComponentType of sourceArchetype.componentTypes) {
+          if (archetypeComponentType !== componentType) {
+            const componentData = sourceArchetype.get(sourceEntityId, archetypeComponentType);
+            currentComponents.set(archetypeComponentType, componentData);
           }
         }
         const newComponentTypes = Array.from(currentComponents.keys()).sort((a, b) => a - b);
-        const newArchetype = this.getOrCreateArchetype(newComponentTypes);
+        const newArchetype = this.ensureArchetype(newComponentTypes);
         sourceArchetype.removeEntity(sourceEntityId);
         if (sourceArchetype.getEntities().length === 0) {
-          this.removeEmptyArchetype(sourceArchetype);
+          this.cleanupEmptyArchetype(sourceArchetype);
         }
         newArchetype.addEntity(sourceEntityId, currentComponents);
         this.entityToArchetype.set(sourceEntityId, newArchetype);
-        this.removeComponentReference(sourceEntityId, componentType, entityId);
-        this.executeComponentLifecycleHooks(sourceEntityId, new Map, new Set([componentType]));
+        this.untrackEntityReference(sourceEntityId, componentType, entityId);
+        this.triggerLifecycleHooks(sourceEntityId, new Map, new Set([componentType]));
       }
     }
-    this.entityReverseIndex.delete(entityId);
+    this.entityReferences.delete(entityId);
     archetype.removeEntity(entityId);
     if (archetype.getEntities().length === 0) {
-      this.removeEmptyArchetype(archetype);
+      this.cleanupEmptyArchetype(archetype);
     }
     this.entityToArchetype.delete(entityId);
     this.entityIdManager.deallocate(entityId);
@@ -785,7 +826,7 @@ class World {
   createQuery(componentTypes, filter = {}) {
     const sortedTypes = [...componentTypes].sort((a, b) => a - b);
     const filterKey = serializeQueryFilter(filter);
-    const key = `${this.getComponentTypesHash(sortedTypes)}${filterKey ? `|${filterKey}` : ""}`;
+    const key = `${this.createArchetypeSignature(sortedTypes)}${filterKey ? `|${filterKey}` : ""}`;
     const cached = this.queryCache.get(key);
     if (cached) {
       cached.refCount++;
@@ -833,15 +874,15 @@ class World {
     }
     const regularComponents = [];
     const wildcardRelations = [];
-    for (const type of componentTypes) {
-      const detailedType = getDetailedIdType(type);
+    for (const componentType of componentTypes) {
+      const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "wildcard-relation") {
         wildcardRelations.push({
           componentId: detailedType.componentId,
-          relationId: type
+          relationId: componentType
         });
       } else {
-        regularComponents.push(type);
+        regularComponents.push(componentType);
       }
     }
     let matchingArchetypes = [];
@@ -849,15 +890,15 @@ class World {
       const sortedRegularTypes = [...regularComponents].sort((a, b) => a - b);
       if (sortedRegularTypes.length === 1) {
         const componentType = sortedRegularTypes[0];
-        matchingArchetypes = this.componentToArchetypes.get(componentType) || [];
+        matchingArchetypes = this.archetypesByComponent.get(componentType) || [];
       } else {
-        const archetypeLists = sortedRegularTypes.map((type) => this.componentToArchetypes.get(type) || []);
+        const archetypeLists = sortedRegularTypes.map((type) => this.archetypesByComponent.get(type) || []);
         const firstList = archetypeLists[0] || [];
         const intersection = new Set;
         for (const archetype of firstList) {
           let hasAllComponents = true;
-          for (let i = 1;i < archetypeLists.length; i++) {
-            const otherList = archetypeLists[i];
+          for (let listIndex = 1;listIndex < archetypeLists.length; listIndex++) {
+            const otherList = archetypeLists[listIndex];
             if (!otherList.includes(archetype)) {
               hasAllComponents = false;
               break;
@@ -873,12 +914,12 @@ class World {
       matchingArchetypes = [...this.archetypes];
     }
     for (const wildcard of wildcardRelations) {
-      const componentArchetypes = this.componentToArchetypes.get(wildcard.componentId) || [];
+      const componentArchetypes = this.archetypesByComponent.get(wildcard.componentId) || [];
       matchingArchetypes = matchingArchetypes.filter((archetype) => componentArchetypes.includes(archetype));
     }
     return matchingArchetypes;
   }
-  queryEntities(componentTypes, includeComponents) {
+  query(componentTypes, includeComponents) {
     const matchingArchetypes = this.getMatchingArchetypes(componentTypes);
     if (includeComponents) {
       const result = [];
@@ -899,7 +940,7 @@ class World {
     const changeset = new ComponentChangeset;
     const hasDestroy = commands.some((cmd) => cmd.type === "destroy");
     if (hasDestroy) {
-      this._destroyEntity(entityId);
+      this.destroyEntityImmediate(entityId);
       return changeset;
     }
     const currentArchetype = this.entityToArchetype.get(entityId);
@@ -908,14 +949,14 @@ class World {
     }
     const currentComponents = new Map;
     for (const componentType of currentArchetype.componentTypes) {
-      const data = currentArchetype.get(entityId, componentType);
-      currentComponents.set(componentType, data);
+      const componentData = currentArchetype.get(entityId, componentType);
+      currentComponents.set(componentType, componentData);
     }
-    for (const cmd of commands) {
-      switch (cmd.type) {
+    for (const command of commands) {
+      switch (command.type) {
         case "set":
-          if (cmd.componentType) {
-            const detailedType = getDetailedIdType(cmd.componentType);
+          if (command.componentType) {
+            const detailedType = getDetailedIdType(command.componentType);
             if ((detailedType.type === "entity-relation" || detailedType.type === "component-relation") && this.exclusiveComponents.has(detailedType.componentId)) {
               for (const componentType of currentArchetype.componentTypes) {
                 const componentDetailedType = getDetailedIdType(componentType);
@@ -924,12 +965,12 @@ class World {
                 }
               }
             }
-            changeset.set(cmd.componentType, cmd.component);
+            changeset.set(command.componentType, command.component);
           }
           break;
         case "delete":
-          if (cmd.componentType) {
-            const detailedType = getDetailedIdType(cmd.componentType);
+          if (command.componentType) {
+            const detailedType = getDetailedIdType(command.componentType);
             if (detailedType.type === "wildcard-relation") {
               const baseComponentId = detailedType.componentId;
               for (const componentType of currentArchetype.componentTypes) {
@@ -941,7 +982,7 @@ class World {
                 }
               }
             } else {
-              changeset.delete(cmd.componentType);
+              changeset.delete(command.componentType);
             }
           }
           break;
@@ -952,7 +993,7 @@ class World {
     const currentComponentTypes = currentArchetype.componentTypes.sort((a, b) => a - b);
     const needsArchetypeChange = finalComponentTypes.length !== currentComponentTypes.length || !finalComponentTypes.every((type, index) => type === currentComponentTypes[index]);
     if (needsArchetypeChange) {
-      const newArchetype = this.getOrCreateArchetype(finalComponentTypes);
+      const newArchetype = this.ensureArchetype(finalComponentTypes);
       currentArchetype.removeEntity(entityId);
       newArchetype.addEntity(entityId, finalComponents);
       this.entityToArchetype.set(entityId, newArchetype);
@@ -965,33 +1006,33 @@ class World {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
-        this.removeComponentReference(entityId, componentType, targetEntityId);
+        this.untrackEntityReference(entityId, componentType, targetEntityId);
       } else if (detailedType.type === "entity") {
-        this.removeComponentReference(entityId, componentType, componentType);
+        this.untrackEntityReference(entityId, componentType, componentType);
       }
     }
     for (const [componentType, component2] of changeset.adds) {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
-        this.addComponentReference(entityId, componentType, targetEntityId);
+        this.trackEntityReference(entityId, componentType, targetEntityId);
       } else if (detailedType.type === "entity") {
-        this.addComponentReference(entityId, componentType, componentType);
+        this.trackEntityReference(entityId, componentType, componentType);
       }
     }
-    this.executeComponentLifecycleHooks(entityId, changeset.adds, changeset.removes);
+    this.triggerLifecycleHooks(entityId, changeset.adds, changeset.removes);
     return changeset;
   }
-  getOrCreateArchetype(componentTypes) {
+  ensureArchetype(componentTypes) {
     const sortedTypes = [...componentTypes].sort((a, b) => a - b);
-    const hashKey = this.getComponentTypesHash(sortedTypes);
-    return getOrCreateWithSideEffect(this.archetypeMap, hashKey, () => {
+    const hashKey = this.createArchetypeSignature(sortedTypes);
+    return getOrCreateWithSideEffect(this.archetypeBySignature, hashKey, () => {
       const newArchetype = new Archetype(sortedTypes);
       this.archetypes.push(newArchetype);
       for (const componentType of sortedTypes) {
-        const archetypes = this.componentToArchetypes.get(componentType) || [];
+        const archetypes = this.archetypesByComponent.get(componentType) || [];
         archetypes.push(newArchetype);
-        this.componentToArchetypes.set(componentType, archetypes);
+        this.archetypesByComponent.set(componentType, archetypes);
       }
       for (const query of this.queries) {
         query.checkNewArchetype(newArchetype);
@@ -999,30 +1040,30 @@ class World {
       return newArchetype;
     });
   }
-  addComponentReference(sourceEntityId, componentType, targetEntityId) {
-    if (!this.entityReverseIndex.has(targetEntityId)) {
-      this.entityReverseIndex.set(targetEntityId, new Set);
+  trackEntityReference(sourceEntityId, componentType, targetEntityId) {
+    if (!this.entityReferences.has(targetEntityId)) {
+      this.entityReferences.set(targetEntityId, new Set);
     }
-    this.entityReverseIndex.get(targetEntityId).add({ sourceEntityId, componentType });
+    this.entityReferences.get(targetEntityId).add({ sourceEntityId, componentType });
   }
-  removeComponentReference(sourceEntityId, componentType, targetEntityId) {
-    const references = this.entityReverseIndex.get(targetEntityId);
+  untrackEntityReference(sourceEntityId, componentType, targetEntityId) {
+    const references = this.entityReferences.get(targetEntityId);
     if (references) {
-      references.forEach((ref) => {
-        if (ref.sourceEntityId === sourceEntityId && ref.componentType === componentType) {
-          references.delete(ref);
+      references.forEach((reference) => {
+        if (reference.sourceEntityId === sourceEntityId && reference.componentType === componentType) {
+          references.delete(reference);
         }
       });
       if (references.size === 0) {
-        this.entityReverseIndex.delete(targetEntityId);
+        this.entityReferences.delete(targetEntityId);
       }
     }
   }
-  getComponentReferences(targetEntityId) {
-    const references = this.entityReverseIndex.get(targetEntityId);
+  getEntityReferences(targetEntityId) {
+    const references = this.entityReferences.get(targetEntityId);
     return references ? Array.from(references) : [];
   }
-  removeEmptyArchetype(archetype) {
+  cleanupEmptyArchetype(archetype) {
     if (archetype.getEntities().length > 0) {
       return;
     }
@@ -1030,28 +1071,28 @@ class World {
     if (index !== -1) {
       this.archetypes.splice(index, 1);
     }
-    const hashKey = this.getComponentTypesHash(archetype.componentTypes);
-    this.archetypeMap.delete(hashKey);
+    const hashKey = this.createArchetypeSignature(archetype.componentTypes);
+    this.archetypeBySignature.delete(hashKey);
     for (const componentType of archetype.componentTypes) {
-      const archetypes = this.componentToArchetypes.get(componentType);
+      const archetypes = this.archetypesByComponent.get(componentType);
       if (archetypes) {
         const compIndex = archetypes.indexOf(archetype);
         if (compIndex !== -1) {
           archetypes.splice(compIndex, 1);
           if (archetypes.length === 0) {
-            this.componentToArchetypes.delete(componentType);
+            this.archetypesByComponent.delete(componentType);
           }
         }
       }
     }
   }
-  executeComponentLifecycleHooks(entityId, addedComponents, removedComponents) {
+  triggerLifecycleHooks(entityId, addedComponents, removedComponents) {
     for (const [componentType, component2] of addedComponents) {
       const directHooks = this.lifecycleHooks.get(componentType);
       if (directHooks) {
-        for (const hook of directHooks) {
-          if (hook.onAdded) {
-            hook.onAdded(entityId, componentType, component2);
+        for (const lifecycleHook of directHooks) {
+          if (lifecycleHook.onAdded) {
+            lifecycleHook.onAdded(entityId, componentType, component2);
           }
         }
       }
@@ -1060,9 +1101,9 @@ class World {
         const wildcardRelationId = relation(detailedType.componentId, "*");
         const wildcardHooks = this.lifecycleHooks.get(wildcardRelationId);
         if (wildcardHooks) {
-          for (const hook of wildcardHooks) {
-            if (hook.onAdded) {
-              hook.onAdded(entityId, componentType, component2);
+          for (const lifecycleHook of wildcardHooks) {
+            if (lifecycleHook.onAdded) {
+              lifecycleHook.onAdded(entityId, componentType, component2);
             }
           }
         }
@@ -1071,9 +1112,9 @@ class World {
     for (const componentType of removedComponents) {
       const directHooks = this.lifecycleHooks.get(componentType);
       if (directHooks) {
-        for (const hook of directHooks) {
-          if (hook.onRemoved) {
-            hook.onRemoved(entityId, componentType);
+        for (const lifecycleHook of directHooks) {
+          if (lifecycleHook.onRemoved) {
+            lifecycleHook.onRemoved(entityId, componentType);
           }
         }
       }
@@ -1091,6 +1132,23 @@ class World {
       }
     }
   }
+  serialize() {
+    const entities = [];
+    for (const [entityId, archetype] of this.entityToArchetype.entries()) {
+      const compEntries = [];
+      for (const compType of archetype.componentTypes) {
+        const value = archetype.get(entityId, compType);
+        compEntries.push({ type: compType, value });
+      }
+      entities.push({ id: entityId, components: compEntries });
+    }
+    return {
+      version: 1,
+      entityManager: this.entityIdManager.serializeState(),
+      exclusiveComponents: Array.from(this.exclusiveComponents),
+      entities
+    };
+  }
 }
 export {
   relation,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codehz/ecs",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "main": "./index.js",
   "types": "./index.d.ts",

package/world.d.ts

@@ -11,43 +11,50 @@ import type { ComponentTuple, LifecycleHook } from "./types";
  * Manages entities, components, and systems
  */
 export declare class World<UpdateParams extends any[] = []> {
+    /** Manages allocation and deallocation of entity IDs */
     private entityIdManager;
+    /** Array of all archetypes in the world */
     private archetypes;
-    private archetypeMap;
+    /** Maps archetype signatures (component type signatures) to archetype instances */
+    private archetypeBySignature;
+    /** Maps entity IDs to their current archetype */
     private entityToArchetype;
-    private systemScheduler;
+    /** Maps component types to arrays of archetypes that contain them */
+    private archetypesByComponent;
+    /** Tracks which entities reference each entity as a component type */
+    private entityReferences;
+    /** Array of all active queries for archetype change notifications */
     private queries;
+    /** Cache for queries keyed by component types and filter signatures */
     private queryCache;
+    /** Schedules and executes systems in dependency order */
+    private systemScheduler;
+    /** Buffers structural changes for deferred execution */
     private commandBuffer;
-    private componentToArchetypes;
-    /**
-     * Hook storage for component and wildcard relation lifecycle events
-     */
+    /** Stores lifecycle hooks for component and relation events */
     private lifecycleHooks;
+    /** Set of component IDs marked as exclusive relations */
+    private exclusiveComponents;
     /**
-     * Reverse index tracking which entities use each entity as a component type
-     * Maps entity ID to set of {sourceEntityId, componentType} pairs where componentType uses this entity
-     * This includes both relation components and direct usage of entities as component types
-     */
-    private entityReverseIndex;
-    /**
-     * Set of component IDs that are marked as exclusive relations
-     * For exclusive relations, an entity can have at most one relation per base component
+     * Create a new World.
+     * If an optional snapshot object is provided (previously produced by `world.serialize()`),
+     * the world will be restored from that snapshot. The snapshot may contain non-JSON values.
      */
-    private exclusiveComponents;
-    constructor();
+    constructor(snapshot?: any);
     /**
-     * Generate a hash key for component types array
+     * Generate a signature string for component types array
+     * @returns A string signature for the component types
      */
-    private getComponentTypesHash;
+    private createArchetypeSignature;
     /**
      * Create a new entity
+     * @returns The ID of the newly created entity
      */
     new(): EntityId;
     /**
      * Destroy an entity and remove all its components (immediate execution)
      */
-    private _destroyEntity;
+    private destroyEntityImmediate;
     /**
      * Check if an entity exists
      */
@@ -74,12 +81,14 @@ export declare class World<UpdateParams extends any[] = []> {
      * Returns an array of all matching relation instances
      * @param entityId The entity
      * @param componentType The wildcard relation type
+     * @returns Array of [targetEntityId, componentData] pairs for all matching relations
      */
     get<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, T][];
     /**
      * Get component data for a specific entity and component type
      * @param entityId The entity
      * @param componentType The component type
+     * @returns The component data
      */
     get<T>(entityId: EntityId, componentType: EntityId<T>): T;
     /**
@@ -109,6 +118,7 @@ export declare class World<UpdateParams extends any[] = []> {
     sync(): void;
     /**
      * Create a cached query for efficient entity lookups
+     * @returns A Query object for the specified component types and filter
      */
     createQuery(componentTypes: EntityId<any>[], filter?: QueryFilter): Query;
     /**
@@ -130,46 +140,55 @@ export declare class World<UpdateParams extends any[] = []> {
     getMatchingArchetypes(componentTypes: EntityId<any>[]): Archetype[];
     /**
      * Query entities with specific components
+     * @returns Array of entity IDs that have all the specified components
      */
-    queryEntities(componentTypes: EntityId<any>[]): EntityId[];
-    queryEntities<const T extends readonly EntityId<any>[]>(componentTypes: T, includeComponents: true): Array<{
+    query(componentTypes: EntityId<any>[]): EntityId[];
+    query<const T extends readonly EntityId<any>[]>(componentTypes: T, includeComponents: true): Array<{
         entity: EntityId;
         components: ComponentTuple<T>;
     }>;
     /**
      * @internal Execute commands for a single entity (for internal use by CommandBuffer)
+     * @returns ComponentChangeset describing the changes made
      */
     executeEntityCommands(entityId: EntityId, commands: Command[]): ComponentChangeset;
     /**
      * Get or create an archetype for the given component types
+     * @returns The archetype for the given component types
      */
-    private getOrCreateArchetype;
+    private ensureArchetype;
     /**
      * Add a component reference to the reverse index when an entity is used as a component type
      * @param sourceEntityId The entity that has the component
      * @param componentType The component type (which may be an entity ID used as component type)
      * @param targetEntityId The entity being used as component type
      */
-    private addComponentReference;
+    private trackEntityReference;
     /**
      * Remove a component reference from the reverse index
      * @param sourceEntityId The entity that has the component
      * @param componentType The component type
      * @param targetEntityId The entity being used as component type
      */
-    private removeComponentReference;
+    private untrackEntityReference;
     /**
      * Get all component references where a target entity is used as a component type
      * @param targetEntityId The target entity
      * @returns Array of {sourceEntityId, componentType} pairs
      */
-    private getComponentReferences;
+    private getEntityReferences;
     /**
      * Remove an empty archetype from all internal data structures
      */
-    private removeEmptyArchetype;
+    private cleanupEmptyArchetype;
     /**
      * Execute component lifecycle hooks for added and removed components
      */
-    private executeComponentLifecycleHooks;
+    private triggerLifecycleHooks;
+    /**
+     * Convert the world into a plain snapshot object.
+     * This returns an in-memory structure and does not perform JSON stringification.
+     * Component values are stored as-is (they may be non-JSON-serializable).
+     */
+    serialize(): any;
 }