Neuro SDK 是官方开源的 AI 游戏接入开发工具包，它通过 WebSocket 协议让 AI 角色（Neuro-sama）实时操作你的游戏——从 Inscryption 的卡牌博弈，到赛博朋克2077 的开放世界探索，共 6 款风格迥异的游戏都已成功接入。本文将带你搞懂它的通信原理、官方 SDK 用法和 0 成本本地联调技巧，帮你快速让自己的游戏也"听得懂 AI"。

🤖 30 秒看懂：Neuro SDK 是什么？

先说结论：Neuro SDK = 一套消息协议 + 两个官方引擎 SDK + 配套测试工具。

• API 规范：定义游戏与 AI 之间通过 WebSocket 收发的 JSON 消息，详见 SPECIFICATION.md
• 官方 SDK：Unity SDK（C#）与 Godot SDK（GDScript），两者接口思路完全一致
• 开源示例：6 款不同玩法的游戏接入案例（见下文清单）
• 测试工具：Randy 机器人，本地模拟 AI 行为，不用真 AI 也能联调

💡 官方 SDK 最初为回合制游戏（Inscryption、Liar's Bar、Buckshot Roulette）优化。高 APM 的操作类游戏需要 AI 只负责"高层决策"，再由游戏内系统执行底层操作，才能玩得好。

⚡ 核心原理：游戏如何与 AI 对话？

所有魔法都发生在这 5 类消息里（完整定义见 SPECIFICATION.md）：

辅助命令还有context（同步游戏内发生的事情给 AI 看）、actions/unregister（下架动作）。

🎯 关键设计：ActionWindow（动作窗口）

回合制游戏最核心的抽象。SDK 把"临时动作 + 强制 AI 行动 + 自动清理"打包成一个窗口，生命周期只有 4 种状态：Building→Registered→Forced→Ended。

• 你的回合开始：创建窗口、加入动作（如play_card）、强制 AI 立即决策
• AI 选完：SDK 自动验证（Validate）、回结果（action/result）、执行（Execute）并注销动作
• 两个 SDK 的完整时序图（mermaid）可对照阅读：Godot USAGE.md、Unity USAGE.md

⚠️新手第一坑：AI 可能在你没强制之前就"抢跑"发出动作。所以动作处理器必须随时待命，不能只在actions/force之后才监听。官方最佳实践见 API/README.md 的 Actions 指南，其中 ActionWindow.cs 是公认的教科书级实现。

🎮 实战案例：6 款风格迥异的游戏如何接入？

README.md 中列出了 6 个官方开源集成项目，覆盖了完全不同的游戏类型——这正是"6 种风格迥异"的出处：

共同规律：能被"文本描述状态 + 文本接收动作"的游戏最适配。官方点名表现好的还有 Uno、Monopoly、《Keep Talking and Nobody Explodes》以及大多数视觉小说（清单见 README.md）。

🛠️ 两套官方 SDK：选型与快速上手

Unity SDK（C#）

• 适用：Unity 原生开发（2022.3 测试）、WebGL 构建、以及Mono / IL2CPP 改造游戏的 Mod 注入（通过 NuGet 包VedalAI.NeuroSdk.Unity分发，见 Unity/NuGet/）
• 接入方式：
  • 拖NeuroSdk预制体到首场景，填游戏名（推荐）
  • 或调用NeuroSdkSetup.Initialize（Mod 环境唯一方式，见 NeuroSdkSetup.cs）
• WebGL 专属：压缩格式设为 Gzip，并用 Web Game Runner/server.py 在/$env/NEURO_SDK_WS_URL路径下发 WebSocket 地址

Godot SDK（GDScript）

• 适用：Godot 4.x 原生项目，可直接从 Godot 资源库安装
• 三步配置：
  1. 启用插件：Project > Project Settings > Plugins勾选Neuro SDK
  2. 在 neuro_sdk_config.gd 中设置game变量为你的游戏名
  3. 设置环境变量NEURO_SDK_WS_URL指向 WebSocket 地址

🎓 内置教学示例：井字棋

两个 SDK 各带一个完整的 Tic Tac Toe 示例，是新手的最佳起点：

• Unity 版：TicTacToe.cs、Tic Tac Toe.prefab
• Godot 版：tic_tac_toe.gd、play_o_action.gd

核心套路只有几行：回合开始时ActionWindow.SetForce(0, "It is your turn...")强制 AI 出招，.AddAction(...)挂上play_o动作，.Register()注册生效——完整代码对照 Godot USAGE.md 与 Unity USAGE.md。

🧪 0 成本联调：用 Randy 机器人自测

没有 AI 也能测！Randy 是一个随机选动作的 WebSocket 服务器，本地模拟 AI：

1. 在Randy目录执行npm install，再npm start
2. 将游戏/SDK 的 WebSocket 地址指向ws://localhost:8000
3. 用 HTTP POST 到localhost:1337手动注入消息（如模拟 AI 执行join_friend_lobby），验证你的游戏能否正确处理

⚠️ Randy 不会模拟"乱发脏数据""不强制就抢跑"等 AI 的真实毛刺，所以 API/README.md 中列出的竞态条件防护依然要做。

✅ 新手接入清单

• 通读 API/SPECIFICATION.md，理解 5 类核心消息
• 跑通官方井字棋示例（Unity / Godot 任选）
• 用 Randy 把startup → register → force → action → result全链路走通
• 给 AI 写清楚每个动作的description和 JSON schema——这些文字会被 AI 直接读到，描述质量决定 AI 发挥
• 一次性动作（如出牌）执行后立即unregister，防止 AI 重复调用
• 关注 CHANGELOG.md：新增的priority参数（low/medium/high/critical）可控制 AI 说话被打断的紧急程度，做语音直播联动时很有用

写在最后

Neuro SDK 的精髓在于把"游戏状态"翻译成文本、把"玩家操作"翻译成动作。只要你的游戏状态可以文字描述、动作可以离散化，AI 就能上手玩——这正是它横跨卡牌、Roguelike、动作、开放世界、模拟器这 6 种风格游戏的底层原因。从井字棋示例出发，你的下一步可能是让 AI 玩自己正在开发的那个游戏 🚀