新增world概念(多world管理多scene概念)现在支持多个world多个scene同时更新

This commit is contained in:
YHH
2025-08-20 17:48:31 +08:00
parent 69616bbddc
commit a44251cc55
15 changed files with 3539 additions and 783 deletions

View File

@@ -14,7 +14,7 @@ ECS 架构将传统的面向对象设计分解为三个核心部分:
## Core核心
Core 是框架的核心管理类,负责游戏的生命周期管理。
Core 是框架的核心管理类,负责游戏的生命周期管理。框架采用融合设计既支持传统的单Scene模式向后兼容也支持高级的多World/多Scene架构。
### 创建和配置
@@ -47,6 +47,40 @@ const core2 = Core.create(false); // 发布模式
const core3 = Core.create(); // 默认调试模式
```
### 场景管理API
```typescript
// 单Scene模式默认向后兼容
const scene = new Scene();
Core.setScene(scene); // 设置场景
const currentScene = Core.getScene(); // 获取当前场景
// 多World模式高级功能
Core.enableWorldManager(); // 启用World管理器
const worldManager = Core.getWorldManager();
// 创建World
const gameWorld = worldManager.createWorld('GameWorld', {
name: 'GameWorld',
maxScenes: 10,
autoCleanup: true
});
// 在World中管理Scene
const battleScene = gameWorld.createScene('battle', new Scene());
const uiScene = gameWorld.createScene('ui', new Scene());
gameWorld.setSceneActive('battle', true);
gameWorld.setSceneActive('ui', true);
// 启动World
gameWorld.start();
// 获取World统计
const worldStats = gameWorld.getStats();
console.log('World状态:', worldStats);
```
### 事件系统
```typescript
@@ -404,6 +438,235 @@ console.log("实体数量:", stats.entityCount);
console.log("系统数量:", stats.processorCount);
```
## World世界
World是Scene的容器提供了更高级的场景管理功能。每个World可以包含多个Scene适用于复杂的游戏架构。
### World基本使用
```typescript
import { World, Scene, IWorldConfig } from '@esengine/ecs-framework';
// 创建World配置
const worldConfig: IWorldConfig = {
name: 'GameWorld',
debug: true,
maxScenes: 10,
autoCleanup: true
};
// 创建World
const gameWorld = new World(worldConfig);
// 在World中创建Scene
const battleScene = gameWorld.createScene('battle', new Scene());
const uiScene = gameWorld.createScene('ui', new Scene());
const menuScene = gameWorld.createScene('menu');
// 激活Scene
gameWorld.setSceneActive('battle', true);
gameWorld.setSceneActive('ui', true);
// 启动World
gameWorld.start();
```
### World生命周期管理
```typescript
// 启动World启动所有全局System
gameWorld.start();
// 检查World状态
if (gameWorld.isActive) {
console.log('World正在运行');
}
// 停止World停止所有Scene和全局System
gameWorld.stop();
// 销毁World清理所有资源
gameWorld.destroy();
```
### Scene管理
```typescript
// 获取Scene
const battleScene = gameWorld.getScene<Scene>('battle');
// 检查Scene是否激活
if (gameWorld.isSceneActive('battle')) {
console.log('战斗场景正在运行');
}
// 移除Scene
gameWorld.removeScene('menu');
// 获取所有Scene ID
const sceneIds = gameWorld.getSceneIds();
console.log('所有Scene:', sceneIds);
// 获取活跃Scene数量
const activeCount = gameWorld.getActiveSceneCount();
console.log('活跃Scene数量:', activeCount);
```
### 全局System管理
World支持全局System这些System会在所有Scene之前执行适用于跨Scene的业务逻辑
```typescript
import { IGlobalSystem } from '@esengine/ecs-framework';
// 全局网络同步系统
class GlobalNetworkSystem implements IGlobalSystem {
public readonly name = 'GlobalNetworkSystem';
public initialize(): void {
// 初始化网络连接
console.log('网络系统初始化');
}
public update(): void {
// 处理全局网络同步逻辑
// 注意全局系统处理的是World级别的逻辑不直接处理实体
// 如需处理特定实体请在Scene中使用EntitySystem
this.syncGlobalNetworkState();
}
public reset(): void {
// 重置系统状态
}
public destroy(): void {
// 清理网络连接
console.log('网络系统销毁');
}
private syncGlobalNetworkState(): void {
// 全局网络状态同步
}
}
// 添加全局System
const networkSystem = gameWorld.addGlobalSystem(new GlobalNetworkSystem());
// 获取全局System
const existingSystem = gameWorld.getGlobalSystem(GlobalNetworkSystem);
// 移除全局System
gameWorld.removeGlobalSystem(networkSystem);
```
> **注意**全局System适用于World级别的业务逻辑如网络管理、资源管理、全局状态管理等。如果需要处理具体的实体和组件请在Scene中使用EntitySystem。
### World状态监控
```typescript
// 获取World状态
const status = gameWorld.getStatus();
console.log('World状态:', {
name: status.name,
isActive: status.isActive,
sceneCount: status.sceneCount,
activeSceneCount: status.activeSceneCount,
globalSystemCount: status.globalSystemCount,
scenes: status.scenes
});
// 获取World统计信息
const stats = gameWorld.getStats();
console.log('World统计:', {
totalEntities: stats.totalEntities,
totalSystems: stats.totalSystems,
memoryUsage: stats.memoryUsage
});
```
## WorldManager世界管理器
WorldManager是单例模式的World管理器负责管理多个World实例。
### WorldManager基本使用
```typescript
import { WorldManager, IWorldManagerConfig } from '@esengine/ecs-framework';
// 获取WorldManager实例
const worldManager = WorldManager.getInstance({
maxWorlds: 50,
autoCleanup: true,
debug: true
});
// 或者通过Core获取
Core.enableWorldManager();
const worldManager2 = Core.getWorldManager();
```
### World管理
```typescript
// 创建World
const gameWorld = worldManager.createWorld('GameRoom_001', {
name: 'GameRoom_001',
maxScenes: 5,
autoCleanup: true
});
// 获取World
const existingWorld = worldManager.getWorld('GameRoom_001');
// 检查World是否存在
if (worldManager.getWorld('GameRoom_001')) {
console.log('World存在');
}
// 销毁World
worldManager.removeWorld('GameRoom_001');
// 获取所有World ID
const worldIds = worldManager.getWorldIds();
console.log('所有World ID:', worldIds);
// 获取活跃World
const activeWorlds = worldManager.getActiveWorlds();
console.log('活跃World数量:', activeWorlds.length);
```
### WorldManager统计和监控
```typescript
// 获取WorldManager状态
const managerStatus = worldManager.getStatus();
console.log('WorldManager状态:', {
totalWorlds: managerStatus.totalWorlds,
activeWorlds: managerStatus.activeWorlds,
maxWorlds: managerStatus.maxWorlds,
memoryUsage: managerStatus.memoryUsage
});
// 获取所有World的统计
const allStats = worldManager.getAllWorldStats();
allStats.forEach(stat => {
console.log(`World ${stat.worldName}:`, stat);
});
// 清理空闲World
const cleanedCount = worldManager.cleanup();
console.log(`清理了 ${cleanedCount} 个空闲World`);
```
### 使用场景
World和WorldManager适用于
- **游戏服务器**每个房间一个独立World
- **复杂客户端**按功能分层管理Scene游戏层、UI层、特效层
- **并发世界**:需要同时运行多个独立游戏世界的场景
> **完整示例和最佳实践**:查看 [场景管理完整指南](scene-management-guide.md#world多场景管理) 了解详细的实现方案和架构设计
## System系统
系统处理实体集合,实现游戏的核心逻辑。
@@ -646,11 +909,18 @@ const movingEntities = scene.querySystem.queryAll(PositionComponent, VelocityCom
ECS Framework 提供了完整的实体组件系统架构:
- **Core** 管理游戏生命周期和全局功能
- **Core** 管理游戏生命周期和全局功能支持单Scene和多World模式
- **Entity** 作为游戏对象的基础容器
- **Component** 实现具体的功能模块,支持对象池优化
- **System** 处理游戏逻辑
- **Scene** 管理游戏世界状态,支持批量操作
- **World** 高级场景容器支持多Scene管理和全局System
- **WorldManager** 管理多个World实例适用于复杂架构
- **高级优化** 位掩码优化器、组件对象池、批量操作等
通过合理使用这些核心概念和优化功能,可以构建出高性能、结构清晰、易于维护的游戏代码。
### 架构选择指南
- **单Scene模式**:适合简单游戏、单机游戏、原型开发
- **多World模式**:适合多人游戏服务器、复杂应用、需要场景隔离的项目
框架采用融合设计,确保向后兼容性的同时提供强大的扩展能力。通过合理使用这些核心概念和优化功能,可以构建出高性能、结构清晰、易于维护的游戏代码。

View File

@@ -33,7 +33,7 @@ Core.update(deltaTime);
### 基础配置
ECS框架提供了灵活的配置选项来满足不同项目需求
ECS框架提供了灵活的配置选项来满足不同项目需求。框架采用融合设计既支持传统的单Scene模式向后兼容也支持高级的多World/多Scene架构
```typescript
import { Core, ICoreConfig } from '@esengine/ecs-framework';
@@ -65,6 +65,31 @@ const config: ICoreConfig = {
const core = Core.create(config);
```
### 架构说明
ECS框架支持两种使用模式
1. **单Scene模式默认向后兼容**
```typescript
// 传统用法,无需任何修改
const scene = new Scene();
Core.setScene(scene);
```
2. **多World模式高级功能**
```typescript
// 启用World管理器支持多World/多Scene架构
Core.enableWorldManager();
const roomWorld = Core.getWorldManager().createWorld('Room_001');
const battleScene = roomWorld.createScene('battle');
```
**使用场景:**
- **单Scene模式**:适合简单游戏、单机游戏、原型开发
- **多World模式**:适合多人游戏服务器、复杂应用、需要场景隔离的项目
> **详细了解World系统**:查看 [场景管理完整指南](scene-management-guide.md) 获取完整的多World架构示例和最佳实践
### 调试功能
ECS框架内置了强大的调试功能支持运行时监控和远程调试
@@ -324,7 +349,7 @@ class CocosRenderSystem extends EntitySystem {
### Node.js后端
```typescript
import { Core, Scene, EntityManager, EntitySystem, Time } from '@esengine/ecs-framework';
import { Core, Scene, EntityManager, EntitySystem, Time, World } from '@esengine/ecs-framework';
class ServerGameManager {
private scene: Scene;
@@ -338,6 +363,7 @@ class ServerGameManager {
Core.create(true); // 启用调试模式
// 完整配置示例: Core.create({ debug: true, enableEntitySystems: true, debugConfig: {...} })
// 单Scene模式简单场景
this.scene = new Scene();
this.scene.name = "ServerScene";
Core.setScene(this.scene);
@@ -418,6 +444,8 @@ const server = new ServerGameManager();
server.start();
```
> **多房间游戏服务器示例**:查看 [场景管理完整指南](scene-management-guide.md#world多场景管理) 了解如何使用多World架构实现复杂的多房间游戏服务器
### 原生浏览器
```typescript

View File

@@ -1,6 +1,6 @@
# 场景管理完整指南
场景Scene是ECS框架中管理游戏对象和系统的核心容器。本指南将详细介绍如何有效地使用场景来构建和管理你的游戏。
场景Scene是ECS框架中管理游戏对象和系统的核心容器。框架采用融合设计既支持传统的单Scene模式向后兼容也支持高级的多World/多Scene架构。本指南将详细介绍如何有效地使用场景来构建和管理你的游戏。
## 场景基础概念
@@ -25,6 +25,47 @@ Core.setScene(gameScene);
> **注意**: `Core.scene = ` 设置方式已被标记为废弃,推荐使用 `Core.setScene()` 方法。新方法提供更好的类型安全性和可预测的激活时序。
### 架构选择指南
ECS框架提供两种使用模式
#### 1. 单Scene模式默认向后兼容
```typescript
// 传统用法,无需任何修改
const scene = new Scene();
Core.setScene(scene);
```
**适用场景:**
- 简单游戏、单机游戏
- 原型开发、快速验证
- 学习ECS架构
- 不需要复杂场景管理的项目
#### 2. 多World模式高级功能
```typescript
// 启用World管理器
Core.enableWorldManager();
const worldManager = Core.getWorldManager();
// 创建多个World每个World可包含多个Scene
const roomWorld = worldManager.createWorld('Room_001');
const battleScene = roomWorld.createScene('battle');
const uiScene = roomWorld.createScene('ui');
roomWorld.start();
roomWorld.setSceneActive('battle', true);
roomWorld.setSceneActive('ui', true);
```
**适用场景:**
- 多人游戏服务器每个房间一个World
- 复杂应用架构(需要场景隔离)
- 需要并发处理多个游戏世界
- 高级场景管理需求
### 场景的生命周期
```typescript
@@ -214,9 +255,374 @@ class GameScene extends Scene {
}
```
## 场景切换和管理
## World多场景管理
### 1. 场景管理器
### 1. World基础使用
对于需要复杂场景管理的项目可以使用World系统
```typescript
import { Core, World, Scene, WorldManager, IGlobalSystem } from '@esengine/ecs-framework';
// 定义全局系统跨Scene的业务逻辑
class NetworkSyncSystem implements IGlobalSystem {
public readonly name = 'NetworkSyncSystem';
public initialize(): void {
console.log('网络同步系统初始化');
}
public update(): void {
// 同步所有Scene的网络状态
this.syncNetworkData();
}
public reset(): void {
// 重置网络连接
}
public destroy(): void {
console.log('网络同步系统销毁');
}
private syncNetworkData(): void {
// 网络数据同步逻辑
}
}
class PlayerManagementSystem implements IGlobalSystem {
public readonly name = 'PlayerManagementSystem';
public initialize(): void {
console.log('玩家管理系统初始化');
}
public update(): void {
// 管理跨Scene的玩家数据
this.managePlayerStates();
}
public reset(): void {
// 重置玩家状态
}
public destroy(): void {
console.log('玩家管理系统销毁');
}
private managePlayerStates(): void {
// 玩家状态管理逻辑
}
}
// 启用World管理功能
Core.enableWorldManager();
const worldManager = Core.getWorldManager();
// 创建游戏房间World
const roomWorld = worldManager.createWorld('GameRoom_001', {
name: 'GameRoom_001',
maxScenes: 5,
autoCleanup: true,
debug: true
});
// 在World中创建多个Scene
const gameScene = roomWorld.createScene('game', new GameScene());
const uiScene = roomWorld.createScene('ui', new UIScene());
const backgroundScene = roomWorld.createScene('background', new BackgroundScene());
// 添加全局系统跨Scene的系统
roomWorld.addGlobalSystem(new NetworkSyncSystem());
roomWorld.addGlobalSystem(new PlayerManagementSystem());
// 启动World并激活Scene
roomWorld.start();
roomWorld.setSceneActive('game', true);
roomWorld.setSceneActive('ui', true);
roomWorld.setSceneActive('background', true);
```
### 2. 多房间游戏服务器示例
```typescript
// 房间管理系统
class RoomManagementSystem implements IGlobalSystem {
public readonly name = 'RoomManagementSystem';
private roomId: string;
constructor(roomId: string) {
this.roomId = roomId;
}
public initialize(): void {
console.log(`房间管理系统初始化: ${this.roomId}`);
}
public update(): void {
// 管理房间状态、玩家进出等
this.manageRoomState();
}
public reset(): void {
// 重置房间状态
}
public destroy(): void {
console.log(`房间管理系统销毁: ${this.roomId}`);
}
private manageRoomState(): void {
// 房间状态管理逻辑
}
}
// 玩家同步系统
class PlayerSyncSystem implements IGlobalSystem {
public readonly name = 'PlayerSyncSystem';
public initialize(): void {
console.log('玩家同步系统初始化');
}
public update(): void {
// 同步房间内所有玩家的状态
this.syncPlayerData();
}
public reset(): void {
// 重置同步状态
}
public destroy(): void {
console.log('玩家同步系统销毁');
}
private syncPlayerData(): void {
// 玩家数据同步逻辑
}
}
class MultiRoomGameServer {
private worldManager: WorldManager;
private rooms: Map<string, World> = new Map();
constructor() {
Core.create({ debug: false });
Core.enableWorldManager();
this.worldManager = Core.getWorldManager();
}
// 创建游戏房间
createRoom(roomId: string): World {
const roomWorld = this.worldManager.createWorld(`Room_${roomId}`, {
name: `GameRoom_${roomId}`,
maxScenes: 3,
autoCleanup: true
});
// 房间内的Scene设置
const gameScene = roomWorld.createScene('game', new ServerGameScene());
const lobbyScene = roomWorld.createScene('lobby', new LobbyScene());
// 设置房间级的全局系统
roomWorld.addGlobalSystem(new RoomManagementSystem(roomId));
roomWorld.addGlobalSystem(new PlayerSyncSystem());
// 启动房间
roomWorld.start();
roomWorld.setSceneActive('lobby', true); // 默认激活大厅
this.rooms.set(roomId, roomWorld);
console.log(`创建房间: ${roomId}`);
return roomWorld;
}
// 开始游戏
startGame(roomId: string): boolean {
const roomWorld = this.rooms.get(roomId);
if (!roomWorld) return false;
// 停用大厅激活游戏Scene
roomWorld.setSceneActive('lobby', false);
roomWorld.setSceneActive('game', true);
console.log(`房间 ${roomId} 开始游戏`);
return true;
}
// 销毁房间
destroyRoom(roomId: string): boolean {
const roomWorld = this.rooms.get(roomId);
if (!roomWorld) return false;
roomWorld.destroy();
this.rooms.delete(roomId);
console.log(`销毁房间: ${roomId}`);
return true;
}
// 获取服务器状态
getServerStats() {
return {
totalRooms: this.rooms.size,
activeWorlds: this.worldManager.getActiveWorlds().length,
rooms: Array.from(this.rooms.keys()).map(roomId => ({
roomId,
world: this.rooms.get(roomId)?.getStatus()
}))
};
}
// 游戏循环
start(): void {
const gameLoop = () => {
const deltaTime = 1000 / 60; // 60 TPS
Core.update(deltaTime / 1000);
setTimeout(gameLoop, deltaTime);
};
gameLoop();
}
}
// 使用示例
const gameServer = new MultiRoomGameServer();
gameServer.start();
// 创建房间
const room1 = gameServer.createRoom('room_001');
const room2 = gameServer.createRoom('room_002');
// 开始游戏
setTimeout(() => {
gameServer.startGame('room_001');
}, 5000);
console.log('服务器状态:', gameServer.getServerStats());
```
### 3. 客户端多Scene管理示例
```typescript
class GameClient {
private worldManager: WorldManager;
private mainWorld: World;
constructor() {
Core.create({ debug: true });
Core.enableWorldManager();
this.worldManager = Core.getWorldManager();
this.setupGameWorld();
}
private setupGameWorld(): void {
// 创建主游戏世界
this.mainWorld = this.worldManager.createWorld('MainWorld', {
name: 'ClientWorld',
maxScenes: 10,
autoCleanup: false // 客户端通常不需要自动清理
});
// 创建不同层级的Scene
this.createGameplayScenes();
this.createUIScenes();
this.createEffectScenes();
// 启动世界
this.mainWorld.start();
this.activateDefaultScenes();
}
private createGameplayScenes(): void {
// 游戏主场景
const gameScene = this.mainWorld.createScene('gameplay', new GameplayScene());
// 背景场景
const backgroundScene = this.mainWorld.createScene('background', new BackgroundScene());
// 特效场景
const effectsScene = this.mainWorld.createScene('effects', new EffectsScene());
}
private createUIScenes(): void {
// 主UI场景
const mainUIScene = this.mainWorld.createScene('mainUI', new MainUIScene());
// 菜单场景
const menuScene = this.mainWorld.createScene('menu', new MenuScene());
// 设置场景
const settingsScene = this.mainWorld.createScene('settings', new SettingsScene());
}
private createEffectScenes(): void {
// 粒子效果场景
const particleScene = this.mainWorld.createScene('particles', new ParticleScene());
// 音效场景
const audioScene = this.mainWorld.createScene('audio', new AudioScene());
}
private activateDefaultScenes(): void {
// 激活基础Scene
this.mainWorld.setSceneActive('background', true);
this.mainWorld.setSceneActive('gameplay', true);
this.mainWorld.setSceneActive('mainUI', true);
this.mainWorld.setSceneActive('particles', true);
this.mainWorld.setSceneActive('audio', true);
// 菜单和设置默认不激活
this.mainWorld.setSceneActive('menu', false);
this.mainWorld.setSceneActive('settings', false);
}
// 切换到菜单
showMenu(): void {
this.mainWorld.setSceneActive('gameplay', false);
this.mainWorld.setSceneActive('menu', true);
}
// 切换回游戏
hideMenu(): void {
this.mainWorld.setSceneActive('menu', false);
this.mainWorld.setSceneActive('gameplay', true);
}
// 显示设置
showSettings(): void {
this.mainWorld.setSceneActive('settings', true);
}
// 隐藏设置
hideSettings(): void {
this.mainWorld.setSceneActive('settings', false);
}
// 获取World状态
getWorldStatus() {
return this.mainWorld.getStatus();
}
}
// 使用示例
const gameClient = new GameClient();
// 显示菜单
gameClient.showMenu();
// 5秒后返回游戏
setTimeout(() => {
gameClient.hideMenu();
}, 5000);
console.log('客户端World状态:', gameClient.getWorldStatus());
```
## 传统场景切换和管理
### 1. 单Scene模式场景管理器
> **注意:** 以下的 SceneManager、TransitionManager 等是自定义的场景管理类示例不是ECS框架提供的内置API。你可以基于这些示例实现自己的场景管理系统。
@@ -731,6 +1137,47 @@ A:
### Q: 多个场景可以同时存在吗?
A: 框架同时只支持一个活跃场景,但可以通过场景栈实现多场景管理(如暂停菜单)。
A:
- **单Scene模式**:框架同时只支持一个活跃场景,但可以通过场景栈实现多场景管理(如暂停菜单)
- **多World模式**每个World可以包含多个同时激活的Scene支持复杂的多场景架构
通过合理使用场景系统,你可以构建出结构清晰、性能优良的游戏架构!
### Q: 什么时候使用World系统
A:
- 多人游戏服务器(每个房间独立管理)
- 需要并发运行多个独立游戏世界
- 复杂的客户端架构游戏层、UI层、特效层分离
- 需要跨Scene的全局系统支持
### Q: World和Scene的性能影响
A:
- **单Scene模式**:最佳性能,适合简单项目
- **多World模式**每个World独立更新合理使用不会显著影响性能
- **建议**:根据项目复杂度选择合适的架构
### Q: 如何从单Scene迁移到多World
A:
```typescript
// 原始单Scene代码
const scene = new Scene();
Core.setScene(scene);
// 迁移到World模式可选
Core.enableWorldManager();
const world = Core.getWorldManager().createWorld('MainWorld');
const scene = world.createScene('main', new Scene());
world.start();
world.setSceneActive('main', true);
```
### Q: World系统的最佳实践
A:
1. **服务器端**每个游戏房间使用独立World
2. **客户端**按功能层级划分Scene游戏、UI、特效
3. **全局系统**将跨Scene的逻辑放在World的全局System中
4. **资源管理**使用World的autoCleanup功能自动清理空闲资源
通过合理选择单Scene或多World架构你可以构建出结构清晰、性能优良的游戏架构