feat(registry): 注册 ComponentDetailManager 到全局 Registry 和 BimEngine
This commit is contained in:
yuding
89
.sisyphus/notepads/walk-mode-api-integration/decisions.md
Normal file
89
.sisyphus/notepads/walk-mode-api-integration/decisions.md
Normal file
@@ -0,0 +1,89 @@
|
||||
# 架构决策记录
|
||||
|
||||
## 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`
|
||||
155
.sisyphus/notepads/walk-mode-api-integration/learnings.md
Normal file
155
.sisyphus/notepads/walk-mode-api-integration/learnings.md
Normal file
@@ -0,0 +1,155 @@
|
||||
# 漫游功能 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. **完整文档**: 调用链文档是关键，方便后续维护
|
||||
Reference in New Issue
Block a user