Unity 插件 · NPC 对话与记忆
AI NPC Agent
面向需要可对话角色的 Unity 游戏,将 NPC 人设、玩家记忆与游戏工具接入同一套对话流程。开发者可以在 Unity 中直接连接模型,也可以通过独立服务集中管理角色、会话与长期记忆。
- 运行端
- Unity / C#
- 服务端
- ASP.NET Core
- 管理台
- Vue
使用场景
从玩家的一句话,到带有上下文的回应
在持续的角色交流中,当前话题、玩家留下的线索与游戏状态需要一起参与对话。只把玩家消息发给模型,还需要额外处理角色设定、历史对话、记忆保存和游戏事件。这个项目将这些环节拆成共享的 C# 核心、Unity 接入层与可选服务端,供游戏工程连接自己的交互界面和业务系统。
- 玩家发起交流Unity 传入角色、玩家、会话与消息
- 组织角色上下文服务端按配置载入人设、世界观与记忆
- 生成并显示回复流式文本交给游戏界面;需要工具时进入回传流程
- 更新后续线索保存会话,达到策略阈值后安排后台摘要
以上是 Server 模式的实现流程示意。是否使用长期记忆、哪些工具可以调用,由角色配置与记忆策略决定;具体回复仍取决于所连接的模型。
角色记忆
让短对话和长期线索分层保存
记忆策略按会话、玩家与 NPC 的关系组织,长摘要可以由后台队列处理。Session 短期上下文
保留近期对话片段,为这一轮交流提供上下文。
滚动摘要与结构化事实
沉淀关系范围内的长记忆;不同策略可调整使用的记忆范围。
摘要队列与重试
当记忆达到策略阈值时排入摘要处理,并保存状态以便后续检查。
记忆层次依据插件与服务端实现概括 · 非运行界面截图
短期窗口负责接住当前话题;长期摘要与事实为之后的交流保留线索,并按游戏、NPC 和玩家区分归属。后台队列单独处理摘要,失败任务保留状态以便重试,避免把所有历史消息持续堆进每次请求。
设计选择
从轻量原型到集中管理
两种模式复用 C# 核心与 Unity 接入层,按项目需要选择模型连接和记忆管理的位置。Local · Unity 直连模型
Unity 客户端直接请求兼容模型;不需要另启 AIBot.Server 或数据库。模型仍须可连接,开发期 API Key 会进入客户端运行环境,因此更适合开发或可信场景。
- 本地 NPC / 世界配置
- 游戏内注册工具可直接执行
- 不含独立服务端管理台
Server · 集中管理
Unity 通过 HTTP 与 SSE 连接 AIBot.Server,由服务端维护模型连接、记忆、日志与会话。服务端模式仍依赖模型服务。
- Connection Profile 连接配置
- 服务端长期记忆与调试管理
- 按 requestId 处理恢复与幂等
工具调用
真实游戏工具由 Unity 侧执行
Server 不直接操作游戏状态;工具回传模式将模型请求与 Unity 已注册的本地工具衔接。- 模型请求工具Server 读取 NPC 启用的工具描述
- 挂起并回传调用通过 tool_pending 事件把待执行工具交给 Unity
- Unity 本地执行NpcAgent 调用已注册的游戏工具
- 携带结果续跑Server 接收结果并继续生成回复
例如,接入“赠送道具”工具时,游戏工程需要实现实际背包操作,并将工具注册到 NPC。模型提出调用后,由 Unity 执行,再将成功或失败的结果交回模型继续回复。仓库的 GiveItemTool 是接入示例,背包写入仍需由游戏工程实现。
Server 的 none 模式为默认且不执行工具;simulated 仅用于调试会话状态;game 模式需在 Connection Profile 启用,并同时满足 NPC 工具白名单和 Unity 本地注册条件。断线重放通过请求标识和挂起轮状态避免同一轮重复执行。
Web 管理台
围绕配置与调试组织工具
管理界面围绕服务端配置、对话调试和运行状态检查组织功能。模型连接
集中维护服务端模型连接。
NPC 与世界观
配置角色资料、世界规则与对话提示。
记忆检查
检查记忆内容、策略与迁移状态。
对话与会话
查看流式调试对话、会话及服务端日志统计。
实现范围
对话框架与游戏业务分别接入
项目代码覆盖共享核心、Unity 插件、独立服务和管理台;模型服务与具体游戏系统由接入方提供。共享核心与 Unity 插件
核心组织提示词、对话上下文和工具调用;NpcAgent 将流式片段、完整回复与工具事件交给游戏界面。
服务端与管理台
服务端处理玩家记忆、后台摘要、会话和日志,管理台提供配置与调试入口。存储可选择 JSON 或 MongoDB。
当前接入范围
Unity Package 面向 Unity 2022.3;本页流程依据仓库文档与实现整理。实际角色效果需要结合模型配置与游戏工程验证,示例工具不代表已接通正式背包或任务系统。
Unity 接入与源码
从组件连接到游戏系统
Unity 插件暴露对话、流式片段与工具执行事件;游戏工程决定哪些本地能力允许 NPC 调用。可先从 Unity Package 的 Demo 场景了解组件与对话事件,再按需要选择 Local 或 Server 模式。公开仓库包含安装步骤、工具注册示例和服务端说明。也可以查看另一款游戏作品:雾港小镇。