建數(shù)據(jù)驅(qū)動(dòng)的互動(dòng)劇情引擎)
如果讓我把《異環(huán)關(guān)于我在異世界撿到青梅竹馬這件事》做成一個(gè)可玩的互動(dòng)劇情第一件事不是畫女主立繪也不是寫一萬字文案而是先想清楚劇情在代碼里到底存成什么。很多人做文字冒險(xiǎn)游戲習(xí)慣把劇情直接寫在組件里點(diǎn)一下按鈕更新一下 text再點(diǎn)一下再更新。這種寫法在三個(gè)節(jié)點(diǎn)的時(shí)候很好用等劇情超過三十個(gè)節(jié)點(diǎn)、開始出現(xiàn)分支和好感度變量時(shí)組件會(huì)膨脹到無法維護(hù)。更合理的做法是把劇情當(dāng)成數(shù)據(jù)把界面當(dāng)成渲染器把狀態(tài)管理當(dāng)成推進(jìn)器。這樣劇本可以單獨(dú)維護(hù)后續(xù)加配音、加立繪、加多結(jié)局都只是換數(shù)據(jù)源和增加渲染能力不需要重寫業(yè)務(wù)邏輯。這篇文章以《異環(huán)》作為項(xiàng)目代號以“在異世界撿到青梅竹馬”作為示例劇情一步步搭建一個(gè)基于 React TypeScript Zustand 的互動(dòng)劇情引擎。你可以把它理解為文字冒險(xiǎn)游戲的“最小可運(yùn)行骨架”也可以直接作為后續(xù)做 Galgame、視覺小說或敘事向小游戲的起點(diǎn)。文章會(huì)從劇情的數(shù)據(jù)結(jié)構(gòu)講起然后搭建工程、編寫狀態(tài)管理和界面渲染最后補(bǔ)上存檔、條件分支、常見排錯(cuò)和生產(chǎn)化建議。每一段代碼都可以直接復(fù)制到項(xiàng)目里運(yùn)行但更重要的是理解每個(gè)節(jié)點(diǎn)字段存在的理由。1. 互動(dòng)劇情的技術(shù)拆解把“撿到青梅竹馬”變成可計(jì)算的結(jié)構(gòu)1.1 劇情不是一段長文本而是一張有向圖傳統(tǒng)的線性小說閱讀體驗(yàn)是從第一行讀到最后一行讀者沒有選擇權(quán)?；?dòng)劇情不一樣玩家在關(guān)鍵節(jié)點(diǎn)做出的選擇會(huì)改變后續(xù)對話、角色好感度和最終結(jié)局。從技術(shù)角度看這就不是線性文本而是一張有向圖每個(gè)可停留的劇情片段是一個(gè)節(jié)點(diǎn)。一個(gè)對話說完后跳到哪個(gè)節(jié)點(diǎn)由next指向。一個(gè)選項(xiàng)節(jié)點(diǎn)包含多個(gè)分支出口每個(gè)出口也是一條邊。某些邊的顯示需要滿足變量條件比如好感度大于某個(gè)值。某些邊的觸發(fā)會(huì)修改變量比如選擇“叫出她的名字”后好感度 10。只要這張圖能穩(wěn)定表達(dá)寫劇情的人只關(guān)心節(jié)點(diǎn)內(nèi)容寫程序的人只關(guān)心節(jié)點(diǎn)如何被訪問。兩者通過一套約定好的數(shù)據(jù)結(jié)構(gòu)解耦。《異環(huán)》這個(gè)標(biāo)題里“異世界”是舞臺“撿到青梅竹馬”是核心事件。用技術(shù)語言翻譯一下玩家從“街道醒來”這個(gè)節(jié)點(diǎn)出發(fā)進(jìn)入“遇到熟悉身影”的對話遇到一個(gè)兩難選擇。選擇“叫出她的名字”會(huì)進(jìn)入好感度上漲的相認(rèn)結(jié)局選擇“表示不認(rèn)識”會(huì)進(jìn)入錯(cuò)過結(jié)局。這就是一個(gè)最小的有向圖。1.2 最小數(shù)據(jù)模型節(jié)點(diǎn)、選項(xiàng)、動(dòng)作和條件為了讓圖能夠被代碼執(zhí)行我建議把節(jié)點(diǎn)設(shè)計(jì)成可辨識的類型。一個(gè)劇情系統(tǒng)通常只需要三種基礎(chǔ)節(jié)點(diǎn)export type StoryNode | DialogNode | ChoiceNode | EndingNode; export interface DialogNode { id: string; type: dialog; speaker: string; text: string; next?: string; onEnter?: StoryAction[]; } export interface ChoiceNode { id: string; type: choice; text: string; choices: StoryChoice[]; onEnter?: StoryAction[]; } export interface EndingNode { id: string; type: ending; text: string; } export interface StoryChoice { label: string; next: string; condition?: StoryCondition; effect?: StoryAction[]; } export interface StoryCondition { key: string; op: | ! | | | | ; value: number | string | boolean; } export type StoryAction | { op: set; key: string; value: number | string | boolean } | { op: add; key: string; value: number };這里有幾個(gè)容易理解錯(cuò)的地方onEnter是進(jìn)入這個(gè)節(jié)點(diǎn)時(shí)立刻執(zhí)行的動(dòng)作適合做“剛走進(jìn)某個(gè)場景就觸發(fā)存檔點(diǎn)”或“一見到青梅竹馬就增加緊張值”這類邏輯。next只對對話節(jié)點(diǎn)有意義。如果對話節(jié)點(diǎn)沒有next就相當(dāng)于這個(gè)節(jié)點(diǎn)是當(dāng)前分支的終點(diǎn)。選擇節(jié)點(diǎn)自己不持有next它通過choices里的每個(gè)選項(xiàng)分別指向后續(xù)節(jié)點(diǎn)。condition不是“這個(gè)選項(xiàng)會(huì)觸發(fā)什么條件”而是“滿足什么條件時(shí)才顯示這個(gè)選項(xiàng)”。不滿足時(shí)當(dāng)前選擇節(jié)點(diǎn)里仍然可以顯示其他選項(xiàng)。effect是選擇這個(gè)選項(xiàng)之后、跳轉(zhuǎn)之前立刻生效的動(dòng)作。把動(dòng)作從節(jié)點(diǎn)里拆出來是因?yàn)閯∏槲陌附?jīng)常要調(diào)整“什么時(shí)候加好感度”。寫成聲明式動(dòng)作以后改好感度不需要改組件代碼只需要改數(shù)據(jù)。2. 從空目錄到可運(yùn)行工程Vite React TypeScript 環(huán)境準(zhǔn)備2.1 環(huán)境要求與依賴選擇在實(shí)際項(xiàng)目中我不會(huì)為了一個(gè) Demo 手寫 webpack 配置?；?dòng)劇情項(xiàng)目本身邏輯并不復(fù)雜主要工作量在數(shù)據(jù)結(jié)構(gòu)、狀態(tài)流轉(zhuǎn)和渲染交互上因此推薦用 Vite 快速搭建 React TypeScript 工程。推薦環(huán)境如下依賴版本建議說明Node.js18 或 20 LTSVite 5 需要 Node 18React18.x使用函數(shù)組件和 HooksTypeScript5.x提供節(jié)點(diǎn)類型約束Vite5.x開發(fā)服務(wù)器與構(gòu)建工具Zustand4.x輕量狀態(tài)管理適合保存游戲狀態(tài)nanoid5.x生成歷史記錄 ID可選也可用 Date.nowZustand 不是唯一選擇。你也可以用 useReducer Context不過當(dāng)項(xiàng)目出現(xiàn)存檔、歷史記錄、變量表和節(jié)點(diǎn)跳轉(zhuǎn)多處狀態(tài)聯(lián)動(dòng)時(shí)Zustand 的寫法和調(diào)試成本更低并且只在狀態(tài)真正變化時(shí)觸發(fā)組件重渲染。2.2 初始化項(xiàng)目和目錄結(jié)構(gòu)打開終端執(zhí)行下面命令創(chuàng)建項(xiàng)目npm create vitelatest yihuan-story -- --template react-ts cd yihuan-story npm install npm install zustand安裝完成后把src下的文件整理成下面結(jié)構(gòu)src/ ├── engine/ │ ├── types.ts # 劇情節(jié)點(diǎn)類型定義 │ ├── store.ts # Zustand 狀態(tài)管理 │ └── actions.ts # 動(dòng)作執(zhí)行、條件判斷工具 ├── data/ │ └── story.ts # 示例劇情數(shù)據(jù) ├── components/ │ ├── DialogPanel.tsx # 對話渲染 │ ├── ChoicePanel.tsx # 選項(xiàng)渲染 │ └── HistoryPanel.tsx # 歷史記錄 ├── App.tsx ├── main.tsx └── index.css這樣分層的原因是data只放劇本engine只放邏輯components只放渲染。以后換劇本只需要改data/story.ts引擎和界面可以完全復(fù)用。2.3 跑通一個(gè)空頁面先修改App.tsx為一個(gè)最簡單的渲染容器確保依賴安裝正確import ./App.css; function App() { return ( div classNamegame-container h1異環(huán)互動(dòng)劇情引擎/h1 p骨架已跑通。/p /div ); } export default App;運(yùn)行npm run dev瀏覽器打開終端提示的地址如果能看到頁面文字說明工程環(huán)境正常。這一步檢查點(diǎn)很明確沒有紅色報(bào)錯(cuò)終端沒有編譯異常瀏覽器控制臺沒有 404。3. 用數(shù)據(jù)驅(qū)動(dòng)劇情定義《異環(huán)》示例故事和引擎核心3.1 先寫一段能跑通的示例劇本為了讓后面每一步都有實(shí)際效果我們先把開頭這一段劇情寫入src/data/story.tsimport type { StoryNode } from ../engine/types; export const storyMap: Recordstring, StoryNode { start: { id: start, type: dialog, speaker: 系統(tǒng), text: 你在異世界的街道上醒來眼前是一塊寫著“歡迎來到異環(huán)”的路牌。, next: meet, }, meet: { id: meet, type: dialog, speaker: , text: “喂你怎么在這里我找了你半天?！? next: choice1, }, choice1: { id: choice1, type: choice, text: 你抬起頭看見一個(gè)熟悉的身影。, choices: [ { label: 叫出她的名字, next: recognize, effect: [{ op: set, key: affection, value: 10 }], }, { label: 表示不認(rèn)識, next: stranger, effect: [{ op: set, key: affection, value: -5 }], }, ], }, recognize: { id: recognize, type: dialog, speaker: 青梅竹馬, text: “果然是你笨蛋你怎么會(huì)跑到異世界來”, next: ending_good, }, stranger: { id: stranger, type: dialog, speaker: 青梅竹馬, text: “啊……抱歉我認(rèn)錯(cuò)人了?！彼拖骂^語氣明顯失落。, next: ending_normal, }, ending_good: { id: ending_good, type: ending, text: 異世界的第一天你重新遇到了最重要的人。結(jié)局相認(rèn)。, }, ending_normal: { id: ending_normal, type: ending, text: 你們擦肩而過。有些重逢只存在于異世界的偶然。結(jié)局錯(cuò)過。, }, };這段劇情雖然不是完整故事但覆蓋了對話節(jié)點(diǎn)、選擇節(jié)點(diǎn)、選項(xiàng)效果和結(jié)尾節(jié)點(diǎn)。后續(xù)加入條件分支時(shí)往choices里加condition字段即可。3.2 Zustand 狀態(tài)管理讓節(jié)點(diǎn)跳轉(zhuǎn)變成可追蹤的“狀態(tài)遷移”游戲狀態(tài)可以拆成四部分currentNodeId當(dāng)前處在哪個(gè)節(jié)點(diǎn)。vars全局變量表比如好感度、已收集物品、是否觸發(fā)過某個(gè)事件。history玩家經(jīng)過的節(jié)點(diǎn)記錄用于回溯和顯示歷史對話。isCompleted是否已經(jīng)到達(dá)結(jié)局。在src/engine/store.ts中實(shí)現(xiàn)核心 storeimport { create } from zustand; import type { StoryNode, StoryChoice, StoryAction } from ./types; import { storyMap } from ../data/story; import { applyActions, checkCondition } from ./actions; interface PersistedState { currentNodeId: string; vars: Recordstring, number | string | boolean; history: Array{ nodeId: string; choiceLabel?: string; time: number; }; } interface GameState extends PersistedState { isCompleted: boolean; goTo: (nodeId: string) void; selectChoice: (choice: StoryChoice) void; applyEnterActions: (node: StoryNode) void; reset: () void; save: () void; load: () boolean; clearSave: () void; } const SAVE_KEY yihuan-story-save-v1; const initialState: PersistedState { currentNodeId: start, vars: { affection: 0 }, history: [], }; export const useGameStore createGameState((set, get) ({ ...initialState, isCompleted: false, applyEnterActions: (node) { const actions node.onEnter ?? []; if (actions.length 0) return; set({ vars: applyActions(get().vars, actions) }); }, goTo: (nodeId) { const node storyMap[nodeId]; if (!node) { console.error([story-engine] 找不到節(jié)點(diǎn): ${nodeId}); return; } const history [ ...get().history, { nodeId, time: Date.now(), }, ]; set({ currentNodeId: nodeId, history, isCompleted: node.type ending, }); get().applyEnterActions(node); }, selectChoice: (choice) { const nextVars applyActions(get().vars, choice.effect ?? []); set({ vars: nextVars, history: [ ...get().history, { nodeId: get().currentNodeId, choiceLabel: choice.label, time: Date.now(), }, ], }); get().goTo(choice.next); }, reset: () { set({ ...initialState, isCompleted: false, }); }, save: () { const state get(); const data: PersistedState { currentNodeId: state.currentNodeId, vars: state.vars, history: state.history, }; localStorage.setItem(SAVE_KEY, JSON.stringify(data)); }, load: () { const raw localStorage.getItem(SAVE_KEY); if (!raw) return false; try { const data JSON.parse(raw) as PersistedState; if (!data.currentNodeId || !storyMap[data.currentNodeId]) { console.warn([story-engine] 存檔節(jié)點(diǎn)不存在忽略存檔); return false; } set({ currentNodeId: data.currentNodeId, vars: { ...data.vars }, history: Array.isArray(data.history) ? data.history : [], isCompleted: storyMap[data.currentNodeId]?.type ending, }); return true; } catch (err) { console.error([story-engine] 存檔解析失敗, err); return false; } }, clearSave: () { localStorage.removeItem(SAVE_KEY); }, }));這里有幾個(gè)關(guān)鍵設(shè)計(jì)決定applyEnterActions和goTo分離是為了在跳轉(zhuǎn)后立刻執(zhí)行節(jié)點(diǎn)的onEnter動(dòng)作。如果你把動(dòng)作放進(jìn)goTo的同一個(gè) set 里要注意動(dòng)作需要基于最新狀態(tài)計(jì)算避免出現(xiàn)連續(xù)跳轉(zhuǎn)時(shí)變量覆蓋。每次選擇都先記錄選擇標(biāo)簽再跳轉(zhuǎn)是為了后面歷史回看時(shí)能知道玩家當(dāng)時(shí)點(diǎn)了哪個(gè)選項(xiàng)。load里做節(jié)點(diǎn)存在性檢查非常重要。一旦劇情改版舊存檔可能指向不存在的節(jié)點(diǎn)。此時(shí)直接恢復(fù)會(huì)導(dǎo)致白屏比較好的方式是返回false由界面提示玩家開始新游戲。3.3 動(dòng)作執(zhí)行和條件判斷不需要 eval 的安全寫法我見過不少劇情引擎用eval執(zhí)行腳本字符串來修改變量雖然寫起來靈活但項(xiàng)目一旦引入玩家輸入或者外部數(shù)據(jù)eval就是安全隱患。這里使用結(jié)構(gòu)化的動(dòng)作和條件描述代碼寫起來稍長但足夠安全。在src/engine/actions.ts中實(shí)現(xiàn)import type { StoryAction, StoryCondition } from ./types; type Vars Recordstring, number | string | boolean; export function applyActions(vars: Vars, actions: StoryAction[]): Vars { let next: Vars { ...vars }; for (const action of actions) { switch (action.op) { case set: next { ...next, [action.key]: action.value }; break; case add: { const current next[action.key]; const base typeof current number ? current : 0; next { ...next, [action.key]: base action.value }; break; } default: console.warn([story-engine] 未知?jiǎng)幼? action); } } return next; } export function checkCondition( condition: StoryCondition | undefined, vars: Vars, ): boolean { if (!condition) return true; const left vars[condition.key]; switch (condition.op) { case : return left condition.value; case !: return left ! condition.value; case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); default: return true; } }使用結(jié)構(gòu)化條件后劇情數(shù)據(jù)變成這樣{ label: 告訴她你失憶了, next: sad_ending, condition: { key: affection, op: , value: 5 }, }條件字段不是必填項(xiàng)。沒有條件時(shí)選項(xiàng)永遠(yuǎn)顯示。4. 渲染層把節(jié)點(diǎn)數(shù)據(jù)變成可點(diǎn)擊的交互界面4.1 對話面板和選項(xiàng)面板在App.tsx中根據(jù)當(dāng)前節(jié)點(diǎn)類型渲染不同組件。先用最簡單的方式import { useEffect } from react; import { useGameStore } from ./engine/store; import { storyMap } from ./data/story; function App() { const currentNodeId useGameStore((s) s.currentNodeId); const isCompleted useGameStore((s) s.isCompleted); const goTo useGameStore((s) s.goTo); const selectChoice useGameStore((s) s.selectChoice); const reset useGameStore((s) s.reset); const save useGameStore((s) s.save); const load useGameStore((s) s.load); const clearSave useGameStore((s) s.clearSave); const node storyMap[currentNodeId]; useEffect(() { if (node?.type dialog node.next) { // 這里不自動(dòng)跳轉(zhuǎn)等待用戶點(diǎn)擊“繼續(xù)” } }, [currentNodeId, node]); if (!node) { return ( div classNamegame-container p當(dāng)前節(jié)點(diǎn)不存在可能存檔已失效。/p button onClick{() { clearSave(); reset(); }} 重新開始 /button /div ); } return ( div classNamegame-container div classNametoolbar button onClick{save}保存/button button onClick{() { if (load()) { // 存檔讀取成功后會(huì)自動(dòng)更新 currentNodeId } }} 讀檔 /button button onClick{reset}重置/button /div {node.type dialog ( div classNamedialog-box div classNamespeaker{node.speaker}/div div classNametext{node.text}/div {node.next ( button onClick{() goTo(node.next!)} 繼續(xù) /button )} /div )} {node.type choice ( div classNamechoice-box p classNamechoice-description{node.text}/p div classNamechoices {node.choices.map((choice) ( button key{choice.label} onClick{() selectChoice(choice)} {choice.label} /button ))} /div /div )} {node.type ending ( div classNameending-box p{node.text}/p button onClick{reset}重新開始/button /div )} {isCompleted p classNamecompleted-tip已到達(dá)結(jié)局/p} /div ); } export default App;注意上面的onClick{() goTo(node.next!)}中用了非空斷言因?yàn)閚ode.next在 if 內(nèi)已經(jīng)判斷存在。更穩(wěn)妥的寫法是抽出子函數(shù)避免 TypeScript 類型收窄問題。4.2 條件選項(xiàng)的隱藏邏輯上面的界面沒有處理condition。如果一個(gè)選項(xiàng)不滿足條件仍然顯示玩家點(diǎn)擊后會(huì)進(jìn)入你不希望進(jìn)入的劇情。正確做法是在渲染選項(xiàng)時(shí)過濾const availableChoices node.choices.filter((choice) checkCondition(choice.condition, useGameStore.getState().vars), );但在組件里直接讀取getState()不會(huì)觸發(fā)重渲染。更規(guī)范的方式是在組件里訂閱varsconst vars useGameStore((s) s.vars); const availableChoices node.choices.filter((choice) checkCondition(choice.condition, vars), );這樣當(dāng)變量變化時(shí)選項(xiàng)列表會(huì)自動(dòng)重新計(jì)算。4.3 歷史記錄讓玩家看到自己走過哪條路歷史記錄不一定是界面必需品但它是排查“玩家到底點(diǎn)了哪里”最好的工具。在 store 中我們已經(jīng)保存了history現(xiàn)在可以渲染到側(cè)邊欄const history useGameStore((s) s.history); div classNamehistory-panel h2經(jīng)歷/h2 {history.map((item, index) ( div key{${item.time}-${index}} [{item.nodeId}] {item.choiceLabel ? - ${item.choiceLabel} : } /div ))} /div這個(gè)簡單列表在開發(fā)階段很有價(jià)值。當(dāng)劇情跳轉(zhuǎn)不符合預(yù)期時(shí)你只需要看歷史記錄就能確認(rèn)玩家是不是在某個(gè)選擇節(jié)點(diǎn)進(jìn)入了錯(cuò)誤分支。5. 運(yùn)行驗(yàn)證從第一句話到結(jié)局把整個(gè)鏈路跑通5.1 正常流程驗(yàn)證啟動(dòng)項(xiàng)目后按以下路徑驗(yàn)證頁面顯示“你在異世界的街道上醒來”。點(diǎn)擊“繼續(xù)”進(jìn)入“”對話。點(diǎn)擊“繼續(xù)”進(jìn)入選擇節(jié)點(diǎn)看到兩個(gè)選項(xiàng)。點(diǎn)擊“叫出她的名字”控制臺打印affection變?yōu)?10進(jìn)入“果然是你笨蛋”。點(diǎn)擊“繼續(xù)”進(jìn)入“結(jié)局相認(rèn)”頁面出現(xiàn)“已到達(dá)結(jié)局”。打開 DevTools 的 Application 面板查看 Local Storage確認(rèn)yihuan-story-save-v1在點(diǎn)擊保存后出現(xiàn)。點(diǎn)擊“重置”確認(rèn)頁面回到開頭且存檔仍存在直到點(diǎn)擊“存檔”覆蓋或“清除”刪除。5.2 添加條件分支讓同一個(gè)節(jié)點(diǎn)在不同好感度下顯示不同選項(xiàng)為了驗(yàn)證條件引擎在choice1的choices中增加一個(gè)只有好感度足夠高時(shí)才出現(xiàn)的選項(xiàng){ label: 一把抱住她好感度 5, next: hug_ending, condition: { key: affection, op: , value: 5 }, effect: [{ op: add, key: affection, value: 5 }], }在初始狀態(tài)下affection為 0這個(gè)選項(xiàng)不會(huì)顯示。當(dāng)玩家先走一遍“叫出名字”流程保存后重置并讀檔affection變成 10此時(shí)再進(jìn)入選擇節(jié)點(diǎn)這個(gè)選項(xiàng)就會(huì)出現(xiàn)。這就是條件分支的基本效果。5.3 異常場景節(jié)點(diǎn)不存在、存檔損壞、變量類型錯(cuò)誤把storyMap中某個(gè)節(jié)點(diǎn)的next改成不存在的 id比如next: not_exist點(diǎn)擊“繼續(xù)”后控制臺會(huì)出現(xiàn)[story-engine] 找不到節(jié)點(diǎn): not_exist頁面不會(huì)跳轉(zhuǎn)因?yàn)?store 在goTo中做了存在性檢查。這是有意為之寧可停在原地報(bào)錯(cuò)也不要跳到 undefined 導(dǎo)致白屏。存檔損壞時(shí)手動(dòng)在 Local Storage 里把值改成{bad json點(diǎn)擊“讀檔”后 load 函數(shù)捕獲異常并返回 false。界面可以提示“存檔讀取失敗”而不是直接崩潰。變量類型錯(cuò)誤最容易出現(xiàn)在add操作上。比如affection被設(shè)成字符串10再做add時(shí)typeof current number判斷為 false會(huì)把 base 當(dāng)成 0于是結(jié)果變成0 10。表面看起來只是數(shù)值異常實(shí)際上會(huì)掩蓋劇本數(shù)據(jù)寫錯(cuò)的問題。建議在開發(fā)環(huán)境給vars加類型校驗(yàn)或者在控制臺打印警告。6. 常見問題排查從現(xiàn)象倒推原因問題現(xiàn)象常見原因檢查方式處理建議點(diǎn)擊選項(xiàng)后沒有反應(yīng)選項(xiàng)的next指向了不存在的節(jié)點(diǎn)打開控制臺看[story-engine] 找不到節(jié)點(diǎn)日志檢查 storyMap 中的 id修正next指向或補(bǔ)全缺失節(jié)點(diǎn)存檔讀取后白屏存檔里的節(jié)點(diǎn) id 在舊版本中存在新版本已被刪除在load中打印data.currentNodeId判斷節(jié)點(diǎn)是否存在增加節(jié)點(diǎn)存在性校驗(yàn)不存在時(shí)返回 false 并重新開始條件選項(xiàng)不顯示condition表達(dá)式寫錯(cuò)或者變量值從未初始化在面板組件中打印vars和checkCondition結(jié)果確保變量在initialState或onEnter中初始化繼續(xù)按鈕點(diǎn)擊后跳過多個(gè)節(jié)點(diǎn)goTo中額外調(diào)用了applyEnterActions而onEnter里又調(diào)用goTo檢查動(dòng)作鏈?zhǔn)欠裥纬蛇f歸跳轉(zhuǎn)不要把跳轉(zhuǎn)寫在onEnter動(dòng)作里動(dòng)作只修改變量繼續(xù)按鈕點(diǎn)擊后所有選項(xiàng)一起出現(xiàn)沒有在渲染前過濾condition只是把 choices 全部 map 出去檢查availableChoices是否基于vars過濾使用filter配合checkCondition并訂閱vars歷史記錄順序混亂history在selectChoice和goTo中重復(fù)追加檢查每條歷史記錄的時(shí)間戳和內(nèi)容統(tǒng)一只在一處追加歷史跳轉(zhuǎn)節(jié)點(diǎn)和選擇節(jié)點(diǎn)分別記錄排查時(shí)建議按下面的優(yōu)先級進(jìn)行先確認(rèn)當(dāng)前節(jié)點(diǎn) id 是不是預(yù)期值。在組件頂部打印currentNodeId。再確認(rèn)storyMap里是否存在該節(jié)點(diǎn)節(jié)點(diǎn)的type是否正確。再檢查變量表。在控制臺執(zhí)行useGameStore.getState().vars查看實(shí)時(shí)變量。再檢查條件判斷。手動(dòng)調(diào)用checkCondition({ key: affection, op: , value: 5 }, { affection: 10 })看返回結(jié)果。最后檢查界面渲染。確認(rèn)availableChoices和node是從同一個(gè) store 中讀取。7. 從 Demo 到完整項(xiàng)目架構(gòu)、存檔和內(nèi)容生產(chǎn)建議7.1 把劇情數(shù)據(jù)從 TS 文件挪到 JSON 或遠(yuǎn)程配置示例中劇情寫在story.ts里好處是類型檢查方便壞處是策劃改劇本需要改代碼。在正經(jīng)項(xiàng)目里劇本通常由策劃或敘事設(shè)計(jì)師維護(hù)他們不應(yīng)該接觸 TypeScript。推薦兩種方式開發(fā)期使用本地 JSON通過 Vite 的import直接讀取。上線后把劇情放在遠(yuǎn)程 CDN 或配置中心版本號和存檔綁定劇情更新時(shí)兼容舊存檔。如果劇情文件很大不要一次性把整棵樹加載到內(nèi)存?？梢园凑鹿?jié)拆分加載一章后再加載下一章。示例中的storyMap是全量數(shù)據(jù)適合小體量互動(dòng)故事超過幾百個(gè)節(jié)點(diǎn)的項(xiàng)目需要引入分片加載。7.2 存檔設(shè)計(jì)要帶版本號和結(jié)構(gòu)校驗(yàn)生產(chǎn)環(huán)境存檔不能只存currentNodeId和vars。建議增加saveVersion用于做遷移。updatedAt用于自動(dòng)存檔排序。storyVersion標(biāo)記當(dāng)前劇情版本劇情更新后決定是否允許讀檔。playTime用于統(tǒng)計(jì)玩家進(jìn)度。示例中的load已經(jīng)做了節(jié)點(diǎn)存在性檢查但生產(chǎn)環(huán)境還需要對vars做默認(rèn)值合并。否則新版本增加了變量affection舊存檔沒有這個(gè)鍵后續(xù)做條件判斷時(shí)會(huì)出現(xiàn) undefined 比較。7.3 可復(fù)用的生產(chǎn)檢查清單在發(fā)布互動(dòng)劇情項(xiàng)目前至少確認(rèn)以下事項(xiàng)已經(jīng)完成節(jié)點(diǎn) id 全局唯一且跳轉(zhuǎn)目標(biāo)全部存在。所有條件分支都能被至少一個(gè)前置狀態(tài)滿足避免出現(xiàn)無法觸發(fā)的分支。變量在進(jìn)入游戲時(shí)初始化條件判斷對 undefined 值有兜底。存檔包含版本號讀取失敗時(shí)有降級策略。所有異常路徑在 UI 上有提示而不是只在控制臺打印。音頻和立繪資源用懶加載避免開局加載整個(gè)劇情包。對save、load、clearSave做防抖避免連續(xù)點(diǎn)擊導(dǎo)致存檔覆蓋錯(cuò)亂。在測試環(huán)境制定一份“全分支通關(guān)測試表”每個(gè)選項(xiàng)點(diǎn)一遍每條結(jié)局跑一遍。如果要把這個(gè)引擎推到更復(fù)雜的方向可以繼續(xù)擴(kuò)展分支嵌套、音量控制、自動(dòng)存檔、多語言文本、文本變量插值比如在對話中顯示{affection}當(dāng)前值。核心仍然不變劇情是數(shù)據(jù)界面是渲染器狀態(tài)管理負(fù)責(zé)所有派生計(jì)算。理解了這層關(guān)系《異環(huán)》這個(gè)項(xiàng)目無論加多少內(nèi)容技術(shù)骨架都不會(huì)散。 用React+TypeScript和Zustand構(gòu)建數(shù)據(jù)驅(qū)動(dòng)的互動(dòng)劇情引擎
如果讓我把《異環(huán)關(guān)于我在異世界撿到青梅竹馬這件事》做成一個(gè)可玩的互動(dòng)劇情第一件事不是畫女主立繪也不是寫一萬字文案而是先想清楚劇情在代碼里到底存成什么。很多人做文字冒險(xiǎn)游戲習(xí)慣把劇情直接寫在組件里點(diǎn)一下按鈕更新一下 text再點(diǎn)一下再更新。這種寫法在三個(gè)節(jié)點(diǎn)的時(shí)候很好用等劇情超過三十個(gè)節(jié)點(diǎn)、開始出現(xiàn)分支和好感度變量時(shí)組件會(huì)膨脹到無法維護(hù)。更合理的做法是把劇情當(dāng)成數(shù)據(jù)把界面當(dāng)成渲染器把狀態(tài)管理當(dāng)成推進(jìn)器。這樣劇本可以單獨(dú)維護(hù)后續(xù)加配音、加立繪、加多結(jié)局都只是換數(shù)據(jù)源和增加渲染能力不需要重寫業(yè)務(wù)邏輯。這篇文章以《異環(huán)》作為項(xiàng)目代號以“在異世界撿到青梅竹馬”作為示例劇情一步步搭建一個(gè)基于 React TypeScript Zustand 的互動(dòng)劇情引擎。你可以把它理解為文字冒險(xiǎn)游戲的“最小可運(yùn)行骨架”也可以直接作為后續(xù)做 Galgame、視覺小說或敘事向小游戲的起點(diǎn)。文章會(huì)從劇情的數(shù)據(jù)結(jié)構(gòu)講起然后搭建工程、編寫狀態(tài)管理和界面渲染最后補(bǔ)上存檔、條件分支、常見排錯(cuò)和生產(chǎn)化建議。每一段代碼都可以直接復(fù)制到項(xiàng)目里運(yùn)行但更重要的是理解每個(gè)節(jié)點(diǎn)字段存在的理由。1. 互動(dòng)劇情的技術(shù)拆解把“撿到青梅竹馬”變成可計(jì)算的結(jié)構(gòu)1.1 劇情不是一段長文本而是一張有向圖傳統(tǒng)的線性小說閱讀體驗(yàn)是從第一行讀到最后一行讀者沒有選擇權(quán)?；?dòng)劇情不一樣玩家在關(guān)鍵節(jié)點(diǎn)做出的選擇會(huì)改變后續(xù)對話、角色好感度和最終結(jié)局。從技術(shù)角度看這就不是線性文本而是一張有向圖每個(gè)可停留的劇情片段是一個(gè)節(jié)點(diǎn)。一個(gè)對話說完后跳到哪個(gè)節(jié)點(diǎn)由next指向。一個(gè)選項(xiàng)節(jié)點(diǎn)包含多個(gè)分支出口每個(gè)出口也是一條邊。某些邊的顯示需要滿足變量條件比如好感度大于某個(gè)值。某些邊的觸發(fā)會(huì)修改變量比如選擇“叫出她的名字”后好感度 10。只要這張圖能穩(wěn)定表達(dá)寫劇情的人只關(guān)心節(jié)點(diǎn)內(nèi)容寫程序的人只關(guān)心節(jié)點(diǎn)如何被訪問。兩者通過一套約定好的數(shù)據(jù)結(jié)構(gòu)解耦。《異環(huán)》這個(gè)標(biāo)題里“異世界”是舞臺“撿到青梅竹馬”是核心事件。用技術(shù)語言翻譯一下玩家從“街道醒來”這個(gè)節(jié)點(diǎn)出發(fā)進(jìn)入“遇到熟悉身影”的對話遇到一個(gè)兩難選擇。選擇“叫出她的名字”會(huì)進(jìn)入好感度上漲的相認(rèn)結(jié)局選擇“表示不認(rèn)識”會(huì)進(jìn)入錯(cuò)過結(jié)局。這就是一個(gè)最小的有向圖。1.2 最小數(shù)據(jù)模型節(jié)點(diǎn)、選項(xiàng)、動(dòng)作和條件為了讓圖能夠被代碼執(zhí)行我建議把節(jié)點(diǎn)設(shè)計(jì)成可辨識的類型。一個(gè)劇情系統(tǒng)通常只需要三種基礎(chǔ)節(jié)點(diǎn)export type StoryNode | DialogNode | ChoiceNode | EndingNode; export interface DialogNode { id: string; type: dialog; speaker: string; text: string; next?: string; onEnter?: StoryAction[]; } export interface ChoiceNode { id: string; type: choice; text: string; choices: StoryChoice[]; onEnter?: StoryAction[]; } export interface EndingNode { id: string; type: ending; text: string; } export interface StoryChoice { label: string; next: string; condition?: StoryCondition; effect?: StoryAction[]; } export interface StoryCondition { key: string; op: | ! | | | | ; value: number | string | boolean; } export type StoryAction | { op: set; key: string; value: number | string | boolean } | { op: add; key: string; value: number };這里有幾個(gè)容易理解錯(cuò)的地方onEnter是進(jìn)入這個(gè)節(jié)點(diǎn)時(shí)立刻執(zhí)行的動(dòng)作適合做“剛走進(jìn)某個(gè)場景就觸發(fā)存檔點(diǎn)”或“一見到青梅竹馬就增加緊張值”這類邏輯。next只對對話節(jié)點(diǎn)有意義。如果對話節(jié)點(diǎn)沒有next就相當(dāng)于這個(gè)節(jié)點(diǎn)是當(dāng)前分支的終點(diǎn)。選擇節(jié)點(diǎn)自己不持有next它通過choices里的每個(gè)選項(xiàng)分別指向后續(xù)節(jié)點(diǎn)。condition不是“這個(gè)選項(xiàng)會(huì)觸發(fā)什么條件”而是“滿足什么條件時(shí)才顯示這個(gè)選項(xiàng)”。不滿足時(shí)當(dāng)前選擇節(jié)點(diǎn)里仍然可以顯示其他選項(xiàng)。effect是選擇這個(gè)選項(xiàng)之后、跳轉(zhuǎn)之前立刻生效的動(dòng)作。把動(dòng)作從節(jié)點(diǎn)里拆出來是因?yàn)閯∏槲陌附?jīng)常要調(diào)整“什么時(shí)候加好感度”。寫成聲明式動(dòng)作以后改好感度不需要改組件代碼只需要改數(shù)據(jù)。2. 從空目錄到可運(yùn)行工程Vite React TypeScript 環(huán)境準(zhǔn)備2.1 環(huán)境要求與依賴選擇在實(shí)際項(xiàng)目中我不會(huì)為了一個(gè) Demo 手寫 webpack 配置?；?dòng)劇情項(xiàng)目本身邏輯并不復(fù)雜主要工作量在數(shù)據(jù)結(jié)構(gòu)、狀態(tài)流轉(zhuǎn)和渲染交互上因此推薦用 Vite 快速搭建 React TypeScript 工程。推薦環(huán)境如下依賴版本建議說明Node.js18 或 20 LTSVite 5 需要 Node 18React18.x使用函數(shù)組件和 HooksTypeScript5.x提供節(jié)點(diǎn)類型約束Vite5.x開發(fā)服務(wù)器與構(gòu)建工具Zustand4.x輕量狀態(tài)管理適合保存游戲狀態(tài)nanoid5.x生成歷史記錄 ID可選也可用 Date.nowZustand 不是唯一選擇。你也可以用 useReducer Context不過當(dāng)項(xiàng)目出現(xiàn)存檔、歷史記錄、變量表和節(jié)點(diǎn)跳轉(zhuǎn)多處狀態(tài)聯(lián)動(dòng)時(shí)Zustand 的寫法和調(diào)試成本更低并且只在狀態(tài)真正變化時(shí)觸發(fā)組件重渲染。2.2 初始化項(xiàng)目和目錄結(jié)構(gòu)打開終端執(zhí)行下面命令創(chuàng)建項(xiàng)目npm create vitelatest yihuan-story -- --template react-ts cd yihuan-story npm install npm install zustand安裝完成后把src下的文件整理成下面結(jié)構(gòu)src/ ├── engine/ │ ├── types.ts # 劇情節(jié)點(diǎn)類型定義 │ ├── store.ts # Zustand 狀態(tài)管理 │ └── actions.ts # 動(dòng)作執(zhí)行、條件判斷工具 ├── data/ │ └── story.ts # 示例劇情數(shù)據(jù) ├── components/ │ ├── DialogPanel.tsx # 對話渲染 │ ├── ChoicePanel.tsx # 選項(xiàng)渲染 │ └── HistoryPanel.tsx # 歷史記錄 ├── App.tsx ├── main.tsx └── index.css這樣分層的原因是data只放劇本engine只放邏輯components只放渲染。以后換劇本只需要改data/story.ts引擎和界面可以完全復(fù)用。2.3 跑通一個(gè)空頁面先修改App.tsx為一個(gè)最簡單的渲染容器確保依賴安裝正確import ./App.css; function App() { return ( div classNamegame-container h1異環(huán)互動(dòng)劇情引擎/h1 p骨架已跑通。/p /div ); } export default App;運(yùn)行npm run dev瀏覽器打開終端提示的地址如果能看到頁面文字說明工程環(huán)境正常。這一步檢查點(diǎn)很明確沒有紅色報(bào)錯(cuò)終端沒有編譯異常瀏覽器控制臺沒有 404。3. 用數(shù)據(jù)驅(qū)動(dòng)劇情定義《異環(huán)》示例故事和引擎核心3.1 先寫一段能跑通的示例劇本為了讓后面每一步都有實(shí)際效果我們先把開頭這一段劇情寫入src/data/story.tsimport type { StoryNode } from ../engine/types; export const storyMap: Recordstring, StoryNode { start: { id: start, type: dialog, speaker: 系統(tǒng), text: 你在異世界的街道上醒來眼前是一塊寫著“歡迎來到異環(huán)”的路牌。, next: meet, }, meet: { id: meet, type: dialog, speaker: , text: “喂你怎么在這里我找了你半天?！? next: choice1, }, choice1: { id: choice1, type: choice, text: 你抬起頭看見一個(gè)熟悉的身影。, choices: [ { label: 叫出她的名字, next: recognize, effect: [{ op: set, key: affection, value: 10 }], }, { label: 表示不認(rèn)識, next: stranger, effect: [{ op: set, key: affection, value: -5 }], }, ], }, recognize: { id: recognize, type: dialog, speaker: 青梅竹馬, text: “果然是你笨蛋你怎么會(huì)跑到異世界來”, next: ending_good, }, stranger: { id: stranger, type: dialog, speaker: 青梅竹馬, text: “啊……抱歉我認(rèn)錯(cuò)人了?！彼拖骂^語氣明顯失落。, next: ending_normal, }, ending_good: { id: ending_good, type: ending, text: 異世界的第一天你重新遇到了最重要的人。結(jié)局相認(rèn)。, }, ending_normal: { id: ending_normal, type: ending, text: 你們擦肩而過。有些重逢只存在于異世界的偶然。結(jié)局錯(cuò)過。, }, };這段劇情雖然不是完整故事但覆蓋了對話節(jié)點(diǎn)、選擇節(jié)點(diǎn)、選項(xiàng)效果和結(jié)尾節(jié)點(diǎn)。后續(xù)加入條件分支時(shí)往choices里加condition字段即可。3.2 Zustand 狀態(tài)管理讓節(jié)點(diǎn)跳轉(zhuǎn)變成可追蹤的“狀態(tài)遷移”游戲狀態(tài)可以拆成四部分currentNodeId當(dāng)前處在哪個(gè)節(jié)點(diǎn)。vars全局變量表比如好感度、已收集物品、是否觸發(fā)過某個(gè)事件。history玩家經(jīng)過的節(jié)點(diǎn)記錄用于回溯和顯示歷史對話。isCompleted是否已經(jīng)到達(dá)結(jié)局。在src/engine/store.ts中實(shí)現(xiàn)核心 storeimport { create } from zustand; import type { StoryNode, StoryChoice, StoryAction } from ./types; import { storyMap } from ../data/story; import { applyActions, checkCondition } from ./actions; interface PersistedState { currentNodeId: string; vars: Recordstring, number | string | boolean; history: Array{ nodeId: string; choiceLabel?: string; time: number; }; } interface GameState extends PersistedState { isCompleted: boolean; goTo: (nodeId: string) void; selectChoice: (choice: StoryChoice) void; applyEnterActions: (node: StoryNode) void; reset: () void; save: () void; load: () boolean; clearSave: () void; } const SAVE_KEY yihuan-story-save-v1; const initialState: PersistedState { currentNodeId: start, vars: { affection: 0 }, history: [], }; export const useGameStore createGameState((set, get) ({ ...initialState, isCompleted: false, applyEnterActions: (node) { const actions node.onEnter ?? []; if (actions.length 0) return; set({ vars: applyActions(get().vars, actions) }); }, goTo: (nodeId) { const node storyMap[nodeId]; if (!node) { console.error([story-engine] 找不到節(jié)點(diǎn): ${nodeId}); return; } const history [ ...get().history, { nodeId, time: Date.now(), }, ]; set({ currentNodeId: nodeId, history, isCompleted: node.type ending, }); get().applyEnterActions(node); }, selectChoice: (choice) { const nextVars applyActions(get().vars, choice.effect ?? []); set({ vars: nextVars, history: [ ...get().history, { nodeId: get().currentNodeId, choiceLabel: choice.label, time: Date.now(), }, ], }); get().goTo(choice.next); }, reset: () { set({ ...initialState, isCompleted: false, }); }, save: () { const state get(); const data: PersistedState { currentNodeId: state.currentNodeId, vars: state.vars, history: state.history, }; localStorage.setItem(SAVE_KEY, JSON.stringify(data)); }, load: () { const raw localStorage.getItem(SAVE_KEY); if (!raw) return false; try { const data JSON.parse(raw) as PersistedState; if (!data.currentNodeId || !storyMap[data.currentNodeId]) { console.warn([story-engine] 存檔節(jié)點(diǎn)不存在忽略存檔); return false; } set({ currentNodeId: data.currentNodeId, vars: { ...data.vars }, history: Array.isArray(data.history) ? data.history : [], isCompleted: storyMap[data.currentNodeId]?.type ending, }); return true; } catch (err) { console.error([story-engine] 存檔解析失敗, err); return false; } }, clearSave: () { localStorage.removeItem(SAVE_KEY); }, }));這里有幾個(gè)關(guān)鍵設(shè)計(jì)決定applyEnterActions和goTo分離是為了在跳轉(zhuǎn)后立刻執(zhí)行節(jié)點(diǎn)的onEnter動(dòng)作。如果你把動(dòng)作放進(jìn)goTo的同一個(gè) set 里要注意動(dòng)作需要基于最新狀態(tài)計(jì)算避免出現(xiàn)連續(xù)跳轉(zhuǎn)時(shí)變量覆蓋。每次選擇都先記錄選擇標(biāo)簽再跳轉(zhuǎn)是為了后面歷史回看時(shí)能知道玩家當(dāng)時(shí)點(diǎn)了哪個(gè)選項(xiàng)。load里做節(jié)點(diǎn)存在性檢查非常重要。一旦劇情改版舊存檔可能指向不存在的節(jié)點(diǎn)。此時(shí)直接恢復(fù)會(huì)導(dǎo)致白屏比較好的方式是返回false由界面提示玩家開始新游戲。3.3 動(dòng)作執(zhí)行和條件判斷不需要 eval 的安全寫法我見過不少劇情引擎用eval執(zhí)行腳本字符串來修改變量雖然寫起來靈活但項(xiàng)目一旦引入玩家輸入或者外部數(shù)據(jù)eval就是安全隱患。這里使用結(jié)構(gòu)化的動(dòng)作和條件描述代碼寫起來稍長但足夠安全。在src/engine/actions.ts中實(shí)現(xiàn)import type { StoryAction, StoryCondition } from ./types; type Vars Recordstring, number | string | boolean; export function applyActions(vars: Vars, actions: StoryAction[]): Vars { let next: Vars { ...vars }; for (const action of actions) { switch (action.op) { case set: next { ...next, [action.key]: action.value }; break; case add: { const current next[action.key]; const base typeof current number ? current : 0; next { ...next, [action.key]: base action.value }; break; } default: console.warn([story-engine] 未知?jiǎng)幼? action); } } return next; } export function checkCondition( condition: StoryCondition | undefined, vars: Vars, ): boolean { if (!condition) return true; const left vars[condition.key]; switch (condition.op) { case : return left condition.value; case !: return left ! condition.value; case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); case : return (left as number) (condition.value as number); default: return true; } }使用結(jié)構(gòu)化條件后劇情數(shù)據(jù)變成這樣{ label: 告訴她你失憶了, next: sad_ending, condition: { key: affection, op: , value: 5 }, }條件字段不是必填項(xiàng)。沒有條件時(shí)選項(xiàng)永遠(yuǎn)顯示。4. 渲染層把節(jié)點(diǎn)數(shù)據(jù)變成可點(diǎn)擊的交互界面4.1 對話面板和選項(xiàng)面板在App.tsx中根據(jù)當(dāng)前節(jié)點(diǎn)類型渲染不同組件。先用最簡單的方式import { useEffect } from react; import { useGameStore } from ./engine/store; import { storyMap } from ./data/story; function App() { const currentNodeId useGameStore((s) s.currentNodeId); const isCompleted useGameStore((s) s.isCompleted); const goTo useGameStore((s) s.goTo); const selectChoice useGameStore((s) s.selectChoice); const reset useGameStore((s) s.reset); const save useGameStore((s) s.save); const load useGameStore((s) s.load); const clearSave useGameStore((s) s.clearSave); const node storyMap[currentNodeId]; useEffect(() { if (node?.type dialog node.next) { // 這里不自動(dòng)跳轉(zhuǎn)等待用戶點(diǎn)擊“繼續(xù)” } }, [currentNodeId, node]); if (!node) { return ( div classNamegame-container p當(dāng)前節(jié)點(diǎn)不存在可能存檔已失效。/p button onClick{() { clearSave(); reset(); }} 重新開始 /button /div ); } return ( div classNamegame-container div classNametoolbar button onClick{save}保存/button button onClick{() { if (load()) { // 存檔讀取成功后會(huì)自動(dòng)更新 currentNodeId } }} 讀檔 /button button onClick{reset}重置/button /div {node.type dialog ( div classNamedialog-box div classNamespeaker{node.speaker}/div div classNametext{node.text}/div {node.next ( button onClick{() goTo(node.next!)} 繼續(xù) /button )} /div )} {node.type choice ( div classNamechoice-box p classNamechoice-description{node.text}/p div classNamechoices {node.choices.map((choice) ( button key{choice.label} onClick{() selectChoice(choice)} {choice.label} /button ))} /div /div )} {node.type ending ( div classNameending-box p{node.text}/p button onClick{reset}重新開始/button /div )} {isCompleted p classNamecompleted-tip已到達(dá)結(jié)局/p} /div ); } export default App;注意上面的onClick{() goTo(node.next!)}中用了非空斷言因?yàn)閚ode.next在 if 內(nèi)已經(jīng)判斷存在。更穩(wěn)妥的寫法是抽出子函數(shù)避免 TypeScript 類型收窄問題。4.2 條件選項(xiàng)的隱藏邏輯上面的界面沒有處理condition。如果一個(gè)選項(xiàng)不滿足條件仍然顯示玩家點(diǎn)擊后會(huì)進(jìn)入你不希望進(jìn)入的劇情。正確做法是在渲染選項(xiàng)時(shí)過濾const availableChoices node.choices.filter((choice) checkCondition(choice.condition, useGameStore.getState().vars), );但在組件里直接讀取getState()不會(huì)觸發(fā)重渲染。更規(guī)范的方式是在組件里訂閱varsconst vars useGameStore((s) s.vars); const availableChoices node.choices.filter((choice) checkCondition(choice.condition, vars), );這樣當(dāng)變量變化時(shí)選項(xiàng)列表會(huì)自動(dòng)重新計(jì)算。4.3 歷史記錄讓玩家看到自己走過哪條路歷史記錄不一定是界面必需品但它是排查“玩家到底點(diǎn)了哪里”最好的工具。在 store 中我們已經(jīng)保存了history現(xiàn)在可以渲染到側(cè)邊欄const history useGameStore((s) s.history); div classNamehistory-panel h2經(jīng)歷/h2 {history.map((item, index) ( div key{${item.time}-${index}} [{item.nodeId}] {item.choiceLabel ? - ${item.choiceLabel} : } /div ))} /div這個(gè)簡單列表在開發(fā)階段很有價(jià)值。當(dāng)劇情跳轉(zhuǎn)不符合預(yù)期時(shí)你只需要看歷史記錄就能確認(rèn)玩家是不是在某個(gè)選擇節(jié)點(diǎn)進(jìn)入了錯(cuò)誤分支。5. 運(yùn)行驗(yàn)證從第一句話到結(jié)局把整個(gè)鏈路跑通5.1 正常流程驗(yàn)證啟動(dòng)項(xiàng)目后按以下路徑驗(yàn)證頁面顯示“你在異世界的街道上醒來”。點(diǎn)擊“繼續(xù)”進(jìn)入“”對話。點(diǎn)擊“繼續(xù)”進(jìn)入選擇節(jié)點(diǎn)看到兩個(gè)選項(xiàng)。點(diǎn)擊“叫出她的名字”控制臺打印affection變?yōu)?10進(jìn)入“果然是你笨蛋”。點(diǎn)擊“繼續(xù)”進(jìn)入“結(jié)局相認(rèn)”頁面出現(xiàn)“已到達(dá)結(jié)局”。打開 DevTools 的 Application 面板查看 Local Storage確認(rèn)yihuan-story-save-v1在點(diǎn)擊保存后出現(xiàn)。點(diǎn)擊“重置”確認(rèn)頁面回到開頭且存檔仍存在直到點(diǎn)擊“存檔”覆蓋或“清除”刪除。5.2 添加條件分支讓同一個(gè)節(jié)點(diǎn)在不同好感度下顯示不同選項(xiàng)為了驗(yàn)證條件引擎在choice1的choices中增加一個(gè)只有好感度足夠高時(shí)才出現(xiàn)的選項(xiàng){ label: 一把抱住她好感度 5, next: hug_ending, condition: { key: affection, op: , value: 5 }, effect: [{ op: add, key: affection, value: 5 }], }在初始狀態(tài)下affection為 0這個(gè)選項(xiàng)不會(huì)顯示。當(dāng)玩家先走一遍“叫出名字”流程保存后重置并讀檔affection變成 10此時(shí)再進(jìn)入選擇節(jié)點(diǎn)這個(gè)選項(xiàng)就會(huì)出現(xiàn)。這就是條件分支的基本效果。5.3 異常場景節(jié)點(diǎn)不存在、存檔損壞、變量類型錯(cuò)誤把storyMap中某個(gè)節(jié)點(diǎn)的next改成不存在的 id比如next: not_exist點(diǎn)擊“繼續(xù)”后控制臺會(huì)出現(xiàn)[story-engine] 找不到節(jié)點(diǎn): not_exist頁面不會(huì)跳轉(zhuǎn)因?yàn)?store 在goTo中做了存在性檢查。這是有意為之寧可停在原地報(bào)錯(cuò)也不要跳到 undefined 導(dǎo)致白屏。存檔損壞時(shí)手動(dòng)在 Local Storage 里把值改成{bad json點(diǎn)擊“讀檔”后 load 函數(shù)捕獲異常并返回 false。界面可以提示“存檔讀取失敗”而不是直接崩潰。變量類型錯(cuò)誤最容易出現(xiàn)在add操作上。比如affection被設(shè)成字符串10再做add時(shí)typeof current number判斷為 false會(huì)把 base 當(dāng)成 0于是結(jié)果變成0 10。表面看起來只是數(shù)值異常實(shí)際上會(huì)掩蓋劇本數(shù)據(jù)寫錯(cuò)的問題。建議在開發(fā)環(huán)境給vars加類型校驗(yàn)或者在控制臺打印警告。6. 常見問題排查從現(xiàn)象倒推原因問題現(xiàn)象常見原因檢查方式處理建議點(diǎn)擊選項(xiàng)后沒有反應(yīng)選項(xiàng)的next指向了不存在的節(jié)點(diǎn)打開控制臺看[story-engine] 找不到節(jié)點(diǎn)日志檢查 storyMap 中的 id修正next指向或補(bǔ)全缺失節(jié)點(diǎn)存檔讀取后白屏存檔里的節(jié)點(diǎn) id 在舊版本中存在新版本已被刪除在load中打印data.currentNodeId判斷節(jié)點(diǎn)是否存在增加節(jié)點(diǎn)存在性校驗(yàn)不存在時(shí)返回 false 并重新開始條件選項(xiàng)不顯示condition表達(dá)式寫錯(cuò)或者變量值從未初始化在面板組件中打印vars和checkCondition結(jié)果確保變量在initialState或onEnter中初始化繼續(xù)按鈕點(diǎn)擊后跳過多個(gè)節(jié)點(diǎn)goTo中額外調(diào)用了applyEnterActions而onEnter里又調(diào)用goTo檢查動(dòng)作鏈?zhǔn)欠裥纬蛇f歸跳轉(zhuǎn)不要把跳轉(zhuǎn)寫在onEnter動(dòng)作里動(dòng)作只修改變量繼續(xù)按鈕點(diǎn)擊后所有選項(xiàng)一起出現(xiàn)沒有在渲染前過濾condition只是把 choices 全部 map 出去檢查availableChoices是否基于vars過濾使用filter配合checkCondition并訂閱vars歷史記錄順序混亂history在selectChoice和goTo中重復(fù)追加檢查每條歷史記錄的時(shí)間戳和內(nèi)容統(tǒng)一只在一處追加歷史跳轉(zhuǎn)節(jié)點(diǎn)和選擇節(jié)點(diǎn)分別記錄排查時(shí)建議按下面的優(yōu)先級進(jìn)行先確認(rèn)當(dāng)前節(jié)點(diǎn) id 是不是預(yù)期值。在組件頂部打印currentNodeId。再確認(rèn)storyMap里是否存在該節(jié)點(diǎn)節(jié)點(diǎn)的type是否正確。再檢查變量表。在控制臺執(zhí)行useGameStore.getState().vars查看實(shí)時(shí)變量。再檢查條件判斷。手動(dòng)調(diào)用checkCondition({ key: affection, op: , value: 5 }, { affection: 10 })看返回結(jié)果。最后檢查界面渲染。確認(rèn)availableChoices和node是從同一個(gè) store 中讀取。7. 從 Demo 到完整項(xiàng)目架構(gòu)、存檔和內(nèi)容生產(chǎn)建議7.1 把劇情數(shù)據(jù)從 TS 文件挪到 JSON 或遠(yuǎn)程配置示例中劇情寫在story.ts里好處是類型檢查方便壞處是策劃改劇本需要改代碼。在正經(jīng)項(xiàng)目里劇本通常由策劃或敘事設(shè)計(jì)師維護(hù)他們不應(yīng)該接觸 TypeScript。推薦兩種方式開發(fā)期使用本地 JSON通過 Vite 的import直接讀取。上線后把劇情放在遠(yuǎn)程 CDN 或配置中心版本號和存檔綁定劇情更新時(shí)兼容舊存檔。如果劇情文件很大不要一次性把整棵樹加載到內(nèi)存?？梢园凑鹿?jié)拆分加載一章后再加載下一章。示例中的storyMap是全量數(shù)據(jù)適合小體量互動(dòng)故事超過幾百個(gè)節(jié)點(diǎn)的項(xiàng)目需要引入分片加載。7.2 存檔設(shè)計(jì)要帶版本號和結(jié)構(gòu)校驗(yàn)生產(chǎn)環(huán)境存檔不能只存currentNodeId和vars。建議增加saveVersion用于做遷移。updatedAt用于自動(dòng)存檔排序。storyVersion標(biāo)記當(dāng)前劇情版本劇情更新后決定是否允許讀檔。playTime用于統(tǒng)計(jì)玩家進(jìn)度。示例中的load已經(jīng)做了節(jié)點(diǎn)存在性檢查但生產(chǎn)環(huán)境還需要對vars做默認(rèn)值合并。否則新版本增加了變量affection舊存檔沒有這個(gè)鍵后續(xù)做條件判斷時(shí)會(huì)出現(xiàn) undefined 比較。7.3 可復(fù)用的生產(chǎn)檢查清單在發(fā)布互動(dòng)劇情項(xiàng)目前至少確認(rèn)以下事項(xiàng)已經(jīng)完成節(jié)點(diǎn) id 全局唯一且跳轉(zhuǎn)目標(biāo)全部存在。所有條件分支都能被至少一個(gè)前置狀態(tài)滿足避免出現(xiàn)無法觸發(fā)的分支。變量在進(jìn)入游戲時(shí)初始化條件判斷對 undefined 值有兜底。存檔包含版本號讀取失敗時(shí)有降級策略。所有異常路徑在 UI 上有提示而不是只在控制臺打印。音頻和立繪資源用懶加載避免開局加載整個(gè)劇情包。對save、load、clearSave做防抖避免連續(xù)點(diǎn)擊導(dǎo)致存檔覆蓋錯(cuò)亂。在測試環(huán)境制定一份“全分支通關(guān)測試表”每個(gè)選項(xiàng)點(diǎn)一遍每條結(jié)局跑一遍。如果要把這個(gè)引擎推到更復(fù)雜的方向可以繼續(xù)擴(kuò)展分支嵌套、音量控制、自動(dòng)存檔、多語言文本、文本變量插值比如在對話中顯示{affection}當(dāng)前值。核心仍然不變劇情是數(shù)據(jù)界面是渲染器狀態(tài)管理負(fù)責(zé)所有派生計(jì)算。理解了這層關(guān)系《異環(huán)》這個(gè)項(xiàng)目無論加多少內(nèi)容技術(shù)骨架都不會(huì)散。