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. **配置属性**
   ```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; // 关闭调试信息
```

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