156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# 漫游功能 API 对接 - 学习笔记
|
||
|
||
## 完成时间
|
||
2026-01-28
|
||
|
||
## 项目结构理解
|
||
|
||
### SDK 层次架构
|
||
```
|
||
UI Layer (WalkControlPanel)
|
||
↓
|
||
Manager Layer (WalkControlManager)
|
||
↓
|
||
Engine Manager (EngineManager)
|
||
↓
|
||
Engine Component (Engine)
|
||
↓
|
||
底层引擎 (bim_engine_base)
|
||
```
|
||
|
||
### 关键模式
|
||
1. **Manager Pattern**: 所有功能通过 Manager 管理生命周期
|
||
2. **代理模式**: EngineManager 作为 Engine 的代理，提供统一访问点
|
||
3. **事件系统**: 使用 EventEmitter 进行组件间通信
|
||
|
||
## 底层 API 发现
|
||
|
||
### V2 vs 旧版差异
|
||
- **V2**: 使用简化版 `firstPersonCameraControl.js`，仅支持基础第一人称漫游
|
||
- **旧版**: `FirstPersonControls_.js` 包含人物模型、小地图等完整功能
|
||
- **教训**: 必须先确认底层版本，避免对接不存在的 API
|
||
|
||
### 底层 API 清单
|
||
```typescript
|
||
// 模式切换
|
||
controlModule.switchFirstPersonMode()
|
||
controlModule.switchDefaultMode()
|
||
|
||
// 第一人称控制属性
|
||
firstPersonControls.moveSpeed // 默认 0.02
|
||
firstPersonControls.applyGravity // 默认 false
|
||
firstPersonControls.applyCollision // 默认 true
|
||
```
|
||
|
||
## 实现细节
|
||
|
||
### 1. 速度值转换
|
||
- **UI 层**: 1-10 (用户友好)
|
||
- **引擎层**: 0.01-0.1 (实际速度)
|
||
- **转换公式**: `engineSpeed = uiSpeed * 0.01`
|
||
- **教训**: 必须在 Manager 层进行值转换，保持 UI 和引擎的解耦
|
||
|
||
### 2. 状态管理
|
||
- Engine 组件维护 `isWalkModeActive` 状态
|
||
- 防止重复激活/停用
|
||
- **教训**: 添加状态检查，避免不必要的底层调用
|
||
|
||
### 3. 错误处理
|
||
所有方法都需要检查：
|
||
1. 引擎是否初始化 (`this._isInitialized`)
|
||
2. 引擎实例是否存在 (`this.engine`)
|
||
3. 控制模块是否可用 (`this.engine.controlModule`)
|
||
|
||
## 代码规范
|
||
|
||
### 注释要求
|
||
- 所有公共方法使用 TSDoc 注释
|
||
- 必须使用中文
|
||
- 包含 `@param`, `@returns`, `@remarks`
|
||
|
||
### 控制台日志
|
||
- 使用统一前缀 `[Engine]`, `[EngineManager]`, `[WalkControl]`
|
||
- 错误用 `console.error()`, 警告用 `console.warn()`
|
||
|
||
## Git 提交策略
|
||
|
||
### 原子提交
|
||
每个任务独立提交：
|
||
1. `feat(engine): 新增漫游功能方法`
|
||
2. `feat(engine-manager): 暴露漫游功能方法`
|
||
3. `feat(walk-control): 对接漫游功能到底层 API`
|
||
4. `docs: 更新漫游功能调用链文档`
|
||
|
||
### Commit Message 格式
|
||
```
|
||
<type>(<scope>): <subject>
|
||
|
||
type: feat, fix, docs, refactor, test, chore
|
||
scope: 功能模块名称
|
||
subject: 简短描述（中文）
|
||
```
|
||
|
||
## 遗留问题
|
||
|
||
### 暂未实现的功能
|
||
- 行走/跑步模式切换（第三人称功能）
|
||
- 角色模型切换（V2 不支持）
|
||
- 地图/平面图（底层无 API）
|
||
- 路径漫游（底层无 API）
|
||
|
||
### 未来改进
|
||
1. 考虑将底层 `FirstPersonControls_.js` 功能集成到 V2
|
||
2. 添加更多漫游参数控制（视角速度、玩家高度等）
|
||
3. 实现漫游状态持久化
|
||
|
||
## 构建验证
|
||
|
||
### 验证步骤
|
||
1. TypeScript 编译: `tsc`
|
||
2. Vite 构建: `vite build`
|
||
3. 检查 dist 产物
|
||
|
||
### 构建结果
|
||
```
|
||
dist/iflow-engine.es.js 2,020.24 kB
|
||
dist/iflow-engine.umd.js 1,326.55 kB
|
||
```
|
||
|
||
## 文档更新
|
||
|
||
### 调用链文档结构
|
||
```markdown
|
||
## 5. 漫游 (Walk) - 第一人称漫游
|
||
|
||
### 5.1 第一人称漫游模式开关
|
||
[完整调用链]
|
||
|
||
### 5.2 速度调节
|
||
[完整调用链]
|
||
|
||
### 5.3 重力开关
|
||
[完整调用链]
|
||
|
||
### 5.4 碰撞检测开关
|
||
[完整调用链]
|
||
```
|
||
|
||
### 标注规范
|
||
- `[SDK]` = SDK 层代码
|
||
- `[底层]` = bim_engine_base 底层引擎
|
||
- 每个步骤都要标注层级
|
||
|
||
## 总结
|
||
|
||
### 成功完成
|
||
✅ 4 个核心功能对接完成
|
||
✅ 完整的调用链文档
|
||
✅ 所有单元构建通过
|
||
✅ Git 提交符合规范
|
||
|
||
### 关键经验
|
||
1. **先调研后实现**: 必须先了解底层 API 能力
|
||
2. **分层清晰**: 每一层职责明确，不越界
|
||
3. **原子提交**: 每个功能独立提交，便于回滚
|
||
4. **完整文档**: 调用链文档是关键，方便后续维护
|