bim_engine/.sisyphus/notepads/walk-mode-api-integration/learnings.md

漫游功能 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 清单

// 模式切换
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

文档更新

调用链文档结构

## 5. 漫游 (Walk) - 第一人称漫游

### 5.1 第一人称漫游模式开关
[完整调用链]

### 5.2 速度调节
[完整调用链]

### 5.3 重力开关
[完整调用链]

### 5.4 碰撞检测开关
[完整调用链]

标注规范

• [SDK] = SDK 层代码
• [底层] = bim_engine_base 底层引擎
• 每个步骤都要标注层级

总结

成功完成

✅ 4 个核心功能对接完成 ✅ 完整的调用链文档 ✅ 所有单元构建通过 ✅ Git 提交符合规范

关键经验

1. 先调研后实现: 必须先了解底层 API 能力
2. 分层清晰: 每一层职责明确，不越界
3. 原子提交: 每个功能独立提交，便于回滚
4. 完整文档: 调用链文档是关键，方便后续维护