Godot AI Hook

简体中文 | English

概要：用途与优点

Godot AI Hook 是一个面向 Godot 4 的 AI 聊天插件，用于快速接入兼容 OpenAI Chat Completions 协议的模型 （例如：部分云厂商提供的兼容接口）。

如果你希望把 DeepSeek、豆包 这类大模型轻松接进游戏里，让：

• 主角和敌人可以对话
• NPC 拥有“自己的想法”
• 背景文本、旁白更加生动

那这个插件就像一个 AI 的钩子，直接挂载在节点上，用起来简单直观。

设计目标

Godot AI Hook 并不是一个“全能 AI 框架”， 而是围绕一个非常明确的目标进行设计：

用最少的心智负担，把 AI「挂」进 Godot 场景里。

因此在设计上遵循了以下原则：

---

1️⃣ 节点即 AI（Node-first）

在 Godot 中，一切都是节点。

与其提供大量静态工具类或复杂 API， 不如让 AI 本身成为一个可以被挂载、被引用、被管理的节点。

• AiManage 就是一个 AI 能力节点
• 你只需要把它挂在场景树里
• UI、NPC、系统逻辑都可以直接调用它

这让 AI 更像一个“游戏组件”，而不是外部服务。

---

2️⃣ 流式与非流式统一抽象

不同使用场景对 AI 输出方式的需求完全不同：

• 对话框、字幕 → 需要流式输出
• 一次性分析、系统提示 → 非流式即可

插件内部将两种模式封装为：

• ChatNode（非流式）
• ChatStreamNode（流式）

但对使用者来说，只需要面对少数入口：

ai_manage.say(...)
ai_manage.say_bind_key(...)

实现方式可以变，使用方式不需要变。

---

3️⃣ 偏客户端定位，而非平台绑定

Godot AI Hook 的定位是：

“AI 调用客户端”，而不是某一家模型平台的 SDK。

因此：

• 不强绑定具体模型
• 不依赖特定云厂商
• 只要是 OpenAI Chat Completions 兼容接口，就尽量支持

这让你可以：

• 自由切换模型（DeepSeek / 豆包 / 本地模型）
• 在开发阶段用便宜模型，发布前再替换

---

4️⃣ 防御性而非“魔法式”设计

插件并不会假设：

• API Key 一定存在
• 网络一定正常
• JSON 返回一定合法

而是尽量：

• 在每一步做校验
• 在控制台给出明确错误
• 不 silently fail（悄悄失败）

这对调试期和学习期尤为重要。

---

🎮 使用场景说明（Use Cases）

以下是 Godot AI Hook 非常适合 的典型场景：

---

🧙 NPC 对话与性格驱动

• 每个 NPC 使用不同的 System Prompt
• 即时生成对话内容
• 让 NPC 不再只是“选项树”

---

📜 剧情旁白 / 世界观文本生成

• 流式输出非常适合：

  • 剧情字幕
  • 世界观介绍
  • 回忆、独白

搭配打字机效果，可以显著提升沉浸感。

---

🧪 原型验证 & 玩法实验

在原型阶段，你可以：

• 不写完整剧情
• 不设计复杂对话树
• 用 AI 快速验证玩法感觉

---

🤖 游戏内 AI 助手 / 引导角色

• 新手教程助手
• 系统提示角色
• “第四面墙外”的解释者

---

🛠️ 非正式用途（工具 / 实验）

虽然是游戏插件，但它也可以用于：

• Godot 内部工具 AI
• 文本生成测试
• AI 行为实验

---

✨ 一句话总结设计理念

Godot AI Hook 不试图教你“如何使用 AI”， 它只负责把 AI，变成一个你熟悉的 Godot 节点。

提示 大多数模型服务商都提供 OpenAI 兼容接口，本插件已尽量适配。 但由于各家在输入输出细节上的差异，个别模型可能无法正常连接，敬请理解。

---

安全声明与免责声明

本项目仅实现 AI 调用逻辑，主要用于个人学习、研究和娱乐实验， 未针对安全与合规场景进行系统性设计。在使用时请自行做好风险评估，包括但不限于：

• 妥善保管 API Key，不要将真实密钥提交到公开仓库或截图中泄露；
• 合理设置调用频率与配额，避免接口滥用或触发服务商风控；
• 根据业务场景对 AI 输出进行审核与过滤，避免直接作为最终决策依据。

本项目仅作为 AI 服务调用的客户端封装，不对模型生成内容承担任何责任。 请在遵守所在地区法律法规及模型服务商使用条款的前提下合理使用。

作者能力有限，如有设计或实现不当之处，欢迎：

• 提 Issue
• 提 PR
• Fork 本仓库一起改进

---

项目结构

addons/
└─ godot_ai_hook/
   ├─ plugin.cfg                  # Godot 插件配置（名称、描述、入口脚本）
   ├─ plugin.gd                   # EditorPlugin：注册菜单、打开测试面板与配置脚本
   │
   ├─ ai_config.gd                # 模型基础配置（url / api_key / model / port）
   ├─ system_prompt_config.gd     # System Prompt 配置字典（按 key 管理）
   │
   ├─ ai_manage/
   │  ├─ ai_manage.gd             # AiManage 核心管理节点（统一入口）
   │  └─ ai_manage.tscn           # AiManage 场景
   │
   ├─ chat_node/
   │  ├─ chat_node.gd             # 非流式实现：HTTPRequest + 单次 JSON 响应
   │  └─ chat_node.tscn           # ChatNode 场景
   │
   ├─ chat_stream_node/
   │  ├─ chat_stream_node.gd      # 流式实现：HTTPClient + SSE 文本流
   │  └─ chat_stream_node.tscn    # ChatStreamNode 场景
   │
   └─ test/
      ├─ test.gd                  # 测试面板脚本（连接测试 + 效果测试）
      └─ test.tscn                # 测试面板场景

核心脚本职责说明

AiManage

• 重要对外接口：

  • say(content, system_prompt)
  • say_bind_key(content, key)
  • set_ai_stream_type(is_true)

ChatNode

• 使用 HTTPRequest 发送一次性请求
• 解析完整 JSON 响应
• 出错时通过 parent.on_ai_error_occurred() 回调

ChatStreamNode

• 使用 HTTPClient 建立 HTTPS 连接

• 发送 stream: true 的请求

• 解析以 data: 开头的 SSE 文本流

• 识别 [DONE] 结束标记

• 通过以下回调推送增量内容：

  • on_ai_reasoning_content_generated
  • on_ai_content_generated

测试面板（test）

• 提供 UI 用于快速测试 API 连接与展示效果
• 包含中断长文本生成的实验逻辑

---

使用方法

1. 安装插件

将 godot_ai_hook 文件夹复制到项目的 addons 目录中。 然后在：

菜单栏 → 项目 → 项目设置 → 插件

中启用插件。

---

2. 配置模型信息

在 菜单栏 → 项目 → 工具 中可以看到 AI Hook 相关选项。

点击 AI Hook：打开模型配置脚本，根据所使用模型服务商的文档填写配置。

---

3. 测试模型连接

点击 AI Hook：打开测试面板，进入测试场景并运行。

连接成功示例：

---

4. 使用 Godot AI Hook

在场景中选择一个文本节点，在其下挂载一个 ai_manage 节点 （Ctrl + A 搜索 ai_manage 即可）。

在脚本中引用该节点并调用：

ai_manage.say("你想问的问题")

运行场景即可看到 AI 回复。

---

5. 使用自定义 System Prompt

虽然可以直接传入 system_prompt：

ai_manage.say("问题内容", system_prompt)

但 System Prompt 通常较长，更推荐使用配置文件 + key 的方式。

在 菜单栏 → 项目 → 工具 → AI Hook：打开提示词配置脚本 中配置：

示例调用：

ai_manage.say_bind_key("你好啊，deepseek", "友情猫娘")

就像一个“猫娘 AI 钩子”挂在节点上一样 🐱

---

6. 将流式节点改为非流式节点

示例调用：

ai_manage.set_ai_stream_type(true)#设为流式
ai_manage.set_ai_stream_type(false)#设为非流式

支持与 Star ⭐

如果这个插件对你有帮助，或者在你的项目中哪怕只发挥了一点点作用， 欢迎在 GitHub 上点一个 Star ⭐。

你的支持是作者持续维护、修复问题并尝试加入更多有趣功能的最大动力 ❤️

---