1
This commit is contained in:
115
docs/reference/RPG_SCRIPT_COMMENTARY_PROGRESS_2026-04-28.md
Normal file
115
docs/reference/RPG_SCRIPT_COMMENTARY_PROGRESS_2026-04-28.md
Normal file
@@ -0,0 +1,115 @@
|
||||
# RPG 脚本中文注释补充进度（2026-04-28）
|
||||
|
||||
## 1. 文档目的
|
||||
|
||||
这份文档用于记录当前仓库里 RPG 相关脚本的中文注释补充进度，避免后续“挨个补充”时重复扫描、重复改同一批文件，或者遗漏运行时主链上的关键脚本。
|
||||
|
||||
当前原则：
|
||||
|
||||
1. 先补职责最核心、状态流最复杂、后续最常被继续修改的脚本。
|
||||
2. 每一批都尽量按完整链路补，不只补单点文件。
|
||||
3. 注释以解释“为什么这样编排”“这一层负责什么边界”为主，不堆砌逐行翻译式废话。
|
||||
|
||||
---
|
||||
|
||||
## 2. 本轮已补充的脚本
|
||||
|
||||
### 2.1 RPG 运行时 session 主链
|
||||
|
||||
1. `src/hooks/rpg-session/useRpgRuntimeSession.ts`
|
||||
2. `src/hooks/rpg-session/useRpgSessionBootstrap.ts`
|
||||
3. `src/hooks/rpg-session/useRpgSessionPersistence.ts`
|
||||
|
||||
本轮重点：
|
||||
|
||||
1. 说明 session 装配器如何组合 bootstrap、story、combat、persistence。
|
||||
2. 说明自定义世界开局场景、首遇 NPC、初始装备与初始物品的装配原因。
|
||||
3. 说明自动存档、继续游戏、手动保存退出的状态边界。
|
||||
|
||||
### 2.2 RPG 运行时 story 主链
|
||||
|
||||
1. `src/hooks/rpg-runtime-story/useRpgRuntimeStory.ts`
|
||||
2. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryController.ts`
|
||||
3. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryFlow.ts`
|
||||
4. `src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts`
|
||||
5. `src/hooks/rpg-runtime-story/useRpgRuntimeStoryState.ts`
|
||||
6. `src/hooks/rpg-runtime-story/storyInteractionCoordinator.ts`
|
||||
7. `src/hooks/rpg-runtime-story/rpgRuntimeStoryGateway.ts`
|
||||
|
||||
本轮重点：
|
||||
|
||||
1. 说明 controller、flow、interaction、state 四层的职责切分。
|
||||
2. 说明 NPC 遭遇自动进入交互态、NPC 战斗快照桥接、地图旅行桥接的原因。
|
||||
3. 说明 story reset、story hydration、服务端动作结算的编排边界。
|
||||
|
||||
### 2.3 RPG 运行时 service / client 主链
|
||||
|
||||
1. `src/services/rpg-runtime/rpgRuntimeRequest.ts`
|
||||
2. `src/services/rpg-runtime/rpgRuntimeStoryClient.ts`
|
||||
3. `src/services/rpg-runtime/rpgSnapshotClient.ts`
|
||||
|
||||
本轮重点：
|
||||
|
||||
1. 说明 runtime 请求的统一重试策略。
|
||||
2. 说明服务端 `RuntimeStoryOptionView` 到前端 `StoryOption` 的适配原因。
|
||||
3. 说明远端快照读取、写入后为什么要先 rehydrate。
|
||||
|
||||
---
|
||||
|
||||
## 3. 建议的后续补充顺序
|
||||
|
||||
为了保持“按链路读得通”，下一轮建议继续按下面顺序推进：
|
||||
|
||||
### 3.1 运行时 story 子模块
|
||||
|
||||
1. `src/hooks/rpg-runtime-story/storyChoiceCoordinator.ts`
|
||||
2. `src/hooks/rpg-runtime-story/storyChoiceRuntime.ts`
|
||||
3. `src/hooks/rpg-runtime-story/storyRequestCoordinator.ts`
|
||||
4. `src/hooks/rpg-runtime-story/storyRequestRuntime.ts`
|
||||
5. `src/hooks/rpg-runtime-story/storyGenerationState.ts`
|
||||
6. `src/hooks/rpg-runtime-story/storyEncounterState.ts`
|
||||
7. `src/hooks/rpg-runtime-story/storyPresentation.ts`
|
||||
8. `src/hooks/rpg-runtime-story/sessionActions.ts`
|
||||
9. `src/hooks/rpg-runtime-story/progressionActions.ts`
|
||||
10. `src/hooks/rpg-runtime-story/npcInteraction.ts`
|
||||
11. `src/hooks/rpg-runtime-story/inventoryActions.ts`
|
||||
12. `src/hooks/rpg-runtime-story/goalFlow.ts`
|
||||
|
||||
原因：
|
||||
|
||||
1. 这些文件已经紧贴本轮完成的主编排层。
|
||||
2. 它们包含大量“局部规则 + 状态迁移 + UI 结果”的细节，最需要注释解释。
|
||||
|
||||
### 3.2 运行时 UI 与入口层
|
||||
|
||||
1. `src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`
|
||||
2. `src/components/rpg-runtime-shell/RpgRuntimeStageRouter.tsx`
|
||||
3. `src/components/rpg-runtime-panels/RpgRuntimePanelRouter.tsx`
|
||||
4. `src/components/rpg-runtime-panels/RpgAdventurePanel.tsx`
|
||||
5. `src/hooks/rpg-session/useRpgSessionBootstrap.ts` 周边引用组件
|
||||
6. `src/components/rpg-entry/` 目录里的 RPG 运行时入口桥接脚本
|
||||
|
||||
原因：
|
||||
|
||||
1. 主链编排层补完后，再补表现层会更容易写出真正有用的注释。
|
||||
2. 入口层里有兼容 façade，需要明确标出“不要继续堆复杂逻辑”的边界。
|
||||
|
||||
### 3.3 RPG 创作链
|
||||
|
||||
1. `src/services/rpg-creation/` 目录主 client
|
||||
2. `src/components/rpg-creation-result/` 主动作脚本
|
||||
3. `src/components/rpg-creation-editor/` 主编辑链
|
||||
4. `src/components/rpg-creation-asset-studio/` 角色资产工坊链
|
||||
|
||||
原因：
|
||||
|
||||
1. 创作链文件也很多，但当前运行时主链更核心、更常改。
|
||||
2. 等运行时链注释连续后，再切创作链更不容易打断理解。
|
||||
|
||||
---
|
||||
|
||||
## 4. 本轮备注
|
||||
|
||||
1. 本轮以局部补丁方式补注释，没有整文件重写。
|
||||
2. 本轮没有改业务逻辑，只补中文注释和进度文档。
|
||||
3. 后续每补完一批，建议同步更新本文件，保持可追踪。
|
||||
Reference in New Issue
Block a user