游戏里的角色

一张卡不一定在网页上玩。它也可以是别人游戏里的一个角色：玩家在游戏里遇到这个角色，说的话由这张卡来接。《杀戮尖塔 2》的 SpireTalk 模组就是这样做的，八位远古先民和商人各是一张 Yumina 卡。

游戏和卡之间只靠变量说话：游戏每回合把自己的数据写进卡的变量，AI 回复以后，游戏再把 AI 写的几个变量读回去。

打开游戏接口

点画布上的 这张卡，在卡的设置里找到 游戏接口，打开 这张卡是游戏里的角色，再填上 游戏名称。

打开以后，画布上的 玩家界面 那一块不再画聊天框，而是三栏：游戏每回合告诉 AI 什么 → AI 扮演谁 → AI 每回合交回游戏什么。这张卡是什么一眼就能看懂。

标出游戏的变量

每个变量的设置里多了一行 游戏接口，三选一：

• 不是：普通变量，跟游戏无关
• 游戏给：游戏每回合写入，比如血量、金币、第几层、身上的遗物。AI 只读。卡上填的值只是试玩用的假数据，进了游戏会换成真的
• 交回游戏：AI 每回合写，游戏读走以后照着做，比如好感变化、给玩家的三个选项、要不要给奖励

标出来的变量 ID 会被锁住，不能改名：游戏是按 ID 找它们的，改了名游戏就悄悄断了。创作助手和外部 AI 也知道这些变量不能动。

奖励、交易这类东西，游戏一定要按自己的规则再检查一遍。AI 只负责说，真正给不给由游戏决定。

写给 mod 作者：怎么运行一张卡

mod 不用连 Yumina 网站，也不需要账号。把 Yumina 引擎打包进游戏（引擎是开源的：yumina-oss），读卡的 JSON，模型用玩家自己的 key 调。每回合四步：

1. startSession({ world, variables })：开一局，拿到初始状态和开场白
2. applyVariables(world, state, values)：把游戏的数据写进 game.inputs 列出的变量
3. buildTurnPrompt({ world, state, history, userText, model })：拿到要发给模型的 messages，用玩家的 key 发出去
4. finishTurn({ world, state, userText, rawText })：解析模型的回复，拿到干净的台词和新状态，再从 state.variables 里读 game.outputs 列出的变量

卡的 JSON 里，game 长这样：

"game": {
  "name": "杀戮尖塔 2",
  "inputs": ["hp", "max_hp", "gold", "act"],
  "outputs": ["affection_delta", "choices", "action"]
}

卡可以在 Studio 里写好，下载数据版的 JSON 放进游戏。换一个角色的说话方式，就是换一个文件。