1

src/hooks/rpg-runtime-story/useRpgRuntimeInteractionFlow.ts

@@ -62,6 +62,8 @@ export function createClearStoryInteractionUi(params: {
   clearNpcInteractionUi: () => void;
 }) {
   return () => {
+    // 中文注释：story 选择面板和 NPC 交互面板是两套独立 UI；
+    // 清理运行时交互态时必须同时重置，避免战斗/对话切换后残留旧弹层。
     params.clearStoryChoiceUi();
     params.clearNpcInteractionUi();
   };
@@ -120,6 +122,8 @@ export function useRpgRuntimeInteractionFlow({
     }
 
     if (isNpcEncounter(gameState.currentEncounter)) {
+      // 中文注释：当场景里已经解析出 NPC 遭遇，且当前不在战斗/加载中时，
+      // 自动进入 NPC 交互态，让开场相遇和旅行后遭遇都能无缝落到对话/互动面板。
       enterNpcInteraction(
         gameState.currentEncounter,
         `与${gameState.currentEncounter.npcName}搭话`,
@@ -180,6 +184,8 @@ export function useRpgRuntimeInteractionFlow({
       );
     },
   };
+  // 中文注释：choice coordinator 只关心“点下某个 story option 后怎么结算”，
+  // NPC 战斗结束后要不要回到对话态，则通过 runtimeSupport 在这里桥接进去。
   const choiceRuntimeSupport: ChoiceRuntimeSupport = {
     ...runtimeSupport,
     handleNpcBattleConversationContinuation: ({
@@ -248,6 +254,8 @@ export function useRpgRuntimeInteractionFlow({
         return false;
       }
 
+      // 中文注释：聊天提交是 fire-and-forget，
+      // 调用方只需要知道“当前能不能发给 NPC”，不需要阻塞等待整轮对话结束。
       void handleNpcChatTurn(encounter, input);
       return true;
     },
@@ -263,6 +271,8 @@ export function useRpgRuntimeInteractionFlow({
         return false;
       }
 
+      // 中文注释：NPC 聊天的“换一组回应建议”当前通过轮转 options 实现，
+      // 不额外发请求，优先复用本轮已经拿到的候选动作。
       interactionConfig.npcEncounterActions.setCurrentStory({
         ...story,
         options: [...restOptions, firstOption],