feat(system): implement system scheduler with dependency management

- Added SystemScheduler class to manage system dependencies and execution order.
- Updated World class to utilize SystemScheduler for registering systems.
- Enhanced README with system scheduling features and examples.
- Added tests for SystemScheduler to ensure correct behavior.

Author: codehz

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              # 工具函数

examples/advanced-scheduling/demo.ts

@@ -0,0 +1,128 @@
+import { component } from "../../src/entity";
+import type { Query } from "../../src/query";
+import type { System } from "../../src/system";
+import { World } from "../../src/world";
+
+// 定义组件类型
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+type Health = { value: number };
+
+// 定义组件ID
+const PositionId = component<Position>();
+const VelocityId = component<Velocity>();
+const HealthId = component<Health>();
+
+// 输入系统 - 处理用户输入
+class InputSystem implements System {
+  update(world: World, deltaTime: number): void {
+    console.log(`[InputSystem] Processing input at ${Date.now()}`);
+    // 这里可以处理键盘/鼠标输入等
+  }
+}
+
+// 移动系统 - 依赖输入系统
+class MovementSystem implements System {
+  private query: Query;
+
+  constructor(world: World) {
+    this.query = world.createQuery([PositionId, VelocityId]);
+  }
+
+  update(world: World, deltaTime: number): void {
+    console.log(`[MovementSystem] Updating positions`);
+
+    this.query.forEach([PositionId, VelocityId], (entity, position, velocity) => {
+      position.x += velocity.x * deltaTime;
+      position.y += velocity.y * deltaTime;
+      console.log(`  Entity ${entity}: Position (${position.x.toFixed(2)}, ${position.y.toFixed(2)})`);
+    });
+  }
+}
+
+// 伤害系统 - 依赖移动系统
+class DamageSystem implements System {
+  private query: Query;
+
+  constructor(world: World) {
+    this.query = world.createQuery([PositionId, HealthId]);
+  }
+
+  update(world: World, deltaTime: number): void {
+    console.log(`[DamageSystem] Applying damage based on position`);
+
+    this.query.forEach([PositionId, HealthId], (entity, position, health) => {
+      // 根据位置计算伤害（示例逻辑）
+      const damage = Math.abs(position.x) * 0.1;
+      health.value -= damage;
+      console.log(`  Entity ${entity}: Health reduced by ${damage.toFixed(2)}, now ${health.value.toFixed(2)}`);
+    });
+  }
+}
+
+// 渲染系统 - 依赖所有其他系统最后执行
+class RenderSystem implements System {
+  private query: Query;
+
+  constructor(world: World) {
+    this.query = world.createQuery([PositionId]);
+  }
+
+  update(world: World, deltaTime: number): void {
+    console.log(`[RenderSystem] Rendering entities`);
+
+    this.query.forEach([PositionId], (entity, position) => {
+      console.log(`  Rendering Entity ${entity} at (${position.x.toFixed(2)}, ${position.y.toFixed(2)})`);
+    });
+  }
+}
+
+function main() {
+  console.log("ECS Advanced Scheduling Demo - System Dependencies");
+  console.log("=================================================");
+
+  const world = new World();
+
+  // 创建系统实例
+  const inputSystem = new InputSystem();
+  const movementSystem = new MovementSystem(world);
+  const damageSystem = new DamageSystem(world);
+  const renderSystem = new RenderSystem(world);
+
+  // 注册系统并指定依赖关系
+  // 输入系统没有依赖
+  world.registerSystem(inputSystem);
+
+  // 移动系统依赖输入系统
+  world.registerSystem(movementSystem, [inputSystem]);
+
+  // 伤害系统依赖移动系统
+  world.registerSystem(damageSystem, [movementSystem]);
+
+  // 渲染系统依赖伤害系统（确保所有更新都完成后才渲染）
+  world.registerSystem(renderSystem, [damageSystem]);
+
+  // 创建一些实体
+  const entity1 = world.createEntity();
+  world.addComponent(entity1, PositionId, { x: 0, y: 0 });
+  world.addComponent(entity1, VelocityId, { x: 2, y: 1 });
+  world.addComponent(entity1, HealthId, { value: 100 });
+
+  const entity2 = world.createEntity();
+  world.addComponent(entity2, PositionId, { x: 5, y: 3 });
+  world.addComponent(entity2, VelocityId, { x: -1, y: 0.5 });
+  world.addComponent(entity2, HealthId, { value: 80 });
+
+  // 运行几帧
+  console.log("\n--- Frame 1 ---");
+  world.update(1.0);
+
+  console.log("\n--- Frame 2 ---");
+  world.update(1.0);
+
+  console.log("\nDemo completed!");
+}
+
+if (import.meta.main) {
+  main();
+}

src/index.ts

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

src/system-scheduler.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from "bun:test";
+import { SystemScheduler } from "./system-scheduler";
+import type { System } from "./system";
+
+describe("SystemScheduler", () => {
+  it("should add and remove systems correctly", () => {
+    const scheduler = new SystemScheduler();
+    const systemA: System = { update: () => {} };
+    const systemB: System = { update: () => {} };
+
+    scheduler.addSystem(systemA);
+    scheduler.addSystem(systemB, [systemA]);
+
+    expect(scheduler.getExecutionOrder()).toEqual([systemA, systemB]);
+
+    scheduler.removeSystem(systemA);
+
+    // After removing systemA, systemB should still exist but without dependencies
+    expect(scheduler.getExecutionOrder()).toEqual([systemB]);
+  });
+
+  it("should clean up dependencies when removing systems", () => {
+    const scheduler = new SystemScheduler();
+    const systemA: System = { update: () => {} };
+    const systemB: System = { update: () => {} };
+    const systemC: System = { update: () => {} };
+
+    scheduler.addSystem(systemA);
+    scheduler.addSystem(systemB, [systemA]);
+    scheduler.addSystem(systemC, [systemB]);
+
+    // Verify initial state
+    expect(scheduler.getExecutionOrder()).toEqual([systemA, systemB, systemC]);
+
+    // Remove systemB
+    scheduler.removeSystem(systemB);
+
+    // Now systemC should no longer depend on systemB
+    // Since systemC's dependencies were cleaned up, it should execute independently
+    const order = scheduler.getExecutionOrder();
+    expect(order).toContain(systemA);
+    expect(order).toContain(systemC);
+    expect(order).not.toContain(systemB);
+
+    // systemA should come before systemC in the execution order
+    const aIndex = order.indexOf(systemA);
+    const cIndex = order.indexOf(systemC);
+    expect(aIndex).toBeLessThan(cIndex);
+  });
+
+  it("should handle removing non-existent systems gracefully", () => {
+    const scheduler = new SystemScheduler();
+    const systemA: System = { update: () => {} };
+    const systemB: System = { update: () => {} };
+
+    scheduler.addSystem(systemA);
+
+    // Removing a system that was never added should not throw
+    expect(() => scheduler.removeSystem(systemB)).not.toThrow();
+
+    // systemA should still be there
+    expect(scheduler.getExecutionOrder()).toEqual([systemA]);
+  });
+
+  it("should clear all systems", () => {
+    const scheduler = new SystemScheduler();
+    const systemA: System = { update: () => {} };
+    const systemB: System = { update: () => {} };
+
+    scheduler.addSystem(systemA, [systemB]);
+    scheduler.addSystem(systemB);
+
+    expect(scheduler.getExecutionOrder()).toHaveLength(2);
+
+    scheduler.clear();
+
+    expect(scheduler.getExecutionOrder()).toHaveLength(0);
+  });
+});

src/system-scheduler.ts

@@ -0,0 +1,84 @@
+import type { System } from "./system";
+
+/**
+ * System Scheduler for managing system dependencies and execution order
+ */
+export class SystemScheduler<ExtraParams extends any[] = [deltaTime: number]> {
+  private systems = new Map<System<ExtraParams>, System<ExtraParams>[]>();
+  private allSystems = new Set<System<ExtraParams>>();
+
+  /**
+   * 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 {
+    this.systems.set(system, dependencies);
+    this.allSystems.add(system);
+    // Also add dependencies to the set
+    for (const dep of dependencies) {
+      this.allSystems.add(dep);
+    }
+  }
+
+  /**
+   * Remove a system
+   * @param system The system to remove
+   */
+  removeSystem(system: System<ExtraParams>): void {
+    this.systems.delete(system);
+    this.allSystems.delete(system);
+
+    // Remove this system from all dependency lists
+    for (const [sys, deps] of this.systems) {
+      const index = deps.indexOf(system);
+      if (index !== -1) {
+        deps.splice(index, 1);
+      }
+    }
+  }
+
+  /**
+   * Get the execution order of systems based on dependencies
+   * Uses topological sort
+   */
+  getExecutionOrder(): System<ExtraParams>[] {
+    const result: System<ExtraParams>[] = [];
+    const visited = new Set<System<ExtraParams>>();
+    const visiting = new Set<System<ExtraParams>>();
+
+    const visit = (system: System<ExtraParams>): void => {
+      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 all systems and dependencies
+   */
+  clear(): void {
+    this.systems.clear();
+    this.allSystems.clear();
+  }
+}

src/world.test.ts

@@ -224,6 +224,30 @@ describe("World", () => {
 
       expect(updateCalled).toBe(true);
     });
+
+    it("should execute systems in dependency order", () => {
+      const world = new World();
+      const executionOrder: string[] = [];
+
+      const systemA = {
+        update: () => executionOrder.push("A"),
+      };
+      const systemB = {
+        update: () => executionOrder.push("B"),
+      };
+      const systemC = {
+        update: () => executionOrder.push("C"),
+      };
+
+      // C depends on B, B depends on A
+      world.registerSystem(systemA);
+      world.registerSystem(systemB, [systemA]);
+      world.registerSystem(systemC, [systemB]);
+
+      world.update(0.016);
+
+      expect(executionOrder).toEqual(["A", "B", "C"]);
+    });
   });
 
   describe("Query", () => {