CraftAgent
一款 Minecraft Fabric 模组,将智能 AI NPC 带入你的世界。NPC 使用大型语言模型 (LLM) 来理解上下文、做出决策并与玩家互动。
功能
- ? AI 驱动 NPC:使用 LLM(Ollama、LM Studio)进行智能决策
- ? 自主行动:NPC 执行 Minecraft 命令与世界互动
- ? 对话记忆:SQLite 持久化对话历史
- ? 世界环境感知:NPC 理解周围环境(方块、实体、物品栏、导航、视线)
- ? 多 LLM 支持:Ollama 和 LM Studio (OpenAI 兼容)
- ? 客户端-服务器架构:客户端 GUI 配置,服务端处理 NPC 逻辑
- ?️ 命令系统:使用 Brigadier 发现并执行所有 Minecraft 命令
- ? Web 仪表板:内置 Web UI (),基于 LLM 处理间隔自动刷新
- ? 邮件系统:NPC 可通过邮件系统发送和接收消息
- ? 定向聊天消息:使用 "npcName: message" 格式向特定 NPC 发送消息,或向所有 NPC 广播
- ? 记忆系统:私有和共享记忆(privateBook, sharebook)用于持久知识
- ⚡ 结构化动作:LLM 返回包含消息和可执行动作的结构化输出
- ? 实时更新:Web UI 自动更新,无需手动刷新
- ? 导航系统:NPC 可前往坐标、实体或方块,并带有状态跟踪
- ?️ 视线检测:NPC 检测其视线范围内的物品、实体和方块
- ⚡ 动作状态管理:跟踪当前动作(挖掘、建造、制作、狩猎、农耕、钓鱼、战斗)
- ?️ 高级动作:挖掘、建造、制作、狩猎、农耕、钓鱼和战斗动作
- ⏸️ LLM 控制:切换以跳过每个 NPC 的 LLM 请求,以及手动触发 LLM 的命令
要求
- Minecraft: 1.20.1 或 1.21.8
- Java: 17 (1.20.1) 或 21 (1.21.8+)
- Fabric Loader: 0.17.3+
- LLM 服务: 本地运行的 Ollama 或 LM Studio
安装
对于玩家
- 从 Modrinth 或 CurseForge 下载最新的 JAR 文件
- 将 JAR 文件放入
mods 文件夹
- 安装并启动以下任一服务:
- 启动 Minecraft 并享受!
对于开发者
-
克隆仓库:
git clone https://github.com/prskid1000/CraftAgent.git
cd CraftAgent
-
构建项目:
# Windows
.\gradlew.bat :1.21.8:build
# Linux/Mac
./gradlew :1.21.8:build
-
在 versions/1.21.8/build/libs/ 中找到编译后的 JAR 文件
构建
# 为特定版本构建
.\gradlew.bat :1.21.8:build
# 构建所有版本
.\gradlew.bat build
# 在开发环境中运行
.\gradlew.bat :1.21.8:runServer
用法
命令
-
/craftagent - 打开配置 GUI
-
/craftagent add <name> <llmType> - 创建新 NPC
-
/craftagent remove <name> - 移除 NPC(保留数据)
-
/craftagent <npcName> llm - 手动触发指定 NPC 的 LLM 调用(NPC 名称不区分大小写)
-
/craftagent <npcName> <action> - 在指定 NPC 上执行动作(NPC 名称不区分大小写)
记忆动作:
/craftagent Steve sharedbook add "Iron Mine" "Iron mine located at coordinates 150, 64, -200"
/craftagent Steve sharedbook add BaseLocation "Our base is at spawn"
/craftagent Steve sharedbook remove "Iron Mine"
/craftagent Steve privatebook add "Secret Plan" "I will build a house tomorrow"
/craftagent Steve privatebook add Notes "Remember to craft more tools"
/craftagent Steve privatebook remove "Secret Plan"
通信动作:
/craftagent Steve mail send Alice "Hello there! Want to mine together?"
/craftagent Steve mail send Bob "Found some diamonds at 200, 50, -100"
导航动作:
/craftagent Steve travel to 100 64 200
/craftagent Steve travel to entity Zombie
/craftagent Steve travel to block iron_ore
/craftagent Steve travel stop
挖掘动作:
/craftagent Steve mine iron_ore 5
/craftagent Steve mine diamond_ore
/craftagent Steve mine at 150 64 -200
建造动作:
/craftagent Steve build stone_bricks at 100 65 200
/craftagent Steve place oak_planks at 101 65 201
制作动作:
/craftagent Steve craft iron_pickaxe
/craftagent Steve craft wooden_sword
狩猎动作:
/craftagent Steve hunt zombie
/craftagent Steve hunt Creeper
/craftagent Steve hunt Skeleton
农耕动作:
/craftagent Steve farm plant wheat at 50 64 50
/craftagent Steve farm plant carrot at 51 64 51
/craftagent Steve farm harvest at 50 64 50
/craftagent Steve farm harvest
钓鱼动作:
/craftagent Steve fish
/craftagent Steve fish stop
战斗动作:
/craftagent Steve attack Zombie
/craftagent Steve attack zombie
/craftagent Steve defend
聊天消息
玩家可以通过聊天向 NPC 发送消息。消息会自动路由到 NPC:
- 定向消息:
steve: Do your homework - 仅发送给名为 "steve" 的 NPC(不区分大小写)
- 广播消息:
Do your homework - 发送给所有 NPC
NPC 名称匹配不区分大小写,因此 steve、STEVE 和 Steve 都匹配同一个 NPC。
有用的 Minecraft 键
- F3: 打开显示坐标、FPS、区块信息和其他技术细节的调试屏幕。在给予 NPC 旅行指令时,可用于查找坐标。
- F3+P: 切换失去焦点时的暂停状态。启用后,当你切换到其他窗口(Alt+Tab)时,游戏将继续运行,这有助于在后台监控 NPC。
Web 仪表盘
CraftAgent 包含一个内置的 Web 仪表盘,用于实时监控 NPC。该仪表盘会在 Minecraft 服务器启动时自动启动。
访问仪表盘:
- 启动安装了 CraftAgent 的 Minecraft 服务器
- 打开你的网页浏览器并导航至:
- 仪表盘将显示所有活跃 NPC 及其当前状态
仪表盘功能:
- NPC 概览:查看所有 NPC 的基本信息(名称、年龄、性别、生命值、饥饿值、位置、当前动作、导航状态)
- 状态选项卡:实时统计数据,包括生命值和饥饿值的进度条、位置坐标以及生物群系信息
- 上下文选项卡:详细的世界上下文信息,包括:
- 状态信息(位置、生命值、饥饿值、生物群系)
- 物品栏详情(快捷栏、主物品栏、护甲、副手)
- 附近方块表格(类型、位置、挖掘等级、所需工具)
- 附近实体表格(名称、类型、ID、玩家状态)
- 导航状态(当前状态、目的地、在该状态下的持续时间)
- 当前动作(动作类型、描述、持续时间、特定于动作的数据)
- 视线数据:
- 视线内的物品(类型、数量、位置、距离)
- 视线内的实体(名称、类型、ID、玩家状态)
- 目标方块(NPC 注视的位置)
- 可见方块(视线范围内可见的方块)
- 消息选项卡:对话历史记录,带有角色徽章和时间戳
- 邮件选项卡:来自其他 NPC 和玩家的邮件消息
- 记忆选项卡:NPC 的持久化记忆,包括:
- 私人书页(NPC 专属记忆)
- 共享书页(所有 NPC 均可访问)
自动刷新:
- 仪表盘基于最大 LLM 处理间隔进行自动刷新
- 所有数据(NPC、消息、邮件、记忆)都会按照配置的间隔自动更新
- 无需手动刷新——用户界面与服务器保持同步
- 触发更新的时机包括:
- 创建或删除 NPC
- 对话历史中添加新消息
- 发送或接收邮件消息
- 记忆(私人/共享书页)更新
创建 NPC
- 启动你的 LLM 服务(Ollama 或 LM Studio)
- 使用
/craftagent create <name> <llmType> 或通过 /craftagent 打开 GUI
- 配置 NPC:
- 名称:显示名称
- LLM 类型:
ollama 或 lm_studio
- 模型:模型名称(例如
llama3)
- URL:LLM 服务 URL(默认值:Ollama 为
http://localhost:11434,LM Studio 为 http://localhost:1234/v1)
- 跳过 LLM 请求:切换此选项可禁用该 NPC 的自动 LLM 处理(适用于测试或在 LLM 服务不可用时使用)
控制 LLM 处理
- 自动处理:NPC 会按照配置的间隔自动处理 LLM 调用(参见基础配置中的
llmProcessingInterval)
- 跳过 LLM 请求:在 NPC 配置中启用“跳过 LLM 请求”切换开关,以禁用该 NPC 的所有 LLM 调用(包括自动和手动)
- 手动触发:使用
/craftagent <npcName> llm 手动触发特定 NPC 的 LLM 调用(仅在 skipLLMRequests 禁用的情况下有效)
LLM 设置
Ollama
- 从 ollama.ai 安装
- 启动:
ollama serve
- 拉取模型:
ollama pull llama3
- 配置 NPC:LLM 类型
ollama,模型 llama3,URL http://localhost:11434
LM Studio
- 从 lmstudio.ai 安装
- 下载模型并启动本地服务器(端口 1234)
- 配置 NPC:LLM 类型
lm_studio,模型名称,URL http://localhost:1234/v1
架构
系统架构概览
graph TB
subgraph "Client Side"
GUI[OWO UI Screens]
ClientNet[Client Network Manager]
GUI --> ClientNet
end
subgraph "Server Side"
Main[CraftAgent Mod]
CmdMgr[Command Manager]
NetHandler[Network Handler]
NPCService[NPC Service]
EventReg[EventListener Registerer]
WebServer[Web Server :8080]
Main --> CmdMgr
Main --> NetHandler
Main --> NPCService
Main --> EventReg
Main --> WebServer
end
subgraph "NPC Components"
NPCFactory[NPC Factory]
NPCEntity[Server Player Entity]
EventHandler[NPCEventHandler]
ContextProv[Context Provider]
History[Conversation History]
LLMClient[LLM Client]
NPCService --> NPCFactory
NPCFactory --> NPCEntity
NPCFactory --> EventHandler
NPCFactory --> ContextProv
NPCFactory --> History
NPCFactory --> LLMClient
end
subgraph "Data Layer"
SQLite[(SQLite Database)]
ConfigFiles[Config Files]
Repos[Repositories]
NPCService --> Repos
Repos --> SQLite
NPCService --> ConfigFiles
end
subgraph "External Services"
Ollama[Ollama API]
LMStudio[LM Studio API]
LLMClient --> Ollama
LLMClient --> LMStudio
end
ClientNet <--> NetHandler
EventReg --> NPCService
WebServer --> NPCService
组件架构
graph LR
subgraph "核心服务"
NPCService[NPC 服务<br/>生命周期管理]
CoordinationService[协调服务<br/>NPC 通信]
ConfigProvider[配置提供程序<br/>配置管理]
end
subgraph "NPC 实例"
NPC[NPC 模型]
EventHandler[事件处理器<br/>LLM 处理]
ContextProvider[上下文提供程序<br/>世界状态]
ConversationHistory[对话历史<br/>消息存储]
MemoryManager[记忆管理器<br/>私有记忆]
end
subgraph "数据仓库"
ConversationRepo[对话仓库]
MessageRepo[消息仓库<br/>邮件系统]
PrivateBookRepo[私人书籍仓库]
SharebookRepo[共享书籍仓库]
end
subgraph "事件监听器"
ChatListener[聊天消息监听器]
AgeListener[年龄更新监听器]
LLMScheduler[LLM 处理调度器]
end
NPCService --> NPC
NPC --> EventHandler
NPC --> ContextProvider
NPC --> ConversationHistory
NPC --> MemoryManager
EventHandler --> ConversationHistory
ContextProvider --> MessageRepo
ContextProvider --> PrivateBookRepo
ContextProvider --> SharebookRepo
NPCService --> CoordinationService
ChatListener --> NPCService
AgeListener --> NPCService
LLMScheduler --> EventHandler
NPC 生命周期流程
stateDiagram-v2
[*] --> Created: /craftagent create
Created --> Validating: 验证名称与配置
Validating --> CheckingLLM: 名称有效
Validating --> Error: 名称无效
CheckingLLM --> Spawning: LLM 可达
CheckingLLM --> Error: LLM 不可达
Spawning --> Active: 实体生成
Active --> Processing: LLM 调度器触发
Processing --> Active: 响应已生成
Active --> Removed: /craftagent remove
Active --> Deleted: /craftagent delete
Active --> Dead: 实体死亡事件
Dead --> Removed: 自动移除
Removed --> [*]: 数据保留
Deleted --> [*]: 数据删除
Error --> [*]
LLM 处理流程
sequenceDiagram
participant Scheduler as LLM 处理调度器
participant EventHandler as NPC 事件处理器
participant History as 对话历史
participant Context as 上下文提供程序
participant LLM as LLM 客户端
participant Ollama as Ollama/LM Studio
participant ActionExecutor as 动作执行器
participant WebServer as Web 服务器
Scheduler->>EventHandler: processLLM()
EventHandler->>History: performSummarizationIfNeeded()
History-->>EventHandler: 如需则摘要
EventHandler->>History: 获取对话消息
EventHandler->>Context: buildContext()
Context-->>EventHandler: WorldContext (状态、物品栏、方块、实体、记忆)
EventHandler->>EventHandler: 格式化带上下文的消息
EventHandler->>LLM: chat(messages, server)
LLM->>Ollama: HTTP POST /api/chat
Ollama-->>LLM: JSON 响应 {"message": "...", "actions": [...]}
LLM-->>EventHandler: LLMResponse (结构化)
EventHandler->>ActionExecutor: executeActions(actions)
ActionExecutor->>ActionExecutor: 路由到处理器 (记忆、通信等)
EventHandler->>History: 将响应添加到历史
EventHandler->>ChatUtil: 发送消息到聊天
EventHandler->>History: 存储响应
EventHandler-->>Scheduler: 成功/失败
消息流程:玩家 → NPC
sequenceDiagram
participant Player
participant ChatListener as 聊天消息监听器
participant NPCService
participant MessageRepo as 消息仓库
participant Context as 上下文提供程序
participant LLM as LLM 客户端
Player->>ChatListener: 发送聊天消息<br/>(定向: "npcName: message"<br/>或广播: "message")
ChatListener->>ChatListener: 解析消息格式
alt 定向消息 (npcName: message)
ChatListener->>ChatListener: 按名称查找 NPC (不区分大小写)
ChatListener->>NPCService: sendPlayerMessageToNpc(特定 NPC)
else 广播消息
ChatListener->>NPCService: sendPlayerMessageToNpc(所有 NPC)
end
NPCService->>MessageRepo: insert(message)
MessageRepo-->>NPCService: 消息已存储
Note over NPCService: 在下一次 LLM 调用期间,<br/>消息在上下文中可用
NPCService-->>ChatListener: 完成
ChatListener-->>Player: 消息已处理
消息流程:NPC → NPC
sequenceDiagram
participant NPC1
participant CoordinationService
participant MessageRepo as 消息仓库
participant NPC2
participant ChatUtil
participant Context as 上下文提供程序
NPC1->>CoordinationService: sendDirectMessage(toNpc, message)
CoordinationService->>MessageRepo: insert(message)
MessageRepo-->>CoordinationService: 消息已存储
CoordinationService->>ChatUtil: sendChatMessage()
ChatUtil-->>NPC2: 在聊天中显示
Note over CoordinationService: 在下一次 LLM 调用期间,<br/>消息在上下文中可用
CoordinationService-->>NPC1: 完成
数据流架构
graph TD
subgraph "输入源"
PlayerChat[玩家聊天消息]
GameEvents[游戏事件<br/>Tick、死亡等]
WorldState[世界状态<br/>方块、实体、物品栏]
end
subgraph "处理层"
EventHandler[事件处理器]
ContextBuilder[上下文构建器]
LLMProcessor[大语言模型处理器]
end
subgraph "存储层"
ConversationDB[(对话历史)]
MessageDB[(邮件消息)]
PrivateMemoryDB[(私有记忆)]
SharedMemoryDB [(共享记忆)]
ConfigFiles[配置文件]
end
subgraph "输出"
ChatOutput[聊天消息]
CommandExecution[Minecraft 命令执行]
WebDashboard[Web 仪表盘]
end
PlayerChat --> EventHandler
GameEvents --> EventHandler
WorldState --> ContextBuilder
EventHandler --> LLMProcessor
ContextBuilder --> LLMProcessor
LLMProcessor --> ConversationDB
EventHandler --> MessageDB
EventHandler --> PrivateMemoryDB
EventHandler --> SharedMemoryDB
EventHandler --> ConfigFiles
LLMProcessor --> ChatOutput
LLMProcessor --> CommandExecution
EventHandler --> WebDashboard
组件参考表
核心组件
| 组件 |
包名 |
职责 |
关键方法 |
| CraftAgent |
me.prskid1000.craftagent |
模组主初始化程序 |
onInitialize(), onStop() |
| NPCService |
me.prskid1000.craftagent.common |
NPC 生命周期管理 |
createNpc(), removeNpc(), deleteNpc() |
| NPCFactory |
me.prskid1000.craftagent.common |
NPC 实例创建 |
createNpc() |
| NPCEventHandler |
me.prskid1000.craftagent.event |
事件处理与大语言模型调用 |
updateState(), processLLM() |
| ContextProvider |
me.prskid1000.craftagent.context |
世界上下文收集 |
buildContext() |
| ConversationHistory |
me.prskid1000.craftagent.history |
消息历史记录管理 |
add(), performSummarizationIfNeeded() |
| CoordinationService |
me.prskid1000.craftagent.coordination |
NPC 间通信 |
sendDirectMessage() |
| ActionProvider |
me.prskid1000.craftagent.action |
将动作路由至处理器 |
executeAction(), isValidAction() |
| ActionProviderFactory |
me.prskid1000.craftagent.action |
使用所有处理器创建 ActionProvider |
create() |
| ActionExecutor |
me.prskid1000.craftagent.action |
执行由大语言模型生成的动作,解析命令 |
executeActions(), executeAction() |
| ActionParser |
me.prskid1000.craftagent.action |
支持引号的通用命令解析器 |
parseQuotedArguments(), wasArgumentQuoted() |
| MemoryActionHandler |
me.prskid1000.craftagent.action |
处理记忆相关动作 |
handleAction() (共享书/私有书) |
| CommunicationActionHandler |
me.prskid1000.craftagent.action |
处理通信相关动作 |
handleAction() (发送邮件) |
| NavigationActionHandler |
me.prskid1000.craftagent.action |
处理导航/移动相关动作 |
handleAction() (前往坐标/实体/方块) |
| MiningActionHandler |
me.prskid1000.craftagent.action |
处理采矿相关动作 |
handleAction() (挖掘方块) |
| BuildingActionHandler |
me.prskid1000.craftagent.action |
处理建造/放置相关动作 |
handleAction() (建造/放置方块) |
| CraftingActionHandler |
me.prskid1000.craftagent.action |
处理制作相关动作 |
handleAction() (合成物品) |
| HuntingActionHandler |
me.prskid1000.craftagent.action |
处理狩猎相关动作 |
handleAction() (猎杀怪物) |
| FarmingActionHandler |
me.prskid1000.craftagent.action |
处理农耕相关动作 |
handleAction() (种植/收获作物) |
| FishingActionHandler |
me.prskid1000.craftagent.action |
处理钓鱼相关动作 |
handleAction() (钓鱼/停止钓鱼) |
| CombatActionHandler |
me.prskid1000.craftagent.action |
处理战斗相关动作 |
handleAction() (攻击/防御) |
| ActionStateManager |
me.prskid1000.craftagent.context |
管理当前动作状态 |
setAction(), getActionDescription() |
| NavigationState |
me.prskid1000.craftagent.context |
管理导航状态 |
setTravelingTo(), update(), hasArrived() |
| LineOfSightProvider |
me.prskid1000.craftagent.context |
检测视线范围内的物品/实体/方块 |
getItemsInLineOfSight(), getEntitiesInLineOfSight() |
| WebServer |
me.prskid1000.craftagent.web |
带有自动刷新功能的 Web 仪表盘 |
HTTP API 端点 |
事件监听器
| 监听器 |
包名 |
事件类型 |
用途 |
| ChatMessageListener |
me.prskid1000.craftagent.listener |
ServerMessageEvents.CHAT_MESSAGE |
通过邮件将玩家消息路由至 NPC。支持定向消息(格式:"npcName: message")和广播消息 |
| AgeUpdateListener |
me.prskid1000.craftagent.listener |
ServerTickEvents.END_SERVER_TICK |
随时间推移更新 NPC 年龄 |
| LLMProcessingScheduler |
me.prskid1000.craftagent.listener |
ServerTickEvents.END_SERVER_TICK |
为 NPC 调度大语言模型处理任务 |
| EventListenerRegisterer |
me.prskid1000.craftagent.listener |
- |
注册所有事件监听器 |
数据模型
| 模型 |
包 |
描述 |
关键字段 |
| NPC |
me.prskid1000.craftagent.model |
主要 NPC 数据结构 |
entity, llmClient, history, eventHandler, contextProvider, config |
| ConversationMessage |
me.prskid1000.craftagent.history |
对话历史记录消息 |
message, role, timestamp |
| Message |
me.prskid1000.craftagent.model.database |
邮件系统消息 |
senderUuid, recipientUuid, content, read |
| WorldContext |
me.prskid1000.craftagent.model.context |
世界状态快照 |
state, inventory, nearbyBlocks, nearbyEntities, memoryData, navigation, lineOfSight, actionState |
| ContextData |
me.prskid1000.craftagent.model.context |
上下文数据结构 |
BlockData, EntityData, ItemData, InventoryData, StateData, NavigationData, LineOfSightData, ActionStateData |
仓库
| 仓库 |
包 |
用途 |
关键方法 |
| ConversationRepository |
me.prskid1000.craftagent.database.repositories |
对话历史记录存储 |
insert(), selectByUuid() |
| MessageRepository |
me.prskid1000.craftagent.database.repositories |
邮件系统存储 |
insert(), selectByRecipient(), markAsRead() |
| PrivateBookPageRepository |
me.prskid1000.craftagent.database.repositories |
NPC 专属记忆 |
insert(), selectByUuid() |
| SharebookRepository |
me.prskid1000.craftagent.database.repositories |
NPC 间共享记忆 |
insert(), selectAll() |
LLM 客户端
| 客户端 |
包 |
LLM 类型 |
API 端点 |
| OllamaClient |
me.prskid1000.craftagent.llm.ollama |
Ollama |
/api/chat |
| LMStudioClient |
me.prskid1000.craftagent.llm.lmstudio |
LM Studio |
/chat/completions |
| LLMClient |
me.prskid1000.craftagent.llm |
接口 |
- |
配置
| 配置项 |
包 |
文件位置 |
用途 |
| BaseConfig |
me.prskid1000.craftagent.config |
config/craftagent/base.json |
全局设置(超时时间、区块半径等) |
| NPCConfig |
me.prskid1000.craftagent.config |
config/craftagent/npcs/{uuid}.json |
每个 NPC 的设置(名称、LLM 类型、模型等) |
| ConfigProvider |
me.prskid1000.craftagent.config |
- |
配置管理 |
数据流详情
上下文构建流程
graph LR
A[ContextProvider.buildContext] --> B[获取 NPC 状态]
A --> C[获取物品栏]
A --> D[获取附近方块]
A --> E[获取附近实体]
A --> F[构建记忆数据]
A --> G[构建导航数据]
A --> H[构建视线数据]
A --> I[构建动作状态数据]
B --> J[StateData<br/>位置, 生命值, 食物值, 生物群系]
C --> K[InventoryData<br/>护甲, 主手, 快捷栏, 副手]
D --> L[BlockData 列表<br/>类型, 位置, 挖掘等级]
E --> M[EntityData 列表<br/>ID, 名称, 是否为玩家]
F --> N[记忆数据<br/>私有书, 邮件, 共享书]
G --> O[NavigationData<br/>状态, 目标, 时间]
H --> P[LineOfSightData<br/>物品, 实体, 方块]
I --> Q[ActionStateData<br/>动作类型, 描述, 数据]
J --> R[WorldContext]
K --> R
L --> R
M --> R
N --> R
O --> R
P --> R
Q --> R
记忆系统结构
| 记忆类型 |
仓库 |
范围 |
访问模式 |
| 对话历史 |
ConversationRepository |
每个 NPC 独立 |
生成时加载,关闭时保存 |
| 邮件消息 |
MessageRepository |
每个 NPC 独立 |
接收时存储,访问时标记为已读 |
| 私人记忆 |
PrivateBookPageRepository |
每个 NPC 独立 |
NPC 专属笔记和知识 |
| 共享记忆 |
SharebookRepository |
全局 |
所有 NPC 均可访问 |
动作系统
NPC 可以通过结构化的 LLM 输出来执行动作。LLM 返回一个包含消息和动作列表的 JSON 响应:
{
"message": "我发现了一个铁矿!",
"actions": [
"sharedbook add IronMine Location at 150, 64, -200",
"mail send Alice Found iron, want to mine together?"
]
}
可用动作:
| 操作类型 |
格式 |
描述 |
| 记忆 - 共享书籍 |
sharedbook add <title> '<content>' |
添加/更新共享记忆页面(所有 NPC 均可阅读)。标题可加引号或不加。内容必须用单引号 (') 或双引号 (") 包裹。 |
| 记忆 - 共享书籍 |
sharedbook remove <title> |
移除共享记忆页面 |
| 记忆 - 私人书籍 |
privatebook add <title> '<content>' |
添加/更新私人记忆页面(特定于某个 NPC)。标题可加引号或不加。内容必须用单引号 (') 或双引号 (") 包裹。 |
| 记忆 - 私人书籍 |
privatebook remove <title> |
移除私人记忆页面 |
| 通信 |
mail send <npc_name> '<message>' |
向另一个 NPC 发送邮件消息。收件人名称可加引号或不加。消息必须用单引号 (') 或双引号 (") 包裹。 |
| 导航 |
travel to <x> <y> <z> |
前往指定坐标 |
| 导航 |
travel to entity <entity_name> |
按名称前往附近的实体 |
| 导航 |
travel to block <block_type> |
前往附近指定类型的方块 |
| 导航 |
travel stop |
停止当前移动 |
| 采矿 |
mine <block_type> [count] |
开采指定类型的方块(默认:1) |
| 采矿 |
mine at <x> <y> <z> |
在指定坐标开采方块 |
| 建造 |
build <block_type> at <x> <y> <z> |
在坐标处放置方块(需要背包中有该方块) |
| 建造 |
place <block_type> at <x> <y> <z> |
放置方块(build 的别名) |
| 制作 |
craft <item_name> |
使用背包中的材料制作物品 |
| 狩猎 |
hunt <mob_type> |
狩猎/攻击特定生物类型 |
| 狩猎 |
hunt <entity_name> |
按名称狩猎/攻击实体 |
| 农耕 |
farm plant <crop_type> at <x> <y> <z> |
在坐标处种植作物 |
| 农耕 |
farm harvest at <x> <y> <z> |
在坐标处收割作物 |
| 农耕 |
farm harvest |
收割附近成熟的作物 |
| 钓鱼 |
fish |
开始钓鱼(抛出鱼竿) |
| 钓鱼 |
fish stop |
停止钓鱼(收杆) |
| 战斗 |
attack <entity_name> |
攻击特定实体 |
| 战斗 |
attack <entity_type> |
按类型攻击实体 |
| 战斗 |
defend |
进入防御姿态 |
操作解析:
- 操作由
ActionExecutor 使用 ActionParser 工具进行一次解析
- 解析器支持单引号和双引号,允许包含空格的参数
- 解析后的数组传递给处理器:
["sharedbook", "add", "title", "content"]
- 内容和消息必须加引号,以处理多词文本和特殊字符
示例:
sharedbook add "My Title" "Content with spaces and special chars!"
sharedbook add title 'Simple content'
mail send "Alice" "Hello world message"
mail send Alice 'Hello world'
操作由 ActionExecutor 自动执行,它会解析命令并将它们路由到相应的处理器(MemoryActionHandler、CommunicationActionHandler 等)。
事件处理流程
graph TD
A[游戏事件发生] --> B{事件类型}
B -->|聊天消息| C[ChatMessageListener]
B -->|服务器刻| D[AgeUpdateListener]
B -->|服务器刻| E[LLMProcessingScheduler]
C --> F[存储在邮件系统中]
F --> H[在上下文中可用]
D --> I[更新 NPC 年龄]
I --> J[保存配置]
E --> K[检查处理间隔]
K -->|间隔已过| L[将 NPC 加入处理队列]
L --> M[NPCEventHandler.processLLM]
M --> N[构建上下文]
N --> O[调用 LLM]
O --> P[解析结构化响应]
P --> Q{是否有操作?}
Q -->|是| R[执行操作]
R --> S[记忆/通信处理器]
Q -->|否| T[更新历史记录]
R --> T
T --> U[发送聊天消息]
U --> V[存储在历史记录中]
配置
配置文件位于 config/craftagent/ 目录下:
- base.json:全局设置(超时时间、区块半径、调试模式)
- npcs/{uuid}.json:每个 NPC 的设置(名称、LLM 类型、模型、性格)
基础配置字段
| 字段 |
类型 |
默认值 |
描述 |
llmTimeout |
int |
30 |
LLM 请求超时时间(秒) |
contextChunkRadius |
int |
2 |
用于上下文的区块扫描半径 |
contextVerticalScanRange |
int |
16 |
垂直方块扫描范围 |
maxNearbyBlocks |
int |
50 |
上下文中最多包含的方块数 |
maxNearbyEntities |
int |
10 |
上下文中最多包含的实体数 |
llmProcessingInterval |
int |
5 |
LLM 处理周期之间的秒数 |
llmMinInterval |
int |
2 |
NPC 处理之间的最小秒数 |
conversationHistoryLength |
int |
5 |
摘要之前的最大聊天消息数 |
maxMessages |
int |
50 |
每个 NPC 的最大邮件消息数 |
maxSharebookPages |
int |
20 |
最大共享记忆页数 |
maxPrivatePages |
int |
20 |
每个 NPC 的最大私人记忆页数 |
lineOfSightMaxRange |
int |
64 |
视线检测的最大范围 |
lineOfSightItemDetectionRange |
int |
32 |
视线内检测物品的范围 |
NPC 配置字段
| 字段 |
类型 |
默认值 |
描述 |
npcName |
String |
"Steve" |
显示名称 |
uuid |
UUID |
random |
唯一标识符 |
isActive |
boolean |
true |
NPC 是否处于活动状态 |
llmType |
LLMType |
LM_STUDIO |
LLM 提供商类型 |
llmModel |
String |
- |
模型名称 |
ollamaUrl |
String |
" |
Ollama API URL |
lmStudioUrl |
String |
" |
LM Studio API URL |
age |
int |
20 |
NPC 年龄(年) |
gender |
String |
"neutral" |
性别(male/female/neutral) |
customSystemPrompt |
String |
"" |
自定义系统提示覆盖 |
skipLLMRequests |
boolean |
false |
如果为 true,则跳过向 LLM 发送请求(NPC 不会自动或手动处理 LLM 调用) |
开发
关键组件
- NPCService:管理 NPC 生命周期(创建、移除、删除、生成)
- NPCEventHandler:处理事件和 LLM 交互,处理结构化输出
- ContextProvider:收集世界状态信息(方块、实体、物品栏)
- ActionProvider:将动作路由到相应的处理器(记忆、通信、导航、挖掘、建造、合成、狩猎、农耕、钓鱼、战斗)
- ActionProviderFactory:工厂类,用于创建包含所有动作处理器的 ActionProvider,集中处理处理器创建逻辑
- ActionExecutor:执行来自结构化 LLM 响应的动作,仅解析一次命令
- ActionParser:支持引号参数的通用命令参数解析工具
- MemoryActionHandler:处理与记忆相关的动作(共享书、私人书)
- CommunicationActionHandler:处理通信动作(发送邮件)
- NavigationActionHandler:处理导航/移动动作(前往坐标/实体/方块)
- MiningActionHandler:处理挖掘动作(挖掘方块)
- BuildingActionHandler:处理建造/放置动作(建造/放置方块)
- CraftingActionHandler:处理合成动作(合成物品)
- HuntingActionHandler:处理狩猎动作(猎杀生物)
- FarmingActionHandler:处理农耕动作(种植/收获作物)
- FishingActionHandler:处理钓鱼动作(钓鱼/停止钓鱼)
- CombatActionHandler:处理战斗动作(攻击/防御)
- ActionStateManager:跟踪当前动作状态并提供动作描述
- NavigationState:管理导航状态(空闲、行进中、已到达)
- LineOfSightProvider:检测 NPC 视线范围内的物品、实体和方块
- MinecraftCommandUtil:通过 Brigadier 发现和执行 Minecraft 命令
- LLMClient:LLM 提供商的接口(Ollama、LM Studio)
- CoordinationService:通过邮件系统处理 NPC 间通信
- WebServer:HTTP 服务器,用于通过自动刷新的 Web 仪表板监控 NPC
包结构
me.prskid1000.craftagent/
├── auth/ # 玩家授权
├── callback/ # 事件回调
├── client/ # 客户端代码(GUI、网络)
├── commands/ # Minecraft 命令
├── common/ # 核心服务(NPCService、NPCFactory)
├── config/ # 配置管理
├── constant/ # 常量和指令
├── context/ # 世界上下文收集
├── coordination/ # NPC 间通信
├── database/ # 数据持久化
│ ├── repositories/ # 数据库仓库
│ └── resources/ # 资源提供者
├── event/ # 事件处理
├── exception/ # 异常类
├── history/ # 对话历史
├── listener/ # 事件监听器
├── llm/ # LLM 客户端实现
│ ├── lmstudio/ # LM Studio 客户端
│ └── ollama/ # Ollama 客户端
├── memory/ # 记忆管理
├── mineskin/ # 皮肤管理
├── mixin/ # Minecraft Mixins
├── model/ # 数据模型
│ ├── context/ # 上下文数据结构
│ └── database/ # 数据库模型
├── networking/ # 网络数据包
├── thread/ # 线程管理
├── util/ # 工具类
└── web/ # Web 服务器
故障排除
- NPC 无响应:检查 LLM 服务是否正在运行,验证配置文件中的 URL/模型
- 命令无效:检查服务器日志,确保 NPC 具有所需权限
- LLM 超时:在基础配置中增加
llmTimeout 或尝试使用更快的模型
- 邮件无法工作:验证 MessageRepository 已初始化且 NPC UUID 正确
- 上下文未更新:检查 ChunkManager 是否正在运行且区块已加载
- 动作未执行:验证动作格式是否符合预期语法(参见“动作系统”部分)
- Web UI 未更新:检查浏览器控制台是否有错误,验证服务器正在运行且刷新间隔已配置
- 结构化输出解析失败:LLM 应返回包含 "message" 和 "actions" 字段的有效 JSON
贡献
欢迎贡献!请 Fork 项目,创建功能分支,并提交拉取请求。
许可证
本项目采用 LGPL-3.0 许可证。
链接
鸣谢
- 作者:prskid1000
- Fabric:模组加载器框架
- Brigadier:命令系统(Mojang)
- Ollama & LM Studio:LLM 提供商
CraftAgent
A Minecraft Fabric mod that brings intelligent AI-powered NPCs to your world. NPCs use Large Language Models (LLMs) to understand context, make decisions, and interact with players.
Features
- ? AI-Powered NPCs: Uses LLMs (Ollama, LM Studio) for intelligent decision-making
- ? Autonomous Actions: NPCs execute Minecraft commands to interact with the world
- ? Conversation Memory: Persistent conversation history in SQLite
- ? World Context Awareness: NPCs understand surroundings (blocks, entities, inventory, navigation, line of sight)
- ? Multi-LLM Support: Ollama and LM Studio (OpenAI-compatible)
- ? Client-Server Architecture: GUI configuration on client, NPC logic on server
- ?️ Command System: Uses Brigadier to discover and execute all Minecraft commands
- ? Web Dashboard: Built-in web UI () with auto-refresh based on LLM processing intervals
- ? Mail System: NPCs can send and receive messages via mail system
- ? Targeted Chat Messages: Send messages to specific NPCs using "npcName: message" format, or broadcast to all NPCs
- ? Memory System: Private and shared memory (privateBook, sharebook) for persistent knowledge
- ⚡ Structured Actions: LLM returns structured output with messages and executable actions
- ? Real-Time Updates: Web UI automatically updates without manual refresh
- ? Navigation System: NPCs can travel to coordinates, entities, or blocks with state tracking
- ?️ Line of Sight Detection: NPCs detect items, entities, and blocks in their line of sight
- ⚡ Action State Management: Track current actions (mining, building, crafting, hunting, farming, fishing, combat)
- ?️ Advanced Actions: Mining, building, crafting, hunting, farming, fishing, and combat actions
- ⏸️ LLM Control: Toggle to skip LLM requests per NPC and manual LLM trigger command
Requirements
- Minecraft: 1.20.1 or 1.21.8
- Java: 17 (1.20.1) or 21 (1.21.8+)
- Fabric Loader: 0.17.3+
- LLM Service: Ollama or LM Studio running locally
Installation
For Players
- Download the latest JAR from Modrinth or CurseForge
- Place the JAR in your
mods folder
- Install and start either:
- Ollama: Download from ollama.ai and run
ollama serve
- LM Studio: Download from lmstudio.ai and start the server
- Launch Minecraft and enjoy!
For Developers
-
Clone the repository:
git clone https://github.com/prskid1000/CraftAgent.git
cd CraftAgent
-
Build the project:
# Windows
.\gradlew.bat :1.21.8:build
# Linux/Mac
./gradlew :1.21.8:build
-
Find the compiled JAR in versions/1.21.8/build/libs/
Building
# Build for specific version
.\gradlew.bat :1.21.8:build
# Build all versions
.\gradlew.bat build
# Run in development
.\gradlew.bat :1.21.8:runServer
Usage
Commands
-
/craftagent - Open configuration GUI
-
/craftagent add <name> <llmType> - Create new NPC
-
/craftagent remove <name> - Remove NPC (keeps data)
-
/craftagent <npcName> llm - Manually trigger LLM call for specified NPC (case-insensitive NPC name)
-
/craftagent <npcName> <action> - Execute action on specified NPC (case-insensitive NPC name)
Memory Actions:
/craftagent Steve sharedbook add "Iron Mine" "Iron mine located at coordinates 150, 64, -200"
/craftagent Steve sharedbook add BaseLocation "Our base is at spawn"
/craftagent Steve sharedbook remove "Iron Mine"
/craftagent Steve privatebook add "Secret Plan" "I will build a house tomorrow"
/craftagent Steve privatebook add Notes "Remember to craft more tools"
/craftagent Steve privatebook remove "Secret Plan"
Communication Actions:
/craftagent Steve mail send Alice "Hello there! Want to mine together?"
/craftagent Steve mail send Bob "Found some diamonds at 200, 50, -100"
Navigation Actions:
/craftagent Steve travel to 100 64 200
/craftagent Steve travel to entity Zombie
/craftagent Steve travel to block iron_ore
/craftagent Steve travel stop
Mining Actions:
/craftagent Steve mine iron_ore 5
/craftagent Steve mine diamond_ore
/craftagent Steve mine at 150 64 -200
Building Actions:
/craftagent Steve build stone_bricks at 100 65 200
/craftagent Steve place oak_planks at 101 65 201
Crafting Actions:
/craftagent Steve craft iron_pickaxe
/craftagent Steve craft wooden_sword
Hunting Actions:
/craftagent Steve hunt zombie
/craftagent Steve hunt Creeper
/craftagent Steve hunt Skeleton
Farming Actions:
/craftagent Steve farm plant wheat at 50 64 50
/craftagent Steve farm plant carrot at 51 64 51
/craftagent Steve farm harvest at 50 64 50
/craftagent Steve farm harvest
Fishing Actions:
/craftagent Steve fish
/craftagent Steve fish stop
Combat Actions:
/craftagent Steve attack Zombie
/craftagent Steve attack zombie
/craftagent Steve defend
Chat Messages
Players can send messages to NPCs via chat. Messages are automatically routed to NPCs:
- Targeted Messages:
steve: Do your homework - Sends message only to NPC named "steve" (case-insensitive)
- Broadcast Messages:
Do your homework - Sends message to all NPCs
NPC names are matched case-insensitively, so steve, STEVE, and Steve all match the same NPC.
Useful Minecraft Keys
- F3: Opens the debug screen showing coordinates, FPS, chunk information, and other technical details. Useful for finding coordinates when giving NPCs travel commands.
- F3+P: Toggles pause on focus loss. When enabled, the game continues running when you alt-tab away, which is useful for monitoring NPCs in the background.
Web Dashboard
CraftAgent includes a built-in web dashboard for monitoring NPCs in real-time. The dashboard automatically starts when the Minecraft server starts.
Access the Dashboard:
- Start your Minecraft server with CraftAgent installed
- Open your web browser and navigate to:
- The dashboard will display all active NPCs with their current status
Dashboard Features:
- NPC Overview: View all NPCs with their basic information (name, age, gender, health, food, position, current action, navigation state)
- State Tab: Real-time statistics with progress bars for health and food, position coordinates, and biome information
- Context Tab: Detailed world context including:
- State information (position, health, food, biome)
- Inventory details (hotbar, main inventory, armor, off-hand)
- Nearby blocks table (type, position, mine level, tool needed)
- Nearby entities table (name, type, ID, player status)
- Navigation state (current state, destination, time in state)
- Current action (action type, description, duration, action-specific data)
- Line of sight data:
- Items in line of sight (type, count, position, distance)
- Entities in line of sight (name, type, ID, player status)
- Target block (where NPC is looking)
- Visible blocks (blocks visible in line of sight)
- Messages Tab: Conversation history with role badges and timestamps
- Mail Tab: Mail messages from other NPCs and players
- Memory Tab: NPC's persistent memory including:
- Private book pages (NPC-specific memory)
- Shared book pages (accessible to all NPCs)
Auto-Refresh:
- The dashboard uses auto-refresh based on the maximum LLM processing interval
- All data (NPCs, messages, mail, memory) updates automatically at configured intervals
- No manual refresh needed - the UI stays synchronized with the server
- Updates are triggered when:
- NPCs are created or removed
- New messages are added to conversation history
- Mail messages are sent or received
- Memory (private/shared book) is updated
Creating an NPC
- Start your LLM service (Ollama or LM Studio)
- Use
/craftagent create <name> <llmType> or open GUI with /craftagent
- Configure the NPC:
- Name: Display name
- LLM Type:
ollama or lm_studio
- Model: Model name (e.g.,
llama3)
- URL: LLM service URL (defaults:
http://localhost:11434 for Ollama, http://localhost:1234/v1 for LM Studio)
- Skip LLM Requests: Toggle to disable automatic LLM processing for this NPC (useful for testing or when LLM service is unavailable)
Controlling LLM Processing
- Automatic Processing: NPCs automatically process LLM calls at configured intervals (see
llmProcessingInterval in base config)
- Skip LLM Requests: Enable the "Skip LLM Requests" toggle in NPC config to disable all LLM calls (both automatic and manual) for that NPC
- Manual Trigger: Use
/craftagent <npcName> llm to manually trigger an LLM call for a specific NPC (only works if skipLLMRequests is disabled)
LLM Setup
Ollama
- Install from ollama.ai
- Start:
ollama serve
- Pull a model:
ollama pull llama3
- Configure NPC: LLM Type
ollama, Model llama3, URL http://localhost:11434
LM Studio
- Install from lmstudio.ai
- Download a model and start local server (port 1234)
- Configure NPC: LLM Type
lm_studio, Model name, URL http://localhost:1234/v1
Architecture
System Architecture Overview
graph TB
subgraph "Client Side"
GUI[OWO UI Screens]
ClientNet[Client Network Manager]
GUI --> ClientNet
end
subgraph "Server Side"
Main[CraftAgent Mod]
CmdMgr[Command Manager]
NetHandler[Network Handler]
NPCService[NPC Service]
EventReg[EventListener Registerer]
WebServer[Web Server :8080]
Main --> CmdMgr
Main --> NetHandler
Main --> NPCService
Main --> EventReg
Main --> WebServer
end
subgraph "NPC Components"
NPCFactory[NPC Factory]
NPCEntity[Server Player Entity]
EventHandler[NPCEventHandler]
ContextProv[Context Provider]
History[Conversation History]
LLMClient[LLM Client]
NPCService --> NPCFactory
NPCFactory --> NPCEntity
NPCFactory --> EventHandler
NPCFactory --> ContextProv
NPCFactory --> History
NPCFactory --> LLMClient
end
subgraph "Data Layer"
SQLite[(SQLite Database)]
ConfigFiles[Config Files]
Repos[Repositories]
NPCService --> Repos
Repos --> SQLite
NPCService --> ConfigFiles
end
subgraph "External Services"
Ollama[Ollama API]
LMStudio[LM Studio API]
LLMClient --> Ollama
LLMClient --> LMStudio
end
ClientNet <--> NetHandler
EventReg --> NPCService
WebServer --> NPCService
Component Architecture
graph LR
subgraph "Core Services"
NPCService[NPC Service<br/>Lifecycle Management]
CoordinationService[Coordination Service<br/>NPC Communication]
ConfigProvider[Config Provider<br/>Configuration Management]
end
subgraph "NPC Instance"
NPC[NPC Model]
EventHandler[Event Handler<br/>LLM Processing]
ContextProvider[Context Provider<br/>World State]
ConversationHistory[Conversation History<br/>Message Storage]
MemoryManager[Memory Manager<br/>Private Memory]
end
subgraph "Data Repositories"
ConversationRepo[Conversation Repository]
MessageRepo[Message Repository<br/>Mail System]
PrivateBookRepo[Private Book Repository]
SharebookRepo[Sharebook Repository]
end
subgraph "Event Listeners"
ChatListener[Chat Message Listener]
AgeListener[Age Update Listener]
LLMScheduler[LLM Processing Scheduler]
end
NPCService --> NPC
NPC --> EventHandler
NPC --> ContextProvider
NPC --> ConversationHistory
NPC --> MemoryManager
EventHandler --> ConversationHistory
ContextProvider --> MessageRepo
ContextProvider --> PrivateBookRepo
ContextProvider --> SharebookRepo
NPCService --> CoordinationService
ChatListener --> NPCService
AgeListener --> NPCService
LLMScheduler --> EventHandler
NPC Lifecycle Flow
stateDiagram-v2
[*] --> Created: /craftagent create
Created --> Validating: Validate Name & Config
Validating --> CheckingLLM: Name Valid
Validating --> Error: Invalid Name
CheckingLLM --> Spawning: LLM Reachable
CheckingLLM --> Error: LLM Unreachable
Spawning --> Active: Entity Spawned
Active --> Processing: LLM Scheduler Trigger
Processing --> Active: Response Generated
Active --> Removed: /craftagent remove
Active --> Deleted: /craftagent delete
Active --> Dead: Entity Death Event
Dead --> Removed: Auto Remove
Removed --> [*]: Data Preserved
Deleted --> [*]: Data Deleted
Error --> [*]
LLM Processing Flow
sequenceDiagram
participant Scheduler as LLM Processing Scheduler
participant EventHandler as NPCEventHandler
participant History as Conversation History
participant Context as Context Provider
participant LLM as LLM Client
participant Ollama as Ollama/LM Studio
participant ActionExecutor as Action Executor
participant WebServer as Web Server
Scheduler->>EventHandler: processLLM()
EventHandler->>History: performSummarizationIfNeeded()
History-->>EventHandler: Summarized if needed
EventHandler->>History: Get conversation messages
EventHandler->>Context: buildContext()
Context-->>EventHandler: WorldContext (state, inventory, blocks, entities, memory)
EventHandler->>EventHandler: Format messages with context
EventHandler->>LLM: chat(messages, server)
LLM->>Ollama: HTTP POST /api/chat
Ollama-->>LLM: JSON Response {"message": "...", "actions": [...]}
LLM-->>EventHandler: LLMResponse (structured)
EventHandler->>ActionExecutor: executeActions(actions)
ActionExecutor->>ActionExecutor: Route to handlers (memory, communication, etc.)
EventHandler->>History: Add response to history
EventHandler->>ChatUtil: Send message to chat
EventHandler->>History: Store response
EventHandler-->>Scheduler: Success/Failure
Message Flow: Player → NPC
sequenceDiagram
participant Player
participant ChatListener as Chat Message Listener
participant NPCService
participant MessageRepo as Message Repository
participant Context as Context Provider
participant LLM as LLM Client
Player->>ChatListener: Sends chat message<br/>(targeted: "npcName: message"<br/>or broadcast: "message")
ChatListener->>ChatListener: Parse message format
alt Targeted Message (npcName: message)
ChatListener->>ChatListener: Find NPC by name (case-insensitive)
ChatListener->>NPCService: sendPlayerMessageToNpc(specific NPC)
else Broadcast Message
ChatListener->>NPCService: sendPlayerMessageToNpc(all NPCs)
end
NPCService->>MessageRepo: insert(message)
MessageRepo-->>NPCService: Message stored
Note over NPCService: Message available in context<br/>during next LLM call
NPCService-->>ChatListener: Complete
ChatListener-->>Player: Message processed
Message Flow: NPC → NPC
sequenceDiagram
participant NPC1
participant CoordinationService
participant MessageRepo as Message Repository
participant NPC2
participant ChatUtil
participant Context as Context Provider
NPC1->>CoordinationService: sendDirectMessage(toNpc, message)
CoordinationService->>MessageRepo: insert(message)
MessageRepo-->>CoordinationService: Message stored
CoordinationService->>ChatUtil: sendChatMessage()
ChatUtil-->>NPC2: Display in chat
Note over CoordinationService: Message available in context<br/>during next LLM call
CoordinationService-->>NPC1: Complete
Data Flow Architecture
graph TD
subgraph "Input Sources"
PlayerChat[Player Chat Messages]
GameEvents[Game Events<br/>Tick, Death, etc.]
WorldState[World State<br/>Blocks, Entities, Inventory]
end
subgraph "Processing Layer"
EventHandler[Event Handler]
ContextBuilder[Context Builder]
LLMProcessor[LLM Processor]
end
subgraph "Storage Layer"
ConversationDB[(Conversation History)]
MessageDB[(Mail Messages)]
PrivateMemoryDB[(Private Memory)]
SharedMemoryDB[(Shared Memory)]
ConfigFiles[Config Files]
end
subgraph "Output"
ChatOutput[Chat Messages]
CommandExecution[Minecraft Commands]
WebDashboard[Web Dashboard]
end
PlayerChat --> EventHandler
GameEvents --> EventHandler
WorldState --> ContextBuilder
EventHandler --> LLMProcessor
ContextBuilder --> LLMProcessor
LLMProcessor --> ConversationDB
EventHandler --> MessageDB
EventHandler --> PrivateMemoryDB
EventHandler --> SharedMemoryDB
EventHandler --> ConfigFiles
LLMProcessor --> ChatOutput
LLMProcessor --> CommandExecution
EventHandler --> WebDashboard
Component Reference Tables
Core Components
| Component |
Package |
Responsibility |
Key Methods |
| CraftAgent |
me.prskid1000.craftagent |
Main mod initializer |
onInitialize(), onStop() |
| NPCService |
me.prskid1000.craftagent.common |
NPC lifecycle management |
createNpc(), removeNpc(), deleteNpc() |
| NPCFactory |
me.prskid1000.craftagent.common |
NPC instance creation |
createNpc() |
| NPCEventHandler |
me.prskid1000.craftagent.event |
Event processing & LLM calls |
updateState(), processLLM() |
| ContextProvider |
me.prskid1000.craftagent.context |
World context gathering |
buildContext() |
| ConversationHistory |
me.prskid1000.craftagent.history |
Message history management |
add(), performSummarizationIfNeeded() |
| CoordinationService |
me.prskid1000.craftagent.coordination |
Inter-NPC communication |
sendDirectMessage() |
| ActionProvider |
me.prskid1000.craftagent.action |
Routes actions to handlers |
executeAction(), isValidAction() |
| ActionProviderFactory |
me.prskid1000.craftagent.action |
Creates ActionProvider with all handlers |
create() |
| ActionExecutor |
me.prskid1000.craftagent.action |
Executes LLM-generated actions, parses commands |
executeActions(), executeAction() |
| ActionParser |
me.prskid1000.craftagent.action |
Generic command parser with quote support |
parseQuotedArguments(), wasArgumentQuoted() |
| MemoryActionHandler |
me.prskid1000.craftagent.action |
Handles memory actions |
handleAction() (sharedbook/privatebook) |
| CommunicationActionHandler |
me.prskid1000.craftagent.action |
Handles communication actions |
handleAction() (mail send) |
| NavigationActionHandler |
me.prskid1000.craftagent.action |
Handles navigation/travel actions |
handleAction() (travel to coordinates/entity/block) |
| MiningActionHandler |
me.prskid1000.craftagent.action |
Handles mining actions |
handleAction() (mine blocks) |
| BuildingActionHandler |
me.prskid1000.craftagent.action |
Handles building/placing actions |
handleAction() (build/place blocks) |
| CraftingActionHandler |
me.prskid1000.craftagent.action |
Handles crafting actions |
handleAction() (craft items) |
| HuntingActionHandler |
me.prskid1000.craftagent.action |
Handles hunting actions |
handleAction() (hunt mobs) |
| FarmingActionHandler |
me.prskid1000.craftagent.action |
Handles farming actions |
handleAction() (plant/harvest crops) |
| FishingActionHandler |
me.prskid1000.craftagent.action |
Handles fishing actions |
handleAction() (fish/stop fishing) |
| CombatActionHandler |
me.prskid1000.craftagent.action |
Handles combat actions |
handleAction() (attack/defend) |
| ActionStateManager |
me.prskid1000.craftagent.context |
Manages current action state |
setAction(), getActionDescription() |
| NavigationState |
me.prskid1000.craftagent.context |
Manages navigation state |
setTravelingTo(), update(), hasArrived() |
| LineOfSightProvider |
me.prskid1000.craftagent.context |
Detects items/entities/blocks in line of sight |
getItemsInLineOfSight(), getEntitiesInLineOfSight() |
| WebServer |
me.prskid1000.craftagent.web |
Web dashboard with auto-refresh |
HTTP API endpoints |
Event Listeners
| Listener |
Package |
Event Type |
Purpose |
| ChatMessageListener |
me.prskid1000.craftagent.listener |
ServerMessageEvents.CHAT_MESSAGE |
Routes player messages to NPCs via mail. Supports targeted messages (format: "npcName: message") and broadcast messages |
| AgeUpdateListener |
me.prskid1000.craftagent.listener |
ServerTickEvents.END_SERVER_TICK |
Updates NPC age over time |
| LLMProcessingScheduler |
me.prskid1000.craftagent.listener |
ServerTickEvents.END_SERVER_TICK |
Schedules LLM processing for NPCs |
| EventListenerRegisterer |
me.prskid1000.craftagent.listener |
- |
Registers all event listeners |
Data Models
| Model |
Package |
Description |
Key Fields |
| NPC |
me.prskid1000.craftagent.model |
Main NPC data structure |
entity, llmClient, history, eventHandler, contextProvider, config |
| ConversationMessage |
me.prskid1000.craftagent.history |
Conversation history message |
message, role, timestamp |
| Message |
me.prskid1000.craftagent.model.database |
Mail system message |
senderUuid, recipientUuid, content, read |
| WorldContext |
me.prskid1000.craftagent.model.context |
World state snapshot |
state, inventory, nearbyBlocks, nearbyEntities, memoryData, navigation, lineOfSight, actionState |
| ContextData |
me.prskid1000.craftagent.model.context |
Context data structures |
BlockData, EntityData, ItemData, InventoryData, StateData, NavigationData, LineOfSightData, ActionStateData |
Repositories
| Repository |
Package |
Purpose |
Key Methods |
| ConversationRepository |
me.prskid1000.craftagent.database.repositories |
Conversation history storage |
insert(), selectByUuid() |
| MessageRepository |
me.prskid1000.craftagent.database.repositories |
Mail system storage |
insert(), selectByRecipient(), markAsRead() |
| PrivateBookPageRepository |
me.prskid1000.craftagent.database.repositories |
NPC-specific memory |
insert(), selectByUuid() |
| SharebookRepository |
me.prskid1000.craftagent.database.repositories |
Shared memory across NPCs |
insert(), selectAll() |
LLM Clients
| Client |
Package |
LLM Type |
API Endpoint |
| OllamaClient |
me.prskid1000.craftagent.llm.ollama |
Ollama |
/api/chat |
| LMStudioClient |
me.prskid1000.craftagent.llm.lmstudio |
LM Studio |
/chat/completions |
| LLMClient |
me.prskid1000.craftagent.llm |
Interface |
- |
Configuration
| Config |
Package |
File Location |
Purpose |
| BaseConfig |
me.prskid1000.craftagent.config |
config/craftagent/base.json |
Global settings (timeout, chunk radius, etc.) |
| NPCConfig |
me.prskid1000.craftagent.config |
config/craftagent/npcs/{uuid}.json |
Per-NPC settings (name, LLM type, model, etc.) |
| ConfigProvider |
me.prskid1000.craftagent.config |
- |
Configuration management |
Data Flow Details
Context Building Process
graph LR
A[ContextProvider.buildContext] --> B[Get NPC State]
A --> C[Get Inventory]
A --> D[Get Nearby Blocks]
A --> E[Get Nearby Entities]
A --> F[Build Memory Data]
A --> G[Build Navigation Data]
A --> H[Build Line of Sight Data]
A --> I[Build Action State Data]
B --> J[StateData<br/>position, health, food, biome]
C --> K[InventoryData<br/>armor, main, hotbar, offhand]
D --> L[List of BlockData<br/>type, position, mineLevel]
E --> M[List of EntityData<br/>id, name, isPlayer]
F --> N[Memory Data<br/>privateBook, mail, sharebook]
G --> O[NavigationData<br/>state, destination, time]
H --> P[LineOfSightData<br/>items, entities, blocks]
I --> Q[ActionStateData<br/>actionType, description, data]
J --> R[WorldContext]
K --> R
L --> R
M --> R
N --> R
O --> R
P --> R
Q --> R
Memory System Structure
| Memory Type |
Repository |
Scope |
Access Pattern |
| Conversation History |
ConversationRepository |
Per-NPC |
Loaded on spawn, saved on shutdown |
| Mail Messages |
MessageRepository |
Per-NPC |
Stored when received, marked read when accessed |
| Private Memory |
PrivateBookPageRepository |
Per-NPC |
NPC-specific notes and knowledge |
| Shared Memory |
SharebookRepository |
Global |
Accessible to all NPCs |
Action System
NPCs can execute actions through structured LLM output. The LLM returns a JSON response with a message and a list of actions:
{
"message": "I found an iron mine!",
"actions": [
"sharedbook add IronMine Location at 150, 64, -200",
"mail send Alice Found iron, want to mine together?"
]
}
Available Actions:
| Action Type |
Format |
Description |
| Memory - Shared Book |
sharedbook add <title> '<content>' |
Add/update shared memory page (all NPCs can read). Title can be quoted or unquoted. Content must be wrapped in single (') or double (") quotes. |
| Memory - Shared Book |
sharedbook remove <title> |
Remove shared memory page |
| Memory - Private Book |
privatebook add <title> '<content>' |
Add/update private memory page (NPC-specific). Title can be quoted or unquoted. Content must be wrapped in single (') or double (") quotes. |
| Memory - Private Book |
privatebook remove <title> |
Remove private memory page |
| Communication |
mail send <npc_name> '<message>' |
Send mail message to another NPC. Recipient name can be quoted or unquoted. Message must be wrapped in single (') or double (") quotes. |
| Navigation |
travel to <x> <y> <z> |
Travel to specific coordinates |
| Navigation |
travel to entity <entity_name> |
Travel to a nearby entity by name |
| Navigation |
travel to block <block_type> |
Travel to a nearby block of specified type |
| Navigation |
travel stop |
Stop current travel |
| Mining |
mine <block_type> [count] |
Mine blocks of specified type (default: 1) |
| Mining |
mine at <x> <y> <z> |
Mine block at specific coordinates |
| Building |
build <block_type> at <x> <y> <z> |
Place block at coordinates (requires block in inventory) |
| Building |
place <block_type> at <x> <y> <z> |
Place block (alias for build) |
| Crafting |
craft <item_name> |
Craft item from inventory materials |
| Hunting |
hunt <mob_type> |
Hunt/attack specific mob type |
| Hunting |
hunt <entity_name> |
Hunt/attack entity by name |
| Farming |
farm plant <crop_type> at <x> <y> <z> |
Plant crop at coordinates |
| Farming |
farm harvest at <x> <y> <z> |
Harvest crop at coordinates |
| Farming |
farm harvest |
Harvest nearby mature crops |
| Fishing |
fish |
Start fishing (cast fishing rod) |
| Fishing |
fish stop |
Stop fishing (reel in) |
| Combat |
attack <entity_name> |
Attack specific entity |
| Combat |
attack <entity_type> |
Attack entity by type |
| Combat |
defend |
Enter defensive stance |
Action Parsing:
- Actions are parsed once by
ActionExecutor using ActionParser utility
- The parser handles both single and double quotes, allowing arguments with spaces
- Parsed arrays are passed to handlers:
["sharedbook", "add", "title", "content"]
- Content and messages must be quoted to handle multi-word text and special characters
Examples:
sharedbook add "My Title" "Content with spaces and special chars!"
sharedbook add title 'Simple content'
mail send "Alice" "Hello world message"
mail send Alice 'Hello world'
Actions are automatically executed by the ActionExecutor, which parses commands and routes them to appropriate handlers (MemoryActionHandler, CommunicationActionHandler, etc.).
Event Processing Flow
graph TD
A[Game Event Occurs] --> B{Event Type}
B -->|Chat Message| C[ChatMessageListener]
B -->|Server Tick| D[AgeUpdateListener]
B -->|Server Tick| E[LLMProcessingScheduler]
C --> F[Store in Mail System]
F --> H[Available in Context]
D --> I[Update NPC Age]
I --> J[Save Config]
E --> K[Check Processing Interval]
K -->|Interval Passed| L[Queue NPC for Processing]
L --> M[NPCEventHandler.processLLM]
M --> N[Build Context]
N --> O[Call LLM]
O --> P[Parse Structured Response]
P --> Q{Has Actions?}
Q -->|Yes| R[Execute Actions]
R --> S[Memory/Communication Handlers]
Q -->|No| T[Update History]
R --> T
T --> U[Send Chat Message]
U --> V[Store in History]
Configuration
Config files are in config/craftagent/:
- base.json: Global settings (timeout, chunk radius, debug mode)
- npcs/{uuid}.json: Per-NPC settings (name, LLM type, model, personality)
Base Config Fields
| Field |
Type |
Default |
Description |
llmTimeout |
int |
30 |
LLM request timeout in seconds |
contextChunkRadius |
int |
2 |
Chunk scan radius for context |
contextVerticalScanRange |
int |
16 |
Vertical block scan range |
maxNearbyBlocks |
int |
50 |
Maximum blocks in context |
maxNearbyEntities |
int |
10 |
Maximum entities in context |
llmProcessingInterval |
int |
5 |
Seconds between LLM processing cycles |
llmMinInterval |
int |
2 |
Minimum seconds between NPC processing |
conversationHistoryLength |
int |
5 |
Max conversation messages before summarization |
maxMessages |
int |
50 |
Maximum mail messages per NPC |
maxSharebookPages |
int |
20 |
Maximum shared memory pages |
maxPrivatePages |
int |
20 |
Maximum private memory pages per NPC |
lineOfSightMaxRange |
int |
64 |
Maximum range for line of sight detection |
lineOfSightItemDetectionRange |
int |
32 |
Range for detecting items in line of sight |
NPC Config Fields
| Field |
Type |
Default |
Description |
npcName |
String |
"Steve" |
Display name |
uuid |
UUID |
random |
Unique identifier |
isActive |
boolean |
true |
Whether NPC is active |
llmType |
LLMType |
LM_STUDIO |
LLM provider type |
llmModel |
String |
- |
Model name |
ollamaUrl |
String |
" |
Ollama API URL |
lmStudioUrl |
String |
" |
LM Studio API URL |
age |
int |
20 |
NPC age in years |
gender |
String |
"neutral" |
Gender (male/female/neutral) |
customSystemPrompt |
String |
"" |
Custom system prompt override |
skipLLMRequests |
boolean |
false |
If true, skip sending requests to LLM (NPC will not process LLM calls automatically or manually) |
Development
Key Components
- NPCService: Manages NPC lifecycle (create, remove, delete, spawn)
- NPCEventHandler: Processes events and LLM interactions, handles structured output
- ContextProvider: Gathers world state information (blocks, entities, inventory)
- ActionProvider: Routes actions to appropriate handlers (memory, communication, navigation, mining, building, crafting, hunting, farming, fishing, combat)
- ActionProviderFactory: Factory class that creates ActionProvider with all action handlers, centralizes handler creation logic
- ActionExecutor: Executes actions from structured LLM responses, parses commands once
- ActionParser: Generic utility for parsing command arguments with quote support
- MemoryActionHandler: Handles memory-related actions (sharedbook, privatebook)
- CommunicationActionHandler: Handles communication actions (mail send)
- NavigationActionHandler: Handles navigation/travel actions (travel to coordinates/entity/block)
- MiningActionHandler: Handles mining actions (mine blocks)
- BuildingActionHandler: Handles building/placing actions (build/place blocks)
- CraftingActionHandler: Handles crafting actions (craft items)
- HuntingActionHandler: Handles hunting actions (hunt mobs)
- FarmingActionHandler: Handles farming actions (plant/harvest crops)
- FishingActionHandler: Handles fishing actions (fish/stop fishing)
- CombatActionHandler: Handles combat actions (attack/defend)
- ActionStateManager: Tracks current action state and provides action descriptions
- NavigationState: Manages navigation state (idle, traveling, arrived)
- LineOfSightProvider: Detects items, entities, and blocks in NPC's line of sight
- MinecraftCommandUtil: Discovers and executes Minecraft commands via Brigadier
- LLMClient: Interface for LLM providers (Ollama, LM Studio)
- CoordinationService: Handles inter-NPC communication via mail system
- WebServer: HTTP server for monitoring NPCs via web dashboard with auto-refresh
Package Structure
me.prskid1000.craftagent/
├── auth/ # Player authorization
├── callback/ # Event callbacks
├── client/ # Client-side code (GUI, networking)
├── commands/ # Minecraft commands
├── common/ # Core services (NPCService, NPCFactory)
├── config/ # Configuration management
├── constant/ # Constants and instructions
├── context/ # World context gathering
├── coordination/ # Inter-NPC communication
├── database/ # Data persistence
│ ├── repositories/ # Database repositories
│ └── resources/ # Resource providers
├── event/ # Event handling
├── exception/ # Exception classes
├── history/ # Conversation history
├── listener/ # Event listeners
├── llm/ # LLM client implementations
│ ├── lmstudio/ # LM Studio client
│ └── ollama/ # Ollama client
├── memory/ # Memory management
├── mineskin/ # Skin management
├── mixin/ # Mixins for Minecraft
├── model/ # Data models
│ ├── context/ # Context data structures
│ └── database/ # Database models
├── networking/ # Network packets
├── thread/ # Thread management
├── util/ # Utility classes
└── web/ # Web server
Troubleshooting
- NPC not responding: Check LLM service is running, verify URL/model in config
- Commands not working: Check server logs, ensure NPC has required permissions
- LLM timeout: Increase
llmTimeout in base config or try a faster model
- Mail not working: Verify MessageRepository is initialized and NPC UUID is correct
- Context not updating: Check ChunkManager is running and chunks are loaded
- Actions not executing: Verify action format matches expected syntax (see Action System section)
- Web UI not updating: Check browser console for errors, verify server is running and refresh interval is configured
- Structured output parsing fails: LLM should return valid JSON with "message" and "actions" fields
Contributing
Contributions welcome! Fork, create a feature branch, and submit a pull request.
License
This project is licensed under LGPL-3.0.
Links
Credits
- Author: prskid1000
- Fabric: Mod loader framework
- Brigadier: Command system (Mojang)
- Ollama & LM Studio: LLM providers
评论 0
登录后参与评分
还没有评论,来抢沙发吧