项目进展

PINBALL_INTEGRATION_GUIDE.md

@@ -0,0 +1,135 @@
+# Pinball Standalone 模式集成指南
+
+## 场景集成步骤
+
+### 1. 打开 client-standalone.scene
+
+在Cocos Creator编辑器中打开 `client-cocos/assets/scenes/client-standalone.scene` 文件。
+
+### 2. 创建PinballManager节点
+
+1. 在场景层级面板中，右键点击根节点
+2. 选择"创建" -> "空节点"
+3. 重命名为 "PinballManager"
+
+### 3. 添加PinballManager脚本
+
+1. 选择 PinballManager 节点
+2. 在属性检查器中点击"添加组件"
+3. 搜索并添加 "PinballManager" 组件
+4. 组件位置：`assets/scripts/Modules/Pinball/PinballManager.ts`
+
+### 4. 设置必需的节点引用
+
+#### 4.1 设置相机节点
+
+1. 在场景中找到或创建主相机节点 "Main Camera"
+2. 在 PinballManager 组件中，将 "Main Camera" 节点拖拽到 "Camera Node" 字段
+
+#### 4.2 设置渲染容器
+
+1. 创建一个空节点命名为 "RenderContainer"
+2. 将此节点拖拽到 PinballManager 组件的 "Render Container" 字段
+
+#### 4.3 设置UI容器（可选）
+
+1. 创建一个空节点命名为 "UIContainer"
+2. 将此节点拖拽到 PinballManager 组件的 "UI Container" 字段
+
+### 5. 配置组件参数
+
+在 PinballManager 组件中设置以下参数：
+
+```
+Default Mode: Standalone
+Auto Start: true
+Debug Mode: true
+```
+
+### 6. 确保WASM文件存在
+
+确认以下文件存在：
+- `client-cocos/assets/wasm/pinball_physics.wasm` (666KB)
+
+### 7. 运行测试
+
+1. 保存场景
+2. 构建并运行项目
+3. 在 client-standalone 场景中应该能看到：
+   - 控制台输出 PinballManager 初始化信息
+   - 点击屏幕可以创建弹珠
+   - 弹珠受物理引擎控制下落
+
+## 预期功能
+
+### 输入交互
+- 鼠标点击：在点击位置创建弹珠
+- 触摸屏幕：在触摸位置创建弹珠
+
+### 物理模拟
+- 弹珠受重力影响下落
+- 弹珠与世界边界发生碰撞
+- 弹珠具有弹性和摩擦属性
+
+### 渲染效果
+- 弹珠以圆形图形渲染
+- 实时更新弹珠位置
+- 支持多个弹珠同时存在
+
+## 调试信息
+
+启用调试模式后，控制台会输出以下信息：
+- `[PinballManager] 初始化完成`
+- `[StandaloneMode] 初始化完成`
+- `[StandaloneMode] 创建弹珠 #X 在位置 (x, y)`
+
+## 故障排除
+
+### 常见问题
+
+1. **WASM加载失败**
+   - 检查 `assets/wasm/pinball_physics.wasm` 文件是否存在
+   - 确认文件大小为 666KB
+
+2. **节点引用缺失**
+   - 确保 Camera Node 和 Render Container 已正确设置
+   - 检查节点名称是否正确
+
+3. **输入无响应**
+   - 确认场景中存在主相机
+   - 检查输入事件是否被其他组件拦截
+
+4. **弹珠不显示**
+   - 检查渲染容器设置是否正确
+   - 确认 Graphics 组件正常工作
+
+## 技术架构
+
+### 组件关系
+```
+PinballManager (主控制器)
+├── StandaloneMode (游戏模式)
+│   ├── WasmPhysicsEngine (物理引擎)
+│   ├── PinballRenderer (渲染器)
+│   └── InputManager (输入管理)
+└── EventBus (事件通信)
+```
+
+### 事件流
+1. InputManager 捕获用户输入
+2. 发送 input.mouse.click/input.touch.start 事件
+3. StandaloneMode 接收事件并创建弹珠
+4. WasmPhysicsEngine 处理物理模拟
+5. PinballRenderer 渲染弹珠位置更新
+
+## 下一步
+
+这个基础的 Standalone 模式为后续开发提供了良好的基础：
+
+1. **增强渲染效果**：添加粒子效果、阴影、光照
+2. **添加游戏机制**：弹珠台元素、得分系统、目标
+3. **多人模式**：实现 Client/Server Multiplayer 模式
+4. **性能优化**：对象池、渲染批次优化
+5. **UI界面**：游戏菜单、设置、统计界面
+
+当前实现已完成 Pinball 物理世界的核心架构，可以作为更复杂功能的稳固基础。