90 lines
2.5 KiB
Markdown
90 lines
2.5 KiB
Markdown
# 架构决策记录
|
||
|
||
## 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 层负责适配不同层级的数据格式
|
||
|
||
**实现**:
|
||
```typescript
|
||
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`
|