切换项目AI NPC Agent
本页目录:项目概览

Unity 插件 · NPC 对话与记忆

AI NPC Agent

面向需要可对话角色的 Unity 游戏,将 NPC 人设、玩家记忆与游戏工具接入同一套对话流程。开发者可以在 Unity 中直接连接模型,也可以通过独立服务集中管理角色、会话与长期记忆。

运行端
Unity / C#
服务端
ASP.NET Core
管理台
Vue

使用场景

从玩家的一句话,到带有上下文的回应

在持续的角色交流中,当前话题、玩家留下的线索与游戏状态需要一起参与对话。

只把玩家消息发给模型,还需要额外处理角色设定、历史对话、记忆保存和游戏事件。这个项目将这些环节拆成共享的 C# 核心、Unity 接入层与可选服务端,供游戏工程连接自己的交互界面和业务系统。

  1. 玩家发起交流Unity 传入角色、玩家、会话与消息
  2. 组织角色上下文服务端按配置载入人设、世界观与记忆
  3. 生成并显示回复流式文本交给游戏界面;需要工具时进入回传流程
  4. 更新后续线索保存会话,达到策略阈值后安排后台摘要

以上是 Server 模式的实现流程示意。是否使用长期记忆、哪些工具可以调用,由角色配置与记忆策略决定;具体回复仍取决于所连接的模型。

角色记忆

让短对话和长期线索分层保存

记忆策略按会话、玩家与 NPC 的关系组织,长摘要可以由后台队列处理。
当前会话

Session 短期上下文

保留近期对话片段,为这一轮交流提供上下文。

玩家 × NPC

滚动摘要与结构化事实

沉淀关系范围内的长记忆;不同策略可调整使用的记忆范围。

异步维护

摘要队列与重试

当记忆达到策略阈值时排入摘要处理,并保存状态以便后续检查。

记忆层次依据插件与服务端实现概括 · 非运行界面截图

短期窗口负责接住当前话题;长期摘要与事实为之后的交流保留线索,并按游戏、NPC 和玩家区分归属。后台队列单独处理摘要,失败任务保留状态以便重试,避免把所有历史消息持续堆进每次请求。

设计选择

从轻量原型到集中管理

两种模式复用 C# 核心与 Unity 接入层,按项目需要选择模型连接和记忆管理的位置。

Local · Unity 直连模型

Unity 客户端直接请求兼容模型;不需要另启 AIBot.Server 或数据库。模型仍须可连接,开发期 API Key 会进入客户端运行环境,因此更适合开发或可信场景。

  • 本地 NPC / 世界配置
  • 游戏内注册工具可直接执行
  • 不含独立服务端管理台

Server · 集中管理

Unity 通过 HTTP 与 SSE 连接 AIBot.Server,由服务端维护模型连接、记忆、日志与会话。服务端模式仍依赖模型服务。

  • Connection Profile 连接配置
  • 服务端长期记忆与调试管理
  • 按 requestId 处理恢复与幂等

工具调用

真实游戏工具由 Unity 侧执行

Server 不直接操作游戏状态;工具回传模式将模型请求与 Unity 已注册的本地工具衔接。
  1. 模型请求工具Server 读取 NPC 启用的工具描述
  2. 挂起并回传调用通过 tool_pending 事件把待执行工具交给 Unity
  3. Unity 本地执行NpcAgent 调用已注册的游戏工具
  4. 携带结果续跑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 模式。公开仓库包含安装步骤、工具注册示例和服务端说明。也可以查看另一款游戏作品:雾港小镇。