import { AnimationState, type StoryOption } from '../../../types';
import type { FunctionDocumentationEntry } from '../types';

/**
 * camp_travel_home_scene
 *
 * 从营地与同伴对话结束后，正式前往角色主线场景的控制 function。
 * 中文注释：前端只保留按钮构造、判定 helper 和视觉元信息；
 * 正式场景迁移、遭遇预览与快照写入统一由后端 resolver 承接。
 */
export const CAMP_TRAVEL_HOME_OPTION_VISUALS: StoryOption['visuals'] = {
  playerAnimation: AnimationState.RUN,
  playerMoveMeters: 1.1,
  playerOffsetY: 0,
  playerFacing: 'right',
  scrollWorld: false,
  monsterChanges: [],
};

export function buildCampTravelHomeOption(sceneName: string): StoryOption {
  return {
    functionId: CAMP_TRAVEL_HOME_FUNCTION.id,
    actionText: `前往 ${sceneName}`,
    text: `前往 ${sceneName}`,
    detailText: `离开营地，前往 ${sceneName}。`,
    visuals: CAMP_TRAVEL_HOME_OPTION_VISUALS,
  };
}

export function isCampTravelHomeFunctionId(functionId: string) {
  return functionId === CAMP_TRAVEL_HOME_FUNCTION.id;
}

export function isCampTravelHomeOption(option: StoryOption) {
  return isCampTravelHomeFunctionId(option.functionId);
}

export const CAMP_TRAVEL_HOME_FUNCTION: FunctionDocumentationEntry = {
  id: 'camp_travel_home_scene',
  domain: 'flow',
  title: '前往角色主场景',
  source: 'src/data/functionCatalog/flow/campTravelHomeScene.ts',
  summary: '营地开场后的专用旅行控制项。',
  detailedDescription:
    '它负责把开局同伴营地流程平稳切到角色真正的起始场景；正式目标场景、encounter 清理、战斗态清理和镜头残留状态由后端 resolver 写入。',
  trigger: '常见于开局同伴营地对话后的跟进选项。',
  execution:
    '点击后作为服务端 runtime function id 提交到 /api/story/sessions/{storySessionId}/actions/resolve，由后端执行定制场景迁移和历史写入。',
  result: '玩家会离开营地进入角色主场景，正式开始该角色的冒险线。',
  active: true,
  runtime: {
    storyMode: 'special_travel',
    uiMode: 'none',
    visuals: CAMP_TRAVEL_HOME_OPTION_VISUALS,
    executor:
      'server-rs/crates/module-runtime-story/src/session_action.rs -> resolve_story_runtime_action',
    animationNote:
      '前端保留 run 视觉元信息；正式状态以服务端 hydrated snapshot 为准。',
    storyNote:
      '后端写入离营结果、生成 encounter preview，并在新场景继续后续剧情。',
    uiNote: '这是专用旅行流程，不会打开 modal。',
  },
};