在《Deltarune》三角符文的同人创作里Susie 这个角色总能带来新的剧情切入点。一个叫 Susies Idea 的小项目可以把它做成一个文本互动游戏玩家扮演玩家角色在教室里遇到 Susie随后通过一连串对话选项影响后续事件走向。这个题材看起来是游戏剧本创作但拆开之后它本质上是一套“对话驱动的事件系统”角色状态、剧情节点、分支选项、事件效果和用户输入解析都需要用代码组织起来。这篇博客围绕这个最小项目从数据结构到可运行版本再到排错和扩展完整走一遍实现过程。适合的读者有两类。一类是刚学 Python、想做一个能给别人演示的小项目的开发者这个项目比学生管理系统更有互动性而且不需要图形界面另一类是想做同人互动小说或文字冒险游戏的策划型开发者读完可以理解对话脚本为什么要数据化、状态变更为什么要和展示分离。正文会带你完成一个控制台版 Susies Idea 最小可运行项目并解释关键代码为什么要这么写。最后会给出扩展方向战斗回合、好感度分支、存档系统、脚本热加载。整个项目不使用任何游戏原版美术和音效资源只做命令行动画和文本模拟适合作为学习 Python 和游戏状态机设计的练习项目。1. 先理解同人互动项目的底层对话系统与状态机1.1 看起来是“写剧情”实际是在设计状态机很多第一次做同人互动项目的开发者会把精力全部放在写对话文本上。写了几百行print和input发现剧情一变就要改代码分支一多就失控。问题不是文本量太大而是没有把“剧情内容”和“剧情驱动逻辑”分开。Susies Idea 这个项目最核心的诉求是玩家看到一段文字做出选择系统根据选择改变某些状态再跳转到下一个剧情节点。这句话翻译成技术语言就是每个剧情节点是一个状态。每个选项是一次状态迁移。选项结果会影响后续可用的内容。所有节点内容应该像数据一样可配置而不是写死在控制流里。所以在写任何界面之前先要设计一套“剧情脚本协议”。比如用 JSON 或 Python 字典描述每个节点的角色、文本、选项、跳转目标和状态变更。运行引擎只负责读脚本、显示文本、接收输入、触发效果。这才是这个项目的主线。如果用一句话概括做对话系统不是为了“输出文字”而是为了“管理状态迁移”。所有剧情变更、战斗胜负、角色好感、隐藏事件本质上都是状态机上的状态迁移。1.2 为什么选择用 Python 做最小版本同人互动项目有很多现成引擎可以用比如 RenPy、Twine、Unity 加 Yarn Spinner。但这些引擎对初学者来说有个问题很多行为被封装在不同层级里出问题不好排查。用纯 Python 做最小版本有四个明显好处依赖少只用标准库就能实现文本显示、输入解析和事件调度。逻辑透明分支、状态、返回跳转全部摊开在代码里容易讲清楚。脚本和逻辑分离剧情数据可以用 JSON 组织改剧情不用改代码。方便调试控制台程序打印日志非常直接能清楚看到每个节点如何跳转、状态如何变化。如果目标是快速做一个可玩版本Python 足够。如果以后要做成网页版或带图形界面的版本可以把这套状态机逻辑直接翻译到其他语言对话脚本本身可以保留。注意这里的“同人项目”只做学习用途不包含游戏原版素材、音乐、字体、特殊符号。所有文本均为原创示例避免版权风险。真正对外发布时还需要特别注意素材授权和作品标注。1.3 最小版本应包含哪些能力一个可以“玩”的 Susies Idea 最小版本至少具备以下四项能力能力说明技术实现文本播放按剧情节点显示角色名和台词可模拟打字机或者直接输出读取 StoryNode 字典Print 格式化输出选项分支每个节点可以有多个选项玩家输入编号后跳转循环读取输入匹配 option.next状态变更选择不同选项后影响角色好感度或全局 Flag在节点效果列表里执行 state 修改结束判断剧情走到结局节点时自动停止流程判断 node 类型为 ending退出循环这四项能力足够支撑一个示范剧情。后续扩展战斗、背包、关卡也是在同样的基础上增加更多状态字段和节点类型。2. 环境准备与项目结构设计2.1 Python 环境要求这个项目没有复杂的第三方依赖。建议使用 Python 3.10 或更高版本因为后续示例会用到dataclass、类型注解和较新的语法。如果你机器上已经安装 Python 3.8 以上的版本也可以运行但类型写法可能需要微调。项目要求说明Python3.10推荐 3.10 以上注解更友好操作系统Windows / macOS / Linux控制台程序跨平台第三方库无只需要标准库开发工具VS Code / PyCharm / 编辑器随意不建议在这个阶段引入 pygame 或 tkinter。图形界面会分散对对话系统核心逻辑的注意力等状态机跑通了再加界面不迟。2.2 目录结构项目采用“数据与逻辑分离”的结构。剧情脚本放到story_data.py状态管理和主循环放到game.py入口函数和玩家输入解析拆成独立函数避免所有代码堆在一个文件里。susies-idea/ ├── game.py # 主循环与输入解析 ├── state.py # 游戏状态管理 ├── story_data.py # 剧情脚本数据 └── README.md # 项目说明这个结构不是固定的但建议保持一个原则剧情数据文件不应该出现input()或print()主循环文件不应该直接修改剧情字典里的文本内容。两层职责分开后续才好扩展。2.3 初始化项目在空目录里创建上述文件然后先写一个最基础的状态类# state.py from dataclasses import dataclass, field from typing import Dict, List dataclass class GameState: current_node: str start flags: Dict[str, bool] field(default_factorydict) affection: Dict[str, int] field(default_factorydict) history: List[str] field(default_factorylist) def set_flag(self, key: str, value: bool True) - None: self.flags[key] value def has_flag(self, key: str) - bool: return self.flags.get(key, False) def add_affection(self, character: str, delta: int) - None: self.affection[character] self.affection.get(character, 0) delta def get_affection(self, character: str) - int: return self.affection.get(character, 0) def enter_node(self, node_id: str) - None: self.current_node node_id self.history.append(node_id)这段代码做了三件事用dataclass声明游戏状态包含哪些字段。提供set_flag和has_flag用于记录剧情中是否做过某件事。提供add_affection和get_affection用于记录角色好感度。这样写的意义在于后续所有剧情节点只通过这四个方法变更状态不会出现某个分支在代码里随手给状态赋值而其他地方读不到的情况。注意field(default_factorydict)是 dataclass 里非常重要的一种写法不能直接写成flags: Dict[str, bool] {}。因为默认可变对象会被多个实例共享导致状态污染。3. 剧情脚本数据结构让剧情可配置、可跳转、可触发效果3.1 StoryNode 数据结构剧情脚本是整个项目的灵魂。每个剧情节点都有几个固定字段# story_data.py from typing import Optional, Dict, List, Any STORY: Dict[str, Dict[str, Any]] { start: { speaker: Noelle, text: Susie 说她想出了一个绝妙的主意。你有兴趣听一下吗, options: [ {text: 当然想听。, next: susie_idea, effects: {affection: {Susie: 1}}}, {text: 我现在有点忙。, next: busy_exit, effects: {flag: missed_idea}} ] }, susie_idea: { speaker: Susie, text: 听着我们放学后去森林里找那个传说中的洞窟。搞不好能带回来点真正有意思的东西。, options: [ {text: 听起来有点危险。, next: risk_response, effects: {affection: {Susie: -1}}}, {text: 我没问题一起去。, next: join_adventure, effects: {affection: {Susie: 2}}} ] }, risk_response: { speaker: Susie, text: 危险你是担心我会被吓到哈哈有你在才没那么容易出事呢。, options: [ {text: 好吧我也去。, next: join_adventure, effects: {affection: {Susie: 1}}} ] }, join_adventure: { speaker: Narrator, text: 你和 Susie 约好了放学后在校门口碰面。新的冒险就这样开始了。, options: [], type: ending }, busy_exit: { speaker: Narrator, text: 你拒绝了这次邀请。Susie 耸了耸肩没有多说什么但总感觉她有点失望。, options: [], type: ending } }每个节点包含四个关键字段speaker当前台词角色用于控制台显示不同颜色或前缀。text台词正文可以直接输出。options选项列表每个选项包含显示文本、跳转目标、执行效果。type可选字段标记为ending表示剧情结束。当一个节点没有任何可选项并且type为ending时系统应该终止主循环而不是继续读取输入。否则会进入死循环。3.2 效果热区统一处理状态变更在上面的脚本里每个选项都有一个effects字段。这个字段设计为字典用于表达三种常见效果affection角色好感度增减。flag设置某个 Flag用于后续节点判断条件。set直接给某个状态变量赋值适合扩展背包或关卡进度。为什么把效果统一放到脚本里而不是写在跳转逻辑里因为“风险响应”这个分支里玩家选择“我也去”之后Susie 的好感度变化和跳转行为是绑定的。如果在引擎代码里为每个节点单独判断剧情一长代码里会堆满if node_id xxx。把效果写成数据引擎只需要一个统一的apply_effects函数。# game.py from typing import Dict, Any from state import GameState def apply_effects(state: GameState, effects: Dict[str, Any]) - None: if not effects: return if affection in effects: for character, delta in effects[affection].items(): state.add_affection(character, delta) if flag in effects: flag_name effects[flag] if isinstance(flag_name, list): for name in flag_name: state.set_flag(name) else: state.set_flag(flag_name) if set in effects: for key, value in effects[set].items(): setattr(state, key, value)这样设计之后后续增加“获得道具”之类的效果只需在apply_effects里增加一个item分支脚本里写对应字段即可不需要改动主循环。3.3 为什么节点要用 ID 而不是用列表顺序剧情跳转如果按列表顺序执行确实写起来很简单但这会导致一个问题分支跳转会变得非常别扭。比如两个不同分支都指向同一个结局如果用列表顺序要么复制一份相同文本要么引入复杂的“从某处继续”逻辑。用节点 ID 作为跳转目标相当于给每个剧情片段一个唯一标识。跳转就是“切换当前节点 ID”。这样多个分支可以汇聚到同一个节点。同一个节点可以从多个地方进入。节点状态可以重复进入只要在效果里控制好 Flag就不会重复触发奖励。这是文本冒险类游戏最基础的结构。后续做更复杂的脚本系统可以把节点扩展成对话行数组每一行有自己的条件、跳转和执行效果。4. 实现游戏主循环与输入解析4.1 主循环读节点、显示文本、等待输入、跳转主循环的设计目标是尽量短短到一眼能看懂整个流程。# game.py import sys from typing import Dict, Any from state import GameState from story_data import STORY def display_speaker(speaker: str) - None: if speaker Narrator: print(【叙述】) else: print(f【{speaker}】) def display_text(text: str) - None: print(text) print() def display_options(options: list) - None: if not options: return print(请选择) for index, option in enumerate(options, start1): print(f{index}. {option[text]}) def parse_input(options: list) - Dict[str, Any]: while True: raw input( ).strip() if not raw: print(输入不能为空请重新选择。) continue if not raw.isdigit(): print(请输入选项对应的数字。) continue choice int(raw) if choice 1 or choice len(options): print(f请输入 1 到 {len(options)} 之间的数字。) continue return options[choice - 1] def run_game() - None: state GameState() while True: node_id state.current_node node STORY[node_id] display_speaker(node[speaker]) display_text(node[text]) options node.get(options, []) if not options: ending_flag node.get(type) ending if ending_flag: print( 结局达成 ) print(f当前 Susie 好感度{state.get_affection(Susie)}) break break display_options(options) selected parse_input(options) effects selected.get(effects) apply_effects(state, effects) state.enter_node(selected[next]) if __name__ __main__: try: run_game() except KeyboardInterrupt: print(\n玩家中断游戏。) sys.exit(0)这段代码的核心逻辑非常直白读取当前节点 ID从STORY中取出节点内容显示角色和台词如果有选项就等待输入。输入命中某个选项后先执行效果再切换当前节点。循环继续。4.2 输入解析要处理的边界情况parse_input函数没有直接写int(input())而是做了四层校验空输入处理玩家直接按回车不能崩溃。非数字处理玩家输入abc不能抛ValueError。越界处理玩家输入99不能访问不存在的选项。合法返回只有命中选项列表中的某一项才返回整个选项字典。这些校验在图形界面里不一定需要因为下拉框或按钮天然限制输入范围。但在控制台版本里非常必要。很多第一次写文字冒险的开发者都会在输入解析上被ValueError打断。4.3 节点不存在时的兜底如果story_data.py中某个next指向了一个不存在的节点 ID主循环会在STORY[node_id]处抛出KeyError。推荐的兜底方式有两种方式一启动时校验所有跳转目标。def validate_story(story: Dict[str, Dict[str, Any]]) - List[str]: errors [] for node_id, node in story.items(): for option in node.get(options, []): target option.get(next) if target not in story: errors.append(f节点 {node_id} 的选项指向不存在的节点 {target}) return errors方式二主循环捕获KeyError并给出明确错误信息。try: node STORY[node_id] except KeyError: print(f剧情脚本错误找不到节点 {node_id}) print(请检查 story_data.py 中的 next 跳转目标。) break在实际开发中两种都要。启动校验用于提前发现脚本问题主循环捕获用于防止运行期崩溃。5. 扩展节点条件只有满足条件才显示某些选项5.1 为什么需要在脚本里写条件上面的最小案例只能做“无条件的选项跳转”。但同人互动项目很快会碰到一个需求某个选项只有在之前做过某件事时才出现。示例场景玩家在前面的分支里问过 Susie 关于洞窟的问题。后面的结局分支里多出一个特殊选项“提起上次聊到的洞窟路标”。如果没问过这个选项不应该显示。这需要给选项增加一个condition字段{ text: 提起洞窟路标。, next: special_ending, condition: {flag: asked_about_trail}, effects: {affection: {Susie: 2}} }然后在显示选项之前过滤def filter_options(state: GameState, options: list) - list: result [] for option in options: condition option.get(condition) if condition is None: result.append(option) continue if condition.get(flag) and state.has_flag(condition[flag]): result.append(option) return result在run_game中调用display_options之前先对options做一次过滤options node.get(options, []) options filter_options(state, options) if not options: # 处理“角色没有可选项”的情况 continue5.2 条件不足时节点必须兜底过滤之后可能出现一种情况某个节点原本有三个选项但因为 Flag 条件不足只剩一个选项更极端时没有任何选项显示。这属于剧本设计问题必须在编写剧情脚本时提前避免。推荐的兜底策略每个有条件的选项至少保证有一个无条件选项。如果全部选项都被条件过滤节点内增加一个默认跳转分支比如default_next: scene_fallback。主循环检测到options为空时直接进入default_next不要等待玩家输入。if not options: default_next node.get(default_next) if default_next: state.enter_node(default_next) continue print(当前节点没有可用选项剧情无法继续。) break这个设计看起来简单但能避免很多运行时死循环。尤其当脚本越来越长条件交叉使用时一个无条件的兜底分支是安全网。5.3 条件的本质把剧情逻辑从代码迁移到数据当条件表达式写进脚本数据之后剧情的可扩展性会明显提升。你可以不修改主循环直接在 JSON 或 Python 字典里增加新节点、新选项、新条件。当然如果条件逻辑非常复杂比如“好感度大于 5 且拥有道具 A 且没有触发过事件 B”那么建议不要只依赖简单的flag判断而是扩展 condition 的语义condition: { op: and, conditions: [ {comparator: affection_gte, character: Susie, value: 5}, {flag: has_item, value: rubbish_junk}, {flag: not, value: event_triggered} ] }然后在引擎里写一个对应的条件解析器。这样设计的好处是剧情策划在写脚本时不需要阅读引擎代码只需要按约定写条件结构。代码人员和剧情策划的协作边界就清晰了。6. 运行验证与结果分析6.1 运行方式与预期输出在项目目录下执行python game.py正确运行时控制台会依次出现如下内容【Noelle】 Susie 说她想出了一个绝妙的主意。你有兴趣听一下吗 请选择 1. 当然想听。 2. 我现在有点忙。 1 【Susie】 听着我们放学后去森林里找那个传说中的洞窟。搞不好能带回来点真正有意思的东西。 请选择 1. 听起来有点危险。 2. 我没问题一起去。 2 【Narrator】 你和 Susie 约好了放学后在校门口碰面。新的冒险就这样开始了。 结局达成 当前 Susie 好感度2选择“我现在有点忙”时【Narrator】 你拒绝了这次邀请。Susie 耸了耸肩没有多说什么但总感觉她有点失望。 结局达成 当前 Susie 好感度0这说明状态变更、节点跳转和结局判断都正常工作了。6.2 验证状态变更是否正确如果玩家选择“当然想听”之后选择“听起来有点危险”则 Susie 好感度应该是先加 1再减 1最终为 0。验证方式可以直接在脚本末尾加一行调试输出或者使用 Python 交互环境模拟from state import GameState from game import apply_effects state GameState() apply_effects(state, {affection: {Susie: 1}}) apply_effects(state, {affection: {Susie: -1}}) print(state.get_affection(Susie)) # 0这个验证能排查一种常见问题效果执行顺序错误。如果先跳转再执行效果或者执行了两次效果数值就会不对。6.3 日志输出方便排查剧情跳转在开发阶段可以在enter_node中增加一个简单的日志记录def enter_node(self, node_id: str) - None: print(f[DEBUG] 进入节点: {node_id}) self.current_node node_id self.history.append(node_id)这样运行游戏时控制台会同时显示调试日志和正常文本。比如[DEBUG] 进入节点: start 【Noelle】 Susie 说她想出了一个绝妙的主意。你有兴趣听一下吗 [DEBUG] 进入节点: susie_idea 【Susie】 ...如果玩家反馈某些分支进不去可以利用这份日志快速定位跳转链路。生产环境下建议将日志写入文件而不是直接打印到控制台。注意不要只验证“程序能启动”就认为功能完整。至少要验证三种分支正常进入结局、拒绝邀请结局、好感度数值是否正确。文本冒险类项目最容易漏掉某个分支的组合路径。7. 常见问题排查7.1 玩家输入“abc”导致程序崩溃现象运行过程中输入非数字程序抛出ValueError。原因直接使用int(input())没有处理非数字输入。检查方式在parse_input函数中打印输入值或观察异常堆栈。解决方案使用raw.isdigit()判断后再转换并在提示信息中说明“请输入数字”。预防建议输入解析统一收敛到一个函数不散落到主流程里。7.2 剧情跳转到不存在的节点程序报 KeyError现象选择某个选项后控制台出现KeyError: some_node。原因选项里的next值写错或节点 ID 拼写不一致。检查方式查看异常信息中的键名再到story_data.py中搜索该节点是否存在。解决方案启动时用validate_story函数检查所有跳转目标发现错误立刻输出。预防建议把节点 ID 抽成常量或写一个简单的脚本自检工具每次运行前自动校验。7.3 状态变更没有生效好感度始终为 0现象选择某个选项后结局打印的好感度没有变化。原因可能是选项字典里没有写effects字段也可能在跳转节点之后才执行效果但效果执行被跳过。检查方式在apply_effects函数里打印传入的 effects 字典确认是否被调用。解决方案if effects: print(f[DEBUG] 执行效果: {effects}) apply_effects(state, effects)预防建议在每个选项里都明确写effects: {}并用validate_story检查选项结构是否合法。7.4 选项被过滤后为空程序卡死或崩溃现象加上条件过滤后某个节点显示完文本程序没有继续。原因所有选项都被条件过滤掉了且没有设置default_next。检查方式在filter_options返回后打印剩余选项数量。解决方案给每个可能被过滤光的节点配置一个无条件选项或者提供default_next。预防建议脚本自检时统计每个节点的“无条件选项数量”至少保证一个。8. 最佳实践与扩展方向8.1 最小可运行示例的学习路径如果你是第一次做这类项目建议按以下顺序练习先跑通“单节点 - 选项 - 结局”的最小链路。再加入GameState和好感度效果。再加入条件选项和default_next兜底。再加入启动自检脚本把所有节点 ID、选项跳转、条件字段统一校验。最后把剧情脚本迁移到 JSON 文件用 Python 读取实现“改剧本不用改代码”。不要跳过前两步。很多人在第一步就习惯性引入图形界面或语音包结果发现问题后无法判断是逻辑问题还是界面问题。8.2 学习环境与生产环境的差异项目学习环境生产环境剧情数据Python 字典JSON / YAML 文件支持热加载存档无JSON 序列化GameState日志打印到控制台写入文件保留节点访问历史输入input()图形界面或事件驱动素材文本占位需要原创素材或获得授权错误处理直接中断捕获错误并返回引导节点测试手动验证自动化脚本遍历所有分支学习环境的目标是“理解”生产环境的目标是“稳定”。差异核心在于剧情数据外置、状态可持久化、错误可恢复。8.3 从控制台到图形界面的扩展如果后续想加界面推荐先做一个极简网页版而不是直接上手 pygame。原因有三个网页的按钮天然限制输入范围省掉输入解析的边界处理。状态逻辑可以原样迁移到 JavaScript对话脚本仍可复用。更容易做存档和分享。如果你用 Python 做一个网页服务推荐流程是用fastapi暴露两个接口一个返回当前节点和选项一个提交选项并返回新节点。前端只需要一个文本框和按钮。核心逻辑仍然是当前的状态机不改变设计。8.4 脚本自检是项目进入长期维护前必须做的投入当剧情节点超过 50 个以后手写脚本一定会出现拼写错误、跳转缺失、条件字段写错等问题。自检脚本的价值会越来越明显。一个合格的自检脚本至少包含以下检查每个节点的text不为空。每个选项的next在剧本中存在。每个选项的effects字段格式合法。每个带条件的选项所在节点存在无条件兜底。所有标记为ending的节点没有任何选项避免死循环。把这些检查放到一个独立函数中运行游戏时先执行全部通过再进入主循环。这个习惯会让后续剧情扩充压力明显降低。8.5 再往下走战斗、背包与好感度分支当对话系统跑通后Susies Idea 可以向真正的同人游戏方向扩展。三个最有用的方向按优先级排列战斗回合把战斗节点定义为一种特殊节点包含敌方状态、玩家命令选项、伤害计算和胜负跳转。背包系统给GameState增加inventory字典支持获取道具、使用道具、条件判断道具是否存在。结局收集在结局节点记录玩家得到的结局 ID配合存档系统鼓励玩家尝试不同分支。这三个方向都不会推翻现有的状态机设计。战斗只是另一种节点类型背包只是状态中的一个字段结局收集只需要在enter_node里检测节点类型。最后回到起点Susies Idea 这个题目看起来只是写一段同人对话但它实际上覆盖了游戏开发中“状态分离、数据驱动、跳转控制、条件判断、防御式输入解析”这些核心概念。把这些概念用最小代码跑通之后你掌握的就不是一个游戏 Demo 的写法而是一套可以迁移到对话机器人、流程引擎、配置驱动工具等场景的通用设计方法。