项目进展

CLIENT_RUNNER_GUIDE.md

@@ -0,0 +1,162 @@
+# ClientRunner 集成说明
+
+## 概览
+
+`ClientRunner` 已更新为支持自动启动 Pinball Standalone 模式。它现在作为游戏的主入口点，自动管理 `PinballManager` 的创建和配置。
+
+## 新增功能
+
+### 1. 自动模式启动
+- 根据 `mode` 属性自动启动相应的游戏模式
+- 当前完全支持 `RunMode.STANDALONE`
+- 为多人模式预留了扩展接口
+
+### 2. 节点引用管理
+- **主相机节点**: 自动配置给 PinballManager
+- **渲染容器**: 游戏对象渲染的父节点
+- **UI容器**: UI界面的容器节点
+
+### 3. 智能回退
+- 如果未设置渲染容器，自动使用当前节点
+- 如果未设置相机节点，PinballManager 会尝试自动查找
+
+## 使用方法
+
+### 在场景中设置 ClientRunner
+
+1. **添加 ClientRunner 组件**
+   ```
+   在场景中创建一个节点（建议命名为 "GameManager"）
+   添加 ClientRunner 组件
+   ```
+
+2. **配置属性**
+   ```typescript
+   运行模式: Standalone (选择下拉菜单中的值)
+   主相机节点: 拖拽场景中的 Main Camera 节点
+   渲染容器: 拖拽或创建一个渲染容器节点
+   UI容器: 拖拽或创建一个UI容器节点（可选）
+   ```
+
+3. **运行游戏**
+   - 启动场景，ClientRunner 会自动：
+     - 创建 PinballManager
+     - 配置所有必需的引用
+     - 启动 Standalone 模式
+     - 开始弹珠物理模拟
+
+## 代码示例
+
+### 基本用法
+```typescript
+// ClientRunner 会在 start() 方法中自动运行
+// 无需手动调用
+
+// 获取 PinballManager 实例（如果需要）
+const pinballManager = clientRunner.getPinballManager();
+
+// 重启游戏
+await clientRunner.restart();
+```
+
+### 高级配置
+```typescript
+// 在运行时切换模式（如果添加了对应实现）
+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 的配置：
+```typescript
+// 自定义物理参数
+this.pinballManager.defaultMode = PinballMode.STANDALONE;
+this.pinballManager.autoStart = true;
+this.pinballManager.debugMode = false; // 关闭调试信息
+```
+
+这个更新让游戏启动变得更加简单和自动化，同时保持了扩展性和配置灵活性。