【免费下载链接】AgentshireOpenClaw / QClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.项目地址https://gitcode.com/gh_mirrors/ag/Agentshire点击查看免费下载Agentshire 是一款让 AI Agent住进3D 游戏小镇的开源插件每个子 Agent 自动变成小镇里的 NPC 居民有名字、有形象、有人格还能在头顶用打字机效果实时吐出对话气泡。本文带你读懂这套「Agent → NPC」的核心映射机制与气泡渲染链路全程无需写代码读完即可理解 src/bridge/ 目录里各模块如何分工协作。一张链路图从 AgentEvent 到头顶气泡整个转换过程可以概括为四步事件接入 → ID 映射 → 事件翻译 → 前端渲染。官方架构文档里画了完整的数据流见 src/bridge/AGENTS.md#L25-L51hook-translator插件层→ AgentEvent → DirectorBridge 编排 → GameEvent → MainScene 渲染AgentEventOpenClaw 协议层的原始信号比如某个子 Agent 启动了模型正在流式输出文字调用了某个工具。GameEvent3D 前端能直接消费的游戏指令比如生成一个 NPC切换为工作状态弹一条对话消息。两者之间的翻译官就是 Bridge 层它的角色定位相当于小镇的总导演DirectorBridge.ts 负责编排其余模块负责寻路、动画、气泡保护等具体事务。核心映射agentId ↔ npcId 双向注册表为什么需要翻译名字Agent 世界和游戏世界的两套 ID 并不相同模型侧叫agent_xxx游戏侧需要稳定、可读的 NPC ID。承担这份户籍管理工作的是 StateTracker.ts它维护一张双向映射表registerMapping(agentId, npcId)子 Agent 一启动就登记户口从此两边可以互相反查removeMapping(agentId)任务结束时销户并释放占用的工位。子 Agent 启动 居民入驻小镇当总导演收到sub_agent.started事件时兜底翻译器 EventTranslator.ts#L84-L123 会发出两件事npc_spawn在小镇里生成一个 3D 居民附带名字、角色如 programming和形象workstation_assign从 A–J 共 10 个工位池中分配一个工位让居民有地方上班。任务完成时sub_agent.done同一个居民会被标记为done或error状态配上绿色/红色辉光和撒花、火花特效——工作成败肉眼可见。状态机8 种 Phase 决定 NPC 的姿态除了 IDAgent 的当前在干什么也被映射成游戏状态。协议层定义了 AgentPhasethinking、tool_calling、streaming 等前端则用 NPCPhaseidle、working、talking、error 等驱动动画。thinking_delta事件让 NPC 进入思考姿态tool_use让它进入工作状态出错时切换为 error 并做出沮丧表情——一套完整的情绪映射。事件翻译与工具特效写代码变成上班ToolVfxMapper.ts#L31-L38 是一张工具 → 表情对照表write_file/edit_file显示 bash显示 ⚡read_file/grep显示 。也就是说Agent 每调用一个工具对应 NPC 就会做出匹配的视觉反馈——这就是电影级工作流的底层原理。实时对话气泡从流式文本到打字机效果这是全文最出片的部分。AI 的回复如何变成 NPC 头顶那个会打字、会自动消失的气泡第一步流式消息进入对话队列模型每吐出一小段文字text_deltaBridge 就会发出 dialog_message 事件并附带isStreaming: true标记。管家的回复由 handleStewardText 统一处理还会顺带发出npc_look_at事件让 NPC 转头看向你——它真的在看着你说话。第二步排队保护气泡不会被抢跑有个容易忽视的细节Agent 输出文字的同时还在频繁切换状态如果状态事件先落地气泡还没来得及显示就会被覆盖。NpcEventQueue.ts#L22-L36 的解法很优雅——对话优先对话事件立即发出并进入保护期时长与文本长度成正比120ms/字1.5s 起、8s 封顶期间到达的状态切换事件先缓存保护期结束后再统一放行。第三步打字机、分页与自动淡出前端真正演出逻辑在 ChatBubble.ts。它的update()循环#L205-L292每帧做三件事打字机约 30ms 显示一个字文字逐个打出来分页超过 4 行的长回复自动翻页页与页之间显示▼提示停留 1.6 秒后翻到下一页定位与淡出气泡锚定在 NPC 头顶 2.2 单位高度处跟随角色移动流式结束后再停留 2.6 秒随后 0.5 秒淡出消失。一套参数调下来气泡既不会一闪而过也不会霸屏太久。彩蛋机制写一个人设文件居民自动出生CitizenManager.ts 还藏着一个好玩的映射当 Agent 往personas目录写入一个.md人设文件时小镇会自动迎接一位新居民。它的入场动画被编排成一段小剧场#L142-L229在小镇入口指定坐标生成 NPC并分配随机形象沿 A* 寻路走到广场向管家鞠躬问好挥手 感叹号特效弹出气泡「你好我是 XX很高兴来到小镇」最后走向一个按评分挑选的目的地正式入住。现成的居民人设可以放在 town-souls/ 目录参考比如 CHEN.md。新手上手路径想动手体验这套映射机制从这几个文件入手最省力想了解的内容去看这里事件如何流转src/bridge/AGENTS.md双向 ID 映射与工位分配src/bridge/StateTracker.ts气泡排队保护src/bridge/NpcEventQueue.ts气泡渲染细节town-frontend/src/ui/ChatBubble.ts小镇默认配置town-workspace/town-defaults.json小结Agentshire 的核心魔法本质上是三层映射的叠加ID 映射agentId ↔ npcId 户籍表解决你是谁状态映射AgentPhase → NPCPhase 工具特效解决你在干什么流式映射text_delta → dialog_message → 打字机气泡解决你怎么说话。理解这三层你就读懂了 AI Agent 变成 3D NPC 的全部秘密。️赞分享【免费下载链接】AgentshireOpenClaw / QClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.项目地址https://gitcode.com/gh_mirrors/ag/Agentshire点击查看免费下载相关推荐Agentshire 是什么把AI Agent变成3D小镇NPC的终极入门指南Agentshire 是什么把AI Agent变成3D小镇NPC的终极入门指南 Agentshire 是一个 OpenClaw / QClaw 插件它的核心深入解析 Forge 实现型 Agent读懂 forge.md 如何驱动 AI 结对编程的核心执行引擎深入解析 Forge 实现型 Agent读懂 forge.md 如何驱动 AI 结对编程的核心执行引擎 导读 本文以 Forge 仓库内置的 forge.m人工智能AI Agent代码智能体AI 应用CLI开发工具Apache Beam 核心变换用 MapElements 与 beam.Map 优雅实现元素的一对一映射Apache Beam 核心变换用 MapElements 与 beam.Map 优雅实现元素的一对一映射 Map 类变换是 Apache Beam 数据处理批处理流处理大数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 【免费下载链接】AgentshireOpenClaw / QClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.项目地址https://gitcode.com/gh_mirrors/ag/Agentshire点击查看免费下载Agentshire 是一款让 AI Agent住进3D 游戏小镇的开源插件每个子 Agent 自动变成小镇里的 NPC 居民有名字、有形象、有人格还能在头顶用打字机效果实时吐出对话气泡。本文带你读懂这套「Agent → NPC」的核心映射机制与气泡渲染链路全程无需写代码读完即可理解 src/bridge/ 目录里各模块如何分工协作。一张链路图从 AgentEvent 到头顶气泡整个转换过程可以概括为四步事件接入 → ID 映射 → 事件翻译 → 前端渲染。官方架构文档里画了完整的数据流见 src/bridge/AGENTS.md#L25-L51hook-translator插件层→ AgentEvent → DirectorBridge 编排 → GameEvent → MainScene 渲染AgentEventOpenClaw 协议层的原始信号比如某个子 Agent 启动了模型正在流式输出文字调用了某个工具。GameEvent3D 前端能直接消费的游戏指令比如生成一个 NPC切换为工作状态弹一条对话消息。两者之间的翻译官就是 Bridge 层它的角色定位相当于小镇的总导演DirectorBridge.ts 负责编排其余模块负责寻路、动画、气泡保护等具体事务。核心映射agentId ↔ npcId 双向注册表为什么需要翻译名字Agent 世界和游戏世界的两套 ID 并不相同模型侧叫agent_xxx游戏侧需要稳定、可读的 NPC ID。承担这份户籍管理工作的是 StateTracker.ts它维护一张双向映射表registerMapping(agentId, npcId)子 Agent 一启动就登记户口从此两边可以互相反查removeMapping(agentId)任务结束时销户并释放占用的工位。子 Agent 启动 居民入驻小镇当总导演收到sub_agent.started事件时兜底翻译器 EventTranslator.ts#L84-L123 会发出两件事npc_spawn在小镇里生成一个 3D 居民附带名字、角色如 programming和形象workstation_assign从 A–J 共 10 个工位池中分配一个工位让居民有地方上班。任务完成时sub_agent.done同一个居民会被标记为done或error状态配上绿色/红色辉光和撒花、火花特效——工作成败肉眼可见。状态机8 种 Phase 决定 NPC 的姿态除了 IDAgent 的当前在干什么也被映射成游戏状态。协议层定义了 AgentPhasethinking、tool_calling、streaming 等前端则用 NPCPhaseidle、working、talking、error 等驱动动画。thinking_delta事件让 NPC 进入思考姿态tool_use让它进入工作状态出错时切换为 error 并做出沮丧表情——一套完整的情绪映射。事件翻译与工具特效写代码变成上班ToolVfxMapper.ts#L31-L38 是一张工具 → 表情对照表write_file/edit_file显示 bash显示 ⚡read_file/grep显示 。也就是说Agent 每调用一个工具对应 NPC 就会做出匹配的视觉反馈——这就是电影级工作流的底层原理。实时对话气泡从流式文本到打字机效果这是全文最出片的部分。AI 的回复如何变成 NPC 头顶那个会打字、会自动消失的气泡第一步流式消息进入对话队列模型每吐出一小段文字text_deltaBridge 就会发出 dialog_message 事件并附带isStreaming: true标记。管家的回复由 handleStewardText 统一处理还会顺带发出npc_look_at事件让 NPC 转头看向你——它真的在看着你说话。第二步排队保护气泡不会被抢跑有个容易忽视的细节Agent 输出文字的同时还在频繁切换状态如果状态事件先落地气泡还没来得及显示就会被覆盖。NpcEventQueue.ts#L22-L36 的解法很优雅——对话优先对话事件立即发出并进入保护期时长与文本长度成正比120ms/字1.5s 起、8s 封顶期间到达的状态切换事件先缓存保护期结束后再统一放行。第三步打字机、分页与自动淡出前端真正演出逻辑在 ChatBubble.ts。它的update()循环#L205-L292每帧做三件事打字机约 30ms 显示一个字文字逐个打出来分页超过 4 行的长回复自动翻页页与页之间显示▼提示停留 1.6 秒后翻到下一页定位与淡出气泡锚定在 NPC 头顶 2.2 单位高度处跟随角色移动流式结束后再停留 2.6 秒随后 0.5 秒淡出消失。一套参数调下来气泡既不会一闪而过也不会霸屏太久。彩蛋机制写一个人设文件居民自动出生CitizenManager.ts 还藏着一个好玩的映射当 Agent 往personas目录写入一个.md人设文件时小镇会自动迎接一位新居民。它的入场动画被编排成一段小剧场#L142-L229在小镇入口指定坐标生成 NPC并分配随机形象沿 A* 寻路走到广场向管家鞠躬问好挥手 感叹号特效弹出气泡「你好我是 XX很高兴来到小镇」最后走向一个按评分挑选的目的地正式入住。现成的居民人设可以放在 town-souls/ 目录参考比如 CHEN.md。新手上手路径想动手体验这套映射机制从这几个文件入手最省力想了解的内容去看这里事件如何流转src/bridge/AGENTS.md双向 ID 映射与工位分配src/bridge/StateTracker.ts气泡排队保护src/bridge/NpcEventQueue.ts气泡渲染细节town-frontend/src/ui/ChatBubble.ts小镇默认配置town-workspace/town-defaults.json小结Agentshire 的核心魔法本质上是三层映射的叠加ID 映射agentId ↔ npcId 户籍表解决你是谁状态映射AgentPhase → NPCPhase 工具特效解决你在干什么流式映射text_delta → dialog_message → 打字机气泡解决你怎么说话。理解这三层你就读懂了 AI Agent 变成 3D NPC 的全部秘密。️赞分享【免费下载链接】AgentshireOpenClaw / QClaw plugin that visualizes AI agents as 3D NPCs in a game town — with social simulation, a map editor, and a character workshop.项目地址https://gitcode.com/gh_mirrors/ag/Agentshire点击查看免费下载相关推荐Agentshire 是什么把AI Agent变成3D小镇NPC的终极入门指南Agentshire 是什么把AI Agent变成3D小镇NPC的终极入门指南 Agentshire 是一个 OpenClaw / QClaw 插件它的核心深入解析 Forge 实现型 Agent读懂 forge.md 如何驱动 AI 结对编程的核心执行引擎深入解析 Forge 实现型 Agent读懂 forge.md 如何驱动 AI 结对编程的核心执行引擎 导读 本文以 Forge 仓库内置的 forge.m人工智能AI Agent代码智能体AI 应用CLI开发工具Apache Beam 核心变换用 MapElements 与 beam.Map 优雅实现元素的一对一映射Apache Beam 核心变换用 MapElements 与 beam.Map 优雅实现元素的一对一映射 Map 类变换是 Apache Beam 数据处理批处理流处理大数据创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考