@codehz/ecs 0.1.2 → 0.1.4

package/README.md

@@ -171,6 +171,8 @@ bun run examples/simple/demo.ts
 
 - `new()`: 创建新实体
 - `set(entity, componentId, data)`: 向实体添加组件
+- `get(entity, componentId)`: 获取实体的组件数据（注意：只能获取已设置的组件，使用前请先用 `has()` 检查组件是否存在）
+- `has(entity, componentId)`: 检查实体是否拥有指定组件
 - `delete(entity, componentId)`: 从实体移除组件
 - `setExclusive(componentId)`: 将组件标记为独占关系
 - `createQuery(componentIds)`: 创建查询
@@ -251,6 +253,7 @@ const restored = World.deserialize(readySnapshot);
 
 注意事项
 
+- **重要警告**：`get()` 方法只能获取实体已设置的组件。如果尝试获取不存在的组件，会抛出错误。由于 `undefined` 是组件的有效值，不能使用 `get()` 的返回值是否为 `undefined` 来判断组件是否存在。请在使用 `get()` 之前先用 `has()` 方法检查组件是否存在。
 - 快照只包含实体、组件、以及 `EntityIdManager` 的分配器状态（用于保留下一次分配的 ID）；并不会自动恢复已注册的系统、查询缓存或生命周期钩子。恢复后应由应用负责重新注册系统与钩子。
 - 若需要跨版本兼容，建议在持久化格式中包含 `version` 字段，并在恢复时进行格式兼容性检查与迁移。
 

package/index.js

@@ -660,64 +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(entityIdManager) {
-    this.entityIdManager = entityIdManager || new EntityIdManager;
-    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);
@@ -760,6 +790,12 @@ class World {
     if (!archetype) {
       throw new Error(`Entity ${entityId} does not exist`);
     }
+    const detailedType = getDetailedIdType(componentType);
+    if (detailedType.type !== "wildcard-relation") {
+      if (!archetype.componentTypes.includes(componentType)) {
+        throw new Error(`Entity ${entityId} does not have component ${componentType}. Use has() to check component existence before calling get().`);
+      }
+    }
     return archetype.get(entityId, componentType);
   }
   registerSystem(system) {
@@ -796,7 +832,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++;
@@ -844,15 +880,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 = [];
@@ -860,15 +896,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;
@@ -884,12 +920,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 = [];
@@ -910,7 +946,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);
@@ -919,14 +955,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);
@@ -935,12 +971,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) {
@@ -952,7 +988,7 @@ class World {
                 }
               }
             } else {
-              changeset.delete(cmd.componentType);
+              changeset.delete(command.componentType);
             }
           }
           break;
@@ -963,7 +999,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);
@@ -976,33 +1012,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);
@@ -1010,30 +1046,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;
     }
@@ -1041,28 +1077,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);
           }
         }
       }
@@ -1071,9 +1107,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);
             }
           }
         }
@@ -1082,9 +1118,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);
           }
         }
       }
@@ -1119,46 +1155,6 @@ class World {
       entities
     };
   }
-  static deserialize(obj) {
-    if (!obj || typeof obj !== "object") {
-      throw new Error("World.deserialize expects a snapshot object (not a JSON string)");
-    }
-    const entityManager = new EntityIdManager;
-    if (obj && obj.entityManager) {
-      entityManager.deserializeState(obj.entityManager);
-    }
-    const world = new World(entityManager);
-    if (obj && Array.isArray(obj.exclusiveComponents)) {
-      for (const id of obj.exclusiveComponents) {
-        world.exclusiveComponents.add(id);
-      }
-    }
-    if (obj && Array.isArray(obj.entities)) {
-      for (const entry of obj.entities) {
-        const entityId = entry.id;
-        const componentsArray = entry.components || [];
-        const componentMap = new Map;
-        const componentTypes = [];
-        for (const c of componentsArray) {
-          componentMap.set(c.type, c.value);
-          componentTypes.push(c.type);
-        }
-        const archetype = world.getOrCreateArchetype(componentTypes);
-        archetype.addEntity(entityId, componentMap);
-        world.entityToArchetype.set(entityId, archetype);
-        for (const compType of componentTypes) {
-          const detailedType = getDetailedIdType(compType);
-          if (detailedType.type === "entity-relation") {
-            const targetEntityId = detailedType.targetId;
-            world.addComponentReference(entityId, compType, targetEntityId);
-          } else if (detailedType.type === "entity") {
-            world.addComponentReference(entityId, compType, compType);
-          }
-        }
-      }
-    }
-    return world;
-  }
 }
 export {
   relation,

package/package.json

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

package/world.d.ts

@@ -2,7 +2,6 @@ import { Archetype } from "./archetype";
 import { ComponentChangeset } from "./changeset";
 import { type Command } from "./command-buffer";
 import type { EntityId, WildcardRelationId } from "./entity";
-import { EntityIdManager } from "./entity";
 import { Query } from "./query";
 import { type QueryFilter } from "./query-filter";
 import type { System } from "./system";
@@ -12,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
+     * 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 entityReverseIndex;
+    constructor(snapshot?: any);
     /**
-     * Set of component IDs that are marked as exclusive relations
-     * For exclusive relations, an entity can have at most one relation per base component
+     * Generate a signature string for component types array
+     * @returns A string signature for the component types
      */
-    private exclusiveComponents;
-    constructor(entityIdManager?: EntityIdManager);
-    /**
-     * Generate a hash key for component types array
-     */
-    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
      */
@@ -75,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;
     /**
@@ -110,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;
     /**
@@ -131,62 +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;
-    /**
-     * Convert the world into a plain JSON-serializable object.
-     * Note: component values must be JSON-serializable by the caller.
-     */
+    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;
-    /**
-     * Deserialize a world from a previously-created snapshot object.
-     * The snapshot must have been produced by `world.serialize()` and may contain
-     * non-JSON values (they will be copied by reference).
-     */
-    static deserialize<T extends any[] = []>(obj: any): World<T>;
 }