162 lines
4.2 KiB
Markdown
162 lines
4.2 KiB
Markdown
# 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; // 关闭调试信息
|
||
```
|
||
|
||
这个更新让游戏启动变得更加简单和自动化，同时保持了扩展性和配置灵活性。 |