@codehz/ecs 0.0.3 → 0.0.5

package/README.md

@@ -10,6 +10,7 @@
 - 📦 轻量级：零依赖，易于集成
 - ⚡ 内存高效：连续内存布局，优化的迭代性能
 - 🎣 生命周期钩子：支持组件和通配符关系的事件监听
+- 🔄 系统调度：支持系统依赖关系和拓扑排序执行
 
 ## 安装
 
@@ -139,7 +140,7 @@ bun run examples/simple/demo.ts
 - `addComponent(entity, componentId, data)`: 向实体添加组件
 - `removeComponent(entity, componentId)`: 从实体移除组件
 - `createQuery(componentIds)`: 创建查询
-- `registerSystem(system)`: 注册系统
+- `registerSystem(system, dependencies?)`: 注册系统，可选指定依赖系统列表
 - `registerLifecycleHook(componentId, hook)`: 注册组件或通配符关系生命周期钩子
 - `unregisterLifecycleHook(componentId, hook)`: 注销组件或通配符关系生命周期钩子
 - `update(deltaTime)`: 更新世界
@@ -167,6 +168,17 @@ class MySystem implements System {
 }
 ```
 
+系统支持依赖关系排序，确保正确的执行顺序：
+
+```typescript
+// 注册系统时指定依赖
+world.registerSystem(inputSystem);
+world.registerSystem(movementSystem, [inputSystem]); // movementSystem 依赖 inputSystem
+world.registerSystem(renderSystem, [movementSystem]); // renderSystem 依赖 movementSystem
+```
+
+系统将按照拓扑排序执行，依赖系统始终在被依赖系统之前运行。
+
 ## 性能特点
 
 - **Archetype 系统**：实体按组件组合分组，实现连续内存访问
@@ -199,6 +211,7 @@ src/
 ├── query.ts              # 查询系统
 ├── query-filter.ts       # 查询过滤器
 ├── system.ts             # 系统接口
+├── system-scheduler.ts   # 系统调度器
 ├── command-buffer.ts     # 命令缓冲区
 ├── types.ts              # 类型定义
 ├── utils.ts              # 工具函数

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

@@ -435,6 +435,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 +470,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 +536,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,14 +553,68 @@ class Query {
   }
 }
 
+// src/system-scheduler.ts
+class SystemScheduler {
+  systems = new Map;
+  allSystems = new Set;
+  addSystem(system, dependencies = []) {
+    this.systems.set(system, dependencies);
+    this.allSystems.add(system);
+    for (const dep of dependencies) {
+      this.allSystems.add(dep);
+    }
+  }
+  removeSystem(system) {
+    this.systems.delete(system);
+    this.allSystems.delete(system);
+    for (const [sys, deps] of this.systems) {
+      const index = deps.indexOf(system);
+      if (index !== -1) {
+        deps.splice(index, 1);
+      }
+    }
+  }
+  getExecutionOrder() {
+    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);
+      const dependencies = this.systems.get(system) || [];
+      for (const dep of dependencies) {
+        visit(dep);
+      }
+      visiting.delete(system);
+      visited.add(system);
+      result.push(system);
+    };
+    for (const system of this.allSystems) {
+      if (!visited.has(system)) {
+        visit(system);
+      }
+    }
+    return result;
+  }
+  clear() {
+    this.systems.clear();
+    this.allSystems.clear();
+  }
+}
+
 // 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;
@@ -649,14 +714,11 @@ class World {
     }
     return archetype.getComponent(entityId, componentType);
   }
-  registerSystem(system) {
-    this.systems.push(system);
+  registerSystem(system, dependencies = []) {
+    this.systemScheduler.addSystem(system, dependencies);
   }
   unregisterSystem(system) {
-    const index = this.systems.indexOf(system);
-    if (index !== -1) {
-      this.systems.splice(index, 1);
-    }
+    this.systemScheduler.removeSystem(system);
   }
   registerLifecycleHook(componentType, hook) {
     if (!this.lifecycleHooks.has(componentType)) {
@@ -674,7 +736,8 @@ class World {
     }
   }
   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 +746,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];
@@ -976,6 +1072,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.3",
+  "version": "0.0.5",
   "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,28 @@
+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 allSystems;
+    /**
+     * Add a system with optional dependencies
+     * @param system The system to add
+     * @param dependencies Systems that this system depends on (must run before this system)
+     */
+    addSystem(system: System<ExtraParams>, dependencies?: System<ExtraParams>[]): void;
+    /**
+     * Remove a system
+     * @param system The system to remove
+     */
+    removeSystem(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/world.d.ts

@@ -2,7 +2,7 @@ import { Archetype } from "./archetype";
 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 +14,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;
     /**
@@ -70,9 +71,9 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      */
     getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
     /**
-     * Register a system
+     * Register a system with optional dependencies
      */
-    registerSystem(system: System<ExtraParams>): void;
+    registerSystem(system: System<ExtraParams>, dependencies?: System<ExtraParams>[]): void;
     /**
      * Unregister a system
      */
@@ -86,7 +87,7 @@ export declare class World<ExtraParams extends any[] = [deltaTime: number]> {
      */
     unregisterLifecycleHook<T>(componentType: EntityId<T>, hook: LifecycleHook<T>): void;
     /**
-     * Update the world (run all systems)
+     * Update the world (run all systems in dependency order)
      */
     update(...params: ExtraParams): void;
     /**
@@ -100,11 +101,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)
      */