9.0 KiB
9.0 KiB
应用状态机 (App/AppStatus)
📋 模块概述
管理应用的整体状态流转,包括启动、登录、游戏等状态,基于 Framework/FSM 实现。
🎯 核心特性
- ✅ 应用状态流转管理
- ✅ 网络初始化
- ✅ 登录流程
- ✅ 游戏状态管理
- ✅ 状态生命周期
- ✅ 服务器消息监听
🗂️ 文件结构
App/AppStatus/
├── AppStatusManager.ts # 应用状态管理器
├── AppStatusBoot.ts # 启动状态
├── AppStatusLogin.ts # 登录状态
└── AppStatusGame.ts # 游戏状态
🔄 状态流转图
[启动 Boot] → [登录 Login] → [游戏 Game]
↑ ↓ ↓
└────────────┴──────────────┘
(退出/死亡返回登录)
📘 核心类详解
AppStatusManager - 应用状态管理器
职责: 管理应用的整体状态流转
class AppStatusManager {
private _fsm: FSM; // 底层状态机
// 获取单例
static getInstance(): AppStatusManager;
// 启动应用(从 Boot 状态开始)
start(): void;
// 切换状态
changeState(stateName: string, params?: any): void;
// 获取当前状态名称
getCurrentStateName(): string | null;
// 获取当前状态实例
getCurrentState(): any;
// 更新状态机(在主循环中调用)
update(dt: number): void;
// 获取底层 FSM 实例
getFSM(): FSM;
// 销毁管理器
destroy(): void;
}
AppStatusBoot - 启动状态
职责: 初始化网络管理器并连接服务器
class AppStatusBoot extends BaseState {
constructor(fsm: FSM);
// 进入启动状态
async onEnter(params?: any): Promise<void>;
// 初始化并连接网络
private async initAndConnectNet(): Promise<void>;
// 退出启动状态
onExit(): void;
}
执行流程:
- 设置服务协议
- 初始化网络配置
- 监听网络事件
- 连接服务器
- 连接成功后切换到登录状态
AppStatusLogin - 登录状态
职责: 显示登录界面,处理登录逻辑
class AppStatusLogin extends BaseState {
constructor(fsm: FSM);
// 进入登录状态
async onEnter(params?: any): Promise<void>;
// 显示登录 UI
private async showLoginUI(): Promise<void>;
// 退出登录状态
onExit(): void;
}
执行流程:
- 通过 UIMgr 加载并显示登录 UI
- 等待用户输入账号并点击登录
- UILogin 调用 NetManager 发送登录请求
- 登录成功后切换到游戏状态
AppStatusGame - 游戏状态
职责: 游戏主循环,处理游戏逻辑和服务器消息
class AppStatusGame extends BaseState {
private _player: any; // 玩家信息
private _isNewPlayer: boolean; // 是否新玩家
private _isPaused: boolean; // 是否暂停
constructor(fsm: FSM);
// 进入游戏状态
async onEnter(params?: any): Promise<void>;
// 加载游戏场景
private async loadGameScene(): Promise<void>;
// 初始化游戏
private async initGame(): Promise<void>;
// 监听服务器广播消息
private listenServerMessages(): void;
// 开始游戏
private startGame(): void;
// 游戏主循环
onUpdate(dt: number): void;
// 暂停游戏
pauseGame(): void;
// 恢复游戏
resumeGame(): void;
// 玩家死亡
private onPlayerDeath(): void;
// 退出游戏(返回登录)
quitGame(): void;
// 退出游戏状态
onExit(): void;
}
执行流程:
- 接收玩家信息
- 加载游戏场景
- 初始化玩家角色
- 监听服务器广播消息
- 开始游戏主循环
- 处理游戏逻辑和网络消息
📝 使用指南
1. 启动应用
import { AppStatusManager } from './App/AppStatus/AppStatusManager';
// 在 Boot 组件中启动
@ccclass('Boot')
export class Boot extends Component {
start() {
// 获取管理器实例
const appManager = AppStatusManager.getInstance();
// 启动应用
appManager.start();
}
update(deltaTime: number) {
// 在主循环中更新状态机
AppStatusManager.getInstance().update(deltaTime);
}
}
2. 切换状态
import { AppStatusManager } from './App/AppStatus/AppStatusManager';
// 从登录状态切换到游戏状态
AppStatusManager.getInstance().changeState('Game', {
player: playerInfo,
isNewPlayer: false
});
// 从游戏状态返回登录状态
AppStatusManager.getInstance().changeState('Login');
3. 获取当前状态
// 获取当前状态名称
const stateName = AppStatusManager.getInstance().getCurrentStateName();
console.log(`当前状态: ${stateName}`);
// 获取当前状态实例
const currentState = AppStatusManager.getInstance().getCurrentState();
🔄 完整流程示例
启动到游戏的完整流程
1. Boot 组件启动
↓
2. AppStatusManager.start()
↓
3. 切换到 Boot 状态
↓
4. 初始化网络并连接服务器
↓
5. 连接成功,切换到 Login 状态
↓
6. 加载并显示登录 UI
↓
7. 用户输入账号并点击登录
↓
8. 调用 Login API
↓
9. 登录成功,切换到 Game 状态
↓
10. 加载游戏场景
↓
11. 初始化玩家角色
↓
12. 监听服务器广播消息
↓
13. 开始游戏主循环
📡 网络协议使用
Boot 状态
// 配置网络
const config: NetConfig = {
serverUrl: 'http://localhost:3000',
timeout: 30000,
autoReconnect: true,
reconnectInterval: 3000,
maxReconnectTimes: 5
};
Login 状态
// 由 UILogin 调用登录 API
const result = await netManager.callApi<ReqLogin, ResLogin>('Login', {
account: account
});
// 登录成功后切换状态
if (result && result.success) {
AppStatusManager.getInstance().changeState('Game', {
player: result.player,
isNewPlayer: result.isNewPlayer
});
}
Game 状态
// 监听服务器广播
netManager.listenMsg<MsgPlayerJoin>('PlayerJoin', (msg) => {
console.log(`玩家 ${msg.playerName} 加入游戏`);
// 在场景中创建其他玩家
});
netManager.listenMsg<MsgPlayerMove>('PlayerMove', (msg) => {
console.log(`玩家 ${msg.playerName} 移动`);
// 更新其他玩家位置
});
// 发送 API
const result = await netManager.callApi<ReqMove, ResMove>('Move', {
x: targetX,
y: targetY
});
⚠️ 注意事项
- 状态切换参数: 切换到 Game 状态时必须传递 player 参数
- 网络初始化: Boot 状态必须在网络连接成功后才能切换状态
- 资源清理: 切换状态时注意清理前一个状态的资源
- 消息监听: Game 状态退出时要取消所有服务器消息监听
- 异步处理: 状态的 onEnter 方法是异步的,注意使用 await
🔍 调试技巧
状态切换日志
// BaseState 会自动输出状态切换日志
// [FSM] Enter state: Boot
// [FSM] Exit state: Boot
// [FSM] Enter state: Login
网络状态日志
// NetManager 会输出网络状态日志
// [NetManager] 网络已连接
// [NetManager] 网络已断开
// [NetManager] 正在重连...
游戏状态信息
// 在 Game 状态中查看玩家信息
const gameState = AppStatusManager.getInstance()
.getCurrentState() as AppStatusGame;
console.log('玩家信息:', gameState._player);
console.log('是否新玩家:', gameState._isNewPlayer);
💡 最佳实践
- 单一入口: 通过 AppStatusManager 统一管理所有状态切换
- 参数传递: 使用 params 在状态间传递必要的数据
- 资源管理: 每个状态负责自己的资源加载和释放
- 错误处理: 网络错误时提供友好的提示并返回合适的状态
- 状态独立: 每个状态保持独立,避免直接依赖其他状态
🎯 扩展状态
添加新状态
// 1. 创建新状态类
class AppStatusLobby extends BaseState {
constructor(fsm: FSM) {
super(fsm, "Lobby");
}
onEnter(params?: any): void {
super.onEnter(params);
console.log("[AppStatusLobby] 进入大厅");
// 显示大厅 UI
}
onExit(): void {
super.onExit();
// 清理大厅资源
}
}
// 2. 在 AppStatusManager 中注册
private initStates(): void {
this._fsm.addState(new AppStatusBoot(this._fsm));
this._fsm.addState(new AppStatusLogin(this._fsm));
this._fsm.addState(new AppStatusLobby(this._fsm)); // 新增
this._fsm.addState(new AppStatusGame(this._fsm));
}
// 3. 修改状态流转
// Login -> Lobby -> Game
📚 相关文档
- Framework/FSM README - 状态机框架
- Framework/Net README - 网络通信
- App/Login README - 登录模块