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

架构决策记录

2026-01-28 - 漫游功能 API 对接

决策背景

需要将漫游控制面板的 UI 回调对接到底层 3D 引擎的第一人称控制器 API。

关键决策

1. 只对接第一人称漫游基础功能

决策: 本次只对接 4 个核心功能：

• 第一人称漫游模式开关
• 速度调节
• 重力开关
• 碰撞检测开关

理由:

• V2 底层引擎只支持基础第一人称漫游
• 第三人称漫游、角色模型等功能需要底层集成 FirstPersonControls_.js
• 地图和路径漫游底层无对应 API

影响:

• UI 层保留了完整功能界面（为未来扩展预留）
• 暂不支持的功能保持现有行为（UI 控制或控制台输出）

2. 速度值在 Manager 层转换

决策: 在 WalkControlManager 层进行 UI 速度值到引擎速度值的转换

理由:

• UI 层使用 1-10 的用户友好范围
• 引擎层需要 0.01-0.1 的实际速度值
• Manager 层负责适配不同层级的数据格式

实现:

const engineSpeed = speed * 0.01;
this.registry.engine3d?.setWalkSpeed(engineSpeed);

3. 状态管理在 Engine 组件

决策: 在 Engine 组件维护 isWalkModeActive 状态

理由:

• Engine 组件是底层引擎的封装层
• 需要防止重复激活/停用导致的底层调用混乱
• 其他组件可通过 isFirstPersonModeActive() 查询状态

4. 所有注释使用中文

决策: 公共 API 的 TSDoc 注释全部使用中文

理由:

• 项目团队主要使用中文
• 提高 TypeScript IntelliSense 的可读性
• 与项目其他部分保持一致

5. 原子提交策略

决策: 每个功能层级独立提交 Git commit

提交顺序:

1. Engine 组件（底层封装）
2. EngineManager（管理器代理）
3. WalkControlManager（业务逻辑）
4. 文档更新

理由:

• 便于代码审查
• 便于问题回滚
• 清晰的功能演进历史

未来改进方向

1. 底层能力增强

• 考虑将 FirstPersonControls_.js 的功能集成到 V2
• 支持角色模型切换
• 支持小地图功能

2. 更多控制参数

• 视角转动速度 (lookSpeed)
• 玩家身高 (playerHeight)
• 相机翻转限制 (maxRotateX)

3. 状态持久化

• 记住用户的漫游设置
• 支持配置预设

参考资料

• 底层引擎: bim_engine_base/src/core/v2/modules/controlModule.ts
• 第一人称控制器: bim_engine_base/src/core/v2/controls/firstPersonCameraControl.js
• 旧版实现: bim_engine_base/src/core/v2/controls/FirstPersonControls_.js