v2.2.4

移除了功能重复的ComponentTypeManager

docs/.vitepress/config.mjs

@@ -66,6 +66,7 @@ export default defineConfig({
           items: [
             { text: '实体类 (Entity)', link: '/guide/entity' },
             { text: '组件系统 (Component)', link: '/guide/component' },
+            { text: '实体查询系统', link: '/guide/entity-query' },
             {
               text: '系统架构 (System)',
               link: '/guide/system',
@@ -73,7 +74,14 @@ export default defineConfig({
                 { text: 'Worker系统 (多线程)', link: '/guide/worker-system' }
               ]
             },
-            { text: '场景管理 (Scene)', link: '/guide/scene' },
+            {
+              text: '场景管理 (Scene)',
+              link: '/guide/scene',
+              items: [
+                { text: 'SceneManager', link: '/guide/scene-manager' },
+                { text: 'WorldManager', link: '/guide/world-manager' }
+              ]
+            },
             { text: '序列化系统 (Serialization)', link: '/guide/serialization' },
             { text: '事件系统 (Event)', link: '/guide/event-system' },
             { text: '时间和定时器 (Time)', link: '/guide/time-and-timers' },

docs/guide/entity-query.md

@@ -0,0 +1,501 @@
+# 实体查询系统
+
+实体查询是 ECS 架构的核心功能之一。本指南将介绍如何使用 Matcher 和 QuerySystem 来查询和筛选实体。
+
+## 核心概念
+
+### Matcher - 查询条件描述符
+
+Matcher 是一个链式 API,用于描述实体查询条件。它本身不执行查询,而是作为条件传递给 EntitySystem 或 QuerySystem。
+
+### QuerySystem - 查询执行引擎
+
+QuerySystem 负责实际执行查询,内部使用响应式查询机制自动优化性能。
+
+## 在 EntitySystem 中使用 Matcher
+
+这是最常见的使用方式。EntitySystem 通过 Matcher 自动筛选和处理符合条件的实体。
+
+### 基础用法
+
+```typescript
+import { EntitySystem, Matcher, Entity, Component } from '@esengine/ecs-framework';
+
+class PositionComponent extends Component {
+    public x: number = 0;
+    public y: number = 0;
+}
+
+class VelocityComponent extends Component {
+    public vx: number = 0;
+    public vy: number = 0;
+}
+
+class MovementSystem extends EntitySystem {
+    constructor() {
+        // 方式1: 使用 Matcher.empty().all()
+        super(Matcher.empty().all(PositionComponent, VelocityComponent));
+
+        // 方式2: 直接使用 Matcher.all() (等价)
+        // super(Matcher.all(PositionComponent, VelocityComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const pos = entity.getComponent(PositionComponent)!;
+            const vel = entity.getComponent(VelocityComponent)!;
+
+            pos.x += vel.vx;
+            pos.y += vel.vy;
+        }
+    }
+}
+
+// 添加到场景
+scene.addEntityProcessor(new MovementSystem());
+```
+
+### Matcher 链式 API
+
+#### all() - 必须包含所有组件
+
+```typescript
+class HealthSystem extends EntitySystem {
+    constructor() {
+        // 实体必须同时拥有 Health 和 Position 组件
+        super(Matcher.empty().all(HealthComponent, PositionComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理同时拥有两个组件的实体
+    }
+}
+```
+
+#### any() - 至少包含一个组件
+
+```typescript
+class DamageableSystem extends EntitySystem {
+    constructor() {
+        // 实体至少拥有 Health 或 Shield 其中之一
+        super(Matcher.any(HealthComponent, ShieldComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 处理拥有生命值或护盾的实体
+    }
+}
+```
+
+#### none() - 不能包含指定组件
+
+```typescript
+class AliveEntitySystem extends EntitySystem {
+    constructor() {
+        // 实体不能拥有 DeadTag 组件
+        super(Matcher.all(HealthComponent).none(DeadTag));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理活着的实体
+    }
+}
+```
+
+#### 组合条件
+
+```typescript
+class CombatSystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(PositionComponent, HealthComponent)  // 必须有位置和生命
+                .any(WeaponComponent, MagicComponent)      // 至少有武器或魔法
+                .none(DeadTag, FrozenTag)                  // 不能是死亡或冰冻状态
+        );
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 处理可以战斗的活着的实体
+    }
+}
+```
+
+### 按标签查询
+
+```typescript
+class PlayerSystem extends EntitySystem {
+    constructor() {
+        // 查询特定标签的实体
+        super(Matcher.empty().withTag(Tags.PLAYER));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理玩家实体
+    }
+}
+```
+
+### 按名称查询
+
+```typescript
+class BossSystem extends EntitySystem {
+    constructor() {
+        // 查询特定名称的实体
+        super(Matcher.empty().withName('Boss'));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 只处理名为 'Boss' 的实体
+    }
+}
+```
+
+## 直接使用 QuerySystem
+
+如果不需要创建系统,可以直接使用 Scene 的 querySystem 进行查询。
+
+### 基础查询方法
+
+```typescript
+// 获取场景的查询系统
+const querySystem = scene.querySystem;
+
+// 查询拥有所有指定组件的实体
+const result1 = querySystem.queryAll(PositionComponent, VelocityComponent);
+console.log(`找到 ${result1.count} 个移动实体`);
+console.log(`查询耗时: ${result1.executionTime.toFixed(2)}ms`);
+
+// 查询拥有任意指定组件的实体
+const result2 = querySystem.queryAny(WeaponComponent, MagicComponent);
+console.log(`找到 ${result2.count} 个战斗单位`);
+
+// 查询不包含指定组件的实体
+const result3 = querySystem.queryNone(DeadTag);
+console.log(`找到 ${result3.count} 个活着的实体`);
+```
+
+### 按标签查询
+
+```typescript
+const playerResult = querySystem.queryByTag(Tags.PLAYER);
+for (const player of playerResult.entities) {
+    console.log('玩家:', player.name);
+}
+```
+
+### 按名称查询
+
+```typescript
+const bossResult = querySystem.queryByName('Boss');
+if (bossResult.count > 0) {
+    const boss = bossResult.entities[0];
+    console.log('找到Boss:', boss);
+}
+```
+
+### 按单个组件查询
+
+```typescript
+const healthResult = querySystem.queryByComponent(HealthComponent);
+console.log(`有 ${healthResult.count} 个实体拥有生命值`);
+```
+
+## 性能优化
+
+### 自动缓存
+
+QuerySystem 内部使用响应式查询自动缓存结果,相同的查询条件会直接使用缓存:
+
+```typescript
+// 第一次查询,执行实际查询
+const result1 = querySystem.queryAll(PositionComponent);
+console.log('fromCache:', result1.fromCache); // false
+
+// 第二次相同查询,使用缓存
+const result2 = querySystem.queryAll(PositionComponent);
+console.log('fromCache:', result2.fromCache); // true
+```
+
+### 实体变化自动更新
+
+当实体添加/移除组件时,查询缓存会自动更新:
+
+```typescript
+// 查询拥有武器的实体
+const before = querySystem.queryAll(WeaponComponent);
+console.log('之前:', before.count); // 假设为 5
+
+// 给实体添加武器
+const enemy = scene.createEntity('Enemy');
+enemy.addComponent(new WeaponComponent());
+
+// 再次查询,自动包含新实体
+const after = querySystem.queryAll(WeaponComponent);
+console.log('之后:', after.count); // 现在是 6
+```
+
+### 查询性能统计
+
+```typescript
+const stats = querySystem.getStats();
+console.log('总查询次数:', stats.queryStats.totalQueries);
+console.log('缓存命中率:', stats.queryStats.cacheHitRate);
+console.log('缓存大小:', stats.cacheStats.size);
+```
+
+## 实际应用场景
+
+### 场景1: 物理系统
+
+```typescript
+class PhysicsSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(TransformComponent, RigidbodyComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        for (const entity of entities) {
+            const transform = entity.getComponent(TransformComponent)!;
+            const rigidbody = entity.getComponent(RigidbodyComponent)!;
+
+            // 应用重力
+            rigidbody.velocity.y -= 9.8 * Time.deltaTime;
+
+            // 更新位置
+            transform.position.x += rigidbody.velocity.x * Time.deltaTime;
+            transform.position.y += rigidbody.velocity.y * Time.deltaTime;
+        }
+    }
+}
+```
+
+### 场景2: 渲染系统
+
+```typescript
+class RenderSystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(TransformComponent, SpriteComponent)
+                .none(InvisibleTag)  // 排除不可见实体
+        );
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 按 z-order 排序
+        const sorted = entities.slice().sort((a, b) => {
+            const zA = a.getComponent(TransformComponent)!.z;
+            const zB = b.getComponent(TransformComponent)!.z;
+            return zA - zB;
+        });
+
+        // 渲染实体
+        for (const entity of sorted) {
+            const transform = entity.getComponent(TransformComponent)!;
+            const sprite = entity.getComponent(SpriteComponent)!;
+
+            renderer.drawSprite(sprite.texture, transform.position);
+        }
+    }
+}
+```
+
+### 场景3: 碰撞检测
+
+```typescript
+class CollisionSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(TransformComponent, ColliderComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 简单的 O(n²) 碰撞检测
+        for (let i = 0; i < entities.length; i++) {
+            for (let j = i + 1; j < entities.length; j++) {
+                this.checkCollision(entities[i], entities[j]);
+            }
+        }
+    }
+
+    private checkCollision(a: Entity, b: Entity): void {
+        const transA = a.getComponent(TransformComponent)!;
+        const transB = b.getComponent(TransformComponent)!;
+        const colliderA = a.getComponent(ColliderComponent)!;
+        const colliderB = b.getComponent(ColliderComponent)!;
+
+        if (this.isOverlapping(transA, colliderA, transB, colliderB)) {
+            // 触发碰撞事件
+            scene.eventSystem.emit('collision', { entityA: a, entityB: b });
+        }
+    }
+
+    private isOverlapping(...args: any[]): boolean {
+        // 碰撞检测逻辑
+        return false;
+    }
+}
+```
+
+### 场景4: 一次性查询
+
+```typescript
+// 在系统外部执行一次性查询
+class GameManager {
+    private scene: Scene;
+
+    public countEnemies(): number {
+        const result = this.scene.querySystem.queryByTag(Tags.ENEMY);
+        return result.count;
+    }
+
+    public findNearestEnemy(playerPos: Vector2): Entity | null {
+        const enemies = this.scene.querySystem.queryByTag(Tags.ENEMY);
+
+        let nearest: Entity | null = null;
+        let minDistance = Infinity;
+
+        for (const enemy of enemies.entities) {
+            const transform = enemy.getComponent(TransformComponent);
+            if (!transform) continue;
+
+            const distance = Vector2.distance(playerPos, transform.position);
+            if (distance < minDistance) {
+                minDistance = distance;
+                nearest = enemy;
+            }
+        }
+
+        return nearest;
+    }
+}
+```
+
+## 最佳实践
+
+### 1. 优先使用 EntitySystem
+
+```typescript
+// 推荐: 使用 EntitySystem
+class GoodSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(HealthComponent));
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 自动获得符合条件的实体,每帧自动更新
+    }
+}
+
+// 不推荐: 在 update 中手动查询
+class BadSystem extends EntitySystem {
+    constructor() {
+        super(Matcher.empty());
+    }
+
+    protected process(entities: readonly Entity[]): void {
+        // 每帧手动查询,浪费性能
+        const result = this.scene!.querySystem.queryAll(HealthComponent);
+        for (const entity of result.entities) {
+            // ...
+        }
+    }
+}
+```
+
+### 2. 合理使用 none() 排除条件
+
+```typescript
+// 排除已死亡的敌人
+class EnemyAISystem extends EntitySystem {
+    constructor() {
+        super(
+            Matcher.empty()
+                .all(EnemyTag, AIComponent)
+                .none(DeadTag)  // 不处理死亡的敌人
+        );
+    }
+}
+```
+
+### 3. 使用标签优化查询
+
+```typescript
+// 不好: 查询所有实体再过滤
+const allEntities = scene.querySystem.getAllEntities();
+const players = allEntities.filter(e => e.hasComponent(PlayerTag));
+
+// 好: 直接按标签查询
+const players = scene.querySystem.queryByTag(Tags.PLAYER).entities;
+```
+
+### 4. 避免过于复杂的查询条件
+
+```typescript
+// 不推荐: 过于复杂
+super(
+    Matcher.empty()
+        .all(A, B, C, D)
+        .any(E, F, G)
+        .none(H, I, J)
+);
+
+// 推荐: 拆分成多个简单系统
+class SystemAB extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(A, B));
+    }
+}
+
+class SystemCD extends EntitySystem {
+    constructor() {
+        super(Matcher.empty().all(C, D));
+    }
+}
+```
+
+## 注意事项
+
+### 1. 查询结果是只读的
+
+```typescript
+const result = querySystem.queryAll(PositionComponent);
+
+// 不要修改返回的数组
+result.entities.push(someEntity);  // 错误!
+
+// 如果需要修改,先复制
+const mutableArray = [...result.entities];
+mutableArray.push(someEntity);  // 正确
+```
+
+### 2. 组件添加/移除后的查询时机
+
+```typescript
+// 创建实体并添加组件
+const entity = scene.createEntity('Player');
+entity.addComponent(new PositionComponent());
+
+// 立即查询可能获取到新实体
+const result = scene.querySystem.queryAll(PositionComponent);
+// result.entities 包含新创建的实体
+```
+
+### 3. Matcher 是不可变的
+
+```typescript
+const matcher = Matcher.empty().all(PositionComponent);
+
+// 链式调用返回新的 Matcher 实例
+const matcher2 = matcher.any(VelocityComponent);
+
+// matcher 本身不变
+console.log(matcher === matcher2); // false
+```
+
+## 相关 API
+
+- [Matcher](../api/classes/Matcher.md) - 查询条件描述符 API 参考
+- [QuerySystem](../api/classes/QuerySystem.md) - 查询系统 API 参考
+- [EntitySystem](../api/classes/EntitySystem.md) - 实体系统 API 参考
+- [Entity](../api/classes/Entity.md) - 实体 API 参考

docs/guide/getting-started.md

@@ -314,8 +314,8 @@ import { Core, WorldManager } from '@esengine/ecs-framework';
 // 初始化Core
 Core.create({ debug: true });
 
-// 创建世界管理器（手动管理）
-const worldManager = new WorldManager();
+// 从服务容器获取 WorldManager（Core 已自动创建并注册）
+const worldManager = Core.services.resolve(WorldManager);
 
 // 创建多个独立的游戏世界
 const room1 = worldManager.createWorld('room_001');

docs/guide/scene-manager.md

@@ -0,0 +1,675 @@
+# SceneManager
+
+SceneManager 是 ECS Framework 提供的轻量级场景管理器，适用于 95% 的游戏应用。它提供简单直观的 API，支持场景切换和延迟加载。
+
+## 适用场景
+
+SceneManager 适合以下场景：
+- 单人游戏
+- 简单多人游戏
+- 移动游戏
+- 需要场景切换的游戏（菜单、游戏、暂停等）
+- 不需要多 World 隔离的项目
+
+## 特点
+
+- 轻量级，零额外开销
+- 简单直观的 API
+- 支持延迟场景切换（避免在当前帧中途切换）
+- 自动管理 ECS 流式 API
+- 自动处理场景生命周期
+- 集成在 Core 中，自动更新
+
+## 基本使用
+
+### 推荐方式：使用 Core 的静态方法
+
+这是最简单和推荐的方式，适合大多数应用：
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 1. 初始化 Core
+Core.create({ debug: true });
+
+// 2. 创建并设置场景
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 添加系统
+    this.addSystem(new MovementSystem());
+    this.addSystem(new RenderSystem());
+
+    // 创建初始实体
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Health(100));
+  }
+
+  public onStart(): void {
+    console.log("游戏场景已启动");
+  }
+}
+
+// 3. 设置场景
+Core.setScene(new GameScene());
+
+// 4. 游戏循环（Core.update 会自动更新场景）
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // 自动更新所有服务和场景
+}
+
+// Laya 引擎集成
+Laya.timer.frameLoop(1, this, () => {
+  const deltaTime = Laya.timer.delta / 1000;
+  Core.update(deltaTime);
+});
+
+// Cocos Creator 集成
+update(deltaTime: number) {
+  Core.update(deltaTime);
+}
+```
+
+### 高级方式：直接使用 SceneManager
+
+如果需要更多控制，可以直接使用 SceneManager：
+
+```typescript
+import { Core, SceneManager, Scene } from '@esengine/ecs-framework';
+
+// 初始化 Core
+Core.create({ debug: true });
+
+// 获取 SceneManager（Core 已自动创建并注册）
+const sceneManager = Core.services.resolve(SceneManager);
+
+// 设置场景
+const gameScene = new GameScene();
+sceneManager.setScene(gameScene);
+
+// 游戏循环（仍然使用 Core.update）
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // Core会自动调用sceneManager.update()
+}
+```
+
+**重要**：无论使用哪种方式，游戏循环中都应该只调用 `Core.update()`，它会自动更新 SceneManager 和场景。不需要手动调用 `sceneManager.update()`。
+
+## 场景切换
+
+### 立即切换
+
+使用 `Core.setScene()` 或 `sceneManager.setScene()` 立即切换场景：
+
+```typescript
+// 方式1：使用 Core（推荐）
+Core.setScene(new MenuScene());
+
+// 方式2：使用 SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new MenuScene());
+```
+
+### 延迟切换
+
+使用 `Core.loadScene()` 或 `sceneManager.loadScene()` 延迟切换场景，场景会在下一帧切换：
+
+```typescript
+// 方式1：使用 Core（推荐）
+Core.loadScene(new GameOverScene());
+
+// 方式2：使用 SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.loadScene(new GameOverScene());
+```
+
+在 System 中切换场景时，应该使用延迟切换：
+
+```typescript
+class GameOverSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    const player = entities.find(e => e.name === 'Player');
+    const health = player?.getComponent(Health);
+
+    if (health && health.value <= 0) {
+      // 延迟切换到游戏结束场景（下一帧生效）
+      Core.loadScene(new GameOverScene());
+      // 当前帧继续执行，不会中断当前系统的处理
+    }
+  }
+}
+```
+
+### 完整的场景切换示例
+
+```typescript
+import { Core, Scene } from '@esengine/ecs-framework';
+
+// 初始化
+Core.create({ debug: true });
+
+// 菜单场景
+class MenuScene extends Scene {
+  protected initialize(): void {
+    this.name = "MenuScene";
+
+    // 监听开始游戏事件
+    this.eventSystem.on('start_game', () => {
+      Core.loadScene(new GameScene());
+    });
+  }
+
+  public onStart(): void {
+    console.log("显示菜单界面");
+  }
+
+  public unload(): void {
+    console.log("菜单场景卸载");
+  }
+}
+
+// 游戏场景
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 创建游戏实体
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Health(100));
+
+    // 监听游戏结束事件
+    this.eventSystem.on('game_over', () => {
+      Core.loadScene(new GameOverScene());
+    });
+  }
+
+  public onStart(): void {
+    console.log("游戏开始");
+  }
+
+  public unload(): void {
+    console.log("游戏场景卸载");
+  }
+}
+
+// 游戏结束场景
+class GameOverScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameOverScene";
+
+    // 监听返回菜单事件
+    this.eventSystem.on('back_to_menu', () => {
+      Core.loadScene(new MenuScene());
+    });
+  }
+
+  public onStart(): void {
+    console.log("显示游戏结束界面");
+  }
+}
+
+// 开始游戏
+Core.setScene(new MenuScene());
+
+// 游戏循环
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // 自动更新场景
+}
+```
+
+## API 参考
+
+### Core 静态方法（推荐）
+
+#### Core.setScene()
+
+立即切换场景。
+
+```typescript
+public static setScene<T extends IScene>(scene: T): T
+```
+
+**参数**：
+- `scene` - 要设置的场景实例
+
+**返回**：
+- 返回设置的场景实例
+
+**示例**：
+```typescript
+const gameScene = Core.setScene(new GameScene());
+console.log(gameScene.name);
+```
+
+#### Core.loadScene()
+
+延迟加载场景（下一帧切换）。
+
+```typescript
+public static loadScene<T extends IScene>(scene: T): void
+```
+
+**参数**：
+- `scene` - 要加载的场景实例
+
+**示例**：
+```typescript
+Core.loadScene(new GameOverScene());
+```
+
+#### Core.scene
+
+获取当前活跃的场景。
+
+```typescript
+public static get scene(): IScene | null
+```
+
+**返回**：
+- 当前场景实例，如果没有场景则返回 null
+
+**示例**：
+```typescript
+const currentScene = Core.scene;
+if (currentScene) {
+  console.log(`当前场景: ${currentScene.name}`);
+}
+```
+
+#### Core.ecsAPI
+
+获取 ECS 流式 API。
+
+```typescript
+public static get ecsAPI(): ECSFluentAPI | null
+```
+
+**返回**：
+- ECS API 实例，如果当前没有场景则返回 null
+
+**示例**：
+```typescript
+const api = Core.ecsAPI;
+if (api) {
+  // 查询实体
+  const enemies = api.find(Enemy, Transform);
+
+  // 发射事件
+  api.emit('game:start', { level: 1 });
+}
+```
+
+### SceneManager 方法（高级）
+
+如果需要直接使用 SceneManager，可以通过服务容器获取：
+
+```typescript
+const sceneManager = Core.services.resolve(SceneManager);
+```
+
+#### setScene()
+
+立即切换场景。
+
+```typescript
+public setScene<T extends IScene>(scene: T): T
+```
+
+#### loadScene()
+
+延迟加载场景。
+
+```typescript
+public loadScene<T extends IScene>(scene: T): void
+```
+
+#### currentScene
+
+获取当前场景。
+
+```typescript
+public get currentScene(): IScene | null
+```
+
+#### api
+
+获取 ECS 流式 API。
+
+```typescript
+public get api(): ECSFluentAPI | null
+```
+
+#### hasScene
+
+检查是否有活跃场景。
+
+```typescript
+public get hasScene(): boolean
+```
+
+#### hasPendingScene
+
+检查是否有待切换的场景。
+
+```typescript
+public get hasPendingScene(): boolean
+```
+
+## 使用 ECS 流式 API
+
+通过 `Core.ecsAPI` 可以方便地访问场景的 ECS 功能：
+
+```typescript
+const api = Core.ecsAPI;
+if (!api) {
+  console.error('没有活跃场景');
+  return;
+}
+
+// 查询实体
+const players = api.find(Player, Transform);
+const enemies = api.find(Enemy, Health, Transform);
+
+// 发射事件
+api.emit('player:scored', { points: 100 });
+
+// 监听事件
+api.on('enemy:died', (data) => {
+  console.log('敌人死亡:', data);
+});
+```
+
+## 最佳实践
+
+### 1. 使用 Core 的静态方法
+
+```typescript
+// 推荐：使用 Core 的静态方法
+Core.setScene(new GameScene());
+Core.loadScene(new MenuScene());
+const currentScene = Core.scene;
+
+// 不推荐：除非有特殊需求，否则不需要直接使用 SceneManager
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+```
+
+### 2. 只调用 Core.update()
+
+```typescript
+// 正确：只调用 Core.update()
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);  // 自动更新所有服务和场景
+}
+
+// 错误：不要手动调用 sceneManager.update()
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);
+  sceneManager.update();  // 重复更新，会导致问题！
+}
+```
+
+### 3. 使用延迟切换避免问题
+
+在 System 中切换场景时，应该使用 `loadScene()` 而不是 `setScene()`：
+
+```typescript
+// 推荐：延迟切换
+class HealthSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      if (health.value <= 0) {
+        Core.loadScene(new GameOverScene());
+        // 当前帧继续处理其他实体
+      }
+    }
+  }
+}
+
+// 不推荐：立即切换可能导致问题
+class HealthSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const health = entity.getComponent(Health);
+      if (health.value <= 0) {
+        Core.setScene(new GameOverScene());
+        // 场景立即切换，当前帧的其他实体可能无法正常处理
+      }
+    }
+  }
+}
+```
+
+### 4. 场景职责分离
+
+每个场景应该只负责一个特定的游戏状态：
+
+```typescript
+// 好的设计 - 职责清晰
+class MenuScene extends Scene {
+  // 只处理菜单相关逻辑
+}
+
+class GameScene extends Scene {
+  // 只处理游戏玩法逻辑
+}
+
+class PauseScene extends Scene {
+  // 只处理暂停界面逻辑
+}
+
+// 避免的设计 - 职责混乱
+class MegaScene extends Scene {
+  // 包含菜单、游戏、暂停等所有逻辑
+}
+```
+
+### 5. 资源管理
+
+在场景的 `unload()` 方法中清理资源：
+
+```typescript
+class GameScene extends Scene {
+  private textures: Map<string, any> = new Map();
+  private sounds: Map<string, any> = new Map();
+
+  protected initialize(): void {
+    this.loadResources();
+  }
+
+  private loadResources(): void {
+    this.textures.set('player', loadTexture('player.png'));
+    this.sounds.set('bgm', loadSound('bgm.mp3'));
+  }
+
+  public unload(): void {
+    // 清理资源
+    this.textures.clear();
+    this.sounds.clear();
+    console.log('场景资源已清理');
+  }
+}
+```
+
+### 6. 事件驱动的场景切换
+
+使用事件系统来触发场景切换，保持代码解耦：
+
+```typescript
+class GameScene extends Scene {
+  protected initialize(): void {
+    // 监听场景切换事件
+    this.eventSystem.on('goto:menu', () => {
+      Core.loadScene(new MenuScene());
+    });
+
+    this.eventSystem.on('goto:gameover', (data) => {
+      Core.loadScene(new GameOverScene());
+    });
+  }
+}
+
+// 在 System 中触发事件
+class GameLogicSystem extends EntitySystem {
+  process(entities: readonly Entity[]): void {
+    if (levelComplete) {
+      this.scene.eventSystem.emitSync('goto:gameover', {
+        score: 1000,
+        level: 5
+      });
+    }
+  }
+}
+```
+
+## 架构层次
+
+SceneManager 在 ECS Framework 中的位置：
+
+```
+Core (全局服务)
+  └── SceneManager (场景管理，自动更新)
+      └── Scene (当前场景)
+          ├── EntitySystem (系统)
+          ├── Entity (实体)
+          └── Component (组件)
+```
+
+## 与 WorldManager 的对比
+
+| 特性 | SceneManager | WorldManager |
+|------|--------------|--------------|
+| 适用场景 | 95% 的游戏应用 | 高级多世界隔离场景 |
+| 复杂度 | 简单 | 复杂 |
+| 场景数量 | 单场景（可切换） | 多 World，每个 World 多场景 |
+| 性能开销 | 最小 | 较高 |
+| 使用方式 | `Core.setScene()` | `worldManager.createWorld()` |
+
+**何时使用 SceneManager**：
+- 单人游戏
+- 简单的多人游戏
+- 移动游戏
+- 场景之间需要切换但不需要同时运行
+
+**何时使用 WorldManager**：
+- MMO 游戏服务器（每个房间一个 World）
+- 游戏大厅系统（每个游戏房间完全隔离）
+- 需要运行多个完全独立的游戏实例
+
+## 完整示例
+
+```typescript
+import { Core, Scene, EntitySystem, Entity, Matcher } from '@esengine/ecs-framework';
+
+// 定义组件
+class Transform {
+  constructor(public x: number, public y: number) {}
+}
+
+class Velocity {
+  constructor(public vx: number, public vy: number) {}
+}
+
+class Health {
+  constructor(public value: number) {}
+}
+
+// 定义系统
+class MovementSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Transform, Velocity));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const transform = entity.getComponent(Transform);
+      const velocity = entity.getComponent(Velocity);
+
+      if (transform && velocity) {
+        transform.x += velocity.vx;
+        transform.y += velocity.vy;
+      }
+    }
+  }
+}
+
+// 定义场景
+class MenuScene extends Scene {
+  protected initialize(): void {
+    this.name = "MenuScene";
+    console.log("菜单场景初始化");
+  }
+
+  public onStart(): void {
+    console.log("菜单场景启动");
+  }
+}
+
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 添加系统
+    this.addSystem(new MovementSystem());
+
+    // 创建玩家
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Velocity(0, 0));
+    player.addComponent(new Health(100));
+
+    // 创建敌人
+    for (let i = 0; i < 5; i++) {
+      const enemy = this.createEntity(`Enemy_${i}`);
+      enemy.addComponent(new Transform(
+        Math.random() * 800,
+        Math.random() * 600
+      ));
+      enemy.addComponent(new Velocity(
+        Math.random() * 100 - 50,
+        Math.random() * 100 - 50
+      ));
+      enemy.addComponent(new Health(50));
+    }
+  }
+
+  public onStart(): void {
+    console.log('游戏场景启动');
+  }
+
+  public unload(): void {
+    console.log('游戏场景卸载');
+  }
+}
+
+// 初始化
+Core.create({ debug: true });
+
+// 设置初始场景
+Core.setScene(new MenuScene());
+
+// 游戏循环
+let lastTime = 0;
+function gameLoop(currentTime: number) {
+  const deltaTime = (currentTime - lastTime) / 1000;
+  lastTime = currentTime;
+
+  // 只需要调用 Core.update，它会自动更新场景
+  Core.update(deltaTime);
+
+  requestAnimationFrame(gameLoop);
+}
+
+requestAnimationFrame(gameLoop);
+
+// 切换到游戏场景
+setTimeout(() => {
+  Core.loadScene(new GameScene());
+}, 3000);
+```
+
+SceneManager 为大多数游戏提供了简单而强大的场景管理能力。通过 Core 的静态方法，你可以轻松地管理场景切换。如果你需要更高级的多世界隔离功能，请参考 [WorldManager](./world-manager.md) 文档。

docs/guide/scene.md

@@ -11,6 +11,22 @@
 - 事件系统支持
 - 性能监控和调试信息
 
+## 场景管理方式
+
+ECS Framework 提供了两种场景管理方式：
+
+1. **[SceneManager](./scene-manager.md)** - 适用于 95% 的游戏应用
+   - 单人游戏、简单多人游戏、移动游戏
+   - 轻量级，简单直观的 API
+   - 支持场景切换
+
+2. **[WorldManager](./world-manager.md)** - 适用于高级多世界隔离场景
+   - MMO 游戏服务器、游戏房间系统
+   - 多 World 管理，每个 World 可包含多个场景
+   - 完全隔离的独立环境
+
+本文档重点介绍 Scene 类本身的使用方法。关于场景管理器的详细信息，请查看对应的文档。
+
 ## 创建场景
 
 ### 继承 Scene 类
@@ -106,6 +122,13 @@ const scene = new ExampleScene();
 // 场景的 initialize(), begin(), update(), end() 由框架自动调用
 ```
 
+**生命周期方法**：
+
+1. `initialize()` - 场景初始化，设置系统和初始实体
+2. `begin()` / `onStart()` - 场景开始运行
+3. `update()` - 每帧更新（由场景管理器调用）
+4. `end()` / `unload()` - 场景卸载，清理资源
+
 ## 实体管理
 
 ### 创建实体
@@ -247,15 +270,42 @@ class EventScene extends Scene {
   }
 
   public triggerGameEvent(): void {
-    // 发送事件
+    // 发送事件（同步）
     this.eventSystem.emitSync('custom_event', {
       message: "这是自定义事件",
       timestamp: Date.now()
     });
+
+    // 发送事件（异步）
+    this.eventSystem.emit('async_event', {
+      data: "异步事件数据"
+    });
   }
 }
 ```
 
+### 事件系统 API
+
+```typescript
+// 监听事件
+this.eventSystem.on('event_name', callback);
+
+// 监听一次（自动取消订阅）
+this.eventSystem.once('event_name', callback);
+
+// 取消监听
+this.eventSystem.off('event_name', callback);
+
+// 同步发送事件
+this.eventSystem.emitSync('event_name', data);
+
+// 异步发送事件
+this.eventSystem.emit('event_name', data);
+
+// 清除所有事件监听
+this.eventSystem.clear();
+```
+
 ## 场景统计和调试
 
 ### 获取场景统计
@@ -287,176 +337,58 @@ class StatsScene extends Scene {
 }
 ```
 
-## 场景集成到框架
+## 组件查询
 
-ECS Framework 提供了灵活的场景管理架构，适用于不同规模的应用：
-
-### 1. 使用 SceneManager（推荐大多数应用）
-
-适用于 95% 的游戏应用（单人游戏、简单多人游戏、移动游戏等）：
+Scene 提供了强大的组件查询系统：
 
 ```typescript
-import { Core, SceneManager } from '@esengine/ecs-framework';
-
-// 初始化Core（全局服务）
-Core.create({ debug: true });
-
-// 创建场景管理器
-const sceneManager = new SceneManager();
-
-// 创建游戏场景
-class GameScene extends Scene {
+class QueryScene extends Scene {
   protected initialize(): void {
-    this.name = "GameScene";
-    this.addSystem(new MovementSystem());
-    this.addSystem(new RenderSystem());
-  }
-}
-
-// 设置场景
-const gameScene = new GameScene();
-sceneManager.setScene(gameScene);
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 更新全局服务
-  sceneManager.update();        // 更新当前场景
-}
-```
-
-### 2. 场景切换
-
-SceneManager 支持流畅的场景切换：
-
-```typescript
-// 立即切换场景
-const menuScene = new MenuScene();
-sceneManager.setScene(menuScene);
-
-// 延迟切换场景（在下一帧切换）
-const gameScene = new GameScene();
-sceneManager.startSceneTransition(gameScene, false);
-
-// 访问当前场景
-const currentScene = sceneManager.currentScene;
-
-// 访问 ECS API
-const ecsAPI = sceneManager.ecsAPI;
-const entity = ecsAPI?.createEntity('player');
-```
-
-### 3. 使用 WorldManager（高级用例）
-
-适用于需要完全隔离的多世界应用（MMO服务器、游戏房间系统等）：
-
-```typescript
-import { Core, WorldManager } from '@esengine/ecs-framework';
-
-// 初始化Core（全局服务）
-Core.create({ debug: true });
-
-// 创建世界管理器
-const worldManager = new WorldManager();
-
-// 创建多个独立的游戏世界
-const gameWorld = worldManager.createWorld('game', {
-  name: 'MainGame',
-  maxScenes: 5
-});
-
-// 在World中创建场景
-const menuScene = gameWorld.createScene('menu', new MenuScene());
-const gameScene = gameWorld.createScene('game', new GameScene());
-
-// 激活场景
-gameWorld.setSceneActive('menu', true);
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 更新全局服务
-  worldManager.updateAll();    // 更新所有世界
-}
-```
-
-## 多场景管理
-
-在World中可以管理多个场景，通过激活/停用来切换：
-
-```typescript
-class GameWorld extends World {
-  private menuScene: Scene;
-  private gameScene: Scene;
-  private gameOverScene: Scene;
-
-  public initialize(): void {
-    // 创建多个场景
-    this.menuScene = this.createScene('menu', new MenuScene());
-    this.gameScene = this.createScene('game', new GameScene());
-    this.gameOverScene = this.createScene('gameover', new GameOverScene());
-
-    // 设置初始场景
-    this.showMenu();
+    // 创建一些实体
+    for (let i = 0; i < 10; i++) {
+      const entity = this.createEntity(`Entity_${i}`);
+      entity.addComponent(new Transform(i * 10, 0));
+      entity.addComponent(new Velocity(1, 0));
+      if (i % 2 === 0) {
+        entity.addComponent(new Renderer());
+      }
+    }
   }
 
-  public showMenu(): void {
-    this.deactivateAllScenes();
-    this.setSceneActive('menu', true);
-  }
+  public queryEntities(): void {
+    // 通过 QuerySystem 查询
+    const entities = this.querySystem.query([Transform, Velocity]);
+    console.log(`找到 ${entities.length} 个有 Transform 和 Velocity 的实体`);
 
-  public startGame(): void {
-    this.deactivateAllScenes();
-    this.setSceneActive('game', true);
-  }
-
-  public showGameOver(): void {
-    this.deactivateAllScenes();
-    this.setSceneActive('gameover', true);
-  }
-
-  private deactivateAllScenes(): void {
-    this.setSceneActive('menu', false);
-    this.setSceneActive('game', false);
-    this.setSceneActive('gameover', false);
+    // 使用 ECS 流式 API（如果通过 SceneManager）
+    // const api = sceneManager.api;
+    // const entities = api?.find(Transform, Velocity);
   }
 }
 ```
 
-## 架构层次
+## 性能监控
 
-ECS Framework 的架构层次清晰，职责分明：
+Scene 内置了性能监控功能：
 
 ```typescript
-// 架构层次：
-// Core (全局服务) → SceneManager (场景管理) → Scene → EntitySystem → Entity → Component
-// 或
-// Core (全局服务) → WorldManager (世界管理) → World → Scene → EntitySystem → Entity → Component
+class PerformanceScene extends Scene {
+  public showPerformance(): void {
+    // 获取性能数据
+    const perfData = this.performanceMonitor?.getPerformanceData();
+    if (perfData) {
+      console.log('FPS:', perfData.fps);
+      console.log('帧时间:', perfData.frameTime);
+      console.log('实体更新时间:', perfData.entityUpdateTime);
+      console.log('系统更新时间:', perfData.systemUpdateTime);
+    }
 
-// 1. 推荐：使用 SceneManager 管理单场景/场景切换
-import { Core, SceneManager } from '@esengine/ecs-framework';
-
-Core.create({ debug: true });
-const sceneManager = new SceneManager();
-sceneManager.setScene(new GameScene());
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 全局服务
-  sceneManager.update();        // 场景更新
-}
-
-// 2. 高级：使用 WorldManager 管理多世界
-import { Core, WorldManager } from '@esengine/ecs-framework';
-
-Core.create({ debug: true });
-const worldManager = new WorldManager();
-const world = worldManager.createWorld('gameWorld');
-const scene = world.createScene('mainScene', new GameScene());
-world.setSceneActive('mainScene', true);
-
-// 游戏循环
-function gameLoop(deltaTime: number) {
-  Core.update(deltaTime);      // 全局服务
-  worldManager.updateAll();    // 所有世界更新
+    // 获取性能报告
+    const report = this.performanceMonitor?.generateReport();
+    if (report) {
+      console.log('性能报告:', report);
+    }
+  }
 }
 ```
 
@@ -465,7 +397,7 @@ function gameLoop(deltaTime: number) {
 ### 1. 场景职责分离
 
 ```typescript
-// ✅ 好的场景设计 - 职责清晰
+// 好的场景设计 - 职责清晰
 class MenuScene extends Scene {
   // 只处理菜单相关逻辑
 }
@@ -478,7 +410,7 @@ class InventoryScene extends Scene {
   // 只处理物品栏逻辑
 }
 
-// ❌ 避免的场景设计 - 职责混乱
+// 避免的场景设计 - 职责混乱
 class MegaScene extends Scene {
   // 包含菜单、游戏、物品栏等所有逻辑
 }
@@ -525,12 +457,25 @@ class ResourceScene extends Scene {
 
   private loadResources(): void {
     // 加载场景所需资源
+    this.textures.set('player', this.loadTexture('player.png'));
+    this.sounds.set('bgm', this.loadSound('bgm.mp3'));
   }
 
   public unload(): void {
     // 清理资源
     this.textures.clear();
     this.sounds.clear();
+    console.log('场景资源已清理');
+  }
+
+  private loadTexture(path: string): any {
+    // 加载纹理
+    return null;
+  }
+
+  private loadSound(path: string): any {
+    // 加载音效
+    return null;
   }
 }
 ```
@@ -571,7 +516,146 @@ class EventHandlingScene extends Scene {
   private onPlayerInput(data: any): void {
     // 处理玩家输入
   }
+
+  public unload(): void {
+    // 清理事件监听
+    this.eventSystem.clear();
+  }
 }
 ```
 
-场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。
+### 5. 初始化顺序
+
+```typescript
+class ProperInitScene extends Scene {
+  protected initialize(): void {
+    // 1. 首先设置场景配置
+    this.name = "GameScene";
+
+    // 2. 然后添加系统（按依赖顺序）
+    this.addSystem(new InputSystem());
+    this.addSystem(new MovementSystem());
+    this.addSystem(new PhysicsSystem());
+    this.addSystem(new RenderSystem());
+
+    // 3. 最后创建实体
+    this.createEntities();
+
+    // 4. 设置事件监听
+    this.setupEvents();
+  }
+
+  private createEntities(): void {
+    // 创建实体
+  }
+
+  private setupEvents(): void {
+    // 设置事件监听
+  }
+}
+```
+
+## 完整示例
+
+```typescript
+import { Scene, EntitySystem, Entity, Matcher } from '@esengine/ecs-framework';
+
+// 定义组件
+class Transform {
+  constructor(public x: number, public y: number) {}
+}
+
+class Velocity {
+  constructor(public vx: number, public vy: number) {}
+}
+
+class Health {
+  constructor(public value: number) {}
+}
+
+// 定义系统
+class MovementSystem extends EntitySystem {
+  constructor() {
+    super(Matcher.all(Transform, Velocity));
+  }
+
+  process(entities: readonly Entity[]): void {
+    for (const entity of entities) {
+      const transform = entity.getComponent(Transform);
+      const velocity = entity.getComponent(Velocity);
+
+      if (transform && velocity) {
+        transform.x += velocity.vx;
+        transform.y += velocity.vy;
+      }
+    }
+  }
+}
+
+// 定义场景
+class GameScene extends Scene {
+  protected initialize(): void {
+    this.name = "GameScene";
+
+    // 添加系统
+    this.addSystem(new MovementSystem());
+
+    // 创建玩家
+    const player = this.createEntity("Player");
+    player.addComponent(new Transform(400, 300));
+    player.addComponent(new Velocity(0, 0));
+    player.addComponent(new Health(100));
+
+    // 创建敌人
+    for (let i = 0; i < 5; i++) {
+      const enemy = this.createEntity(`Enemy_${i}`);
+      enemy.addComponent(new Transform(
+        Math.random() * 800,
+        Math.random() * 600
+      ));
+      enemy.addComponent(new Velocity(
+        Math.random() * 100 - 50,
+        Math.random() * 100 - 50
+      ));
+      enemy.addComponent(new Health(50));
+    }
+
+    // 设置事件监听
+    this.eventSystem.on('player_died', () => {
+      console.log('玩家死亡！');
+    });
+  }
+
+  public onStart(): void {
+    console.log('游戏场景启动');
+  }
+
+  public unload(): void {
+    console.log('游戏场景卸载');
+    this.eventSystem.clear();
+  }
+}
+
+// 使用场景
+// 方式1：通过 SceneManager（推荐）
+import { Core, SceneManager } from '@esengine/ecs-framework';
+
+Core.create({ debug: true });
+const sceneManager = Core.services.resolve(SceneManager);
+sceneManager.setScene(new GameScene());
+
+// 方式2：通过 WorldManager（高级用例）
+import { WorldManager } from '@esengine/ecs-framework';
+
+const worldManager = Core.services.resolve(WorldManager);
+const world = worldManager.createWorld('game');
+world.createScene('main', new GameScene());
+world.setSceneActive('main', true);
+```
+
+## 下一步
+
+- 了解 [SceneManager](./scene-manager.md) - 适用于大多数游戏的简单场景管理
+- 了解 [WorldManager](./world-manager.md) - 适用于需要多世界隔离的高级场景
+
+场景是 ECS 框架的核心容器，正确使用场景管理能让你的游戏架构更加清晰、模块化和易于维护。

docs/guide/serialization.md

@@ -14,6 +14,18 @@
 - **JSON格式**：人类可读，便于调试和编辑
 - **Binary格式**：使用MessagePack，体积更小，性能更高
 
+> **📢 v2.2.2 重要变更**
+>
+> 从 v2.2.2 开始，二进制序列化格式返回 `Uint8Array` 而非 Node.js 的 `Buffer`，以确保浏览器兼容性：
+> - `serialize({ format: 'binary' })` 返回 `string | Uint8Array`（原为 `string | Buffer`）
+> - `deserialize(data)` 接收 `string | Uint8Array`（原为 `string | Buffer`）
+> - `applyIncremental(data)` 接收 `IncrementalSnapshot | string | Uint8Array`（原为包含 `Buffer`）
+>
+> **迁移影响**：
+> - ✅ **运行时兼容**：Node.js 的 `Buffer` 继承自 `Uint8Array`，现有代码可直接运行
+> - ⚠️ **类型检查**：如果你的 TypeScript 代码中显式使用了 `Buffer` 类型，需要改为 `Uint8Array`
+> - ✅ **浏览器支持**：`Uint8Array` 是标准 JavaScript 类型，所有现代浏览器都支持
+
 ## 全量序列化
 
 ### 基础用法
@@ -63,6 +75,7 @@ const binaryData = scene.serialize({
 });
 
 // 保存为文件（Node.js环境）
+// 注意：binaryData 是 Uint8Array 类型，Node.js 的 fs 可以直接写入
 fs.writeFileSync('save.bin', binaryData);
 ```
 
@@ -285,7 +298,7 @@ otherScene.applyIncremental(incremental);
 const jsonData = IncrementalSerializer.serializeIncremental(incremental, { format: 'json' });
 otherScene.applyIncremental(jsonData);
 
-// 从二进制Buffer应用
+// 从二进制Uint8Array应用
 const binaryData = IncrementalSerializer.serializeIncremental(incremental, { format: 'binary' });
 otherScene.applyIncremental(binaryData);
 ```
@@ -552,9 +565,9 @@ class NetworkSync {
   }
 
   private receiveIncremental(data: ArrayBuffer): void {
-    // 直接应用二进制数据
-    const buffer = Buffer.from(data);
-    this.scene.applyIncremental(buffer);
+    // 直接应用二进制数据（ArrayBuffer 转 Uint8Array）
+    const uint8Array = new Uint8Array(data);
+    this.scene.applyIncremental(uint8Array);
   }
 }
 ```
@@ -790,7 +803,7 @@ class LargeDataComponent extends Component {
 
 - [`Scene.createIncrementalSnapshot()`](/api/classes/Scene#createincrementalsnapshot) - 创建基础快照
 - [`Scene.serializeIncremental()`](/api/classes/Scene#serializeincremental) - 获取增量变更
-- [`Scene.applyIncremental()`](/api/classes/Scene#applyincremental) - 应用增量变更（支持IncrementalSnapshot对象、JSON字符串或二进制Buffer）
+- [`Scene.applyIncremental()`](/api/classes/Scene#applyincremental) - 应用增量变更（支持IncrementalSnapshot对象、JSON字符串或二进制Uint8Array）
 - [`Scene.updateIncrementalSnapshot()`](/api/classes/Scene#updateincrementalsnapshot) - 更新快照基准
 - [`Scene.clearIncrementalSnapshot()`](/api/classes/Scene#clearincrementalsnapshot) - 清除快照
 - [`Scene.hasIncrementalSnapshot()`](/api/classes/Scene#hasincrementalsnapshot) - 检查是否有快照

docs/guide/service-container.md

@@ -196,15 +196,49 @@ const fps = monitor.getFPS();
 
 ### SceneManager
 
-场景管理器，管理场景的生命周期：
+场景管理器，管理单场景应用的场景生命周期：
 
 ```typescript
 const sceneManager = Core.services.resolve(SceneManager);
 
+// 设置当前场景
+sceneManager.setScene(new GameScene());
+
 // 获取当前场景
 const currentScene = sceneManager.currentScene;
+
+// 延迟切换场景
+sceneManager.loadScene(new MenuScene());
+
+// 更新场景
+sceneManager.update();
 ```
 
+### WorldManager
+
+世界管理器，管理多个独立的 World 实例（高级用例）：
+
+```typescript
+const worldManager = Core.services.resolve(WorldManager);
+
+// 创建独立的游戏世界
+const gameWorld = worldManager.createWorld('game_room_001', {
+  name: 'GameRoom',
+  maxScenes: 5
+});
+
+// 在World中创建场景
+const scene = gameWorld.createScene('battle', new BattleScene());
+gameWorld.setSceneActive('battle', true);
+
+// 更新所有World
+worldManager.updateAll();
+```
+
+**适用场景**:
+- SceneManager: 适用于 95% 的游戏（单人游戏、简单多人游戏）
+- WorldManager: 适用于 MMO 服务器、游戏房间系统等需要完全隔离的多世界应用
+
 ### PoolManager
 
 对象池管理器，管理所有对象池：

docs/guide/world-manager.md

@@ -0,0 +1,761 @@
+# WorldManager
+
+WorldManager 是 ECS Framework 提供的高级世界管理器，用于管理多个完全隔离的游戏世界（World）。每个 World 都是独立的 ECS 环境，可以包含多个场景。
+
+## 适用场景
+
+WorldManager 适合以下高级场景：
+- MMO 游戏服务器的多房间管理
+- 游戏大厅系统（每个游戏房间完全隔离）
+- 服务器端的多游戏实例
+- 需要完全隔离的多个游戏环境
+- 需要同时运行多个独立世界的应用
+
+## 特点
+
+- 多 World 管理，每个 World 完全独立
+- 每个 World 可以包含多个 Scene
+- 支持 World 的激活/停用
+- 自动清理空 World
+- World 级别的全局系统
+- 批量操作和查询
+
+## 基本使用
+
+### 初始化
+
+WorldManager 是 Core 的内置服务，通过服务容器获取：
+
+```typescript
+import { Core, WorldManager } from '@esengine/ecs-framework';
+
+// 初始化 Core
+Core.create({ debug: true });
+
+// 从服务容器获取 WorldManager（Core 已自动创建并注册）
+const worldManager = Core.services.resolve(WorldManager);
+```
+
+### 创建 World
+
+```typescript
+// 创建游戏房间 World
+const room1 = worldManager.createWorld('room_001', {
+  name: 'GameRoom_001',
+  maxScenes: 5,
+  debug: true
+});
+
+// 激活 World
+worldManager.setWorldActive('room_001', true);
+
+// 创建更多房间
+const room2 = worldManager.createWorld('room_002', {
+  name: 'GameRoom_002',
+  maxScenes: 5
+});
+
+worldManager.setWorldActive('room_002', true);
+```
+
+### 游戏循环
+
+在游戏循环中更新所有活跃的 World：
+
+```typescript
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);        // 更新全局服务
+  worldManager.updateAll();      // 更新所有活跃的 World
+}
+
+// 启动游戏循环
+let lastTime = 0;
+setInterval(() => {
+  const currentTime = Date.now();
+  const deltaTime = (currentTime - lastTime) / 1000;
+  lastTime = currentTime;
+
+  gameLoop(deltaTime);
+}, 16); // 60 FPS
+```
+
+## World 管理
+
+### 创建 World
+
+```typescript
+// 基本创建
+const world = worldManager.createWorld('worldId');
+
+// 带配置创建
+const world = worldManager.createWorld('worldId', {
+  name: 'MyWorld',
+  maxScenes: 10,
+  autoCleanup: true,
+  debug: true
+});
+```
+
+**配置选项（IWorldConfig）**：
+- `name?: string` - World 名称
+- `maxScenes?: number` - 最大场景数量限制（默认 10）
+- `autoCleanup?: boolean` - 是否自动清理空场景（默认 true）
+- `debug?: boolean` - 是否启用调试模式（默认 false）
+
+### 获取 World
+
+```typescript
+// 通过 ID 获取
+const world = worldManager.getWorld('room_001');
+if (world) {
+  console.log(`World: ${world.name}`);
+}
+
+// 获取所有 World
+const allWorlds = worldManager.getAllWorlds();
+console.log(`共有 ${allWorlds.length} 个 World`);
+
+// 获取所有 World ID
+const worldIds = worldManager.getWorldIds();
+console.log('World 列表:', worldIds);
+
+// 通过名称查找
+const world = worldManager.findWorldByName('GameRoom_001');
+```
+
+### 激活和停用 World
+
+```typescript
+// 激活 World（开始运行和更新）
+worldManager.setWorldActive('room_001', true);
+
+// 停用 World（停止更新但保留数据）
+worldManager.setWorldActive('room_001', false);
+
+// 检查 World 是否激活
+if (worldManager.isWorldActive('room_001')) {
+  console.log('房间正在运行');
+}
+
+// 获取所有活跃的 World
+const activeWorlds = worldManager.getActiveWorlds();
+console.log(`当前有 ${activeWorlds.length} 个活跃 World`);
+```
+
+### 移除 World
+
+```typescript
+// 移除 World（会自动停用并销毁）
+const removed = worldManager.removeWorld('room_001');
+if (removed) {
+  console.log('World 已移除');
+}
+```
+
+## World 中的场景管理
+
+每个 World 可以包含多个 Scene 并独立管理它们的生命周期。
+
+### 创建场景
+
+```typescript
+const world = worldManager.getWorld('room_001');
+if (!world) return;
+
+// 创建场景
+const mainScene = world.createScene('main', new MainScene());
+const uiScene = world.createScene('ui', new UIScene());
+const hudScene = world.createScene('hud', new HUDScene());
+
+// 激活场景
+world.setSceneActive('main', true);
+world.setSceneActive('ui', true);
+world.setSceneActive('hud', false);
+```
+
+### 查询场景
+
+```typescript
+// 获取特定场景
+const mainScene = world.getScene<MainScene>('main');
+if (mainScene) {
+  console.log(`场景名称: ${mainScene.name}`);
+}
+
+// 获取所有场景
+const allScenes = world.getAllScenes();
+console.log(`World 中共有 ${allScenes.length} 个场景`);
+
+// 获取所有场景 ID
+const sceneIds = world.getSceneIds();
+console.log('场景列表:', sceneIds);
+
+// 获取活跃场景数量
+const activeCount = world.getActiveSceneCount();
+console.log(`当前有 ${activeCount} 个活跃场景`);
+
+// 检查场景是否激活
+if (world.isSceneActive('main')) {
+  console.log('主场景正在运行');
+}
+```
+
+### 场景切换
+
+World 支持多场景同时运行，也支持场景切换：
+
+```typescript
+class GameWorld {
+  private world: World;
+
+  constructor(worldManager: WorldManager) {
+    this.world = worldManager.createWorld('game', {
+      name: 'GameWorld',
+      maxScenes: 5
+    });
+
+    // 创建所有场景
+    this.world.createScene('menu', new MenuScene());
+    this.world.createScene('game', new GameScene());
+    this.world.createScene('pause', new PauseScene());
+    this.world.createScene('gameover', new GameOverScene());
+
+    // 激活 World
+    worldManager.setWorldActive('game', true);
+  }
+
+  public showMenu(): void {
+    this.deactivateAllScenes();
+    this.world.setSceneActive('menu', true);
+  }
+
+  public startGame(): void {
+    this.deactivateAllScenes();
+    this.world.setSceneActive('game', true);
+  }
+
+  public pauseGame(): void {
+    // 游戏场景继续存在但停止更新
+    this.world.setSceneActive('game', false);
+    // 显示暂停界面
+    this.world.setSceneActive('pause', true);
+  }
+
+  public resumeGame(): void {
+    this.world.setSceneActive('pause', false);
+    this.world.setSceneActive('game', true);
+  }
+
+  public showGameOver(): void {
+    this.deactivateAllScenes();
+    this.world.setSceneActive('gameover', true);
+  }
+
+  private deactivateAllScenes(): void {
+    const sceneIds = this.world.getSceneIds();
+    sceneIds.forEach(id => this.world.setSceneActive(id, false));
+  }
+}
+```
+
+### 移除场景
+
+```typescript
+// 移除不再需要的场景
+const removed = world.removeScene('oldScene');
+if (removed) {
+  console.log('场景已移除');
+}
+
+// 场景会自动调用 end() 方法进行清理
+```
+
+## 全局系统
+
+World 支持全局系统，这些系统在 World 级别运行，不依赖特定 Scene。
+
+### 定义全局系统
+
+```typescript
+import { IGlobalSystem } from '@esengine/ecs-framework';
+
+// 网络系统（World 级别）
+class NetworkSystem implements IGlobalSystem {
+  readonly name = 'NetworkSystem';
+
+  private connectionId: string;
+
+  constructor(connectionId: string) {
+    this.connectionId = connectionId;
+  }
+
+  initialize(): void {
+    console.log(`网络系统初始化: ${this.connectionId}`);
+    // 建立网络连接
+  }
+
+  update(deltaTime?: number): void {
+    // 处理网络消息，不依赖任何 Scene
+    // 接收和发送网络包
+  }
+
+  destroy(): void {
+    console.log(`网络系统销毁: ${this.connectionId}`);
+    // 关闭网络连接
+  }
+}
+
+// 物理系统（World 级别）
+class PhysicsSystem implements IGlobalSystem {
+  readonly name = 'PhysicsSystem';
+
+  initialize(): void {
+    console.log('物理系统初始化');
+  }
+
+  update(deltaTime?: number): void {
+    // 物理模拟，作用于 World 中所有场景
+  }
+
+  destroy(): void {
+    console.log('物理系统销毁');
+  }
+}
+```
+
+### 使用全局系统
+
+```typescript
+const world = worldManager.getWorld('room_001');
+if (!world) return;
+
+// 添加全局系统
+const networkSystem = world.addGlobalSystem(new NetworkSystem('conn_001'));
+const physicsSystem = world.addGlobalSystem(new PhysicsSystem());
+
+// 获取全局系统
+const network = world.getGlobalSystem(NetworkSystem);
+if (network) {
+  console.log('找到网络系统');
+}
+
+// 移除全局系统
+world.removeGlobalSystem(networkSystem);
+```
+
+## 批量操作
+
+### 更新所有 World
+
+```typescript
+// 更新所有活跃的 World（应该在游戏循环中调用）
+worldManager.updateAll();
+
+// 这会自动更新每个 World 的：
+// 1. 全局系统
+// 2. 所有活跃场景
+```
+
+### 启动和停止
+
+```typescript
+// 启动所有 World
+worldManager.startAll();
+
+// 停止所有 World
+worldManager.stopAll();
+
+// 检查是否正在运行
+if (worldManager.isRunning) {
+  console.log('WorldManager 正在运行');
+}
+```
+
+### 查找 World
+
+```typescript
+// 使用条件查找
+const emptyWorlds = worldManager.findWorlds(world => {
+  return world.sceneCount === 0;
+});
+
+// 查找活跃的 World
+const activeWorlds = worldManager.findWorlds(world => {
+  return world.isActive;
+});
+
+// 查找特定名称的 World
+const world = worldManager.findWorldByName('GameRoom_001');
+```
+
+## 统计和监控
+
+### 获取统计信息
+
+```typescript
+const stats = worldManager.getStats();
+
+console.log(`总 World 数: ${stats.totalWorlds}`);
+console.log(`活跃 World 数: ${stats.activeWorlds}`);
+console.log(`总场景数: ${stats.totalScenes}`);
+console.log(`总实体数: ${stats.totalEntities}`);
+console.log(`总系统数: ${stats.totalSystems}`);
+
+// 查看每个 World 的详细信息
+stats.worlds.forEach(worldInfo => {
+  console.log(`World: ${worldInfo.name}`);
+  console.log(`  场景数: ${worldInfo.sceneCount}`);
+  console.log(`  是否活跃: ${worldInfo.isActive}`);
+});
+```
+
+### 获取详细状态
+
+```typescript
+const status = worldManager.getDetailedStatus();
+
+// 包含所有 World 的详细状态
+status.worlds.forEach(worldStatus => {
+  console.log(`World ID: ${worldStatus.id}`);
+  console.log(`状态:`, worldStatus.status);
+});
+```
+
+## 自动清理
+
+WorldManager 支持自动清理空的 World。
+
+### 配置清理
+
+```typescript
+// 创建带清理配置的 WorldManager
+const worldManager = Core.services.resolve(WorldManager);
+
+// WorldManager 的配置在 Core 中设置：
+// {
+//   maxWorlds: 50,
+//   autoCleanup: true,
+//   cleanupInterval: 30000  // 30 秒
+// }
+```
+
+### 手动清理
+
+```typescript
+// 手动触发清理
+const cleanedCount = worldManager.cleanup();
+console.log(`清理了 ${cleanedCount} 个 World`);
+```
+
+**清理条件**：
+- World 未激活
+- 没有 Scene 或所有 Scene 都是空的
+- 创建时间超过 10 分钟
+
+## API 参考
+
+### WorldManager API
+
+| 方法 | 说明 |
+|------|------|
+| `createWorld(worldId, config?)` | 创建新 World |
+| `removeWorld(worldId)` | 移除 World |
+| `getWorld(worldId)` | 获取 World |
+| `getAllWorlds()` | 获取所有 World |
+| `getWorldIds()` | 获取所有 World ID |
+| `setWorldActive(worldId, active)` | 设置 World 激活状态 |
+| `isWorldActive(worldId)` | 检查 World 是否激活 |
+| `getActiveWorlds()` | 获取所有活跃的 World |
+| `updateAll()` | 更新所有活跃 World |
+| `startAll()` | 启动所有 World |
+| `stopAll()` | 停止所有 World |
+| `findWorlds(predicate)` | 查找满足条件的 World |
+| `findWorldByName(name)` | 根据名称查找 World |
+| `getStats()` | 获取统计信息 |
+| `getDetailedStatus()` | 获取详细状态信息 |
+| `cleanup()` | 清理空 World |
+| `destroy()` | 销毁 WorldManager |
+
+### World API
+
+| 方法 | 说明 |
+|------|------|
+| `createScene(sceneId, sceneInstance?)` | 创建并添加 Scene |
+| `removeScene(sceneId)` | 移除 Scene |
+| `getScene(sceneId)` | 获取 Scene |
+| `getAllScenes()` | 获取所有 Scene |
+| `getSceneIds()` | 获取所有 Scene ID |
+| `setSceneActive(sceneId, active)` | 设置 Scene 激活状态 |
+| `isSceneActive(sceneId)` | 检查 Scene 是否激活 |
+| `getActiveSceneCount()` | 获取活跃 Scene 数量 |
+| `addGlobalSystem(system)` | 添加全局系统 |
+| `removeGlobalSystem(system)` | 移除全局系统 |
+| `getGlobalSystem(type)` | 获取全局系统 |
+| `start()` | 启动 World |
+| `stop()` | 停止 World |
+| `updateGlobalSystems()` | 更新全局系统 |
+| `updateScenes()` | 更新所有激活 Scene |
+| `destroy()` | 销毁 World |
+| `getStatus()` | 获取 World 状态 |
+| `getStats()` | 获取统计信息 |
+
+### 属性
+
+| 属性 | 说明 |
+|------|------|
+| `worldCount` | World 总数 |
+| `activeWorldCount` | 活跃 World 数量 |
+| `isRunning` | 是否正在运行 |
+| `config` | 配置信息 |
+
+## 完整示例
+
+### MMO 游戏房间系统
+
+```typescript
+import { Core, WorldManager, Scene, World } from '@esengine/ecs-framework';
+
+// 初始化
+Core.create({ debug: true });
+const worldManager = Core.services.resolve(WorldManager);
+
+// 房间管理器
+class RoomManager {
+  private worldManager: WorldManager;
+  private rooms: Map<string, World> = new Map();
+
+  constructor(worldManager: WorldManager) {
+    this.worldManager = worldManager;
+  }
+
+  // 创建游戏房间
+  public createRoom(roomId: string, maxPlayers: number): World {
+    const world = this.worldManager.createWorld(roomId, {
+      name: `Room_${roomId}`,
+      maxScenes: 3,
+      debug: true
+    });
+
+    // 创建房间场景
+    world.createScene('lobby', new LobbyScene());
+    world.createScene('game', new GameScene());
+    world.createScene('result', new ResultScene());
+
+    // 添加房间级别的系统
+    world.addGlobalSystem(new NetworkSystem(roomId));
+    world.addGlobalSystem(new RoomLogicSystem(maxPlayers));
+
+    // 激活 World 和初始场景
+    this.worldManager.setWorldActive(roomId, true);
+    world.setSceneActive('lobby', true);
+
+    this.rooms.set(roomId, world);
+    console.log(`房间 ${roomId} 已创建`);
+
+    return world;
+  }
+
+  // 玩家加入房间
+  public joinRoom(roomId: string, playerId: string): boolean {
+    const world = this.rooms.get(roomId);
+    if (!world) {
+      console.log(`房间 ${roomId} 不存在`);
+      return false;
+    }
+
+    // 在大厅场景中创建玩家实体
+    const lobbyScene = world.getScene('lobby');
+    if (lobbyScene) {
+      const player = lobbyScene.createEntity(`Player_${playerId}`);
+      // 添加玩家组件...
+      console.log(`玩家 ${playerId} 加入房间 ${roomId}`);
+      return true;
+    }
+
+    return false;
+  }
+
+  // 开始游戏
+  public startGame(roomId: string): void {
+    const world = this.rooms.get(roomId);
+    if (!world) return;
+
+    // 切换到游戏场景
+    world.setSceneActive('lobby', false);
+    world.setSceneActive('game', true);
+
+    console.log(`房间 ${roomId} 游戏开始`);
+  }
+
+  // 结束游戏
+  public endGame(roomId: string): void {
+    const world = this.rooms.get(roomId);
+    if (!world) return;
+
+    // 切换到结果场景
+    world.setSceneActive('game', false);
+    world.setSceneActive('result', true);
+
+    console.log(`房间 ${roomId} 游戏结束`);
+  }
+
+  // 关闭房间
+  public closeRoom(roomId: string): void {
+    this.worldManager.removeWorld(roomId);
+    this.rooms.delete(roomId);
+    console.log(`房间 ${roomId} 已关闭`);
+  }
+
+  // 获取房间列表
+  public getRoomList(): string[] {
+    return Array.from(this.rooms.keys());
+  }
+
+  // 获取房间统计
+  public getRoomStats(roomId: string) {
+    const world = this.rooms.get(roomId);
+    return world?.getStats();
+  }
+}
+
+// 使用房间管理器
+const roomManager = new RoomManager(worldManager);
+
+// 创建多个游戏房间
+roomManager.createRoom('room_001', 4);
+roomManager.createRoom('room_002', 4);
+roomManager.createRoom('room_003', 2);
+
+// 玩家加入
+roomManager.joinRoom('room_001', 'player_1');
+roomManager.joinRoom('room_001', 'player_2');
+
+// 开始游戏
+roomManager.startGame('room_001');
+
+// 游戏循环
+function gameLoop(deltaTime: number) {
+  Core.update(deltaTime);
+  worldManager.updateAll();  // 更新所有房间
+}
+
+// 定期清理空房间
+setInterval(() => {
+  const stats = worldManager.getStats();
+  console.log(`当前房间数: ${stats.totalWorlds}`);
+  console.log(`活跃房间数: ${stats.activeWorlds}`);
+
+  worldManager.cleanup();
+}, 60000); // 每分钟清理一次
+```
+
+## 最佳实践
+
+### 1. 合理的 World 粒度
+
+```typescript
+// 推荐：每个独立环境一个 World
+const room1 = worldManager.createWorld('room_1');  // 游戏房间1
+const room2 = worldManager.createWorld('room_2');  // 游戏房间2
+
+// 不推荐：过度使用 World
+const world1 = worldManager.createWorld('ui');     // UI 不需要独立 World
+const world2 = worldManager.createWorld('menu');   // 菜单不需要独立 World
+```
+
+### 2. 使用全局系统处理跨场景逻辑
+
+```typescript
+// 推荐：World 级别的系统
+class NetworkSystem implements IGlobalSystem {
+  update() {
+    // 网络处理不依赖场景
+  }
+}
+
+// 不推荐：在每个场景中重复创建
+class GameScene extends Scene {
+  initialize() {
+    this.addSystem(new NetworkSystem());  // 不应该在场景级别
+  }
+}
+```
+
+### 3. 及时清理不用的 World
+
+```typescript
+// 推荐：玩家离开时清理房间
+function onPlayerLeave(roomId: string) {
+  const world = worldManager.getWorld(roomId);
+  if (world && world.sceneCount === 0) {
+    worldManager.removeWorld(roomId);
+  }
+}
+
+// 或使用自动清理
+worldManager.cleanup();
+```
+
+### 4. 监控资源使用
+
+```typescript
+// 定期检查资源使用情况
+setInterval(() => {
+  const stats = worldManager.getStats();
+
+  if (stats.totalWorlds > 100) {
+    console.warn('World 数量过多，考虑清理');
+    worldManager.cleanup();
+  }
+
+  if (stats.totalEntities > 10000) {
+    console.warn('实体数量过多，检查是否有泄漏');
+  }
+}, 30000);
+```
+
+## 与 SceneManager 的对比
+
+| 特性 | SceneManager | WorldManager |
+|------|--------------|--------------|
+| 适用场景 | 95% 的游戏应用 | 高级多世界隔离场景 |
+| 复杂度 | 简单 | 复杂 |
+| 场景数量 | 单场景（可切换） | 多 World，每个 World 多场景 |
+| 场景隔离 | 无（场景切换） | 完全隔离（每个 World 独立） |
+| 性能开销 | 最小 | 较高 |
+| 全局系统 | 无 | 支持（World 级别） |
+| 使用示例 | 单人游戏、移动游戏 | MMO 服务器、游戏房间系统 |
+
+**何时使用 WorldManager**：
+- MMO 游戏服务器（每个房间一个 World）
+- 游戏大厅系统（每个游戏房间完全隔离）
+- 需要运行多个完全独立的游戏实例
+- 服务器端模拟多个游戏世界
+
+**何时使用 SceneManager**：
+- 单人游戏
+- 简单的多人游戏
+- 移动游戏
+- 场景之间需要切换但不需要同时运行
+
+## 架构层次
+
+WorldManager 在 ECS Framework 中的位置：
+
+```
+Core (全局服务)
+  └── WorldManager (世界管理)
+      ├── World 1 (游戏房间1)
+      │   ├── GlobalSystem (全局系统)
+      │   ├── Scene 1 (场景1)
+      │   │   ├── EntitySystem
+      │   │   ├── Entity
+      │   │   └── Component
+      │   └── Scene 2 (场景2)
+      ├── World 2 (游戏房间2)
+      │   ├── GlobalSystem
+      │   └── Scene 1
+      └── World 3 (游戏房间3)
+```
+
+WorldManager 为需要多世界隔离的高级应用提供了强大的管理能力。如果你的应用不需要多世界隔离，建议使用更简单的 [SceneManager](./scene-manager.md)。

package-lock.json

@@ -3559,6 +3559,15 @@
         "url": "https://github.com/sponsors/isaacs"
       }
     },
+    "node_modules/@msgpack/msgpack": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@msgpack/msgpack/-/msgpack-3.1.2.tgz",
+      "integrity": "sha512-JEW4DEtBzfe8HvUYecLU9e6+XJnKDlUAIve8FvPzF3Kzs6Xo/KuZkZJsDH0wJXl/qEZbeeE7edxDNY3kMs39hQ==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 18"
+      }
+    },
     "node_modules/@napi-rs/wasm-runtime": {
       "version": "0.2.4",
       "resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-0.2.4.tgz",
@@ -5220,16 +5229,6 @@
       "dev": true,
       "license": "MIT"
     },
-    "node_modules/@types/msgpack-lite": {
-      "version": "0.1.11",
-      "resolved": "https://registry.npmjs.org/@types/msgpack-lite/-/msgpack-lite-0.1.11.tgz",
-      "integrity": "sha512-cdCZS/gw+jIN22I4SUZUFf1ZZfVv5JM1//Br/MuZcI373sxiy3eSSoiyLu0oz+BPatTbGGGBO5jrcvd0siCdTQ==",
-      "dev": true,
-      "license": "MIT",
-      "dependencies": {
-        "@types/node": "*"
-      }
-    },
     "node_modules/@types/multer": {
       "version": "1.4.13",
       "resolved": "https://registry.npmjs.org/@types/multer/-/multer-1.4.13.tgz",
@@ -7715,12 +7714,6 @@
         "node": ">=0.10.0"
       }
     },
-    "node_modules/event-lite": {
-      "version": "0.1.3",
-      "resolved": "https://registry.npmjs.org/event-lite/-/event-lite-0.1.3.tgz",
-      "integrity": "sha512-8qz9nOz5VeD2z96elrEKD2U433+L3DWdUdDkOINLGOJvx1GsMBbMn0aCeu28y8/e85A6mCigBiFlYMnTBEGlSw==",
-      "license": "MIT"
-    },
     "node_modules/eventemitter3": {
       "version": "4.0.7",
       "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-4.0.7.tgz",
@@ -8672,6 +8665,7 @@
       "version": "1.2.1",
       "resolved": "https://registry.npmjs.org/ieee754/-/ieee754-1.2.1.tgz",
       "integrity": "sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==",
+      "dev": true,
       "funding": [
         {
           "type": "github",
@@ -8861,12 +8855,6 @@
         "node": ">=8"
       }
     },
-    "node_modules/int64-buffer": {
-      "version": "0.1.10",
-      "resolved": "https://registry.npmjs.org/int64-buffer/-/int64-buffer-0.1.10.tgz",
-      "integrity": "sha512-v7cSY1J8ydZ0GyjUHqF+1bshJ6cnEVLo9EnjB8p+4HDRPZc9N5jjmvUV7NvEsqQOKyH0pmIBFWXVQbiS0+OBbA==",
-      "license": "MIT"
-    },
     "node_modules/ip-address": {
       "version": "9.0.5",
       "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-9.0.5.tgz",
@@ -9138,6 +9126,7 @@
       "version": "1.0.0",
       "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
       "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
+      "dev": true,
       "license": "MIT"
     },
     "node_modules/isexe": {
@@ -11543,21 +11532,6 @@
       "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==",
       "dev": true
     },
-    "node_modules/msgpack-lite": {
-      "version": "0.1.26",
-      "resolved": "https://registry.npmjs.org/msgpack-lite/-/msgpack-lite-0.1.26.tgz",
-      "integrity": "sha512-SZ2IxeqZ1oRFGo0xFGbvBJWMp3yLIY9rlIJyxy8CGrwZn1f0ZK4r6jV/AM1r0FZMDUkWkglOk/eeKIL9g77Nxw==",
-      "license": "MIT",
-      "dependencies": {
-        "event-lite": "^0.1.1",
-        "ieee754": "^1.1.8",
-        "int64-buffer": "^0.1.9",
-        "isarray": "^1.0.0"
-      },
-      "bin": {
-        "msgpack": "bin/msgpack"
-      }
-    },
     "node_modules/multimatch": {
       "version": "5.0.0",
       "resolved": "https://registry.npmjs.org/multimatch/-/multimatch-5.0.0.tgz",
@@ -15556,10 +15530,10 @@
     },
     "packages/core": {
       "name": "@esengine/ecs-framework",
-      "version": "2.2.0",
+      "version": "2.2.4",
       "license": "MIT",
       "dependencies": {
-        "msgpack-lite": "^0.1.26",
+        "@msgpack/msgpack": "^3.0.0",
         "tslib": "^2.8.1"
       },
       "devDependencies": {
@@ -15572,7 +15546,6 @@
         "@rollup/plugin-node-resolve": "^16.0.1",
         "@rollup/plugin-terser": "^0.4.4",
         "@types/jest": "^29.5.14",
-        "@types/msgpack-lite": "^0.1.11",
         "@types/node": "^20.19.17",
         "jest": "^29.7.0",
         "jest-environment-jsdom": "^29.7.0",

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esengine/ecs-framework",
-  "version": "2.2.0",
+  "version": "2.2.4",
   "description": "用于Laya、Cocos Creator等JavaScript游戏引擎的高性能ECS框架",
   "main": "bin/index.js",
   "types": "bin/index.d.ts",
@@ -58,7 +58,6 @@
     "@rollup/plugin-node-resolve": "^16.0.1",
     "@rollup/plugin-terser": "^0.4.4",
     "@types/jest": "^29.5.14",
-    "@types/msgpack-lite": "^0.1.11",
     "@types/node": "^20.19.17",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
@@ -78,7 +77,7 @@
     "directory": "packages/core"
   },
   "dependencies": {
-    "msgpack-lite": "^0.1.26",
+    "@msgpack/msgpack": "^3.0.0",
     "tslib": "^2.8.1"
   }
 }

packages/core/src/Core.ts

@@ -13,6 +13,8 @@ import { ServiceContainer } from './Core/ServiceContainer';
 import { PluginManager } from './Core/PluginManager';
 import { IPlugin } from './Core/Plugin';
 import { WorldManager } from './ECS/WorldManager';
+import { DebugConfigService } from './Utils/Debug/DebugConfigService';
+import { createInstance } from './Core/DI/Decorators';
 
 /**
  * 游戏引擎核心类
@@ -202,14 +204,15 @@ export class Core {
 
         // 初始化调试管理器
         if (this._config.debugConfig?.enabled) {
-            // 使用DI容器创建DebugManager（前两个参数从容器解析，config手动传入）
-            const config = this._config.debugConfig;
-            this._debugManager = new DebugManager(
-                this._serviceContainer.resolve(SceneManager),
-                this._serviceContainer.resolve(PerformanceMonitor),
-                config
+            const configService = new DebugConfigService();
+            configService.setConfig(this._config.debugConfig);
+            this._serviceContainer.registerInstance(DebugConfigService, configService);
+
+            this._serviceContainer.registerSingleton(DebugManager, (c) =>
+                createInstance(DebugManager, c)
             );
-            this._serviceContainer.registerInstance(DebugManager, this._debugManager);
+
+            this._debugManager = this._serviceContainer.resolve(DebugManager);
         }
 
         this.initialize();
@@ -248,6 +251,30 @@ export class Core {
         return this._instance._serviceContainer;
     }
 
+    /**
+     * 获取World管理器
+     *
+     * 用于管理多个独立的World实例（高级用户）。
+     *
+     * @returns WorldManager实例
+     * @throws 如果Core实例未创建
+     *
+     * @example
+     * ```typescript
+     * // 创建多个游戏房间
+     * const wm = Core.worldManager;
+     * const room1 = wm.createWorld('room_001');
+     * room1.createScene('game', new GameScene());
+     * room1.start();
+     * ```
+     */
+    public static get worldManager(): WorldManager {
+        if (!this._instance) {
+            throw new Error('Core实例未创建，请先调用Core.create()');
+        }
+        return this._instance._worldManager;
+    }
+
     /**
      * 创建Core实例
      *
@@ -452,13 +479,15 @@ export class Core {
         if (this._instance._debugManager) {
             this._instance._debugManager.updateConfig(config);
         } else {
-            // 使用DI容器创建DebugManager
-            this._instance._debugManager = new DebugManager(
-                this._instance._serviceContainer.resolve(SceneManager),
-                this._instance._serviceContainer.resolve(PerformanceMonitor),
-                config
+            const configService = new DebugConfigService();
+            configService.setConfig(config);
+            this._instance._serviceContainer.registerInstance(DebugConfigService, configService);
+
+            this._instance._serviceContainer.registerSingleton(DebugManager, (c) =>
+                createInstance(DebugManager, c)
             );
-            this._instance._serviceContainer.registerInstance(DebugManager, this._instance._debugManager);
+
+            this._instance._debugManager = this._instance._serviceContainer.resolve(DebugManager);
         }
 
         // 更新Core配置
@@ -629,13 +658,11 @@ export class Core {
         // 更新对象池管理器
         this._poolManager.update();
 
-        // 更新场景
+        // 更新默认场景（通过 SceneManager）
         this._sceneManager.update();
 
-        // 更新调试管理器（基于FPS的数据发送）
-        if (this._debugManager) {
-            this._debugManager.onFrameUpdate(deltaTime);
-        }
+        // 更新额外的 WorldManager
+        this._worldManager.updateAll();
 
         // 结束性能监控
         this._performanceMonitor.endMonitoring('Core.update', frameStartTime);

packages/core/src/Core/DI/Decorators.ts

@@ -35,6 +35,12 @@ export interface InjectableMetadata {
      * 依赖列表
      */
     dependencies: Array<ServiceType<any> | string | symbol>;
+
+    /**
+     * 属性注入映射
+     * key: 属性名, value: 服务类型
+     */
+    properties?: Map<string | symbol, ServiceType<any>>;
 }
 
 /**
@@ -77,10 +83,12 @@ export interface UpdatableMetadata {
  */
 export function Injectable(): ClassDecorator {
     return function <T extends Function>(target: T): T {
-        // 标记为可注入
+        const existing = injectableMetadata.get(target);
+
         injectableMetadata.set(target, {
             injectable: true,
-            dependencies: []
+            dependencies: [],
+            properties: existing?.properties
         });
 
         return target;
@@ -142,20 +150,7 @@ export function Updatable(priority: number = 0): ClassDecorator {
  *
  * 标记构造函数参数需要注入的服务类型
  *
- * @param serviceType 服务类型标识符（类、字符串或Symbol）
- *
- * @example
- * ```typescript
- * @Injectable()
- * class MySystem extends EntitySystem {
- *     constructor(
- *         @Inject(TimeService) private timeService: TimeService,
- *         @Inject(PhysicsService) private physics: PhysicsService
- *     ) {
- *         super();
- *     }
- * }
- * ```
+ * @param serviceType 服务类型标识符
  */
 export function Inject(serviceType: ServiceType<any> | string | symbol): ParameterDecorator {
     return function (target: Object, propertyKey: string | symbol | undefined, parameterIndex: number) {
@@ -171,6 +166,35 @@ export function Inject(serviceType: ServiceType<any> | string | symbol): Paramet
     };
 }
 
+/**
+ * @InjectProperty() 装饰器
+ *
+ * 通过属性装饰器注入依赖
+ *
+ * 注入时机：在构造函数执行后、onInitialize() 调用前完成
+ *
+ * @param serviceType 服务类型
+ */
+export function InjectProperty(serviceType: ServiceType<any>): PropertyDecorator {
+    return function (target: any, propertyKey: string | symbol) {
+        let metadata = injectableMetadata.get(target.constructor);
+
+        if (!metadata) {
+            metadata = {
+                injectable: true,
+                dependencies: []
+            };
+            injectableMetadata.set(target.constructor, metadata);
+        }
+
+        if (!metadata.properties) {
+            metadata.properties = new Map();
+        }
+
+        metadata.properties.set(propertyKey, serviceType);
+    };
+}
+
 /**
  * 检查类是否标记为可注入
  *
@@ -252,6 +276,29 @@ export function createInstance<T>(
     return new constructor(...dependencies);
 }
 
+/**
+ * 为实例注入属性依赖
+ *
+ * @param instance 目标实例
+ * @param container 服务容器
+ */
+export function injectProperties<T>(instance: T, container: ServiceContainer): void {
+    const constructor = (instance as any).constructor;
+    const metadata = getInjectableMetadata(constructor);
+
+    if (!metadata?.properties || metadata.properties.size === 0) {
+        return;
+    }
+
+    for (const [propertyKey, serviceType] of metadata.properties) {
+        const service = container.resolve(serviceType);
+
+        if (service !== null) {
+            (instance as any)[propertyKey] = service;
+        }
+    }
+}
+
 /**
  * 检查类是否标记为可更新
  *

packages/core/src/Core/DI/index.ts

@@ -7,6 +7,7 @@
 export {
     Injectable,
     Inject,
+    InjectProperty,
     Updatable,
     isInjectable,
     getInjectableMetadata,
@@ -14,6 +15,7 @@ export {
     isUpdatable,
     getUpdatableMetadata,
     createInstance,
+    injectProperties,
     registerInjectable
 } from './Decorators';
 

packages/core/src/ECS/Core/ArchetypeSystem.ts

@@ -1,6 +1,6 @@
 import { Entity } from '../Entity';
-import { ComponentType } from './ComponentStorage';
-import { BitMask64Data, BitMask64Utils, ComponentTypeManager } from "../Utils";
+import { ComponentType, ComponentRegistry } from './ComponentStorage';
+import { BitMask64Data, BitMask64Utils } from "../Utils";
 import { BitMaskHashMap } from "../Utils/BitMaskHashMap";
 
 /**
@@ -266,10 +266,18 @@ export class ArchetypeSystem {
     
     /**
      * 生成原型ID
+     * 使用ComponentRegistry确保与Entity.componentMask使用相同的bitIndex
      */
     private generateArchetypeId(componentTypes: ComponentType[]): ArchetypeId {
-        let entityBits = ComponentTypeManager.instance.getEntityBits(componentTypes);
-        return entityBits.getValue();
+        let mask = BitMask64Utils.clone(BitMask64Utils.ZERO);
+        for (const type of componentTypes) {
+            if (!ComponentRegistry.isRegistered(type)) {
+                ComponentRegistry.register(type);
+            }
+            const bitMask = ComponentRegistry.getBitMask(type);
+            BitMask64Utils.orInPlace(mask, bitMask);
+        }
+        return mask;
     }
     
     /**

packages/core/src/ECS/Core/QuerySystem.ts

@@ -5,40 +5,10 @@ import { BitMask64Utils, BitMask64Data } from '../Utils/BigIntCompatibility';
 import { createLogger } from '../../Utils/Logger';
 import { getComponentTypeName } from '../Decorators';
 import { Archetype, ArchetypeSystem } from './ArchetypeSystem';
-import { ComponentTypeManager } from "../Utils";
+import { ReactiveQuery, ReactiveQueryConfig } from './ReactiveQuery';
+import { QueryCondition, QueryConditionType, QueryResult } from './QueryTypes';
 
-/**
- * 查询条件类型
- */
-export enum QueryConditionType {
-    /** 必须包含所有指定组件 */
-    ALL = 'all',
-    /** 必须包含任意一个指定组件 */
-    ANY = 'any',
-    /** 不能包含任何指定组件 */
-    NONE = 'none'
-}
-
-/**
- * 查询条件接口
- */
-export interface QueryCondition {
-    type: QueryConditionType;
-    componentTypes: ComponentType[];
-    mask: BitMask64Data;
-}
-
-/**
- * 实体查询结果接口
- */
-export interface QueryResult {
-    entities: readonly Entity[];
-    count: number;
-    /** 查询执行时间（毫秒） */
-    executionTime: number;
-    /** 是否来自缓存 */
-    fromCache: boolean;
-}
+export { QueryCondition, QueryConditionType, QueryResult };
 
 /**
  * 实体索引结构
@@ -124,15 +94,16 @@ export class QuerySystem {
 
     /**
      * 设置实体列表并重建索引
-     * 
+     *
      * 当实体集合发生大规模变化时调用此方法。
      * 系统将重新构建所有索引以确保查询性能。
-     * 
+     *
      * @param entities 新的实体列表
      */
     public setEntities(entities: Entity[]): void {
         this.entities = entities;
         this.clearQueryCache();
+        this.clearReactiveQueries();
         this.rebuildIndexes();
     }
 
@@ -152,12 +123,14 @@ export class QuerySystem {
 
             this.archetypeSystem.addEntity(entity);
 
+            // 通知响应式查询
+            this.notifyReactiveQueriesEntityAdded(entity);
 
             // 只有在非延迟模式下才立即清理缓存
             if (!deferCacheClear) {
                 this.clearQueryCache();
             }
-            
+
             // 更新版本号
             this._version++;
         }
@@ -235,14 +208,24 @@ export class QuerySystem {
     public removeEntity(entity: Entity): void {
         const index = this.entities.indexOf(entity);
         if (index !== -1) {
+            const componentTypes: ComponentType[] = [];
+            for (const component of entity.components) {
+                componentTypes.push(component.constructor as ComponentType);
+            }
+
             this.entities.splice(index, 1);
             this.removeEntityFromIndexes(entity);
 
             this.archetypeSystem.removeEntity(entity);
 
+            if (componentTypes.length > 0) {
+                this.notifyReactiveQueriesEntityRemoved(entity, componentTypes);
+            } else {
+                this.notifyReactiveQueriesEntityRemovedFallback(entity);
+            }
+
             this.clearQueryCache();
 
-            // 更新版本号
             this._version++;
         }
     }
@@ -270,6 +253,9 @@ export class QuerySystem {
         // 重新添加实体到索引（基于新的组件状态）
         this.addEntityToIndexes(entity);
 
+        // 通知响应式查询
+        this.notifyReactiveQueriesEntityChanged(entity);
+
         // 清理查询缓存，因为实体组件状态已改变
         this.clearQueryCache();
 
@@ -357,13 +343,13 @@ export class QuerySystem {
 
     /**
      * 查询包含所有指定组件的实体
-     * 
+     *
      * 返回同时包含所有指定组件类型的实体列表。
-     * 系统会自动选择最高效的查询策略，包括索引查找和缓存机制。
-     * 
+     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
+     *
      * @param componentTypes 要查询的组件类型列表
      * @returns 查询结果，包含匹配的实体和性能信息
-     * 
+     *
      * @example
      * ```typescript
      * // 查询同时具有位置和速度组件的实体
@@ -375,38 +361,20 @@ export class QuerySystem {
         const startTime = performance.now();
         this.queryStats.totalQueries++;
 
-        // 生成缓存键
-        const cacheKey = this.generateCacheKey('all', componentTypes);
+        // 使用内部响应式查询作为智能缓存
+        const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.ALL, componentTypes);
 
-        // 检查缓存
-        const cached = this.getFromCache(cacheKey);
-        if (cached) {
-            this.queryStats.cacheHits++;
-            return {
-                entities: cached,
-                count: cached.length,
-                executionTime: performance.now() - startTime,
-                fromCache: true
-            };
-        }
+        // 从响应式查询获取结果(永远是最新的)
+        const entities = reactiveQuery.getEntities();
 
-        this.queryStats.archetypeHits++;
-        const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'AND');
-
-        const entities: Entity[] = [];
-        for (const archetype of archetypeResult.archetypes) {
-            for (const entity of archetype.entities) {
-                entities.push(entity);
-            }
-        }
-
-        this.addToCache(cacheKey, entities);
+        // 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
+        this.queryStats.cacheHits++;
 
         return {
             entities,
             count: entities.length,
             executionTime: performance.now() - startTime,
-            fromCache: false
+            fromCache: true
         };
     }
 
@@ -436,13 +404,13 @@ export class QuerySystem {
 
     /**
      * 查询包含任意指定组件的实体
-     * 
+     *
      * 返回包含任意一个指定组件类型的实体列表。
-     * 使用集合合并算法确保高效的查询性能。
-     * 
+     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
+     *
      * @param componentTypes 要查询的组件类型列表
      * @returns 查询结果，包含匹配的实体和性能信息
-     * 
+     *
      * @example
      * ```typescript
      * // 查询具有武器或护甲组件的实体
@@ -454,52 +422,32 @@ export class QuerySystem {
         const startTime = performance.now();
         this.queryStats.totalQueries++;
 
-        const cacheKey = this.generateCacheKey('any', componentTypes);
+        // 使用内部响应式查询作为智能缓存
+        const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.ANY, componentTypes);
 
-        // 检查缓存
-        const cached = this.getFromCache(cacheKey);
-        if (cached) {
-            this.queryStats.cacheHits++;
-            return {
-                entities: cached,
-                count: cached.length,
-                executionTime: performance.now() - startTime,
-                fromCache: true
-            };
-        }
+        // 从响应式查询获取结果(永远是最新的)
+        const entities = reactiveQuery.getEntities();
 
-        this.queryStats.archetypeHits++;
-        const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'OR');
-
-        const entities = this.acquireResultArray();
-        for (const archetype of archetypeResult.archetypes) {
-            for (const entity of archetype.entities) {
-                entities.push(entity);
-            }
-        }
-
-        const frozenEntities = [...entities];
-        this.releaseResultArray(entities);
-
-        this.addToCache(cacheKey, frozenEntities);
+        // 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
+        this.queryStats.cacheHits++;
 
         return {
-            entities: frozenEntities,
-            count: frozenEntities.length,
+            entities,
+            count: entities.length,
             executionTime: performance.now() - startTime,
-            fromCache: false
+            fromCache: true
         };
     }
 
     /**
      * 查询不包含任何指定组件的实体
-     * 
+     *
      * 返回不包含任何指定组件类型的实体列表。
-     * 适用于排除特定类型实体的查询场景。
-     * 
+     * 内部使用响应式查询作为智能缓存,自动跟踪实体变化,性能更优。
+     *
      * @param componentTypes 要排除的组件类型列表
      * @returns 查询结果，包含匹配的实体和性能信息
-     * 
+     *
      * @example
      * ```typescript
      * // 查询不具有AI和玩家控制组件的实体（如静态物体）
@@ -511,32 +459,20 @@ export class QuerySystem {
         const startTime = performance.now();
         this.queryStats.totalQueries++;
 
-        const cacheKey = this.generateCacheKey('none', componentTypes);
+        // 使用内部响应式查询作为智能缓存
+        const reactiveQuery = this.getOrCreateReactiveQuery(QueryConditionType.NONE, componentTypes);
 
-        // 检查缓存
-        const cached = this.getFromCache(cacheKey);
-        if (cached) {
-            this.queryStats.cacheHits++;
-            return {
-                entities: cached,
-                count: cached.length,
-                executionTime: performance.now() - startTime,
-                fromCache: true
-            };
-        }
+        // 从响应式查询获取结果(永远是最新的)
+        const entities = reactiveQuery.getEntities();
 
-        const mask = this.createComponentMask(componentTypes);
-        const entities = this.entities.filter(entity =>
-            BitMask64Utils.hasNone(entity.componentMask, mask)
-        );
-
-        this.addToCache(cacheKey, entities);
+        // 统计为缓存命中(响应式查询本质上是永不过期的智能缓存)
+        this.queryStats.cacheHits++;
 
         return {
             entities,
             count: entities.length,
             executionTime: performance.now() - startTime,
-            fromCache: false
+            fromCache: true
         };
     }
 
@@ -759,6 +695,20 @@ export class QuerySystem {
         this.componentMaskCache.clear();
     }
 
+    /**
+     * 清除所有响应式查询
+     *
+     * 销毁所有响应式查询实例并清理索引
+     * 通常在setEntities时调用以确保缓存一致性
+     */
+    private clearReactiveQueries(): void {
+        for (const query of this._reactiveQueries.values()) {
+            query.dispose();
+        }
+        this._reactiveQueries.clear();
+        this._reactiveQueriesByComponent.clear();
+    }
+
     /**
      * 高效的缓存键生成
      */
@@ -782,11 +732,111 @@ export class QuerySystem {
 
     /**
      * 清理查询缓存
-     * 
+     *
      * 用于外部调用清理缓存，通常在批量操作后使用。
+     * 注意:此方法也会清理响应式查询缓存
      */
     public clearCache(): void {
         this.clearQueryCache();
+        this.clearReactiveQueries();
+    }
+
+    /**
+     * 创建响应式查询
+     *
+     * 响应式查询会自动跟踪实体/组件的变化,并通过事件通知订阅者。
+     * 适合需要实时响应实体变化的场景(如UI更新、AI系统等)。
+     *
+     * @param componentTypes 查询的组件类型列表
+     * @param config 可选的查询配置
+     * @returns 响应式查询实例
+     *
+     * @example
+     * ```typescript
+     * const query = querySystem.createReactiveQuery([Position, Velocity], {
+     *     enableBatchMode: true,
+     *     batchDelay: 16
+     * });
+     *
+     * query.subscribe((change) => {
+     *     if (change.type === ReactiveQueryChangeType.ADDED) {
+     *         console.log('新实体:', change.entity);
+     *     }
+     * });
+     * ```
+     */
+    public createReactiveQuery(
+        componentTypes: ComponentType[],
+        config?: ReactiveQueryConfig
+    ): ReactiveQuery {
+        if (!componentTypes || componentTypes.length === 0) {
+            throw new Error('组件类型列表不能为空');
+        }
+
+        const mask = this.createComponentMask(componentTypes);
+        const condition: QueryCondition = {
+            type: QueryConditionType.ALL,
+            componentTypes,
+            mask
+        };
+
+        const query = new ReactiveQuery(condition, config);
+
+        const initialEntities = this.executeTraditionalQuery(
+            QueryConditionType.ALL,
+            componentTypes
+        );
+        query.initializeWith(initialEntities);
+
+        const cacheKey = this.generateCacheKey('all', componentTypes);
+        this._reactiveQueries.set(cacheKey, query);
+
+        for (const type of componentTypes) {
+            let queries = this._reactiveQueriesByComponent.get(type);
+            if (!queries) {
+                queries = new Set();
+                this._reactiveQueriesByComponent.set(type, queries);
+            }
+            queries.add(query);
+        }
+
+        return query;
+    }
+
+    /**
+     * 销毁响应式查询
+     *
+     * 清理查询占用的资源,包括监听器和实体引用。
+     * 销毁后的查询不应再被使用。
+     *
+     * @param query 要销毁的响应式查询
+     *
+     * @example
+     * ```typescript
+     * const query = querySystem.createReactiveQuery([Position, Velocity]);
+     * // ... 使用查询
+     * querySystem.destroyReactiveQuery(query);
+     * ```
+     */
+    public destroyReactiveQuery(query: ReactiveQuery): void {
+        if (!query) {
+            return;
+        }
+
+        const cacheKey = query.id;
+        this._reactiveQueries.delete(cacheKey);
+
+        for (const type of query.condition.componentTypes) {
+            const queries = this._reactiveQueriesByComponent.get(type);
+            if (queries) {
+                queries.delete(query);
+                if (queries.size === 0) {
+                    this._reactiveQueriesByComponent.delete(type);
+                }
+            }
+        }
+
+        query.dispose();
     }
 
     /**
@@ -794,6 +844,7 @@ export class QuerySystem {
      *
      * 根据组件类型列表生成对应的位掩码。
      * 使用缓存避免重复计算。
+     * 注意:必须使用ComponentRegistry来确保与Entity.componentMask使用相同的bitIndex
      *
      * @param componentTypes 组件类型列表
      * @returns 生成的位掩码
@@ -810,10 +861,20 @@ export class QuerySystem {
             return cached;
         }
 
-        let mask = ComponentTypeManager.instance.getEntityBits(componentTypes);
+        // 使用ComponentRegistry而不是ComponentTypeManager,确保bitIndex一致
+        let mask = BitMask64Utils.clone(BitMask64Utils.ZERO);
+        for (const type of componentTypes) {
+            // 确保组件已注册
+            if (!ComponentRegistry.isRegistered(type)) {
+                ComponentRegistry.register(type);
+            }
+            const bitMask = ComponentRegistry.getBitMask(type);
+            BitMask64Utils.orInPlace(mask, bitMask);
+        }
+
         // 缓存结果
-        this.componentMaskCache.set(cacheKey, mask.getValue());
-        return mask.getValue();
+        this.componentMaskCache.set(cacheKey, mask);
+        return mask;
     }
 
     /**
@@ -882,7 +943,7 @@ export class QuerySystem {
                 }))
             },
             cacheStats: {
-                size: this.queryCache.size,
+                size: this._reactiveQueries.size,
                 hitRate: this.queryStats.totalQueries > 0 ?
                     (this.queryStats.cacheHits / this.queryStats.totalQueries * 100).toFixed(2) + '%' : '0%'
             }
@@ -891,12 +952,230 @@ export class QuerySystem {
 
     /**
      * 获取实体所属的原型信息
-     * 
+     *
      * @param entity 要查询的实体
      */
     public getEntityArchetype(entity: Entity): Archetype | undefined {
         return this.archetypeSystem.getEntityArchetype(entity);
     }
+
+    // ============================================================
+    // 响应式查询支持(内部智能缓存)
+    // ============================================================
+
+    /**
+     * 响应式查询集合(内部使用,作为智能缓存)
+     * 传统查询API(queryAll/queryAny/queryNone)内部自动使用响应式查询优化性能
+     */
+    private _reactiveQueries: Map<string, ReactiveQuery> = new Map();
+
+    /**
+     * 按组件类型索引的响应式查询
+     * 用于快速定位哪些查询关心某个组件类型
+     */
+    private _reactiveQueriesByComponent: Map<ComponentType, Set<ReactiveQuery>> = new Map();
+
+    /**
+     * 获取或创建内部响应式查询(作为智能缓存)
+     *
+     * @param queryType 查询类型
+     * @param componentTypes 组件类型列表
+     * @returns 响应式查询实例
+     */
+    private getOrCreateReactiveQuery(
+        queryType: QueryConditionType,
+        componentTypes: ComponentType[]
+    ): ReactiveQuery {
+        // 生成缓存键(与传统缓存键格式一致)
+        const cacheKey = this.generateCacheKey(queryType, componentTypes);
+
+        // 检查是否已存在响应式查询
+        let reactiveQuery = this._reactiveQueries.get(cacheKey);
+
+        if (!reactiveQuery) {
+            // 创建查询条件
+            const mask = this.createComponentMask(componentTypes);
+            const condition: QueryCondition = {
+                type: queryType,
+                componentTypes,
+                mask
+            };
+
+            // 创建响应式查询(禁用批量模式,保持实时性)
+            reactiveQuery = new ReactiveQuery(condition, {
+                enableBatchMode: false,
+                debug: false
+            });
+
+            // 初始化查询结果(使用传统方式获取初始数据)
+            const initialEntities = this.executeTraditionalQuery(queryType, componentTypes);
+            reactiveQuery.initializeWith(initialEntities);
+
+            // 注册响应式查询
+            this._reactiveQueries.set(cacheKey, reactiveQuery);
+
+            // 为每个组件类型注册索引
+            for (const type of componentTypes) {
+                let queries = this._reactiveQueriesByComponent.get(type);
+                if (!queries) {
+                    queries = new Set();
+                    this._reactiveQueriesByComponent.set(type, queries);
+                }
+                queries.add(reactiveQuery);
+            }
+
+            this._logger.debug(`创建内部响应式查询缓存: ${cacheKey}`);
+        }
+
+        return reactiveQuery;
+    }
+
+    /**
+     * 执行传统查询(内部使用,用于响应式查询初始化)
+     *
+     * @param queryType 查询类型
+     * @param componentTypes 组件类型列表
+     * @returns 匹配的实体列表
+     */
+    private executeTraditionalQuery(
+        queryType: QueryConditionType,
+        componentTypes: ComponentType[]
+    ): Entity[] {
+        switch (queryType) {
+            case QueryConditionType.ALL: {
+                const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'AND');
+                const entities: Entity[] = [];
+                for (const archetype of archetypeResult.archetypes) {
+                    for (const entity of archetype.entities) {
+                        entities.push(entity);
+                    }
+                }
+                return entities;
+            }
+            case QueryConditionType.ANY: {
+                const archetypeResult = this.archetypeSystem.queryArchetypes(componentTypes, 'OR');
+                const entities: Entity[] = [];
+                for (const archetype of archetypeResult.archetypes) {
+                    for (const entity of archetype.entities) {
+                        entities.push(entity);
+                    }
+                }
+                return entities;
+            }
+            case QueryConditionType.NONE: {
+                const mask = this.createComponentMask(componentTypes);
+                return this.entities.filter(entity =>
+                    BitMask64Utils.hasNone(entity.componentMask, mask)
+                );
+            }
+            default:
+                return [];
+        }
+    }
+
+    /**
+     * 通知所有响应式查询实体已添加
+     *
+     * 使用组件类型索引,只通知关心该实体组件的查询
+     *
+     * @param entity 添加的实体
+     */
+    private notifyReactiveQueriesEntityAdded(entity: Entity): void {
+        if (this._reactiveQueries.size === 0) return;
+
+        const notified = new Set<ReactiveQuery>();
+
+        for (const component of entity.components) {
+            const componentType = component.constructor as ComponentType;
+            const queries = this._reactiveQueriesByComponent.get(componentType);
+
+            if (queries) {
+                for (const query of queries) {
+                    if (!notified.has(query)) {
+                        query.notifyEntityAdded(entity);
+                        notified.add(query);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 通知响应式查询实体已移除
+     *
+     * 使用组件类型索引,只通知关心该实体组件的查询
+     *
+     * @param entity 移除的实体
+     * @param componentTypes 实体移除前的组件类型列表
+     */
+    private notifyReactiveQueriesEntityRemoved(entity: Entity, componentTypes: ComponentType[]): void {
+        if (this._reactiveQueries.size === 0) return;
+
+        const notified = new Set<ReactiveQuery>();
+
+        for (const componentType of componentTypes) {
+            const queries = this._reactiveQueriesByComponent.get(componentType);
+            if (queries) {
+                for (const query of queries) {
+                    if (!notified.has(query)) {
+                        query.notifyEntityRemoved(entity);
+                        notified.add(query);
+                    }
+                }
+            }
+        }
+    }
+
+    /**
+     * 通知响应式查询实体已移除(后备方案)
+     *
+     * 当实体已经清空组件时使用,通知所有查询
+     *
+     * @param entity 移除的实体
+     */
+    private notifyReactiveQueriesEntityRemovedFallback(entity: Entity): void {
+        if (this._reactiveQueries.size === 0) return;
+
+        for (const query of this._reactiveQueries.values()) {
+            query.notifyEntityRemoved(entity);
+        }
+    }
+
+    /**
+     * 通知响应式查询实体已变化
+     *
+     * 使用混合策略:
+     * 1. 首先通知关心实体当前组件的查询
+     * 2. 然后通知所有其他查询(包括那些可能因为组件移除而不再匹配的查询)
+     *
+     * @param entity 变化的实体
+     */
+    private notifyReactiveQueriesEntityChanged(entity: Entity): void {
+        if (this._reactiveQueries.size === 0) {
+            return;
+        }
+
+        const notified = new Set<ReactiveQuery>();
+
+        for (const component of entity.components) {
+            const componentType = component.constructor as ComponentType;
+            const queries = this._reactiveQueriesByComponent.get(componentType);
+            if (queries) {
+                for (const query of queries) {
+                    if (!notified.has(query)) {
+                        query.notifyEntityChanged(entity);
+                        notified.add(query);
+                    }
+                }
+            }
+        }
+
+        for (const query of this._reactiveQueries.values()) {
+            if (!notified.has(query)) {
+                query.notifyEntityChanged(entity);
+            }
+        }
+    }
 }
 
 /**

packages/core/src/ECS/Core/QueryTypes.ts

@@ -0,0 +1,36 @@
+import { ComponentType } from './ComponentStorage';
+import { BitMask64Data } from '../Utils/BigIntCompatibility';
+import { Entity } from '../Entity';
+
+/**
+ * 查询条件类型
+ */
+export enum QueryConditionType {
+    /** 必须包含所有指定组件 */
+    ALL = 'all',
+    /** 必须包含任意一个指定组件 */
+    ANY = 'any',
+    /** 不能包含任何指定组件 */
+    NONE = 'none'
+}
+
+/**
+ * 查询条件接口
+ */
+export interface QueryCondition {
+    type: QueryConditionType;
+    componentTypes: ComponentType[];
+    mask: BitMask64Data;
+}
+
+/**
+ * 实体查询结果接口
+ */
+export interface QueryResult {
+    entities: readonly Entity[];
+    count: number;
+    /** 查询执行时间（毫秒） */
+    executionTime: number;
+    /** 是否来自缓存 */
+    fromCache: boolean;
+}

packages/core/src/ECS/Core/ReactiveQuery.ts

@@ -0,0 +1,475 @@
+import { Entity } from '../Entity';
+import { QueryCondition, QueryConditionType } from './QueryTypes';
+import { BitMask64Utils } from '../Utils/BigIntCompatibility';
+import { createLogger } from '../../Utils/Logger';
+
+const logger = createLogger('ReactiveQuery');
+
+/**
+ * 响应式查询变化类型
+ */
+export enum ReactiveQueryChangeType {
+    /** 实体添加到查询结果 */
+    ADDED = 'added',
+    /** 实体从查询结果移除 */
+    REMOVED = 'removed',
+    /** 查询结果批量更新 */
+    BATCH_UPDATE = 'batch_update'
+}
+
+/**
+ * 响应式查询变化事件
+ */
+export interface ReactiveQueryChange {
+    /** 变化类型 */
+    type: ReactiveQueryChangeType;
+    /** 变化的实体 */
+    entity?: Entity;
+    /** 批量变化的实体 */
+    entities?: readonly Entity[];
+    /** 新增的实体列表(仅batch_update时有效) */
+    added?: readonly Entity[];
+    /** 移除的实体列表(仅batch_update时有效) */
+    removed?: readonly Entity[];
+}
+
+/**
+ * 响应式查询监听器
+ */
+export type ReactiveQueryListener = (change: ReactiveQueryChange) => void;
+
+/**
+ * 响应式查询配置
+ */
+export interface ReactiveQueryConfig {
+    /** 是否启用批量模式(减少通知频率) */
+    enableBatchMode?: boolean;
+    /** 批量模式的延迟时间(毫秒) */
+    batchDelay?: number;
+    /** 调试模式 */
+    debug?: boolean;
+}
+
+/**
+ * 响应式查询类
+ *
+ * 提供基于事件驱动的实体查询机制,只在实体/组件真正变化时触发通知。
+ *
+ * 核心特性:
+ * - Event-driven: 基于事件的增量更新
+ * - 精确通知: 只通知真正匹配的变化
+ * - 性能优化: 避免每帧重复查询
+ *
+ * @example
+ * ```typescript
+ * // 创建响应式查询
+ * const query = new ReactiveQuery(querySystem, {
+ *     type: QueryConditionType.ALL,
+ *     componentTypes: [Position, Velocity],
+ *     mask: createMask([Position, Velocity])
+ * });
+ *
+ * // 订阅变化
+ * query.subscribe((change) => {
+ *     if (change.type === ReactiveQueryChangeType.ADDED) {
+ *         console.log('新实体:', change.entity);
+ *     }
+ * });
+ *
+ * // 获取当前结果
+ * const entities = query.getEntities();
+ * ```
+ */
+export class ReactiveQuery {
+    /** 当前查询结果 */
+    private _entities: Entity[] = [];
+
+    /** 实体ID集合,用于快速查找 */
+    private _entityIdSet: Set<number> = new Set();
+
+    /** 查询条件 */
+    private readonly _condition: QueryCondition;
+
+    /** 监听器列表 */
+    private _listeners: ReactiveQueryListener[] = [];
+
+    /** 配置 */
+    private readonly _config: ReactiveQueryConfig;
+
+    /** 批量变化缓存 */
+    private _batchChanges: {
+        added: Entity[];
+        removed: Entity[];
+        timer: ReturnType<typeof setTimeout> | null;
+    };
+
+    /** 查询ID(用于调试) */
+    private readonly _id: string;
+
+    /** 是否已激活 */
+    private _active: boolean = true;
+
+    constructor(condition: QueryCondition, config: ReactiveQueryConfig = {}) {
+        this._condition = condition;
+        this._config = {
+            enableBatchMode: config.enableBatchMode ?? true,
+            batchDelay: config.batchDelay ?? 16, // 默认一帧
+            debug: config.debug ?? false
+        };
+
+        this._id = this.generateQueryId();
+
+        this._batchChanges = {
+            added: [],
+            removed: [],
+            timer: null
+        };
+
+        if (this._config.debug) {
+            logger.debug(`创建ReactiveQuery: ${this._id}`);
+        }
+    }
+
+    /**
+     * 生成查询ID
+     */
+    private generateQueryId(): string {
+        const typeStr = this._condition.type;
+        const componentsStr = this._condition.componentTypes
+            .map(t => t.name)
+            .sort()
+            .join(',');
+        return `${typeStr}:${componentsStr}`;
+    }
+
+    /**
+     * 订阅查询变化
+     *
+     * @param listener 监听器函数
+     * @returns 取消订阅的函数
+     */
+    public subscribe(listener: ReactiveQueryListener): () => void {
+        if (!this._active) {
+            throw new Error(`Cannot subscribe to disposed ReactiveQuery ${this._id}`);
+        }
+
+        if (typeof listener !== 'function') {
+            throw new TypeError('Listener must be a function');
+        }
+
+        this._listeners.push(listener);
+
+        if (this._config.debug) {
+            logger.debug(`订阅ReactiveQuery: ${this._id}, 监听器数量: ${this._listeners.length}`);
+        }
+
+        return () => {
+            const index = this._listeners.indexOf(listener);
+            if (index !== -1) {
+                this._listeners.splice(index, 1);
+            }
+        };
+    }
+
+    /**
+     * 取消所有订阅
+     */
+    public unsubscribeAll(): void {
+        this._listeners.length = 0;
+    }
+
+    /**
+     * 获取当前查询结果
+     */
+    public getEntities(): readonly Entity[] {
+        return this._entities;
+    }
+
+    /**
+     * 获取查询结果数量
+     */
+    public get count(): number {
+        return this._entities.length;
+    }
+
+    /**
+     * 检查实体是否匹配查询条件
+     *
+     * @param entity 要检查的实体
+     * @returns 是否匹配
+     */
+    public matches(entity: Entity): boolean {
+        const entityMask = entity.componentMask;
+
+        switch (this._condition.type) {
+            case QueryConditionType.ALL:
+                return BitMask64Utils.hasAll(entityMask, this._condition.mask);
+            case QueryConditionType.ANY:
+                return BitMask64Utils.hasAny(entityMask, this._condition.mask);
+            case QueryConditionType.NONE:
+                return BitMask64Utils.hasNone(entityMask, this._condition.mask);
+            default:
+                return false;
+        }
+    }
+
+    /**
+     * 通知实体添加
+     *
+     * 当Scene中添加实体时调用
+     *
+     * @param entity 添加的实体
+     */
+    public notifyEntityAdded(entity: Entity): void {
+        if (!this._active) return;
+
+        // 检查实体是否匹配查询条件
+        if (!this.matches(entity)) {
+            return;
+        }
+
+        // 检查是否已存在
+        if (this._entityIdSet.has(entity.id)) {
+            return;
+        }
+
+        // 添加到结果集
+        this._entities.push(entity);
+        this._entityIdSet.add(entity.id);
+
+        // 通知监听器
+        if (this._config.enableBatchMode) {
+            this.addToBatch('added', entity);
+        } else {
+            this.notifyListeners({
+                type: ReactiveQueryChangeType.ADDED,
+                entity
+            });
+        }
+
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 实体添加 ${entity.name}(${entity.id})`);
+        }
+    }
+
+    /**
+     * 通知实体移除
+     *
+     * 当Scene中移除实体时调用
+     *
+     * @param entity 移除的实体
+     */
+    public notifyEntityRemoved(entity: Entity): void {
+        if (!this._active) return;
+
+        // 检查是否在结果集中
+        if (!this._entityIdSet.has(entity.id)) {
+            return;
+        }
+
+        // 从结果集移除
+        const index = this._entities.indexOf(entity);
+        if (index !== -1) {
+            this._entities.splice(index, 1);
+        }
+        this._entityIdSet.delete(entity.id);
+
+        // 通知监听器
+        if (this._config.enableBatchMode) {
+            this.addToBatch('removed', entity);
+        } else {
+            this.notifyListeners({
+                type: ReactiveQueryChangeType.REMOVED,
+                entity
+            });
+        }
+
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 实体移除 ${entity.name}(${entity.id})`);
+        }
+    }
+
+    /**
+     * 通知实体组件变化
+     *
+     * 当实体的组件发生变化时调用
+     *
+     * @param entity 变化的实体
+     */
+    public notifyEntityChanged(entity: Entity): void {
+        if (!this._active) return;
+
+        const wasMatching = this._entityIdSet.has(entity.id);
+        const isMatching = this.matches(entity);
+
+        if (wasMatching && !isMatching) {
+            // 实体不再匹配,从结果集移除
+            this.notifyEntityRemoved(entity);
+        } else if (!wasMatching && isMatching) {
+            // 实体现在匹配,添加到结果集
+            this.notifyEntityAdded(entity);
+        }
+    }
+
+    /**
+     * 批量初始化查询结果
+     *
+     * @param entities 初始实体列表
+     */
+    public initializeWith(entities: readonly Entity[]): void {
+        // 清空现有结果
+        this._entities.length = 0;
+        this._entityIdSet.clear();
+
+        // 筛选匹配的实体
+        for (const entity of entities) {
+            if (this.matches(entity)) {
+                this._entities.push(entity);
+                this._entityIdSet.add(entity.id);
+            }
+        }
+
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 初始化 ${this._entities.length} 个实体`);
+        }
+    }
+
+    /**
+     * 添加到批量变化缓存
+     */
+    private addToBatch(type: 'added' | 'removed', entity: Entity): void {
+        if (type === 'added') {
+            this._batchChanges.added.push(entity);
+        } else {
+            this._batchChanges.removed.push(entity);
+        }
+
+        // 启动批量通知定时器
+        if (this._batchChanges.timer === null) {
+            this._batchChanges.timer = setTimeout(() => {
+                this.flushBatchChanges();
+            }, this._config.batchDelay);
+        }
+    }
+
+    /**
+     * 刷新批量变化
+     */
+    private flushBatchChanges(): void {
+        if (this._batchChanges.added.length === 0 && this._batchChanges.removed.length === 0) {
+            this._batchChanges.timer = null;
+            return;
+        }
+
+        const added = [...this._batchChanges.added];
+        const removed = [...this._batchChanges.removed];
+
+        // 清空缓存
+        this._batchChanges.added.length = 0;
+        this._batchChanges.removed.length = 0;
+        this._batchChanges.timer = null;
+
+        // 通知监听器
+        this.notifyListeners({
+            type: ReactiveQueryChangeType.BATCH_UPDATE,
+            added,
+            removed,
+            entities: this._entities
+        });
+
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 批量更新 +${added.length} -${removed.length}`);
+        }
+    }
+
+    /**
+     * 通知所有监听器
+     */
+    private notifyListeners(change: ReactiveQueryChange): void {
+        const listeners = [...this._listeners];
+
+        for (const listener of listeners) {
+            try {
+                listener(change);
+            } catch (error) {
+                logger.error(`ReactiveQuery ${this._id}: 监听器执行出错`, error);
+            }
+        }
+    }
+
+    /**
+     * 暂停响应式查询
+     *
+     * 暂停后不再响应实体变化,但可以继续获取当前结果
+     */
+    public pause(): void {
+        this._active = false;
+
+        // 清空批量变化缓存
+        if (this._batchChanges.timer !== null) {
+            clearTimeout(this._batchChanges.timer);
+            this._batchChanges.timer = null;
+        }
+        this._batchChanges.added.length = 0;
+        this._batchChanges.removed.length = 0;
+    }
+
+    /**
+     * 恢复响应式查询
+     */
+    public resume(): void {
+        this._active = true;
+    }
+
+    /**
+     * 销毁响应式查询
+     *
+     * 释放所有资源,清空监听器和结果集
+     */
+    public dispose(): void {
+        if (this._batchChanges.timer !== null) {
+            clearTimeout(this._batchChanges.timer);
+            this._batchChanges.timer = null;
+        }
+
+        this._batchChanges.added.length = 0;
+        this._batchChanges.removed.length = 0;
+
+        this._active = false;
+        this.unsubscribeAll();
+        this._entities.length = 0;
+        this._entityIdSet.clear();
+
+        if (this._config.debug) {
+            logger.debug(`ReactiveQuery ${this._id}: 已销毁`);
+        }
+    }
+
+    /**
+     * 获取查询条件
+     */
+    public get condition(): QueryCondition {
+        return this._condition;
+    }
+
+    /**
+     * 获取查询ID
+     */
+    public get id(): string {
+        return this._id;
+    }
+
+    /**
+     * 检查是否激活
+     */
+    public get active(): boolean {
+        return this._active;
+    }
+
+    /**
+     * 获取监听器数量
+     */
+    public get listenerCount(): number {
+        return this._listeners.length;
+    }
+}

packages/core/src/ECS/Decorators/TypeDecorators.ts

@@ -75,7 +75,7 @@ export interface SystemMetadata {
  * @ECSSystem('Physics', { updateOrder: 10 })
  * class PhysicsSystem extends EntitySystem {
  *     constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
- *         super(Matcher.of(Transform, RigidBody));
+ *         super(Matcher.empty().all(Transform, RigidBody));
  *     }
  * }
  * ```

packages/core/src/ECS/Scene.ts

@@ -15,7 +15,7 @@ import { IncrementalSerializer, IncrementalSnapshot, IncrementalSerializationOpt
 import { ComponentPoolManager } from './Core/ComponentPool';
 import { PerformanceMonitor } from '../Utils/PerformanceMonitor';
 import { ServiceContainer, type ServiceType } from '../Core/ServiceContainer';
-import { createInstance, isInjectable } from '../Core/DI';
+import { createInstance, isInjectable, injectProperties } from '../Core/DI';
 import { isUpdatable, getUpdatableMetadata } from '../Core/DI/Decorators';
 import { createLogger } from '../Utils/Logger';
 
@@ -527,7 +527,7 @@ export class Scene implements IScene {
      * @Injectable()
      * class PhysicsSystem extends EntitySystem {
      *     constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
-     *         super(Matcher.of(Transform));
+     *         super(Matcher.empty().all(Transform));
      *     }
      * }
      * scene.addEntityProcessor(PhysicsSystem);
@@ -547,7 +547,9 @@ export class Scene implements IScene {
             constructor = systemTypeOrInstance;
 
             if (this._services.isRegistered(constructor)) {
-                return this._services.resolve(constructor) as T;
+                const existingSystem = this._services.resolve(constructor) as T;
+                this.logger.debug(`System ${constructor.name} already registered, returning existing instance`);
+                return existingSystem;
             }
 
             if (isInjectable(constructor)) {
@@ -560,7 +562,17 @@ export class Scene implements IScene {
             constructor = system.constructor;
 
             if (this._services.isRegistered(constructor)) {
-                return system;
+                const existingSystem = this._services.resolve(constructor);
+                if (existingSystem === system) {
+                    this.logger.debug(`System ${constructor.name} instance already registered, returning it`);
+                    return system;
+                } else {
+                    this.logger.warn(
+                        `Attempting to register a different instance of ${constructor.name}, ` +
+                        `but type is already registered. Returning existing instance.`
+                    );
+                    return existingSystem as T;
+                }
             }
         }
 
@@ -578,8 +590,12 @@ export class Scene implements IScene {
 
         this._services.registerInstance(constructor, system);
 
+        injectProperties(system, this._services);
+
         system.initialize();
 
+        this.logger.debug(`System ${constructor.name} registered and initialized`);
+
         return system;
     }
 
@@ -597,7 +613,7 @@ export class Scene implements IScene {
      * @Injectable()
      * @ECSSystem('Collision', { updateOrder: 5 })
      * class CollisionSystem extends EntitySystem implements IService {
-     *     constructor() { super(Matcher.of(Collider)); }
+     *     constructor() { super(Matcher.empty().all(Collider)); }
      *     dispose() {}
      * }
      *
@@ -605,7 +621,7 @@ export class Scene implements IScene {
      * @ECSSystem('Physics', { updateOrder: 10 })
      * class PhysicsSystem extends EntitySystem implements IService {
      *     constructor(@Inject(CollisionSystem) private collision: CollisionSystem) {
-     *         super(Matcher.of(Transform, RigidBody));
+     *         super(Matcher.empty().all(Transform, RigidBody));
      *     }
      *     dispose() {}
      * }
@@ -742,10 +758,10 @@ export class Scene implements IScene {
     /**
      * 序列化场景
      *
-     * 将场景及其所有实体、组件序列化为JSON字符串或二进制Buffer
+     * 将场景及其所有实体、组件序列化为JSON字符串或二进制Uint8Array
      *
      * @param options 序列化选项
-     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     * @returns 序列化后的数据（JSON字符串或二进制Uint8Array）
      *
      * @example
      * ```typescript
@@ -761,7 +777,7 @@ export class Scene implements IScene {
      * });
      * ```
      */
-    public serialize(options?: SceneSerializationOptions): string | Buffer {
+    public serialize(options?: SceneSerializationOptions): string | Uint8Array {
         return SceneSerializer.serialize(this, options);
     }
 
@@ -770,7 +786,7 @@ export class Scene implements IScene {
      *
      * 从序列化数据恢复场景状态
      *
-     * @param saveData 序列化的数据（JSON字符串或二进制Buffer）
+     * @param saveData 序列化的数据（JSON字符串或二进制Uint8Array）
      * @param options 反序列化选项
      *
      * @example
@@ -786,7 +802,7 @@ export class Scene implements IScene {
      * });
      * ```
      */
-    public deserialize(saveData: string | Buffer, options?: SceneDeserializationOptions): void {
+    public deserialize(saveData: string | Uint8Array, options?: SceneDeserializationOptions): void {
         SceneSerializer.deserialize(this, saveData, options);
     }
 
@@ -858,7 +874,7 @@ export class Scene implements IScene {
     /**
      * 应用增量变更到场景
      *
-     * @param incremental 增量快照数据（IncrementalSnapshot对象、JSON字符串或二进制Buffer）
+     * @param incremental 增量快照数据（IncrementalSnapshot对象、JSON字符串或二进制Uint8Array）
      * @param componentRegistry 组件类型注册表（可选，默认使用全局注册表）
      *
      * @example
@@ -870,21 +886,20 @@ export class Scene implements IScene {
      * const jsonData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'json' });
      * scene.applyIncremental(jsonData);
      *
-     * // 从二进制Buffer应用
+     * // 从二进制Uint8Array应用
      * const binaryData = IncrementalSerializer.serializeIncremental(snapshot, { format: 'binary' });
      * scene.applyIncremental(binaryData);
      * ```
      */
     public applyIncremental(
-        incremental: IncrementalSnapshot | string | Buffer,
+        incremental: IncrementalSnapshot | string | Uint8Array,
         componentRegistry?: Map<string, any>
     ): void {
         const isSerializedData = typeof incremental === 'string' ||
-            (typeof Buffer !== 'undefined' && Buffer.isBuffer(incremental)) ||
             incremental instanceof Uint8Array;
 
         const snapshot = isSerializedData
-            ? IncrementalSerializer.deserializeIncremental(incremental as string | Buffer)
+            ? IncrementalSerializer.deserializeIncremental(incremental as string | Uint8Array)
             : incremental as IncrementalSnapshot;
 
         const registry = componentRegistry || ComponentRegistry.getAllComponentNames() as Map<string, any>;

packages/core/src/ECS/SceneManager.ts

@@ -3,6 +3,7 @@ import { ECSFluentAPI, createECSAPI } from './Core/FluentAPI';
 import { Time } from '../Utils/Time';
 import { createLogger } from '../Utils/Logger';
 import type { IService } from '../Core/ServiceContainer';
+import { World } from './World';
 
 /**
  * 单场景管理器
@@ -48,9 +49,9 @@ import type { IService } from '../Core/ServiceContainer';
  */
 export class SceneManager implements IService {
     /**
-     * 当前活跃场景
+     * 内部默认World
      */
-    private _currentScene: IScene | null = null;
+    private _defaultWorld: World;
 
     /**
      * 待切换的下一个场景（延迟切换用）
@@ -72,6 +73,16 @@ export class SceneManager implements IService {
      */
     private _onSceneChangedCallback?: () => void;
 
+    /**
+     * 默认场景ID
+     */
+    private static readonly DEFAULT_SCENE_ID = '__main__';
+
+    constructor() {
+        this._defaultWorld = new World({ name: '__default__' });
+        this._defaultWorld.start();
+    }
+
     /**
      * 设置场景切换回调
      *
@@ -97,16 +108,12 @@ export class SceneManager implements IService {
      * ```
      */
     public setScene<T extends IScene>(scene: T): T {
-        // 结束旧场景
-        if (this._currentScene) {
-            this._logger.info(`Ending scene: ${this._currentScene.name}`);
-            this._currentScene.end();
-        }
+        // 移除旧场景
+        this._defaultWorld.removeAllScenes();
 
-        // 设置并初始化新场景
-        this._currentScene = scene;
-        this._currentScene.initialize();
-        this._currentScene.begin();
+        // 通过 World 创建新场景
+        this._defaultWorld.createScene(SceneManager.DEFAULT_SCENE_ID, scene);
+        this._defaultWorld.setSceneActive(SceneManager.DEFAULT_SCENE_ID, true);
 
         // 重建ECS API
         if (scene.querySystem && scene.eventSystem) {
@@ -160,7 +167,7 @@ export class SceneManager implements IService {
      * @returns 当前场景实例，如果没有场景则返回null
      */
     public get currentScene(): IScene | null {
-        return this._currentScene;
+        return this._defaultWorld.getScene(SceneManager.DEFAULT_SCENE_ID);
     }
 
     /**
@@ -207,10 +214,9 @@ export class SceneManager implements IService {
             this._nextScene = null;
         }
 
-        // 更新当前场景
-        if (this._currentScene) {
-            this._currentScene.update();
-        }
+        // 通过 World 统一更新
+        this._defaultWorld.updateGlobalSystems();
+        this._defaultWorld.updateScenes();
     }
 
     /**
@@ -220,12 +226,9 @@ export class SceneManager implements IService {
      * 通常在应用程序关闭时调用。
      */
     public destroy(): void {
-        if (this._currentScene) {
-            this._logger.info(`Destroying scene: ${this._currentScene.name}`);
-            this._currentScene.end();
-            this._currentScene = null;
-        }
+        this._logger.info('SceneManager destroying');
 
+        this._defaultWorld.destroy();
         this._nextScene = null;
         this._ecsAPI = null;
 
@@ -238,7 +241,7 @@ export class SceneManager implements IService {
      * @returns 如果有活跃场景返回true，否则返回false
      */
     public get hasScene(): boolean {
-        return this._currentScene !== null;
+        return this._defaultWorld.getScene(SceneManager.DEFAULT_SCENE_ID) !== null;
     }
 
     /**

packages/core/src/ECS/Serialization/IncrementalSerializer.ts

@@ -11,7 +11,7 @@ import { Component } from '../Component';
 import { ComponentSerializer, SerializedComponent } from './ComponentSerializer';
 import { SerializedEntity } from './EntitySerializer';
 import { ComponentType } from '../Core/ComponentStorage';
-import * as msgpack from 'msgpack-lite';
+import { encode, decode } from '@msgpack/msgpack';
 
 /**
  * 变更操作类型
@@ -609,7 +609,7 @@ export class IncrementalSerializer {
      *
      * @param incremental 增量快照
      * @param options 序列化选项
-     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     * @returns 序列化后的数据（JSON字符串或二进制Uint8Array）
      *
      * @example
      * ```typescript
@@ -631,7 +631,7 @@ export class IncrementalSerializer {
     public static serializeIncremental(
         incremental: IncrementalSnapshot,
         options?: { format?: IncrementalSerializationFormat; pretty?: boolean }
-    ): string | Buffer {
+    ): string | Uint8Array {
         const opts = {
             format: 'json' as IncrementalSerializationFormat,
             pretty: false,
@@ -639,7 +639,7 @@ export class IncrementalSerializer {
         };
 
         if (opts.format === 'binary') {
-            return msgpack.encode(incremental);
+            return encode(incremental);
         } else {
             return opts.pretty
                 ? JSON.stringify(incremental, null, 2)
@@ -650,7 +650,7 @@ export class IncrementalSerializer {
     /**
      * 反序列化增量快照
      *
-     * @param data 序列化的数据（JSON字符串或二进制Buffer）
+     * @param data 序列化的数据（JSON字符串或二进制Uint8Array）
      * @returns 增量快照
      *
      * @example
@@ -662,13 +662,13 @@ export class IncrementalSerializer {
      * const snapshot = IncrementalSerializer.deserializeIncremental(buffer);
      * ```
      */
-    public static deserializeIncremental(data: string | Buffer): IncrementalSnapshot {
+    public static deserializeIncremental(data: string | Uint8Array): IncrementalSnapshot {
         if (typeof data === 'string') {
             // JSON格式
             return JSON.parse(data);
         } else {
             // 二进制格式（MessagePack）
-            return msgpack.decode(data);
+            return decode(data) as IncrementalSnapshot;
         }
     }
 

packages/core/src/ECS/Serialization/SceneSerializer.ts

@@ -11,7 +11,7 @@ import { ComponentType, ComponentRegistry } from '../Core/ComponentStorage';
 import { EntitySerializer, SerializedEntity } from './EntitySerializer';
 import { getComponentTypeName } from '../Decorators';
 import { getSerializationMetadata } from './SerializationDecorators';
-import * as msgpack from 'msgpack-lite';
+import { encode, decode } from '@msgpack/msgpack';
 
 /**
  * 场景序列化格式
@@ -154,9 +154,9 @@ export class SceneSerializer {
      *
      * @param scene 要序列化的场景
      * @param options 序列化选项
-     * @returns 序列化后的数据（JSON字符串或二进制Buffer）
+     * @returns 序列化后的数据（JSON字符串或二进制Uint8Array）
      */
-    public static serialize(scene: IScene, options?: SceneSerializationOptions): string | Buffer {
+    public static serialize(scene: IScene, options?: SceneSerializationOptions): string | Uint8Array {
         const opts: SceneSerializationOptions = {
             systems: false,
             format: 'json',
@@ -207,7 +207,7 @@ export class SceneSerializer {
                 : JSON.stringify(serializedScene);
         } else {
             // 二进制格式（使用 MessagePack）
-            return msgpack.encode(serializedScene);
+            return encode(serializedScene);
         }
     }
 
@@ -215,12 +215,12 @@ export class SceneSerializer {
      * 反序列化场景
      *
      * @param scene 目标场景
-     * @param saveData 序列化的数据（JSON字符串或二进制Buffer）
+     * @param saveData 序列化的数据（JSON字符串或二进制Uint8Array）
      * @param options 反序列化选项
      */
     public static deserialize(
         scene: IScene,
-        saveData: string | Buffer,
+        saveData: string | Uint8Array,
         options?: SceneDeserializationOptions
     ): void {
         const opts: SceneDeserializationOptions = {
@@ -237,7 +237,7 @@ export class SceneSerializer {
                 serializedScene = JSON.parse(saveData);
             } else {
                 // 二进制格式（MessagePack）
-                serializedScene = msgpack.decode(saveData);
+                serializedScene = decode(saveData) as SerializedScene;
             }
         } catch (error) {
             throw new Error(`Failed to parse save data: ${error}`);

packages/core/src/ECS/Systems/EntitySystem.ts

@@ -36,7 +36,7 @@ interface EventListenerRecord {
  * // 传统方式
  * class MovementSystem extends EntitySystem {
  *     constructor() {
- *         super(Matcher.of(Transform, Velocity));
+ *         super(Matcher.empty().all(Transform, Velocity));
  *     }
  *
  *     protected process(entities: readonly Entity[]): void {
@@ -51,7 +51,7 @@ interface EventListenerRecord {
  * // 类型安全方式
  * class MovementSystem extends EntitySystem<[typeof Transform, typeof Velocity]> {
  *     constructor() {
- *         super(Matcher.of(Transform, Velocity));
+ *         super(Matcher.empty().all(Transform, Velocity));
  *     }
  *
  *     protected process(entities: readonly Entity[]): void {
@@ -555,6 +555,7 @@ export abstract class EntitySystem<
         try {
             this.onBegin();
             // 查询实体并存储到帧缓存中
+            // 响应式查询会自动维护最新的实体列表，updateEntityTracking会在检测到变化时invalidate
             this._entityCache.frame = this.queryEntities();
             entityCount = this._entityCache.frame.length;
 

packages/core/src/ECS/Utils/ComponentTypeManager.ts

@@ -1,101 +0,0 @@
-import { Bits } from './Bits';
-import { getComponentTypeName } from '../Decorators';
-import { ComponentType } from "../../Types";
-
-/**
- * 组件类型管理器
- * 负责管理组件类型的注册和ID分配
- * 支持无限数量的组件类型（通过自动扩展 BitMask）
- */
-export class ComponentTypeManager {
-    private static _instance: ComponentTypeManager;
-    private _componentTypes = new Map<Function, number>();
-    private _typeNames = new Map<number, string>();
-    private _nextTypeId = 0;
-
-    /**
-     * 获取单例实例
-     */
-    public static get instance(): ComponentTypeManager {
-        if (!ComponentTypeManager._instance) {
-            ComponentTypeManager._instance = new ComponentTypeManager();
-        }
-        return ComponentTypeManager._instance;
-    }
-
-    private constructor() {}
-
-    /**
-     * 获取组件类型的ID
-     * @param componentType 组件类型构造函数
-     * @returns 组件类型ID
-     */
-    public getTypeId(componentType: ComponentType): number {
-        let typeId = this._componentTypes.get(componentType);
-
-        if (typeId === undefined) {
-            typeId = this._nextTypeId++;
-            this._componentTypes.set(componentType, typeId);
-            this._typeNames.set(typeId, getComponentTypeName(componentType));
-        }
-
-        return typeId;
-    }
-
-    /**
-     * 获取组件类型名称
-     * @param typeId 组件类型ID
-     * @returns 组件类型名称
-     */
-    public getTypeName(typeId: number): string {
-        return this._typeNames.get(typeId) || 'Unknown';
-    }
-
-    /**
-     * 创建包含指定组件类型的Bits对象
-     * @param componentTypes 组件类型构造函数数组
-     * @returns Bits对象
-     */
-    public createBits(...componentTypes: ComponentType[]): Bits {
-        const bits = new Bits();
-        
-        for (const componentType of componentTypes) {
-            const typeId = this.getTypeId(componentType);
-            bits.set(typeId);
-        }
-        
-        return bits;
-    }
-
-    /**
-     * 获取实体的组件位掩码
-     * @param components 组件数组
-     * @returns Bits对象
-     */
-    public getEntityBits(components: ComponentType[]): Bits {
-        const bits = new Bits();
-        
-        for (const component of components) {
-            const typeId = this.getTypeId(component);
-            bits.set(typeId);
-        }
-        
-        return bits;
-    }
-
-    /**
-     * 重置管理器（主要用于测试）
-     */
-    public reset(): void {
-        this._componentTypes.clear();
-        this._typeNames.clear();
-        this._nextTypeId = 0;
-    }
-
-    /**
-     * 获取已注册的组件类型数量
-     */
-    public get registeredTypeCount(): number {
-        return this._componentTypes.size;
-    }
-} 

packages/core/src/ECS/Utils/index.ts

@@ -4,7 +4,6 @@ export { EntityProcessorList } from './EntityProcessorList';
 export { IdentifierPool } from './IdentifierPool';
 export { Matcher } from './Matcher';
 export { Bits } from './Bits';
-export { ComponentTypeManager } from './ComponentTypeManager';
 export { BitMask64Utils, BitMask64Data } from './BigIntCompatibility';
 export { SparseSet } from './SparseSet';
 export { ComponentSparseSet } from './ComponentSparseSet';

packages/core/src/ECS/World.ts

@@ -183,6 +183,17 @@ export class World {
         return Array.from(this._scenes.values());
     }
 
+    /**
+     * 移除所有Scene
+     */
+    public removeAllScenes(): void {
+        const sceneIds = Array.from(this._scenes.keys());
+        for (const sceneId of sceneIds) {
+            this.removeScene(sceneId);
+        }
+        logger.info(`从World '${this.name}' 中移除所有Scene`);
+    }
+
     /**
      * 设置Scene激活状态
      */

packages/core/src/ECS/index.ts

@@ -15,4 +15,6 @@ export * from './Core/Storage';
 export * from './Core/StorageDecorators';
 export * from './Serialization';
 export { ReferenceTracker, getSceneByEntityId } from './Core/ReferenceTracker';
-export type { EntityRefRecord } from './Core/ReferenceTracker'; 
+export type { EntityRefRecord } from './Core/ReferenceTracker';
+export { ReactiveQuery, ReactiveQueryChangeType } from './Core/ReactiveQuery';
+export type { ReactiveQueryChange, ReactiveQueryListener, ReactiveQueryConfig } from './Core/ReactiveQuery'; 

packages/core/src/Utils/Debug/DebugConfigService.ts

@@ -0,0 +1,45 @@
+import { IECSDebugConfig } from '../../Types';
+import { Injectable } from '../../Core/DI/Decorators';
+import type { IService } from '../../Core/ServiceContainer';
+
+/**
+ * 调试配置服务
+ *
+ * 管理调试系统的配置信息
+ */
+@Injectable()
+export class DebugConfigService implements IService {
+    private _config: IECSDebugConfig;
+
+    constructor() {
+        this._config = {
+            enabled: false,
+            websocketUrl: '',
+            debugFrameRate: 30,
+            autoReconnect: true,
+            channels: {
+                entities: true,
+                systems: true,
+                performance: true,
+                components: true,
+                scenes: true
+            }
+        };
+    }
+
+    public setConfig(config: IECSDebugConfig): void {
+        this._config = config;
+    }
+
+    public getConfig(): IECSDebugConfig {
+        return this._config;
+    }
+
+    public isEnabled(): boolean {
+        return this._config.enabled;
+    }
+
+    dispose(): void {
+        // 清理资源
+    }
+}

packages/core/src/Utils/Debug/DebugManager.ts

@@ -10,17 +10,20 @@ import { ComponentPoolManager } from '../../ECS/Core/ComponentPool';
 import { Pool } from '../../Utils/Pool';
 import { getComponentInstanceTypeName, getSystemInstanceTypeName } from '../../ECS/Decorators';
 import type { IService } from '../../Core/ServiceContainer';
+import type { IUpdatable } from '../../Types/IUpdatable';
 import { SceneManager } from '../../ECS/SceneManager';
 import { PerformanceMonitor } from '../PerformanceMonitor';
+import { Injectable, Inject, Updatable } from '../../Core/DI/Decorators';
+import { DebugConfigService } from './DebugConfigService';
 
 /**
  * 调试管理器
  *
  * 整合所有调试数据收集器，负责收集和发送调试数据
- *
- * 通过构造函数接收SceneManager和PerformanceMonitor，避免直接依赖Core实例
  */
-export class DebugManager implements IService {
+@Injectable()
+@Updatable()
+export class DebugManager implements IService, IUpdatable {
     private config: IECSDebugConfig;
     private webSocketManager: WebSocketManager;
     private entityCollector: EntityDataCollector;
@@ -36,18 +39,12 @@ export class DebugManager implements IService {
     private sendInterval: number;
     private isRunning: boolean = false;
 
-    /**
-     * 构造调试管理器
-     * @param sceneManager 场景管理器
-     * @param performanceMonitor 性能监控器
-     * @param config 调试配置
-     */
     constructor(
-        sceneManager: SceneManager,
-        performanceMonitor: PerformanceMonitor,
-        config: IECSDebugConfig
+        @Inject(SceneManager) sceneManager: SceneManager,
+        @Inject(PerformanceMonitor) performanceMonitor: PerformanceMonitor,
+        @Inject(DebugConfigService) configService: DebugConfigService
     ) {
-        this.config = config;
+        this.config = configService.getConfig();
         this.sceneManager = sceneManager;
         this.performanceMonitor = performanceMonitor;
 
@@ -60,15 +57,15 @@ export class DebugManager implements IService {
 
         // 初始化WebSocket管理器
         this.webSocketManager = new WebSocketManager(
-            config.websocketUrl,
-            config.autoReconnect !== false
+            this.config.websocketUrl,
+            this.config.autoReconnect !== false
         );
 
         // 设置消息处理回调
         this.webSocketManager.setMessageHandler(this.handleMessage.bind(this));
 
         // 计算发送间隔（基于帧率）
-        const debugFrameRate = config.debugFrameRate || 30;
+        const debugFrameRate = this.config.debugFrameRate || 30;
         this.sendInterval = 1000 / debugFrameRate;
 
         this.start();
@@ -116,16 +113,12 @@ export class DebugManager implements IService {
         }
     }
 
-    /**
-     * 帧更新回调
-     */
-    public onFrameUpdate(deltaTime: number): void {
+    public update(deltaTime?: number): void {
         if (!this.isRunning || !this.config.enabled) return;
 
         this.frameCounter++;
         const currentTime = Date.now();
 
-        // 基于配置的帧率发送数据
         if (currentTime - this.lastSendTime >= this.sendInterval) {
             this.sendDebugData();
             this.lastSendTime = currentTime;

packages/core/src/Utils/Debug/EntityDataCollector.ts

@@ -1,7 +1,6 @@
 import { IEntityDebugData } from '../../Types';
 import { Entity } from '../../ECS/Entity';
 import { Component } from '../../ECS/Component';
-import { ComponentTypeManager } from '../../ECS/Utils/ComponentTypeManager';
 import { getComponentInstanceTypeName, getSystemInstanceTypeName } from '../../ECS/Decorators';
 import { IScene } from '../../ECS/IScene';
 
@@ -722,20 +721,7 @@ export class EntityDataCollector {
         properties: Record<string, any>;
     }> {
         return components.map((component: Component) => {
-            let typeName = getComponentInstanceTypeName(component);
-            
-            if (!typeName || typeName === 'Object' || typeName === 'Function') {
-                try {
-                    const typeManager = ComponentTypeManager.instance;
-                    const componentType = component.constructor as any;
-                    const typeId = typeManager.getTypeId(componentType);
-                    typeName = typeManager.getTypeName(typeId);
-                } catch (error) {
-                    typeName = 'UnknownComponent';
-                }
-            }
-            
-            // 提取实际的组件属性
+            const typeName = getComponentInstanceTypeName(component);
             const properties: Record<string, any> = {};
             
             try {

packages/core/src/Utils/Debug/index.ts

@@ -4,4 +4,5 @@ export { PerformanceDataCollector } from './PerformanceDataCollector';
 export { ComponentDataCollector } from './ComponentDataCollector';
 export { SceneDataCollector } from './SceneDataCollector';
 export { WebSocketManager } from './WebSocketManager';
-export { DebugManager } from './DebugManager';
+export { DebugManager } from './DebugManager';
+export { DebugConfigService } from './DebugConfigService';

packages/core/tests/DebugManager.test.ts

@@ -0,0 +1,668 @@
+import { Core } from '../src/Core';
+import { Scene } from '../src/ECS/Scene';
+import { DebugManager } from '../src/Utils/Debug/DebugManager';
+import { DebugConfigService } from '../src/Utils/Debug/DebugConfigService';
+import { IECSDebugConfig } from '../src/Types';
+import { createLogger } from '../src/Utils/Logger';
+
+const logger = createLogger('DebugManagerTest');
+
+class TestScene extends Scene {
+    public initializeCalled = false;
+
+    public override initialize(): void {
+        this.initializeCalled = true;
+    }
+
+    public override begin(): void {
+    }
+
+    public override end(): void {
+    }
+}
+
+describe('DebugManager DI Architecture Tests', () => {
+    let originalConsoleWarn: typeof console.warn;
+    let originalConsoleError: typeof console.error;
+
+    beforeEach(() => {
+        (Core as any)._instance = null;
+        originalConsoleWarn = console.warn;
+        originalConsoleError = console.error;
+        console.warn = jest.fn();
+        console.error = jest.fn();
+    });
+
+    afterEach(() => {
+        console.warn = originalConsoleWarn;
+        console.error = originalConsoleError;
+        if (Core.Instance) {
+            Core.destroy();
+        }
+    });
+
+    describe('DebugConfigService - Configuration Service', () => {
+        test('should create with default configuration', () => {
+            const configService = new DebugConfigService();
+            const config = configService.getConfig();
+
+            expect(config).toBeDefined();
+            expect(config.enabled).toBe(false);
+            expect(config.websocketUrl).toBe('');
+            expect(config.debugFrameRate).toBe(30);
+            expect(config.autoReconnect).toBe(true);
+            expect(config.channels).toBeDefined();
+        });
+
+        test('should set and get configuration', () => {
+            const configService = new DebugConfigService();
+            const newConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 60,
+                autoReconnect: false,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            configService.setConfig(newConfig);
+            const retrievedConfig = configService.getConfig();
+
+            expect(retrievedConfig).toEqual(newConfig);
+            expect(retrievedConfig.enabled).toBe(true);
+            expect(retrievedConfig.websocketUrl).toBe('ws://localhost:9229');
+            expect(retrievedConfig.debugFrameRate).toBe(60);
+        });
+
+        test('should return correct enabled status', () => {
+            const configService = new DebugConfigService();
+            expect(configService.isEnabled()).toBe(false);
+
+            configService.setConfig({
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            });
+
+            expect(configService.isEnabled()).toBe(true);
+        });
+
+        test('should implement dispose method', () => {
+            const configService = new DebugConfigService();
+            expect(() => configService.dispose()).not.toThrow();
+        });
+    });
+
+    describe('DebugManager - DI Initialization', () => {
+        test('should initialize DebugManager through DI when debug config is enabled', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({
+                debug: true,
+                debugConfig: debugConfig
+            });
+
+            expect((core as any)._debugManager).toBeDefined();
+            expect((core as any)._debugManager).toBeInstanceOf(DebugManager);
+        });
+
+        test('should not create DebugManager when debug config is disabled', () => {
+            const core = Core.create({
+                debug: true,
+                debugConfig: {
+                    enabled: false,
+                    websocketUrl: '',
+                    debugFrameRate: 30,
+                    autoReconnect: true,
+                    channels: {
+                        entities: true,
+                        systems: true,
+                        performance: true,
+                        components: true,
+                        scenes: true
+                    }
+                }
+            });
+
+            expect((core as any)._debugManager).toBeUndefined();
+        });
+
+        test('should not create DebugManager when no debug config provided', () => {
+            const core = Core.create({ debug: true });
+            expect((core as any)._debugManager).toBeUndefined();
+        });
+
+        test('should register DebugConfigService in ServiceContainer', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({
+                debug: true,
+                debugConfig: debugConfig
+            });
+
+            const configService = Core.services.resolve(DebugConfigService);
+            expect(configService).toBeDefined();
+            expect(configService).toBeInstanceOf(DebugConfigService);
+        });
+
+        test('should inject all dependencies correctly', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({
+                debug: true,
+                debugConfig: debugConfig
+            });
+
+            const debugManager = (core as any)._debugManager as DebugManager;
+            expect(debugManager).toBeDefined();
+
+            const sceneManager = (debugManager as any).sceneManager;
+            const performanceMonitor = (debugManager as any).performanceMonitor;
+            const config = (debugManager as any).config;
+
+            expect(sceneManager).toBeDefined();
+            expect(performanceMonitor).toBeDefined();
+            expect(config).toBeDefined();
+            expect(config.enabled).toBe(true);
+            expect(config.websocketUrl).toBe('ws://localhost:9229');
+        });
+    });
+
+    describe('Core.enableDebug - Runtime Activation', () => {
+        test('should enable debug at runtime', () => {
+            const core = Core.create({ debug: true });
+            expect(Core.isDebugEnabled).toBe(false);
+
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.enableDebug(debugConfig);
+
+            expect(Core.isDebugEnabled).toBe(true);
+            expect((core as any)._debugManager).toBeDefined();
+        });
+
+        test('should create DebugConfigService when enabling debug at runtime', () => {
+            Core.create({ debug: true });
+
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.enableDebug(debugConfig);
+
+            const configService = Core.services.resolve(DebugConfigService);
+            expect(configService).toBeDefined();
+            expect(configService.getConfig()).toEqual(debugConfig);
+        });
+
+        test('should update existing DebugManager config when already enabled', () => {
+            const initialConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: initialConfig });
+
+            const updatedConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:8080',
+                debugFrameRate: 60,
+                autoReconnect: false,
+                channels: {
+                    entities: false,
+                    systems: true,
+                    performance: true,
+                    components: false,
+                    scenes: true
+                }
+            };
+
+            Core.enableDebug(updatedConfig);
+
+            expect(Core.isDebugEnabled).toBe(true);
+            const debugManager = (Core.Instance as any)._debugManager;
+            expect(debugManager).toBeDefined();
+        });
+
+        test('should show warning when enabling debug without Core instance', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.enableDebug(debugConfig);
+
+            expect(console.warn).toHaveBeenCalledWith(
+                expect.stringContaining('Core实例未创建，请先调用Core.create()')
+            );
+        });
+    });
+
+    describe('Core.disableDebug', () => {
+        test('should disable debug functionality', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+            expect(Core.isDebugEnabled).toBe(true);
+
+            Core.disableDebug();
+
+            expect(Core.isDebugEnabled).toBe(false);
+            expect((Core.Instance as any)._debugManager).toBeUndefined();
+        });
+
+        test('should handle disabling when Core instance does not exist', () => {
+            expect(() => Core.disableDebug()).not.toThrow();
+        });
+
+        test('should handle disabling when debug was never enabled', () => {
+            Core.create({ debug: true });
+            expect(() => Core.disableDebug()).not.toThrow();
+        });
+    });
+
+    describe('DebugManager - Auto Update Integration', () => {
+        test('should be registered as updatable service', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+
+            const serviceContainer = (Core.Instance as any)._serviceContainer;
+            const updatableCount = serviceContainer.getUpdatableCount();
+
+            expect(updatableCount).toBeGreaterThan(0);
+        });
+
+        test('should be updated during Core.update cycle', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (core as any)._debugManager as DebugManager;
+            const updateSpy = jest.spyOn(debugManager, 'update');
+
+            Core.update(0.016);
+
+            expect(updateSpy).toHaveBeenCalledWith(0.016);
+        });
+    });
+
+    describe('DebugManager - Scene Integration', () => {
+        test('should respond to scene changes', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (core as any)._debugManager as DebugManager;
+            const sceneChangeSpy = jest.spyOn(debugManager, 'onSceneChanged');
+
+            const testScene = new TestScene();
+            Core.setScene(testScene);
+
+            expect(sceneChangeSpy).toHaveBeenCalled();
+        });
+
+        test('should collect debug data from current scene', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+            const testScene = new TestScene();
+            Core.setScene(testScene);
+
+            const debugData = Core.getDebugData();
+
+            expect(debugData).toBeDefined();
+            expect(debugData).toHaveProperty('timestamp');
+            expect(debugData).toHaveProperty('frameworkVersion');
+            expect(debugData).toHaveProperty('currentScene');
+        });
+    });
+
+    describe('DebugManager - Configuration Management', () => {
+        test('should use correct debug frame rate', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 60,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (core as any)._debugManager as DebugManager;
+            const sendInterval = (debugManager as any).sendInterval;
+
+            expect(sendInterval).toBe(1000 / 60);
+        });
+
+        test('should handle channel configuration correctly', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: false,
+                    performance: false,
+                    components: true,
+                    scenes: false
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+            const testScene = new TestScene();
+            Core.setScene(testScene);
+
+            const debugData = Core.getDebugData() as any;
+
+            expect(debugData.entities).toBeDefined();
+            expect(debugData.components).toBeDefined();
+            expect(debugData.systems).toBeUndefined();
+            expect(debugData.performance).toBeUndefined();
+            expect(debugData.scenes).toBeUndefined();
+        });
+    });
+
+    describe('DebugManager - Lifecycle', () => {
+        test('should start automatically on creation', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (core as any)._debugManager as DebugManager;
+            const isRunning = (debugManager as any).isRunning;
+
+            expect(isRunning).toBe(true);
+        });
+
+        test('should stop when disabling debug', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (Core.Instance as any)._debugManager as DebugManager;
+            const stopSpy = jest.spyOn(debugManager, 'stop');
+
+            Core.disableDebug();
+
+            expect(stopSpy).toHaveBeenCalled();
+        });
+
+        test('should dispose properly on Core.destroy', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (Core.Instance as any)._debugManager as DebugManager;
+            const stopSpy = jest.spyOn(debugManager, 'stop');
+
+            Core.destroy();
+
+            expect(stopSpy).toHaveBeenCalled();
+        });
+    });
+
+    describe('DebugManager - Pure DI Architecture Validation', () => {
+        test('should resolve all dependencies through ServiceContainer', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+
+            const debugConfigService = Core.services.resolve(DebugConfigService);
+            expect(debugConfigService).toBeDefined();
+
+            const config = debugConfigService.getConfig();
+            expect(config).toEqual(debugConfig);
+        });
+
+        test('should not have mixed DI patterns', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            const core = Core.create({ debug: true, debugConfig: debugConfig });
+            const debugManager = (core as any)._debugManager as DebugManager;
+
+            const sceneManager = (debugManager as any).sceneManager;
+            const performanceMonitor = (debugManager as any).performanceMonitor;
+            const config = (debugManager as any).config;
+
+            expect(sceneManager).toBeDefined();
+            expect(performanceMonitor).toBeDefined();
+            expect(config).toBeDefined();
+            expect(config.enabled).toBe(true);
+        });
+
+        test('should use factory pattern for registration', () => {
+            const debugConfig: IECSDebugConfig = {
+                enabled: true,
+                websocketUrl: 'ws://localhost:9229',
+                debugFrameRate: 30,
+                autoReconnect: true,
+                channels: {
+                    entities: true,
+                    systems: true,
+                    performance: true,
+                    components: true,
+                    scenes: true
+                }
+            };
+
+            Core.create({ debug: true, debugConfig: debugConfig });
+
+            const debugManager1 = (Core.Instance as any)._debugManager;
+            const debugManager2 = Core.services.resolve(DebugManager);
+
+            expect(debugManager1).toBe(debugManager2);
+        });
+    });
+});

packages/core/tests/ECS/Core/MinimalSystemInit.test.ts

@@ -0,0 +1,94 @@
+import { Scene } from '../../../src/ECS/Scene';
+import { Entity } from '../../../src/ECS/Entity';
+import { Component } from '../../../src/ECS/Component';
+import { EntitySystem } from '../../../src/ECS/Systems/EntitySystem';
+import { Matcher } from '../../../src/ECS/Utils/Matcher';
+import { ComponentRegistry } from '../../../src/ECS/Core/ComponentStorage';
+
+// 简单的测试组件
+class HealthComponent extends Component {
+    public health: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [health = 100] = args as [number?];
+        this.health = health;
+    }
+}
+
+// 简单的测试系统
+class HealthSystem extends EntitySystem {
+    public onAddedEntities: Entity[] = [];
+
+    constructor() {
+        super(Matcher.empty().all(HealthComponent));
+    }
+
+    protected override onAdded(entity: Entity): void {
+        console.log('[HealthSystem] onAdded called:', { id: entity.id, name: entity.name });
+        this.onAddedEntities.push(entity);
+    }
+}
+
+describe('MinimalSystemInit - 最小化系统初始化测试', () => {
+    let scene: Scene;
+
+    beforeEach(() => {
+        ComponentRegistry.reset();
+        scene = new Scene();
+    });
+
+    afterEach(() => {
+        if (scene) {
+            scene.end();
+        }
+    });
+
+    test('先创建实体和组件，再添加系统 - 应该触发onAdded', () => {
+        console.log('\\n=== Test 1: 先创建实体再添加系统 ===');
+
+        // 1. 创建实体并添加组件
+        const entity = scene.createEntity('TestEntity');
+        entity.addComponent(new HealthComponent(100));
+
+        console.log('[Test] Entity created with HealthComponent');
+        console.log('[Test] ComponentRegistry registered types:', ComponentRegistry.getRegisteredCount());
+
+        // 2. 验证QuerySystem能查询到实体
+        const queryResult = scene.querySystem.queryAll(HealthComponent);
+        console.log('[Test] QuerySystem result:', { count: queryResult.count });
+
+        // 3. 添加系统
+        const system = new HealthSystem();
+        console.log('[Test] Adding system to scene...');
+        scene.addEntityProcessor(system);
+
+        console.log('[Test] System added, onAddedEntities.length =', system.onAddedEntities.length);
+
+        // 4. 验证
+        expect(system.onAddedEntities).toHaveLength(1);
+    });
+
+    test('先添加系统，再创建实体和组件 - 应该在update时触发onAdded', () => {
+        console.log('\\n=== Test 2: 先添加系统再创建实体 ===');
+
+        // 1. 先添加系统
+        const system = new HealthSystem();
+        scene.addEntityProcessor(system);
+        console.log('[Test] System added, onAddedEntities.length =', system.onAddedEntities.length);
+
+        // 2. 创建实体并添加组件
+        const entity = scene.createEntity('TestEntity');
+        entity.addComponent(new HealthComponent(100));
+        console.log('[Test] Entity created with HealthComponent');
+
+        // 3. 调用update触发系统查询
+        console.log('[Test] Calling scene.update()...');
+        scene.update();
+
+        console.log('[Test] After update, onAddedEntities.length =', system.onAddedEntities.length);
+
+        // 4. 验证
+        expect(system.onAddedEntities).toHaveLength(1);
+    });
+});

packages/core/tests/ECS/Core/MultiSystemInit.test.ts

@@ -0,0 +1,160 @@
+import { Scene } from '../../../src/ECS/Scene';
+import { Entity } from '../../../src/ECS/Entity';
+import { Component } from '../../../src/ECS/Component';
+import { EntitySystem } from '../../../src/ECS/Systems/EntitySystem';
+import { Matcher } from '../../../src/ECS/Utils/Matcher';
+import { ComponentRegistry } from '../../../src/ECS/Core/ComponentStorage';
+
+// 测试组件
+class PositionComponent extends Component {
+    public x: number;
+    public y: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [x = 0, y = 0] = args as [number?, number?];
+        this.x = x;
+        this.y = y;
+    }
+}
+
+class VelocityComponent extends Component {
+    public vx: number;
+    public vy: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [vx = 0, vy = 0] = args as [number?, number?];
+        this.vx = vx;
+        this.vy = vy;
+    }
+}
+
+class HealthComponent extends Component {
+    public health: number;
+
+    constructor(...args: unknown[]) {
+        super();
+        const [health = 100] = args as [number?];
+        this.health = health;
+    }
+}
+
+// 测试系统
+class MovementSystem extends EntitySystem {
+    public onAddedEntities: Entity[] = [];
+
+    constructor() {
+        super(Matcher.empty().all(PositionComponent, VelocityComponent));
+    }
+
+    protected override onAdded(entity: Entity): void {
+        console.log('[MovementSystem] onAdded:', { id: entity.id, name: entity.name });
+        this.onAddedEntities.push(entity);
+    }
+}
+
+class HealthSystem extends EntitySystem {
+    public onAddedEntities: Entity[] = [];
+
+    constructor() {
+        super(Matcher.empty().all(HealthComponent));
+    }
+
+    protected override onAdded(entity: Entity): void {
+        console.log('[HealthSystem] onAdded:', { id: entity.id, name: entity.name });
+        this.onAddedEntities.push(entity);
+    }
+}
+
+describe('MultiSystemInit - 多系统初始化测试', () => {
+    let scene: Scene;
+
+    beforeEach(() => {
+        ComponentRegistry.reset();
+        scene = new Scene();
+    });
+
+    afterEach(() => {
+        if (scene) {
+            scene.end();
+        }
+    });
+
+    test('多个系统同时响应同一实体 - 复现失败场景', () => {
+        console.log('\\n=== Test: 多个系统同时响应同一实体 ===');
+
+        // 1. 创建实体并添加所有组件
+        const entity = scene.createEntity('Entity');
+        entity.addComponent(new PositionComponent(0, 0));
+        entity.addComponent(new VelocityComponent(1, 1));
+        entity.addComponent(new HealthComponent(100));
+
+        console.log('[Test] Entity created with Position, Velocity, Health');
+        console.log('[Test] ComponentRegistry registered types:', ComponentRegistry.getRegisteredCount());
+
+        // 2. 验证QuerySystem能查询到实体
+        const movementQuery = scene.querySystem.queryAll(PositionComponent, VelocityComponent);
+        const healthQuery = scene.querySystem.queryAll(HealthComponent);
+        console.log('[Test] MovementQuery result:', { count: movementQuery.count });
+        console.log('[Test] HealthQuery result:', { count: healthQuery.count });
+
+        // 3. 添加两个系统
+        console.log('[Test] Adding MovementSystem...');
+        const movementSystem = new MovementSystem();
+        scene.addEntityProcessor(movementSystem);
+        console.log('[Test] MovementSystem added, onAddedEntities.length =', movementSystem.onAddedEntities.length);
+
+        console.log('[Test] Adding HealthSystem...');
+        const healthSystem = new HealthSystem();
+        scene.addEntityProcessor(healthSystem);
+        console.log('[Test] HealthSystem added, onAddedEntities.length =', healthSystem.onAddedEntities.length);
+
+        // 4. 验证
+        console.log('[Test] Final check:');
+        console.log('  MovementSystem.onAddedEntities.length =', movementSystem.onAddedEntities.length);
+        console.log('  HealthSystem.onAddedEntities.length =', healthSystem.onAddedEntities.length);
+
+        expect(movementSystem.onAddedEntities).toHaveLength(1);
+        expect(healthSystem.onAddedEntities).toHaveLength(1);
+    });
+
+    test('不同系统匹配不同实体 - 复现失败场景', () => {
+        console.log('\\n=== Test: 不同系统匹配不同实体 ===');
+
+        // 1. 创建两个实体
+        const movingEntity = scene.createEntity('Moving');
+        movingEntity.addComponent(new PositionComponent(0, 0));
+        movingEntity.addComponent(new VelocityComponent(1, 1));
+
+        const healthEntity = scene.createEntity('Health');
+        healthEntity.addComponent(new HealthComponent(100));
+
+        console.log('[Test] Two entities created');
+
+        // 2. 验证QuerySystem
+        const movementQuery = scene.querySystem.queryAll(PositionComponent, VelocityComponent);
+        const healthQuery = scene.querySystem.queryAll(HealthComponent);
+        console.log('[Test] MovementQuery result:', { count: movementQuery.count });
+        console.log('[Test] HealthQuery result:', { count: healthQuery.count });
+
+        // 3. 添加系统
+        console.log('[Test] Adding systems...');
+        const movementSystem = new MovementSystem();
+        const healthSystem = new HealthSystem();
+
+        scene.addEntityProcessor(movementSystem);
+        scene.addEntityProcessor(healthSystem);
+
+        console.log('[Test] Systems added');
+        console.log('  MovementSystem.onAddedEntities.length =', movementSystem.onAddedEntities.length);
+        console.log('  HealthSystem.onAddedEntities.length =', healthSystem.onAddedEntities.length);
+
+        // 4. 验证
+        expect(movementSystem.onAddedEntities).toHaveLength(1);
+        expect(movementSystem.onAddedEntities[0]).toBe(movingEntity);
+
+        expect(healthSystem.onAddedEntities).toHaveLength(1);
+        expect(healthSystem.onAddedEntities[0]).toBe(healthEntity);
+    });
+});

packages/core/tests/ECS/Core/QuerySystem.test.ts

@@ -449,22 +449,24 @@ describe('QuerySystem - 查询系统测试', () => {
             expect(parseFloat(stats.cacheStats.hitRate)).toBeLessThanOrEqual(100);
         });
 
-        test('缓存命中率应该在重复查询时提高', () => {
+        test('缓存命中率应该在重复查询时保持高命中率', () => {
             entities[0].addComponent(new PositionComponent(10, 20));
             entities[1].addComponent(new PositionComponent(30, 40));
 
-            // 第一次查询（缓存未命中）
+            // 第一次查询(创建响应式查询缓存)
             querySystem.queryAll(PositionComponent);
             let stats = querySystem.getStats();
             const initialHitRate = parseFloat(stats.cacheStats.hitRate);
 
-            // 重复查询（应该命中缓存）
+            // 重复查询(应该持续命中响应式查询缓存)
             for (let i = 0; i < 10; i++) {
                 querySystem.queryAll(PositionComponent);
             }
 
             stats = querySystem.getStats();
-            expect(parseFloat(stats.cacheStats.hitRate)).toBeGreaterThan(initialHitRate);
+            // 响应式查询永远100%命中,这是期望的优化效果
+            expect(parseFloat(stats.cacheStats.hitRate)).toBeGreaterThanOrEqual(initialHitRate);
+            expect(parseFloat(stats.cacheStats.hitRate)).toBe(100);
         });
 
         test('应该能够清理查询缓存', () => {

packages/core/tests/ECS/Core/SystemInitialization.test.ts

@@ -3,7 +3,6 @@ import { Entity } from '../../../src/ECS/Entity';
 import { Component } from '../../../src/ECS/Component';
 import { EntitySystem } from '../../../src/ECS/Systems/EntitySystem';
 import { Matcher } from '../../../src/ECS/Utils/Matcher';
-import { ComponentTypeManager } from '../../../src/ECS/Utils/ComponentTypeManager';
 
 /**
  * System初始化测试套件
@@ -205,11 +204,16 @@ describe('SystemInitialization - 系统初始化测试', () => {
     let scene: Scene;
 
     beforeEach(() => {
-        ComponentTypeManager.instance.reset();
         scene = new Scene();
         scene.name = 'InitializationTestScene';
     });
 
+    afterEach(() => {
+        if (scene) {
+            scene.end();
+        }
+    });
+
     describe('初始化时序', () => {
         test('先添加实体再添加系统 - 系统应该正确初始化', () => {
             const player = scene.createEntity('Player');

packages/core/tests/ECS/EntitySystemDI.test.ts

@@ -3,7 +3,7 @@ import { EntitySystem } from '../../src/ECS/Systems/EntitySystem';
 import { Entity } from '../../src/ECS/Entity';
 import { Component } from '../../src/ECS/Component';
 import { Matcher } from '../../src/ECS/Utils/Matcher';
-import { Injectable, Inject } from '../../src/Core/DI';
+import { Injectable, Inject, InjectProperty } from '../../src/Core/DI';
 import { Core } from '../../src/Core';
 import type { IService } from '../../src/Core/ServiceContainer';
 import { ECSSystem } from '../../src/ECS/Decorators';
@@ -423,4 +423,170 @@ describe('EntitySystem - 依赖注入测试', () => {
             expect(transform.y).toBeCloseTo(0.8, 1);
         });
     });
+
+    describe('属性注入 @InjectProperty', () => {
+        test('应该支持单个属性注入', () => {
+            @Injectable()
+            @ECSSystem('Config')
+            class GameConfig extends EntitySystem implements IService {
+                public bulletDamage = 10;
+
+                constructor() {
+                    super(Matcher.empty());
+                }
+                override dispose() {}
+            }
+
+            @Injectable()
+            @ECSSystem('Combat')
+            class CombatSystem extends EntitySystem implements IService {
+                @InjectProperty(GameConfig)
+                gameConfig!: GameConfig;
+
+                constructor() {
+                    super(Matcher.empty().all(Health));
+                }
+
+                protected override onInitialize(): void {
+                    expect(this.gameConfig).toBeInstanceOf(GameConfig);
+                    expect(this.gameConfig.bulletDamage).toBe(10);
+                }
+
+                override dispose() {}
+            }
+
+            scene.addEntityProcessor(GameConfig);
+            scene.addEntityProcessor(CombatSystem);
+        });
+
+        test('应该支持多个属性注入', () => {
+            @Injectable()
+            @ECSSystem('Time')
+            class TimeService extends EntitySystem implements IService {
+                public deltaTime = 0.016;
+                constructor() {
+                    super(Matcher.empty());
+                }
+                override dispose() {}
+            }
+
+            @Injectable()
+            @ECSSystem('Collision')
+            class CollisionSystem extends EntitySystem implements IService {
+                public checkCount = 0;
+                constructor() {
+                    super(Matcher.empty());
+                }
+                override dispose() {}
+            }
+
+            @Injectable()
+            @ECSSystem('Physics')
+            class PhysicsSystem extends EntitySystem implements IService {
+                @InjectProperty(TimeService)
+                time!: TimeService;
+
+                @InjectProperty(CollisionSystem)
+                collision!: CollisionSystem;
+
+                constructor() {
+                    super(Matcher.empty());
+                }
+
+                protected override onInitialize(): void {
+                    expect(this.time).toBeInstanceOf(TimeService);
+                    expect(this.collision).toBeInstanceOf(CollisionSystem);
+                    expect(this.time.deltaTime).toBe(0.016);
+                }
+
+                override dispose() {}
+            }
+
+            scene.registerSystems([TimeService, CollisionSystem, PhysicsSystem]);
+        });
+
+        test('属性注入应该在onInitialize之前完成', () => {
+            @Injectable()
+            @ECSSystem('Service')
+            class TestService extends EntitySystem implements IService {
+                public value = 42;
+                constructor() {
+                    super(Matcher.empty());
+                }
+                override dispose() {}
+            }
+
+            @Injectable()
+            @ECSSystem('Consumer')
+            class ConsumerSystem extends EntitySystem implements IService {
+                @InjectProperty(TestService)
+                service!: TestService;
+
+                private initializeValue = 0;
+
+                constructor() {
+                    super(Matcher.empty());
+                }
+
+                protected override onInitialize(): void {
+                    this.initializeValue = this.service.value;
+                }
+
+                public getInitializeValue(): number {
+                    return this.initializeValue;
+                }
+
+                override dispose() {}
+            }
+
+            scene.addEntityProcessor(TestService);
+            const consumer = scene.addEntityProcessor(ConsumerSystem);
+
+            expect(consumer.getInitializeValue()).toBe(42);
+        });
+
+        test('属性注入可以与构造函数注入混合使用', () => {
+            @Injectable()
+            @ECSSystem('A')
+            class ServiceA extends EntitySystem implements IService {
+                public valueA = 'A';
+                constructor() {
+                    super(Matcher.empty());
+                }
+                override dispose() {}
+            }
+
+            @Injectable()
+            @ECSSystem('B')
+            class ServiceB extends EntitySystem implements IService {
+                public valueB = 'B';
+                constructor() {
+                    super(Matcher.empty());
+                }
+                override dispose() {}
+            }
+
+            @Injectable()
+            @ECSSystem('Mixed')
+            class MixedSystem extends EntitySystem implements IService {
+                @InjectProperty(ServiceB)
+                serviceB!: ServiceB;
+
+                constructor(@Inject(ServiceA) public serviceA: ServiceA) {
+                    super(Matcher.empty());
+                }
+
+                protected override onInitialize(): void {
+                    expect(this.serviceA).toBeInstanceOf(ServiceA);
+                    expect(this.serviceB).toBeInstanceOf(ServiceB);
+                    expect(this.serviceA.valueA).toBe('A');
+                    expect(this.serviceB.valueB).toBe('B');
+                }
+
+                override dispose() {}
+            }
+
+            scene.registerSystems([ServiceA, ServiceB, MixedSystem]);
+        });
+    });
 });

packages/core/tests/ECS/Serialization/IncrementalSerialization.test.ts

@@ -464,7 +464,7 @@ describe('Incremental Serialization System', () => {
             const incremental = scene.serializeIncremental();
             const binary = IncrementalSerializer.serializeIncremental(incremental, { format: 'binary' });
 
-            expect(Buffer.isBuffer(binary)).toBe(true);
+            expect(binary instanceof Uint8Array).toBe(true);
 
             const deserialized = IncrementalSerializer.deserializeIncremental(binary);
             expect(deserialized.version).toBe(incremental.version);

packages/core/tests/ECS/Serialization/Serialization.test.ts

@@ -557,14 +557,14 @@ describe('ECS Serialization System', () => {
             // 二进制序列化
             const binaryData = scene1.serialize({ format: 'binary' });
 
-            // 验证是Buffer类型
-            expect(Buffer.isBuffer(binaryData)).toBe(true);
+            // 验证是Uint8Array类型
+            expect(binaryData instanceof Uint8Array).toBe(true);
 
             // JSON序列化对比
             const jsonData = scene1.serialize({ format: 'json', pretty: false });
 
             // 二进制应该更小
-            const binarySize = (binaryData as Buffer).length;
+            const binarySize = (binaryData as Uint8Array).length;
             const jsonSize = (jsonData as string).length;
             console.log(`Binary size: ${binarySize} bytes, JSON size: ${jsonSize} bytes`);
             expect(binarySize).toBeLessThan(jsonSize);

packages/core/tests/reactive-query-debug.test.ts

@@ -0,0 +1,109 @@
+import { describe, it, expect, beforeEach } from '@jest/globals';
+import { Scene, Entity, Component, EntitySystem, Matcher, ECSComponent } from '../src';
+
+@ECSComponent('TestTransform')
+class TestTransform extends Component {
+    constructor(public x: number = 0, public y: number = 0) {
+        super();
+    }
+}
+
+@ECSComponent('TestRenderable')
+class TestRenderable extends Component {
+    constructor(public sprite: string = 'default') {
+        super();
+    }
+}
+
+class TestRenderSystem extends EntitySystem {
+    public entitiesFound: Entity[] = [];
+
+    constructor() {
+        super(Matcher.all(TestTransform, TestRenderable));
+    }
+
+    protected override process(entities: readonly Entity[]): void {
+        this.entitiesFound = Array.from(entities);
+        console.log(`TestRenderSystem.process: 找到 ${entities.length} 个实体`);
+    }
+
+    protected override onAdded(entity: Entity): void {
+        console.log(`TestRenderSystem.onAdded: 实体 ${entity.name}(${entity.id}) 被添加`);
+    }
+}
+
+describe('响应式查询调试', () => {
+    let scene: Scene;
+    let system: TestRenderSystem;
+
+    beforeEach(() => {
+        scene = new Scene();
+        system = new TestRenderSystem();
+        scene.addEntityProcessor(system);
+        scene.begin();
+    });
+
+    it('应该在实体添加组件后能被System发现', () => {
+        console.log('\n=== 测试开始 ===');
+
+        // 1. 创建实体（此时没有组件）
+        console.log('\n步骤1: 创建实体');
+        const entity = scene.createEntity('TestEntity');
+        console.log(`实体已创建: ${entity.name}(${entity.id})`);
+        console.log(`QuerySystem中的实体数量: ${scene.querySystem.getAllEntities().length}`);
+
+        // 2. 添加组件
+        console.log('\n步骤2: 添加 TestTransform 组件');
+        entity.addComponent(new TestTransform(100, 200));
+        console.log(`实体组件数量: ${entity.components.length}`);
+
+        console.log('\n步骤3: 添加 TestRenderable 组件');
+        entity.addComponent(new TestRenderable('test-sprite'));
+        console.log(`实体组件数量: ${entity.components.length}`);
+
+        // 3. 触发系统更新
+        console.log('\n步骤4: 更新Scene');
+        scene.update();
+
+        // 4. 检查System是否找到了实体
+        console.log(`\nSystem找到的实体数量: ${system.entitiesFound.length}`);
+        if (system.entitiesFound.length > 0) {
+            console.log(`找到的实体: ${system.entitiesFound.map(e => `${e.name}(${e.id})`).join(', ')}`);
+        }
+
+        // 5. 直接查询QuerySystem
+        console.log('\n步骤5: 直接查询QuerySystem');
+        const queryResult = scene.querySystem.queryAll(TestTransform, TestRenderable);
+        console.log(`QuerySystem.queryAll 返回: ${queryResult.entities.length} 个实体`);
+
+        console.log('\n=== 测试结束 ===\n');
+
+        expect(system.entitiesFound.length).toBe(1);
+        expect(system.entitiesFound[0]).toBe(entity);
+        expect(queryResult.entities.length).toBe(1);
+        expect(queryResult.entities[0]).toBe(entity);
+    });
+
+    it('应该测试响应式查询的内部状态', () => {
+        console.log('\n=== 响应式查询内部状态测试 ===');
+
+        // 创建实体并添加组件
+        const entity = scene.createEntity('TestEntity');
+        entity.addComponent(new TestTransform(100, 200));
+        entity.addComponent(new TestRenderable('test-sprite'));
+
+        // 获取QuerySystem的内部状态
+        const querySystem = scene.querySystem as any;
+        console.log(`\n响应式查询数量: ${querySystem._reactiveQueries.size}`);
+        console.log(`组件索引数量: ${querySystem._reactiveQueriesByComponent.size}`);
+
+        // 检查响应式查询
+        for (const [key, query] of querySystem._reactiveQueries) {
+            console.log(`\n查询: ${key}`);
+            console.log(`  实体数量: ${(query as any)._entities.length}`);
+            console.log(`  实体ID集合: ${Array.from((query as any)._entityIdSet).join(', ')}`);
+        }
+
+        console.log('\n=== 测试结束 ===\n');
+    });
+});

packages/core/tests/reactive-query-timing.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect } from '@jest/globals';
+import { Scene, Entity, Component, EntitySystem, Matcher, ECSComponent } from '../src';
+
+@ECSComponent('TestTransform')
+class TestTransform extends Component {
+    constructor(public x: number = 0, public y: number = 0) {
+        super();
+    }
+}
+
+@ECSComponent('TestRenderable')
+class TestRenderable extends Component {
+    constructor(public sprite: string = 'default') {
+        super();
+    }
+}
+
+class TestRenderSystem extends EntitySystem {
+    public entitiesFound: Entity[] = [];
+
+    constructor() {
+        super(Matcher.all(TestTransform, TestRenderable));
+    }
+
+    protected override process(entities: readonly Entity[]): void {
+        this.entitiesFound = Array.from(entities);
+        console.log(`TestRenderSystem.process: 找到 ${entities.length} 个实体`);
+    }
+
+    protected override onAdded(entity: Entity): void {
+        console.log(`TestRenderSystem.onAdded: 实体 ${entity.name}(${entity.id}) 被添加`);
+    }
+}
+
+class TestGameScene extends Scene {
+    private renderSystem: TestRenderSystem | null = null;
+
+    public override initialize(): void {
+        super.initialize();
+
+        console.log('\n=== Scene.initialize() 开始 ===');
+
+        // 1. 先添加System（这是GameScene的做法）
+        console.log('步骤1: 添加RenderSystem');
+        this.renderSystem = new TestRenderSystem();
+        this.addEntityProcessor(this.renderSystem);
+
+        // 2. 然后创建实体（这是GameScene的做法）
+        console.log('\n步骤2: 创建实体');
+        const entity = this.createEntity('Player');
+        console.log(`实体已创建: ${entity.name}(${entity.id})`);
+
+        console.log('\n步骤3: 添加组件');
+        entity.addComponent(new TestTransform(100, 200));
+        entity.addComponent(new TestRenderable('player-sprite'));
+        console.log(`实体组件数量: ${entity.components.length}`);
+
+        console.log('=== Scene.initialize() 结束 ===\n');
+    }
+
+    public getRenderSystem(): TestRenderSystem | null {
+        return this.renderSystem;
+    }
+}
+
+describe('响应式查询时序测试（模拟GameScene）', () => {
+    it('应该在Scene.initialize()中先添加System再创建实体时正常工作', () => {
+        console.log('\n\n========== 测试开始 ==========');
+
+        const scene = new TestGameScene();
+
+        console.log('\n调用scene.initialize()');
+        scene.initialize();
+
+        console.log('\n调用Scene.begin()');
+        scene.begin();
+
+        console.log('\n第一次Scene.update()');
+        scene.update();
+
+        const renderSystem = scene.getRenderSystem();
+        expect(renderSystem).not.toBeNull();
+
+        console.log(`\nRenderSystem找到的实体数量: ${renderSystem!.entitiesFound.length}`);
+        expect(renderSystem!.entitiesFound.length).toBe(1);
+
+        console.log('========== 测试结束 ==========\n\n');
+    });
+});

packages/core/tests/setup.ts

@@ -60,15 +60,15 @@ afterEach(() => {
     const { Core } = require('../src/Core');
     const { WorldManager } = require('../src/ECS/WorldManager');
 
-    // 重置 Core 和 WorldManager 单例
+    // 销毁 Core 和 WorldManager 单例
     if (Core._instance) {
-      Core.reset();
+      Core.destroy();
     }
     if (WorldManager._instance) {
       if (WorldManager._instance.destroy) {
         WorldManager._instance.destroy();
       }
-      WorldManager.reset();
+      WorldManager._instance = null;
     }
   } catch (error) {
     // 忽略清理错误