1. 项目概述一个为AI时代重写的回合制游戏引擎如果你是一个独立游戏开发者或者对卡牌、策略类游戏的机制设计感兴趣那你一定对《杀戮尖塔》这类数据驱动的回合制游戏不陌生。这类游戏的核心魅力在于其丰富的策略深度和可重玩性而这背后是海量的卡牌、遗物、敌人和状态效果相互交织构成的复杂规则系统。传统的开发模式下每增加一张新卡牌可能都需要程序员修改底层代码、美术师绘制卡面、策划反复调整数值整个流程冗长且耦合度高。今天要聊的 OpenSpire 项目正是为了解决这个痛点而生。它不是一个简单的《杀戮尖塔》克隆而是一个通用的、基于事件的回合制卡牌游戏编排引擎。它的核心思想极其大胆将游戏的所有规则和数据完全用 Lua 脚本来定义。这意味着游戏设计师甚至不需要懂 C 或 C# 这类“硬核”的引擎开发语言只需要会写 Lua 脚本就能创建新的卡牌、敌人、状态效果并且能做到热插拔——即改即生效无需重启游戏。更关键的是OpenSpire 从设计之初就是“AI原生”的。它内置了完整的命令行接口CLI和 JSON 通信协议游戏的每一个操作出牌、选择目标、结束回合都可以被程序化地控制和观察。这为 AI 智能体Agent介入游戏测试、平衡性调整甚至是自动生成游戏内容铺平了道路。想象一下你可以让一个 AI 在几分钟内生成上百张符合当前规则集的新卡牌初稿或者让另一个 AI 在后台进行数万场对局来测试新卡牌的强度是否超标。这能将游戏设计和逻辑开发的周期从传统的数月缩短到数周甚至更短。2. 核心设计理念与架构拆解2.1 事件驱动与纯数据驱动的哲学OpenSpire 的架构核心是一个事件管道。游戏内发生的所有事情无论是玩家打出一张牌敌人发动一次攻击还是某个状态效果触发都被抽象为一个“事件”。例如event:card:played(卡牌被使用)event:entity:damaged(实体受到伤害)event:turn:end(回合结束)引擎本身不关心“一张火焰冲击牌应该造成多少伤害”它只负责事件的派发、传递和监听。具体的游戏逻辑比如“火焰冲击对目标造成8点伤害”则被定义在附着于卡牌数据上的 Lua 脚本钩子中。当event:card:played事件发生时引擎会执行这张卡牌对应的 Lua 脚本脚本再触发event:entity:damaged事件从而驱动整个游戏状态的变化。这种设计的优势非常明显解耦与热插拔游戏逻辑Lua脚本和引擎核心C/Rust/Go等完全分离。修改或新增规则只需改动脚本文件引擎可以在运行时动态加载实现真正的热更新。可观测性与可控制性所有状态变更都通过事件暴露出来使得外部程序如AI可以清晰地知道游戏内发生了什么也可以通过发送特定事件来“操纵”游戏。规则组合的无限可能由于逻辑是脚本化的你可以轻松实现一些在硬编码中非常复杂的联动效果。例如“当你生命值低于50%时抽到的所有攻击牌伤害翻倍”这种效果只需要在状态脚本和卡牌脚本中编写相应的监听器即可。2.2 CLI化与AI原生接口的实现“游戏CLI化”是OpenSpire另一个革命性的特点。项目内置了两套交互接口终端UI模式使用 Ink 框架构建了完整的命令行界面玩家可以直接在终端里进行游戏拥有不错的视觉呈现和操作体验。JSON/Stdio 模式这是为AI和自动化测试准备的“无头模式”。引擎通过标准输入输出与外部程序通信所有游戏状态和可执行动作都以JSON格式交换。一个典型的工作流如下AI 向引擎发送{action: get_state}。引擎回复当前游戏状态的JSON包括玩家手牌、血量、能量、敌人信息、可用的行动列表等。AI 分析状态后决定出牌发送{action: play_card, card_id: strike, target: enemy_0}。引擎执行该动作推进游戏并返回新的状态。这种设计让OpenSpire成为了一个完美的AI训练与测试环境。强化学习算法可以将其作为一个标准的“环境”来交互而大语言模型LLM也可以通过分析JSON状态以“文本游戏”的方式来理解和决策。实操心得在设计CLI接口时关键是要保证状态的“完备性”和动作的“原子性”。完备性是指AI仅凭状态JSON就能做出完全信息决策原子性是指一个动作指令应对应游戏内一个最小操作单元如“出牌”避免复合动作。OpenSpire将“选择目标”也作为动作的一部分这是一个很好的设计。2.3 项目目录结构解析理解项目结构有助于我们快速定位代码和进行扩展。OpenSpire的目录组织得非常清晰evt/ core/ # 引擎核心事件管道、Lua运行时、游戏状态管理 sts/ # 《杀戮尖塔》规则实现卡牌、敌人、状态、角色定义 game/ # 会话编排层场景加载、视图呈现、回合流程控制 bin/ # CLI入口点终端UI JSON模式 ui/ # Ink终端界面实现 scenarios/ # 战斗场景的JSON配置文件evt/core是引擎的“大脑”它定义了事件系统、如何加载和执行Lua脚本、如何管理实体玩家、敌人的状态。这部分通常由高性能语言实现以保证运行效率。evt/sts是《杀戮尖塔》这个“Demo”的具体实现。它完全由Lua脚本和数据文件构成是“纯数据驱动”理念的完美示例。如果你想基于OpenSpire做自己的游戏理论上可以删除这个目录然后在evt/下新建一个mygame/目录用同样的方式组织你的游戏规则。evt/game可以看作是“导演”它负责将核心引擎和具体规则集如STS组合起来管理一场完整的对局流程。scenarios/存放的是静态数据比如第一层会遇到哪些敌人、地图的构成等通常由JSON或YAML定义在游戏开始时被加载。3. 从零开始扩展创建你的第一张自定义卡牌让我们抛开理论动手实践。扩展OpenSpire的最佳方式就是从创建一张属于自己的卡牌开始。这个过程将清晰地展示其“热插拔”和“数据驱动”的威力。3.1 环境准备与项目运行首先你需要克隆项目并安装依赖。OpenSpire 使用 pnpm 作为包管理器确保了依赖管理的效率和一致性。# 克隆项目 git clone https://github.com/shixiangxi0/OpenSpire.git cd OpenSpire # 安装依赖 pnpm install # 运行《杀戮尖塔》演示会先进入语言选择 pnpm sts # 或者直接指定场景和语言启动跳过选择界面 pnpm sts -- iron_plague --lang en运行成功后你应该能在终端看到一个完整的游戏界面。用方向键和回车键可以操作。先体验一下原版游戏这有助于理解我们即将修改的内容。3.2 卡牌数据与脚本的解剖在evt/sts/cards/目录下你可以找到所有卡牌的定义。让我们以一张简单的攻击牌为例。在common无色牌文件夹中Strike.js或.lua可能长这样以下为概念性示例具体语法请参考项目文档-- evt/sts/cards/common/MyCustomStrike.lua local card { id my_custom_strike, -- 卡牌唯一标识符 name 自定义打击, type ATTACK, rarity BASIC, cost 1, -- 费用 description 造成 10 点伤害。如果目标处于虚弱状态额外造成 5 点伤害。, -- 核心钩子Hooks将卡牌逻辑绑定到事件上 hooks { -- 当“卡牌生效”事件触发时执行此函数 [event:card:effect] function(state, event) local damage 10 local target event.target -- 检查目标是否有“虚弱”状态 if target:hasStatus(weak) then damage damage 5 -- 可以在这里触发一个额外动画或日志事件 state:emit(log, {text string.format(利用虚弱伤害提升至 %d, damage)}) end -- 触发“实体:攻击”事件这是引擎理解的标准伤害事件 state:emit(entity:attack, { source event.source, -- 伤害来源玩家 target target, amount damage }) end } } return card这张卡牌的逻辑非常清晰静态数据id,name,cost等定义了卡牌的基本属性。动态逻辑hooks是核心。它告诉引擎“当event:card:effect事件发生时即这张牌被打出并生效时请运行我后面的Lua函数。”脚本内的交互在函数内部我们可以查询游戏状态target:hasStatus(weak)进行计算并最终通过state:emit触发新的事件来改变游戏世界。3.3 实现热插拔让新卡牌即时生效传统游戏引擎中添加新内容需要重新编译、打包、重启游戏。在OpenSpire中这个过程被简化为两步第一步注册卡牌你需要在一个集中的清单文件中声明这张新卡牌以便游戏在加载卡牌池时能找到它。这个文件可能在evt/sts/data/card_pools.lua。-- 在相应的卡牌池中添加你的卡牌ID local commonPool { strike, defend, my_custom_strike, -- 添加这一行 -- ... 其他卡牌 }第二步触发重载OpenSpire 引擎监听文件系统的变化。当你保存了MyCustomStrike.lua和修改后的card_pools.lua文件后在游戏内通常通过某个调试命令或菜单具体请查阅项目Wiki可以触发“重载规则”操作。# 在游戏的JSON模式中可以发送重载命令 {action: reload_rules}引擎会重新扫描evt/sts/目录下的所有脚本文件并更新内存中的规则定义。之后新开一局游戏你的“自定义打击”就有机会出现在卡牌奖励中了。注意事项热重载虽然强大但需谨慎处理状态依赖。例如如果一场对局正在进行中而你又修改了场上某张已存在卡牌的伤害公式可能会导致状态不一致。最佳实践是在对局开始前或结束后进行规则修改。OpenSpire的事件系统通常能很好地处理动态加载的脚本但对于已实例化的对象其行为可能已被固化。4. 构建全新规则集超越《杀戮尖塔》OpenSpire的真正潜力不在于魔改《杀戮尖塔》而在于用它作为引擎创造属于自己的游戏。这意味着你需要定义一套全新的规则集。4.1 定义游戏的基本实体和状态一个回合制游戏通常包含几种核心实体角色玩家控制的单位拥有生命、能量、手牌上限等属性。敌人AI控制的单位拥有行为模式。卡牌玩家的主要操作手段。状态附着在实体上的持续性效果如“中毒”、“力量”、“敏捷”。你需要为你的游戏定义这些实体的数据结构和基础事件。例如在evt/mygame/目录下创建evt/mygame/ ├── entities/ │ ├── hero.lua -- 英雄角色定义 │ └── enemy_archer.lua -- 一种敌人定义 ├── cards/ │ ├── attack.lua │ └── skill.lua ├── statuses/ │ ├── poison.lua │ └── strength.lua └── data/ ├── characters.lua -- 角色列表 └── encounters.lua -- 敌人遭遇配置在hero.lua中你可能会定义local Hero { id warrior, max_hp 80, max_energy 3, hand_size 5, -- 英雄特有的钩子例如回合开始抽牌 hooks { [event:turn:start] function(state, event) if event.entity self then state:emit(player:draw_cards, {amount 5}) end end } } return Hero4.2 设计核心事件流你需要规划好游戏进行的主事件流。这通常是一个循环game:startround:startturn:start(玩家回合)player:draw... (玩家行动)turn:endturn:start(敌人回合遍历所有敌人)enemy:intent(决定敌人意图)enemy:action(执行敌人行动)turn:end回到步骤3或触发round:end/game:over。在evt/mygame/game.lua中你会编写一个“场景控制器”来发射这些事件并驱动流程。4.3 连接前端与配置场景最后你需要告诉引擎如何启动你的游戏。创建场景配置在scenarios/下新建my_first_dungeon.json定义初始英雄、首场战斗的敌人、初始卡组等。修改CLI入口在evt/bin/中参考sts.js创建一个新的入口文件mygame.js将引擎指向你的规则集目录 (evt/mygame) 和你的场景配置。更新UI适配ui/目录下的 Ink 脚本可能需要调整以正确显示你游戏特有的状态和文本如资源名称从“能量”改为“法力”。完成这些后你就可以通过pnpm mygame来运行你自己的游戏了。5. AI集成与自动化测试实战OpenSpire的CLI接口为AI集成打开了大门。这里介绍两种最实用的应用场景。5.1 使用大语言模型LLM进行游戏测试与设计你可以将OpenSpire的JSON状态输出连同一些指令发送给像Claude、GPT这样的LLM让它来扮演玩家或设计师。场景一AI玩家你编写一个简单的Python脚本作为桥梁import subprocess import json # 启动OpenSpire JSON模式进程 process subprocess.Popen([node, evt/bin/sts.js, --mode, json], stdinsubprocess.PIPE, stdoutsubprocess.PIPE, stderrsubprocess.PIPE, textTrue) def send_action(action_dict): process.stdin.write(json.dumps(action_dict) \n) process.stdin.flush() def get_state(): send_action({action: get_state}) # 简化处理实际需要更严谨的读取 output_line process.stdout.readline() return json.loads(output_line) # 主循环 state get_state() while not state[game_over]: # 将游戏状态、手牌信息、历史记录整理成提示词 prompt f 你正在玩一个卡牌游戏。当前状态 生命{state[player][hp]}/{state[player][max_hp]} 能量{state[player][energy]}/{state[player][max_energy]} 手牌{, .join([c[name] for c in state[hand]])} 敌人{[e[name] f({e[hp]}HP) for e in state[enemies]]} 请从以下可行动作中选择一个并回复JSON{state[valid_actions]} # 调用LLM API获取其决策 llm_decision call_llm_api(prompt) # 假设的函数 # 执行决策 send_action(llm_decision) state get_state()通过观察AI玩家的决策你可以发现哪些卡牌过于强大AI总是选或过于弱小AI从不选从而进行平衡性调整。场景二AI游戏设计师你可以要求LLM根据现有规则生成新的、平衡的卡牌设计。提示词请为我的游戏设计一张新的稀有技能牌。现有规则能量上限3点“格挡”牌消耗1点能量获得5点格挡“攻击”牌消耗1点能量造成6点伤害。请生成一张有创意且强度合理的卡牌Lua脚本。LLM可能会生成一张如“以眼还眼消耗2点能量。本回合你每受到1点伤害就对随机敌人造成1点伤害”的脚本初稿。你可以快速将其放入游戏进行实测。5.2 构建强化学习RL智能体环境对于更专业的平衡性测试强化学习是利器。OpenSpire的JSON接口可以轻松封装成一个标准的Gym环境。import gym from gym import spaces import numpy as np class OpenSpireEnv(gym.Env): def __init__(self): super().__init__() # 定义观察空间例如将玩家血量、能量、手牌编码为向量 self.observation_space spaces.Box(low0, high100, shape(50,)) # 定义动作空间例如0-49代表50种不同的出牌/目标组合 self.action_space spaces.Discrete(50) self.process ... # 启动游戏进程 def reset(self): self._send({action: new_game}) obs self._get_state_vector() return obs def step(self, action): # 将离散动作ID映射为游戏内的具体动作JSON action_json self._action_mapping(action) self._send(action_json) next_obs self._get_state_vector() reward self._calculate_reward() # 例如胜利100每造成1点伤害0.1 done self._is_game_over() return next_obs, reward, done, {} # ... 其他辅助方法然后你就可以使用Stable-Baselines3、RLlib等库来训练一个AI让它进行成千上万局游戏。通过分析AI的策略你可以发现最优解MetaAI是否发现了开发者未预料到的无敌连招无用设计是否有卡牌或遗物在AI的百万局对战中从未被使用过难度曲线AI在不同关卡下的胜率如何哪一层是难度陡升的点实操心得在将游戏封装为RL环境时状态表示和奖励函数设计是两大难点。状态表示要尽可能包含所有相关信息且维度不能太高。奖励函数要能引导AI学习到“有趣”的策略而不是简单的刷分。例如除了给予胜利奖励对使用不同卡牌组合、达成特殊连击给予小额奖励可以鼓励AI探索更多样化的玩法。6. 常见问题、调试技巧与性能考量在实际使用和扩展OpenSpire的过程中你可能会遇到一些典型问题。6.1 规则脚本调试Lua脚本写错了怎么办OpenSpire的引擎通常会捕获Lua运行时错误并在日志中输出。你需要开启详细日志检查启动参数确保引擎日志级别设置为DEBUG或INFO。使用print调试在Lua脚本中插入print(“Reached here, value is:”, someVar)输出会显示在引擎的控制台。检查事件触发顺序有时问题不是脚本逻辑错误而是事件触发时机不对。在关键事件钩子开始处打印日志确认事件是否如预期般被触发。隔离测试新建一个最简单的测试脚本和场景单独测试你新增的卡牌或状态排除其他复杂规则的干扰。6.2 性能优化建议当卡牌和状态效果非常多且钩子逻辑复杂时性能可能成为问题。潜在瓶颈优化策略Lua JIT编译确保使用的Lua运行时支持JIT如LuaJIT这对脚本执行速度有数量级提升。事件监听器过多避免为每个实体都注册通用事件的监听器。优先使用“事件总线”模式或按需注册/注销监听器。频繁的状态深拷贝为了支持AI和回放游戏状态可能需要被序列化或拷贝。设计不可变immutable的数据结构或使用结构共享来减少拷贝开销。复杂的Lua脚本逻辑将性能关键路径如伤害计算循环转移到引擎层用原生代码实现通过Lua绑定暴露为API供脚本调用。6.3 与AI协同工作的注意事项状态暴露的完整性确保AI通过JSON接口能获取到所有做出理性决策所需的信息包括隐藏信息如对手的意图如果规则允许AI知道的话。动作空间的离散化对于复杂的游戏可行动作可能非常多卡牌×目标。你需要设计一个合理的动作编码方案或者让AI输出结构化的动作JSON。随机性的处理游戏中的随机如抽牌、暴击必须在引擎端严格处理但要将随机种子或结果明确包含在状态JSON中保证AI训练的可重复性。速度与吞吐量如果用于大规模RL训练需要考虑游戏模拟的速度。可以关闭所有图形和日志输出甚至以多进程并行运行多个游戏实例。OpenSpire代表了一种未来游戏开发范式的探索将游戏逻辑彻底数据化、脚本化并通过标准接口向AI开放。它降低了策略类游戏原型的开发门槛也为游戏设计提供了前所未有的自动化测试和平衡工具。虽然目前它以《杀戮尖塔》为演示但其架构的通用性足以支撑各种回合制、事件驱动的游戏类型。对于独立开发者和游戏研究者而言深入理解和运用这样的工具或许就是抓住下一次游戏开发效率革命的关键。