@codehz/ecs 0.0.4 → 0.0.6

package/README.md

@@ -10,6 +10,7 @@
 - 📦 轻量级：零依赖，易于集成
 - ⚡ 内存高效：连续内存布局，优化的迭代性能
 - 🎣 生命周期钩子：支持组件和通配符关系的事件监听
+- 🔄 系统调度：支持系统依赖关系和拓扑排序执行
 
 ## 安装
 
@@ -119,6 +120,39 @@ world.addComponent(entity, positionRelation, { x: 10, y: 20 });
 world.flushCommands(); // 通配符钩子会被触发
 ```
 
+### Exclusive Relations
+
+ECS 支持 Exclusive Relations，确保实体对于指定的组件类型最多只能有一个关系。当添加新的关系时，会自动移除之前的所有同类型关系：
+
+```typescript
+import { World, component, relation } from "@codehz/ecs";
+
+// 定义组件ID
+const ChildOf = component(); // 空组件，用于关系
+
+// 创建世界
+const world = new World();
+
+// 设置 ChildOf 为独占关系
+world.setExclusive(ChildOf);
+
+// 创建实体
+const child = world.createEntity();
+const parent1 = world.createEntity();
+const parent2 = world.createEntity();
+
+// 添加第一个关系
+world.addComponent(child, relation(ChildOf, parent1));
+world.flushCommands();
+console.log(world.hasComponent(child, relation(ChildOf, parent1))); // true
+
+// 添加第二个关系 - 会自动移除第一个
+world.addComponent(child, relation(ChildOf, parent2));
+world.flushCommands();
+console.log(world.hasComponent(child, relation(ChildOf, parent1))); // false
+console.log(world.hasComponent(child, relation(ChildOf, parent2))); // true
+```
+
 ### 运行示例
 
 ```bash
@@ -138,6 +172,7 @@ bun run examples/simple/demo.ts
 - `createEntity()`: 创建新实体
 - `addComponent(entity, componentId, data)`: 向实体添加组件
 - `removeComponent(entity, componentId)`: 从实体移除组件
+- `setExclusive(componentId)`: 将组件标记为独占关系
 - `createQuery(componentIds)`: 创建查询
 - `registerSystem(system)`: 注册系统
 - `registerLifecycleHook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
@@ -167,6 +202,17 @@ class MySystem implements System {
 }
 ```
 
+系统支持依赖关系排序，确保正确的执行顺序：
+
+```typescript
+// 注册系统时指定依赖
+world.registerSystem(inputSystem);
+world.registerSystem(movementSystem, [inputSystem]); // movementSystem 依赖 inputSystem
+world.registerSystem(renderSystem, [movementSystem]); // renderSystem 依赖 movementSystem
+```
+
+系统将按照拓扑排序执行，依赖系统始终在被依赖系统之前运行。
+
 ## 性能特点
 
 - **Archetype 系统**：实体按组件组合分组，实现连续内存访问
@@ -199,6 +245,7 @@ src/
 ├── query.ts              # 查询系统
 ├── query-filter.ts       # 查询过滤器
 ├── system.ts             # 系统接口
+├── system-scheduler.ts   # 系统调度器
 ├── command-buffer.ts     # 命令缓冲区
 ├── types.ts              # 类型定义
 ├── utils.ts              # 工具函数

package/archetype.d.ts

@@ -66,13 +66,13 @@ export declare class Archetype {
      * @param entityId The entity
      * @param componentType The wildcard relation type
      */
-    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
+    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][];
     /**
      * Get component data for a specific entity and component type
      * @param entityId The entity
      * @param componentType The component type
      */
-    getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
+    getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T;
     /**
      * Set component data for a specific entity and component type
      * @param entityId The entity

package/changeset.d.ts

@@ -0,0 +1,36 @@
+import type { EntityId } from "./entity";
+/**
+ * @internal Represents a set of component changes to be applied to an entity
+ */
+export declare class ComponentChangeset {
+    readonly adds: Map<EntityId<any>, any>;
+    readonly removes: Set<EntityId<any>>;
+    /**
+     * Add a component to the changeset
+     */
+    addComponent<T>(componentType: EntityId<T>, component: T): void;
+    /**
+     * Remove a component from the changeset
+     */
+    removeComponent<T>(componentType: EntityId<T>): void;
+    /**
+     * Check if the changeset has any changes
+     */
+    hasChanges(): boolean;
+    /**
+     * Clear all changes
+     */
+    clear(): void;
+    /**
+     * Merge another changeset into this one
+     */
+    merge(other: ComponentChangeset): void;
+    /**
+     * Apply the changeset to existing components and return the final state
+     */
+    applyTo(existingComponents: Map<EntityId<any>, any>): Map<EntityId<any>, any>;
+    /**
+     * Get the final component types after applying changes
+     */
+    getFinalComponentTypes(existingComponents: Map<EntityId<any>, any>): EntityId<any>[];
+}

package/command-buffer.d.ts

@@ -21,7 +21,8 @@ export declare class CommandBuffer {
     /**
      * Add a component to an entity (deferred)
      */
-    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: T): void;
+    addComponent(entityId: EntityId, componentType: EntityId<void>): void;
+    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
     /**
      * Remove a component from an entity (deferred)
      */

package/entity.d.ts

@@ -153,5 +153,5 @@ export declare class ComponentIdAllocator {
 /**
  * Allocate a new component ID from the global allocator
  */
-export declare function component<T>(): ComponentId<T>;
+export declare function component<T = void>(): ComponentId<T>;
 export {};

package/index.d.ts

@@ -3,4 +3,5 @@ export * from "./world";
 export * from "./archetype";
 export * from "./query";
 export * from "./system";
+export * from "./system-scheduler";
 export * from "./types";

package/index.js

@@ -226,6 +226,8 @@ function getOrCreateWithSideEffect(cache, key, create) {
 }
 
 // src/archetype.ts
+var MISSING_COMPONENT = Symbol("missing component");
+
 class Archetype {
   componentTypes;
   entities = [];
@@ -257,10 +259,7 @@ class Archetype {
     this.entityToIndex.set(entityId, index);
     for (const componentType of this.componentTypes) {
       const data = componentData.get(componentType);
-      if (data === undefined) {
-        throw new Error(`Missing component data for type ${componentType}`);
-      }
-      this.componentData.get(componentType).push(data);
+      this.componentData.get(componentType).push(data === undefined ? MISSING_COMPONENT : data);
     }
   }
   removeEntity(entityId) {
@@ -287,11 +286,7 @@ class Archetype {
   getComponent(entityId, componentType) {
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
-      if (getIdType(componentType) === "wildcard-relation") {
-        return [];
-      } else {
-        return;
-      }
+      throw new Error(`Entity ${entityId} is not in this archetype`);
     }
     if (isWildcardRelationId(componentType)) {
       const decoded = decodeRelationId(componentType);
@@ -302,24 +297,26 @@ class Archetype {
         if ((relDetailed.type === "entity-relation" || relDetailed.type === "component-relation") && relDetailed.componentId === componentId) {
           const dataArray = this.componentData.get(relType);
           if (dataArray && dataArray[index] !== undefined) {
-            relations.push([relDetailed.targetId, dataArray[index]]);
+            const data = dataArray[index];
+            relations.push([relDetailed.targetId, data === MISSING_COMPONENT ? undefined : data]);
           }
         }
       }
       return relations;
     } else {
-      return this.componentData.get(componentType)?.[index];
+      const data = this.componentData.get(componentType)?.[index];
+      return data === MISSING_COMPONENT ? undefined : data;
     }
   }
   setComponent(entityId, componentType, data) {
+    if (!this.componentData.has(componentType)) {
+      throw new Error(`Component type ${componentType} is not in this archetype`);
+    }
     const index = this.entityToIndex.get(entityId);
     if (index === undefined) {
       throw new Error(`Entity ${entityId} is not in this archetype`);
     }
     const dataArray = this.componentData.get(componentType);
-    if (!dataArray) {
-      throw new Error(`Component type ${componentType} is not in this archetype`);
-    }
     dataArray[index] = data;
   }
   getEntities() {
@@ -364,14 +361,16 @@ class Archetype {
           for (const relType of matchingRelations) {
             const dataArray = this.componentData.get(relType);
             if (dataArray && dataArray[entityIndex] !== undefined) {
+              const data = dataArray[entityIndex];
               const decodedRel = decodeRelationId(relType);
-              relations.push([decodedRel.targetId, dataArray[entityIndex]]);
+              relations.push([decodedRel.targetId, data === MISSING_COMPONENT ? undefined : data]);
             }
           }
           return relations;
         } else {
           const dataArray = dataSource;
-          return dataArray ? dataArray[entityIndex] : undefined;
+          const data = dataArray ? dataArray[entityIndex] : undefined;
+          return data === MISSING_COMPONENT ? undefined : data;
         }
       });
       callback(entity, ...components);
@@ -381,13 +380,59 @@ class Archetype {
     for (let i = 0;i < this.entities.length; i++) {
       const components = new Map;
       for (const componentType of this.componentTypes) {
-        components.set(componentType, this.componentData.get(componentType)[i]);
+        const data = this.componentData.get(componentType)[i];
+        components.set(componentType, data === MISSING_COMPONENT ? undefined : data);
       }
       callback(this.entities[i], components);
     }
   }
 }
 
+// src/changeset.ts
+class ComponentChangeset {
+  adds = new Map;
+  removes = new Set;
+  addComponent(componentType, component2) {
+    this.adds.set(componentType, component2);
+    this.removes.delete(componentType);
+  }
+  removeComponent(componentType) {
+    this.removes.add(componentType);
+    this.adds.delete(componentType);
+  }
+  hasChanges() {
+    return this.adds.size > 0 || this.removes.size > 0;
+  }
+  clear() {
+    this.adds.clear();
+    this.removes.clear();
+  }
+  merge(other) {
+    for (const [componentType, component2] of other.adds) {
+      this.adds.set(componentType, component2);
+      this.removes.delete(componentType);
+    }
+    for (const componentType of other.removes) {
+      this.removes.add(componentType);
+      this.adds.delete(componentType);
+    }
+  }
+  applyTo(existingComponents) {
+    const finalComponents = new Map(existingComponents);
+    for (const componentType of this.removes) {
+      finalComponents.delete(componentType);
+    }
+    for (const [componentType, component2] of this.adds) {
+      finalComponents.set(componentType, component2);
+    }
+    return finalComponents;
+  }
+  getFinalComponentTypes(existingComponents) {
+    const finalComponents = this.applyTo(existingComponents);
+    return Array.from(finalComponents.keys()).sort((a, b) => a - b);
+  }
+}
+
 // src/command-buffer.ts
 class CommandBuffer {
   commands = [];
@@ -435,6 +480,12 @@ class CommandBuffer {
 }
 
 // src/query-filter.ts
+function serializeQueryFilter(filter = {}) {
+  const negative = (filter.negativeComponentTypes || []).slice().sort((a, b) => a - b);
+  if (negative.length === 0)
+    return "";
+  return `neg:${negative.join(",")}`;
+}
 function matchesComponentTypes(archetype, componentTypes) {
   return componentTypes.every((type) => {
     const detailedType = getDetailedIdType(type);
@@ -464,17 +515,19 @@ function matchesFilter(archetype, filter) {
 
 // src/query.ts
 class Query {
+  key;
   world;
   componentTypes;
   filter;
   cachedArchetypes = [];
   isDisposed = false;
-  constructor(world, componentTypes, filter = {}) {
+  constructor(world, componentTypes, filter = {}, key) {
     this.world = world;
     this.componentTypes = [...componentTypes].sort((a, b) => a - b);
     this.filter = filter;
+    this.key = key ?? `${this.componentTypes.join(",")}|`;
     this.updateCache();
-    world.registerQuery(this);
+    world._registerQuery(this);
   }
   getEntities() {
     if (this.isDisposed) {
@@ -528,8 +581,11 @@ class Query {
     }
   }
   dispose() {
+    this.world.releaseQuery(this);
+  }
+  _disposeInternal() {
     if (!this.isDisposed) {
-      this.world.unregisterQuery(this);
+      this.world._unregisterQuery(this);
       this.cachedArchetypes = [];
       this.isDisposed = true;
     }
@@ -542,18 +598,66 @@ class Query {
   }
 }
 
+// src/system-scheduler.ts
+class SystemScheduler {
+  systems = new Set;
+  cachedExecutionOrder = null;
+  addSystem(system) {
+    this.systems.add(system);
+    for (const dep of system.dependencies || []) {
+      this.systems.add(dep);
+    }
+    this.cachedExecutionOrder = null;
+  }
+  getExecutionOrder() {
+    if (this.cachedExecutionOrder !== null) {
+      return this.cachedExecutionOrder;
+    }
+    const result = [];
+    const visited = new Set;
+    const visiting = new Set;
+    const visit = (system) => {
+      if (visited.has(system))
+        return;
+      if (visiting.has(system)) {
+        throw new Error("Circular dependency detected in system scheduling");
+      }
+      visiting.add(system);
+      for (const dep of system.dependencies || []) {
+        visit(dep);
+      }
+      visiting.delete(system);
+      visited.add(system);
+      result.push(system);
+    };
+    for (const system of this.systems) {
+      if (!visited.has(system)) {
+        visit(system);
+      }
+    }
+    this.cachedExecutionOrder = result;
+    return result;
+  }
+  clear() {
+    this.systems.clear();
+    this.cachedExecutionOrder = null;
+  }
+}
+
 // src/world.ts
 class World {
   entityIdManager = new EntityIdManager;
   archetypes = [];
   archetypeMap = new Map;
   entityToArchetype = new Map;
-  systems = [];
+  systemScheduler = new SystemScheduler;
   queries = [];
+  queryCache = new Map;
   commandBuffer;
   componentToArchetypes = new Map;
   lifecycleHooks = new Map;
   entityReverseIndex = new Map;
+  exclusiveComponents = new Set;
   constructor() {
     this.commandBuffer = new CommandBuffer((entityId, commands) => this.executeEntityCommands(entityId, commands));
   }
@@ -641,22 +745,12 @@ class World {
   getComponent(entityId, componentType) {
     const archetype = this.entityToArchetype.get(entityId);
     if (!archetype) {
-      if (getIdType(componentType) === "wildcard-relation") {
-        return [];
-      } else {
-        return;
-      }
+      throw new Error(`Entity ${entityId} does not exist`);
     }
     return archetype.getComponent(entityId, componentType);
   }
   registerSystem(system) {
-    this.systems.push(system);
-  }
-  unregisterSystem(system) {
-    const index = this.systems.indexOf(system);
-    if (index !== -1) {
-      this.systems.splice(index, 1);
-    }
+    this.systemScheduler.addSystem(system);
   }
   registerLifecycleHook(componentType, hook) {
     if (!this.lifecycleHooks.has(componentType)) {
@@ -673,8 +767,12 @@ class World {
       }
     }
   }
+  setExclusive(componentId) {
+    this.exclusiveComponents.add(componentId);
+  }
   update(...params) {
-    for (const system of this.systems) {
+    const systems = this.systemScheduler.getExecutionOrder();
+    for (const system of systems) {
       system.update(this, ...params);
     }
     this.commandBuffer.execute();
@@ -683,17 +781,50 @@ class World {
     this.commandBuffer.execute();
   }
   createQuery(componentTypes, filter = {}) {
-    return new Query(this, componentTypes, filter);
-  }
-  registerQuery(query) {
+    const sortedTypes = [...componentTypes].sort((a, b) => a - b);
+    const filterKey = serializeQueryFilter(filter);
+    const key = `${this.getComponentTypesHash(sortedTypes)}${filterKey ? `|${filterKey}` : ""}`;
+    const cached = this.queryCache.get(key);
+    if (cached) {
+      cached.refCount++;
+      return cached.query;
+    }
+    const query = new Query(this, sortedTypes, filter, key);
+    this.queryCache.set(key, { query, refCount: 1 });
+    return query;
+  }
+  _registerQuery(query) {
     this.queries.push(query);
   }
-  unregisterQuery(query) {
+  _unregisterQuery(query) {
     const index = this.queries.indexOf(query);
     if (index !== -1) {
       this.queries.splice(index, 1);
     }
   }
+  releaseQuery(query) {
+    const key = query.key;
+    for (const [k, v] of this.queryCache.entries()) {
+      if (v.query === query) {
+        v.refCount--;
+        if (v.refCount <= 0) {
+          this.queryCache.delete(k);
+          v.query._disposeInternal();
+        }
+        return;
+      }
+    }
+    const entry = this.queryCache.get(key);
+    if (!entry) {
+      this._unregisterQuery(query);
+      return;
+    }
+    entry.refCount--;
+    if (entry.refCount <= 0) {
+      this.queryCache.delete(key);
+      entry.query._disposeInternal();
+    }
+  }
   getMatchingArchetypes(componentTypes) {
     if (componentTypes.length === 0) {
       return [...this.archetypes];
@@ -763,30 +894,35 @@ class World {
     }
   }
   executeEntityCommands(entityId, commands) {
+    const changeset = new ComponentChangeset;
     const hasDestroy = commands.some((cmd) => cmd.type === "destroyEntity");
     if (hasDestroy) {
       this._destroyEntity(entityId);
-      return;
+      return changeset;
     }
     const currentArchetype = this.entityToArchetype.get(entityId);
     if (!currentArchetype) {
-      return;
+      return changeset;
     }
     const currentComponents = new Map;
     for (const componentType of currentArchetype.componentTypes) {
       const data = currentArchetype.getComponent(entityId, componentType);
-      if (data !== undefined) {
-        currentComponents.set(componentType, data);
-      }
+      currentComponents.set(componentType, data);
     }
-    const adds = new Map;
-    const removes = new Set;
     for (const cmd of commands) {
       switch (cmd.type) {
         case "addComponent":
-          if (cmd.componentType && cmd.component !== undefined) {
-            adds.set(cmd.componentType, cmd.component);
-            removes.delete(cmd.componentType);
+          if (cmd.componentType) {
+            const detailedType = getDetailedIdType(cmd.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);
+                if ((componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") && componentDetailedType.componentId === detailedType.componentId) {
+                  changeset.removeComponent(componentType);
+                }
+              }
+            }
+            changeset.addComponent(cmd.componentType, cmd.component);
           }
           break;
         case "removeComponent":
@@ -798,27 +934,19 @@ class World {
                 const componentDetailedType = getDetailedIdType(componentType);
                 if (componentDetailedType.type === "entity-relation" || componentDetailedType.type === "component-relation") {
                   if (componentDetailedType.componentId === baseComponentId) {
-                    removes.add(componentType);
-                    adds.delete(componentType);
+                    changeset.removeComponent(componentType);
                   }
                 }
               }
             } else {
-              removes.add(cmd.componentType);
-              adds.delete(cmd.componentType);
+              changeset.removeComponent(cmd.componentType);
             }
           }
           break;
       }
     }
-    const finalComponents = new Map(currentComponents);
-    for (const componentType of removes) {
-      finalComponents.delete(componentType);
-    }
-    for (const [componentType, component2] of adds) {
-      finalComponents.set(componentType, component2);
-    }
-    const finalComponentTypes = Array.from(finalComponents.keys()).sort((a, b) => a - b);
+    const finalComponents = changeset.applyTo(currentComponents);
+    const finalComponentTypes = changeset.getFinalComponentTypes(currentComponents);
     const currentComponentTypes = currentArchetype.componentTypes.sort((a, b) => a - b);
     const needsArchetypeChange = finalComponentTypes.length !== currentComponentTypes.length || !finalComponentTypes.every((type, index) => type === currentComponentTypes[index]);
     if (needsArchetypeChange) {
@@ -827,11 +955,11 @@ class World {
       newArchetype.addEntity(entityId, finalComponents);
       this.entityToArchetype.set(entityId, newArchetype);
     } else {
-      for (const [componentType, component2] of adds) {
+      for (const [componentType, component2] of changeset.adds) {
         currentArchetype.setComponent(entityId, componentType, component2);
       }
     }
-    for (const componentType of removes) {
+    for (const componentType of changeset.removes) {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
@@ -840,7 +968,7 @@ class World {
         this.removeComponentReference(entityId, componentType, componentType);
       }
     }
-    for (const [componentType, component2] of adds) {
+    for (const [componentType, component2] of changeset.adds) {
       const detailedType = getDetailedIdType(componentType);
       if (detailedType.type === "entity-relation") {
         const targetEntityId = detailedType.targetId;
@@ -849,7 +977,8 @@ class World {
         this.addComponentReference(entityId, componentType, componentType);
       }
     }
-    this.executeComponentLifecycleHooks(entityId, adds, removes);
+    this.executeComponentLifecycleHooks(entityId, changeset.adds, changeset.removes);
+    return changeset;
   }
   getOrCreateArchetype(componentTypes) {
     const sortedTypes = [...componentTypes].sort((a, b) => a - b);
@@ -976,6 +1105,7 @@ export {
   component,
   World,
   WILDCARD_TARGET_ID,
+  SystemScheduler,
   RELATION_SHIFT,
   Query,
   INVALID_COMPONENT_ID,

package/package.json

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

package/query-filter.d.ts

@@ -6,6 +6,11 @@ import type { EntityId } from "./entity";
 export interface QueryFilter {
     negativeComponentTypes?: EntityId<any>[];
 }
+/**
+ * Serialize a QueryFilter into a deterministic string suitable for cache keys.
+ * Currently only serializes `negativeComponentTypes`.
+ */
+export declare function serializeQueryFilter(filter?: QueryFilter): string;
 /**
  * Check if an archetype matches the given component types
  */

package/query.d.ts

@@ -1,18 +1,19 @@
 import { Archetype } from "./archetype";
 import type { EntityId } from "./entity";
-import type { ComponentTuple } from "./types";
 import { type QueryFilter } from "./query-filter";
+import type { ComponentTuple } from "./types";
 import type { World } from "./world";
 /**
  * Query class for efficient entity queries with cached archetypes
  */
 export declare class Query {
+    readonly key: string;
     private world;
     private componentTypes;
     private filter;
     private cachedArchetypes;
     private isDisposed;
-    constructor(world: World<any[]>, componentTypes: EntityId<any>[], filter?: QueryFilter);
+    constructor(world: World<any[]>, componentTypes: EntityId<any>[], filter?: QueryFilter, key?: string);
     /**
      * Get all entities matching the query
      */
@@ -50,7 +51,16 @@ export declare class Query {
     /**
      * Dispose the query and disconnect from world
      */
+    /**
+     * Request disposal of this query.
+     * This will decrement the world's reference count for the query.
+     * The query will only be fully disposed when the ref count reaches zero.
+     */
     dispose(): void;
+    /**
+     * Internal full dispose called by World when refCount reaches zero.
+     */
+    _disposeInternal(): void;
     /**
      * Symbol.dispose implementation for automatic resource management
      */

package/system-scheduler.d.ts

@@ -0,0 +1,22 @@
+import type { System } from "./system";
+/**
+ * System Scheduler for managing system dependencies and execution order
+ */
+export declare class SystemScheduler<ExtraParams extends any[] = [deltaTime: number]> {
+    private systems;
+    private cachedExecutionOrder;
+    /**
+     * Add a system with optional dependencies
+     * @param system The system to add
+     */
+    addSystem(system: System<ExtraParams>): void;
+    /**
+     * Get the execution order of systems based on dependencies
+     * Uses topological sort
+     */
+    getExecutionOrder(): System<ExtraParams>[];
+    /**
+     * Clear all systems and dependencies
+     */
+    clear(): void;
+}

package/system.d.ts

@@ -7,4 +7,8 @@ export interface System<ExtraParams extends any[] = [deltaTime: number]> {
      * Update the system
      */
     update(world: World<ExtraParams>, ...params: ExtraParams): void;
+    /**
+     * Dependencies of this system (systems that must run before this one)
+     */
+    readonly dependencies?: readonly System<ExtraParams>[];
 }

package/world.d.ts

@@ -1,8 +1,9 @@
 import { Archetype } from "./archetype";
+import { ComponentChangeset } from "./changeset";
 import { type Command } from "./command-buffer";
 import type { EntityId, WildcardRelationId } from "./entity";
 import { Query } from "./query";
-import type { QueryFilter } from "./query-filter";
+import { type QueryFilter } from "./query-filter";
 import type { System } from "./system";
 import type { ComponentTuple, LifecycleHook } from "./types";
 /**
@@ -14,8 +15,9 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     private archetypes;
     private archetypeMap;
     private entityToArchetype;
-    private systems;
+    private systemScheduler;
     private queries;
+    private queryCache;
     private commandBuffer;
     private componentToArchetypes;
     /**
@@ -28,6 +30,11 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      * 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
+     */
+    private exclusiveComponents;
     constructor();
     /**
      * Generate a hash key for component types array
@@ -48,7 +55,8 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     /**
      * Add a component to an entity (deferred)
      */
-    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: T): void;
+    addComponent(entityId: EntityId, componentType: EntityId<void>): void;
+    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: NoInfer<T>): void;
     /**
      * Remove a component from an entity (deferred)
      */
@@ -64,19 +72,15 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     /**
      * Get wildcard relations from an entity
      */
-    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][] | undefined;
+    getComponent<T>(entityId: EntityId, componentType: WildcardRelationId<T>): [EntityId<unknown>, any][];
     /**
      * Get a component from an entity
      */
-    getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
+    getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T;
     /**
-     * Register a system
+     * Register a system with optional dependencies
      */
     registerSystem(system: System<ExtraParams>): void;
-    /**
-     * Unregister a system
-     */
-    unregisterSystem(system: System<ExtraParams>): void;
     /**
      * Register a lifecycle hook for component or wildcard relation events
      */
@@ -86,7 +90,12 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      */
     unregisterLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
-     * Update the world (run all systems)
+     * Mark a component as exclusive relation
+     * For exclusive relations, an entity can have at most one relation per base component
+     */
+    setExclusive(componentId: EntityId): void;
+    /**
+     * Update the world (run all systems in dependency order)
      */
     update(...params: ExtraParams): void;
     /**
@@ -100,11 +109,16 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     /**
      * @internal Register a query for archetype update notifications
      */
-    registerQuery(query: Query): void;
+    _registerQuery(query: Query): void;
     /**
      * @internal Unregister a query
      */
-    unregisterQuery(query: Query): void;
+    _unregisterQuery(query: Query): void;
+    /**
+     * Release a query reference obtained from createQuery.
+     * Decrements the refCount and fully disposes the query when it reaches zero.
+     */
+    releaseQuery(query: Query): void;
     /**
      * @internal Get archetypes that match specific component types (for internal use by queries)
      */
@@ -120,7 +134,7 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
     /**
      * @internal Execute commands for a single entity (for internal use by CommandBuffer)
      */
-    executeEntityCommands(entityId: EntityId, commands: Command[]): void;
+    executeEntityCommands(entityId: EntityId, commands: Command[]): ComponentChangeset;
     /**
      * Get or create an archetype for the given component types
      */