FishFlow Preview

-├── router.ts # createStackNavigator：pages + overlays，含类型注册 -├── error.tsx # 全局 ErrorBoundary fallback -├── actors/ # Stage 下的 actor（可视 + headless） -│ ├── background.tsx # 背景 + fade transition + tint spring -│ ├── character.tsx # 立绘（position / scale / tint / fade 动画） -│ ├── textbox.tsx # 文本框 + typewriter + 功能按钮 -│ ├── selection.tsx # 选项菜单（期间用 skip/auto blocker 阻断） -│ ├── bgm.tsx # BGM（headless） -│ ├── voice.tsx # 语音（headless，参与 auto ticket） -│ ├── sfx.tsx # 一次性音效（headless；skip 期间丢弃） -│ └── sound.tsx # 命名声道音效（headless） -├── commands/ -│ ├── commands.ts # Zod schema（含 x-i18n / x-asset-kind / format 等 meta） -│ └── handlers.ts # 命令响应层：更新框架状态与流程控制，让 Stage / actor 执行效果 -├── components/ # UI 组件：button / dialog / checkbox / slider / select / frame / notification -├── hooks/ -│ ├── useBacklog.ts # Backlog 滚动 + 滚动条 -│ ├── useButton.ts # 按钮状态机（idle / hover / press） -│ └── useSaveLoad.ts # 存读档槽位管理 -├── pages/ -│ ├── title.tsx # 标题画面 -│ ├── stage.tsx # 游戏主舞台：注册命令 + 装配 actor -│ └── menu.tsx / settings.tsx / saveload.tsx / backlog.tsx # overlay 页 -├── state/ -│ ├── game.ts # GameState（valtio proxy）+ resetGameState() -│ ├── ui.ts # UIState：通知队列、confirm 弹窗入口 -│ └── settings.ts # 设置（持久化到 scenario permanent variable） -└── utils/ - ├── mergeEvent.ts - └── scenarioGameState.ts # gameState ⇌ scenario variable 序列化/恢复 -``` - ---- - -## 架构 - -### App 生命周期 - -``` -引擎发 'ready' 事件 - → index.tsx 调 createRoot().render(

) - → ErrorBoundary 包 + - → router.ts 的 createStackNavigator（initialPage: 'title'） - → Title 页 -``` - -`index.tsx` 同时在 `beforeunload` 上挂了退出确认，会调 `system.quit`。 - -### Stage 两层架构 - -Stage 是剧情驱动 UI 的核心页面，采用严格的双层设计： - -- **Layer 1 — Command handler**（`commands/handlers.ts`）：负责响应 scenario 命令，更新框架状态与流程控制，让 Stage / actor 执行出对应效果。当前 handler 主要改 `gameState`、调用 `control.setWaiting()` / `control.hold()` / `control.record()`，并在少量需要与 backlog / 存档保持一致的路径上先同步 scenario 变量快照。 -- **Layer 2 — Actor**（`actors/*.tsx`）：React 组件，`useSnapshot` 订阅 `gameState`，承担副作用（音频、动画、节点命令、auto ticket）。 - -换句话说，handler 负责描述“命令发生后，框架状态应该变成什么、流程应该停在哪里”；actor 负责把这些状态变化落实成真实的视觉、音频和引擎行为。 - -**Stage 单例跨 HMR 保活**：`pages/stage.tsx` 把 stage 实例挂到 `globalThis.__MOYU_FRAMEWORK_STAGE__`，防止 Fast Refresh 重建 stage 后 scenario 事件监听错乱或 runtime 状态丢失： - -```typescript -// pages/stage.tsx -function getStageSingleton(): StageInstance { - const g = globalThis as StageGlobal; - g.__MOYU_FRAMEWORK_STAGE__ ??= createStage(); - return g.__MOYU_FRAMEWORK_STAGE__; -} - -const stage = getStageSingleton(); - -export function Stage() { - const params = useNavigationParams(); - const stories = useMemo(() => [params.story], [params.story]); - - useEffect(() => { - const unregs = registerStageHandlers(stage); - return () => unregs.forEach((fn) => fn()); - }, []); - - useScenario(stories, params.story, params.entry, params.isNewGame); - - return ( - - - - - - - - - - - ); -} -``` - -Stage 同时处理顶层输入： - -- 点击 / 触摸结束时，若 overlay 可见或选项菜单可见，则不推进剧情。 -- 若 textbox 当前不可见，则本次点击会先重新显示 textbox，并消费掉这次输入，不会继续推进剧情。 -- 在可推进状态下，Stage 会先让 `tryInterrupt()` 消费输入（例如完成打字机）；只有没有 interrupt callback 接管时才会 `nextLine()`。 -- `mousedown` / `touchstart` 会停止 skip；窗口失焦会同时停止 auto 和 skip。 -- 在 stage 页面且没有 overlay 时，滚轮向下会停止 auto 并打开 backlog overlay。 - -### 流程控制（GameControl） - -Handler 收到的 `control` 对象： - -| 方法 | 作用 | -|------|------| -| `control.hold()` | 暂停直到用户点击 / 按键；若在 skip 中且当前 dispatch `unskippable()` 则会停止 skip | -| `control.setWaiting(ms, skippable)` | 定时等待，到期或可跳过时由用户 / skip 触发推进 | -| `control.nextLine()` | 立即推进（少用） | -| `control.unskippable()` | 标记本次 dispatch 不可跳过 | -| `control.record(meta)` | 写入 backlog 历史，返回 id | - -**默认行为**（handler 不调任何 control 方法）：自动推进到下一行。 - -### 状态管理 - -**`gameState`**（`state/game.ts`，valtio proxy）—— 剧情可见、会被序列化到存档的状态： - -```typescript -gameState.story // { title } -gameState.background // { src, fadeTime, tint?, skippable } -gameState.character // { presets, characters[], currentSpeaker?, autoTintEnabled, autoTint } -gameState.textbox // { name, text, visible, printMode, printSpeed, fillColor, ... stroke/shadow 配置 } -gameState.bgm // { src, loop, volume?, fadeTime? } -gameState.voice // { src, channelName, volume? } -gameState.sfx // { seq, src, loop, volume?, fadeTime?, stopSeq, stopFadeTime? } -gameState.sound // { seq, channel, src, loop, ..., stopSeq, stopChannel, stopFadeTime? } -gameState.selection // { visible, options[], saveTo? } -``` - -- 读：actor / component 里走 `useSnapshot(gameState.xxx)`；不要在 render 路径中直接读 proxy。 -- 写：handler 直接改 proxy：`gameState.textbox.text = '...'`。 -- **存档流程**（`utils/scenarioGameState.ts`）：`writeCurrentGameStateToScenario()` 把当前 snapshot 写入 scenario 变量 `gameState`；`restoreGameStateFromScenario()` 恢复后会把 `sfx.seq` / `sfx.stopSeq` / `sound.seq` / `sound.stopSeq` 归零、并清空 `voice.src`，防止 actor 把恢复值当作新播放 / 停止请求而重放旧音频。 - -**`uiState`**（`state/ui.ts`）：通知队列 + `uiActions.notify()` / `uiActions.confirm()` / `uiActions.takeSnapshot()` 等辅助函数。`confirm` 通过 overlay navigator 的 `confirm` overlay 实现。 - -**`settingsState`**（`state/settings.ts`）：音量、文字速度、auto 间隔、skip 配置等。启动时从 scenario permanent variable `settings` 载入（兼容历史 Map 结构），首次为空会写入默认值。任何变更 debounce 300ms 回写。`auto_interval`（秒）会通过 `setDefaultAutoTailMs(auto_interval * 1000)` 同步给 kit 的 auto barrier。 - -**存档 / 读档 / Backlog 数据流**：框架同时维护引擎存档与 `gameState` 镜像，两者需要显式同步。 - -- 存档前，`useSaveLoad.saveToSlot()` 会先调用 `writeCurrentGameStateToScenario()`，把当前 `gameState` snapshot 写入 scenario 变量 `gameState`，再调用引擎 `saveGame`。 -- 读档后，`useSaveLoad.loadFromSlot()` 会先调用引擎 `loadGame`，再执行 `restoreGameStateFromScenario()` 把框架状态恢复回来。 -- backlog 跳转成功后，`useBacklog.jumpToRecord()` 也会调用 `restoreGameStateFromScenario()`，确保 UI 状态与 runtime snapshot 对齐。 -- `restoreGameStateFromScenario()` 会额外重置 `sfx` / `sound` 的 seq 触发器并清空 `voice.src`，避免恢复快照时把旧音频误当成新的播放请求。 - -**音频 actor 的 seq 模式**：`SfxActor` / `SoundActor` 不使用队列，而是 `seq` / `stopSeq` 计数器的变更检测 —— handler 每次播放 / 停止都自增 seq，actor 的 effect 以 seq 为依赖。SFX 在 skip 模式下直接丢弃（通过 `isSkippingRef` 防止 skip 结束后重放被抑制的请求）。两者都不发放 auto ticket，auto 模式不会等 sfx / sound 播完。 - ---- - -## 常见定制任务 - -### 新增一个命令 - -1. 在 `commands/commands.ts` 定义 Zod schema： - - ```typescript - const MyCommandSchema = z - .object({ - command: z.literal('myCommand'), - param1: z.string(), - param2: z.number().optional(), - }) - .describe('What this command does'); - ``` - - 并把它加入 `ScenarioCommandSchema` 的 union。涉及国际化 / 资源选择 / 颜色的字段加 `.meta({ title, format, 'x-asset-kind', 'x-i18n', 'x-i18n-desc' })` —— 这些元信息会直通 `commands.schema.json`，被外部编辑器（如 fishflow）消费。 - -2. 在 `commands/handlers.ts` 写 handler（负责根据命令更新框架状态与流程控制）： - - ```typescript - export const handleMyCommand: CommandHandler = (cmd, control) => { - if (cmd.command !== 'myCommand') return; - gameState.someField = cmd.param1; - // control.hold() / control.setWaiting(ms, skippable) / 或什么都不调（自动推进） - }; - ``` - -3. 在 `pages/stage.tsx` 的 `registerStageHandlers` 里注册： - - ```typescript - stage.registerCommand('myCommand', handleMyCommand), - ``` - -4. 运行 `yarn generate:schema` 刷新 `commands.schema.json`。 - -### Timed command（带过渡时长的命令）约定 - -涉及 `fadeTime` 的命令遵循统一约定，以便流程控制与 actor 行为一致： - -- **固定三参数**：`fadeTime` + `skippable` + `noWait`，均通过 Zod `.optional().default(...)` 给默认值，handler 拿到的总是具体值。 -- **每次都重写 state**：handler 里每次把 `fadeTime`（给 actor 用）写入对应 state，**不要**沿用前一次命令的残留，避免 state 泄漏。 -- **`noWait` 控制流程**：`!cmd.noWait` ⇒ handler 调 `control.setWaiting(cmd.fadeTime, cmd.skippable)` 阻塞剧情；`cmd.noWait` ⇒ handler **不调** `setWaiting`，立即放行下一条命令（允许并行动画）。 -- **state 保存粒度**：`fadeTime` 入 state（actor 读作动画时长）；`skippable` / `noWait` 通常只被 handler 消费，除非 actor 显式需要（例：`BackgroundState.skippable` 用于背景过渡期间是否可跳过）。 -- **默认值约定**（按现有命令对齐）： - - 视觉类（`bg` / `bgTint`）：`noWait: false`，默认等待过渡完成。 - - 音频类（`bgm` / `sfx` / `sound` 及其 stop 变体）：`noWait: true`，fire-and-forget。 - - 立绘类（`charEnter` / `charAction` / `charLeave` / `charClear`）：`noWait: true`。 - -### 新增一个 actor - -Actor 渲染于 `` 内部，共享 stage context。 - -**可视 actor**： - -```typescript -export function MyActor() { - const state = useSnapshot(gameState.myField); - const skipping = useIsSkipping(); - - // Finish any in-flight animation instantly when skip activates - useSkipCallback(() => { /* ... */ }); - - // Consume user click before scenario advances; return true if handled - useInterruptCallback(() => { /* return true when something was consumed */ }); - - return ...; -} -``` - -**Headless actor**： - -```typescript -export function MyHeadlessActor() { - const state = useSnapshot(gameState.myField); - useLayoutEffect(() => { - executePluginCommand('audio', { subCommand: 'play', /* ... */ }); - }, [state.src]); - return null; -} -``` - -**参与自动模式**：长耗时 actor（语音、视频等）用 `useAutoTicket()` 发放 ticket；auto barrier 会等所有 ticket `done()` 后才推进： - -```typescript -const issueAutoTicket = useAutoTicket(); -const ticket = issueAutoTicket({ label: 'voice:...' }); -// 异步完成时 ticket?.done()；提前取消 / 失败时 ticket?.cancel() -``` - -**阻断 skip / auto**：必须等用户操作的 actor（如选项菜单）用 blocker 而不是 skip callback： - -```typescript -const block = useCallback(() => gameState.selection.visible, []); -useSkipBlocker(block); -useAutoBlocker(block); -``` - -最后把 actor 挂到 `pages/stage.tsx` 的 JSX 树里。 - -### 新增一个页面 / overlay - -1. 在 `pages/` 或 `components/` 下写组件（只用 kit intrinsic element）。 -2. 在 `router.ts` 里注册；需要强校验参数时用 descriptor： - - ```typescript - pages: { mypage: MyPage } - overlays: { - myoverlay: { component: MyOverlay, requiredParams: ['x'] }, - } - ``` - -3. 导航： - - ```typescript - navigation.navigate('mypage', { /* ... */ }); - navigation.pushOverlay('myoverlay', { x: 1 }); - ``` - -### 新增一个可复用组件 - -放 `components/`，仅使用 kit intrinsic element 与现有 hook（如 `useButton`）： - -```typescript -export function MyButton({ label, onClick }: { label: string; onClick: () => void }) { - const { buttonState, handlers } = useButton({ onClick }); - return ( - - - - ); -} -``` - ---- - -## Kit API 速查 - -以下 API 均从 `@momoyu-ink/kit` 导入。精确字段定义见其 `src/bindings/` 下的 TS 类型。 - -### JSX 元素 - -| 元素 | 用途 | 关键 props | -|------|------|-----------| -| `` | 容器 / 布局节点 | 通用变换属性 | -| `` | 图片 | `src`, `area`, `mode`, `bounds` | -| `` | 文本 | `text`, `fontSize`, `fillColor`, `printMode`, `printSpeed`, `onFinish`, `onProgress` | -| `` | 裁剪 | 区域尺寸 | -| `

My New Game