shooter-demo/CLIENT_RUNNER_GUIDE.md

ClientRunner 集成说明

概览

ClientRunner 已更新为支持自动启动 Pinball Standalone 模式。它现在作为游戏的主入口点，自动管理 PinballManager 的创建和配置。

新增功能

1. 自动模式启动

• 根据 mode 属性自动启动相应的游戏模式
• 当前完全支持 RunMode.STANDALONE
• 为多人模式预留了扩展接口

2. 节点引用管理

• 主相机节点: 自动配置给 PinballManager
• 渲染容器: 游戏对象渲染的父节点
• UI容器: UI界面的容器节点

3. 智能回退

• 如果未设置渲染容器，自动使用当前节点
• 如果未设置相机节点，PinballManager 会尝试自动查找

使用方法

在场景中设置 ClientRunner

1. 添加 ClientRunner 组件

   在场景中创建一个节点（建议命名为 "GameManager"）
   添加 ClientRunner 组件
   

2. 配置属性

   运行模式: Standalone (选择下拉菜单中的值)
   主相机节点: 拖拽场景中的 Main Camera 节点
   渲染容器: 拖拽或创建一个渲染容器节点
   UI容器: 拖拽或创建一个UI容器节点（可选）
   

3. 运行游戏

   • 启动场景，ClientRunner 会自动：
     • 创建 PinballManager
     • 配置所有必需的引用
     • 启动 Standalone 模式
     • 开始弹珠物理模拟

代码示例

基本用法

// ClientRunner 会在 start() 方法中自动运行
// 无需手动调用

// 获取 PinballManager 实例（如果需要）
const pinballManager = clientRunner.getPinballManager();

// 重启游戏
await clientRunner.restart();

高级配置

// 在运行时切换模式（如果添加了对应实现）
clientRunner.mode = RunMode.CLIENT_MULTIPLAYER;
await clientRunner.restart();

// 检查当前模式
if (clientRunner.isMode('standalone')) {
    console.log('当前正在运行单机模式');
}

场景设置建议

推荐的节点层级结构

Scene
├── Main Camera (Camera 组件)
├── GameManager (ClientRunner 组件)
├── RenderContainer (空节点，用作渲染容器)
│   └── [游戏对象将在此创建]
└── UIContainer (空节点，UI元素容器)
    └── [UI元素]

最小设置

如果只想快速测试，最少只需要：

Scene
├── Main Camera
└── GameManager (ClientRunner 组件)
    ├── mode: Standalone
    └── cameraNode: Main Camera

控制台输出

成功启动时会看到以下日志：

[ClientRunner] 开始启动，运行模式: standalone
[ClientRunner] 启动 Standalone 模式...
[ClientRunner] Standalone 模式启动成功
[PinballManager] 初始化完成
[StandaloneMode] 初始化完成

游戏交互

启动成功后：

• 点击/触摸屏幕: 在点击位置创建弹珠
• 弹珠物理: 弹珠受重力影响下落并与边界碰撞
• 实时渲染: 弹珠位置实时更新显示

故障排除

常见问题

1. WASM 加载失败

   确保 assets/wasm/pinball_physics.wasm 文件存在
   文件大小应该是 666KB
   

2. 相机未找到

   检查 cameraNode 是否正确设置
   确保相机节点有 Camera 组件
   

3. 渲染不显示

   检查 renderContainer 设置
   确保渲染容器在相机视野内
   

4. 控制台错误

   查看具体错误信息
   检查所有必需的文件是否存在
   确认节点引用是否正确设置
   

扩展功能

为多人模式做准备

ClientRunner 已经为多人模式预留了接口：

• startClientMultiplayerMode()
• startServerMultiplayerMode()

当实现这些模式时，只需要在对应方法中添加逻辑即可。

自定义配置

可以通过修改 startStandaloneMode() 方法来自定义 PinballManager 的配置：

// 自定义物理参数
this.pinballManager.defaultMode = PinballMode.STANDALONE;
this.pinballManager.autoStart = true;
this.pinballManager.debugMode = false; // 关闭调试信息

这个更新让游戏启动变得更加简单和自动化，同时保持了扩展性和配置灵活性。