用 AI 给你的 Minecraft 加一个真正的伙伴！AICompanion 模组开发分享

前言

你有没有幻想过，在 Minecraft 的冒险中有一个真正能思考、会聊天、自主行动的伙伴？不是那种只会跟着你走的宠物，而是能砍树、挖矿、打怪、甚至和你闲聊的 AI 同伴？

作为一个 Minecraft 玩家和 AI 爱好者，我一直在想：如果把大语言模型接入 Minecraft，让 NPC 拥有真正的"大脑"，会是什么体验？

于是，我利用三天的业余时间，在Claude Code的辅助下，做出了这个模组 —— AICompanion。

效果展示

想象一下这些场景：

  • 你刚进入一片森林，同伴说：“这里有树，我来砍点木头吧。” 然后开始挥斧砍树
  • 天黑了，僵尸袭来，同伴拔出弓箭，精准预判弹道，一箭射爆远处的骷髅
  • 同伴血量低于 30%，大喊一声"我得撤了！"然后后退脱离战斗
  • 你饿了，同伴背包里也没食物，它会在聊天里对你说：“大哥，给点吃的吧！”
    在这里插入图片描述
    在这里插入图片描述
    这不是模组宣传片，这就是 AICompanion 的日常。

它是什么？

AICompanion 是一个基于大语言模型（LLM）的 Minecraft NeoForge 模组。它会生成一个外观与玩家完全相同（Steve 皮肤）的 AI 同伴，能够：

  • 实时观察周围环境（方块、实体、天气、时间）
  • 分析自身状态（血量、饥饿值、背包）
  • 自主决定下一步行动
  • 与你进行自然语言对话

简单来说：它不是脚本 NPC，它会"思考"。

核心功能一览

1. AI 自主决策

每隔约 3 秒，同伴会收集当前游戏状态（附近的方块类型和数量、周围实体的位置和血量、背包内容、饥饿值、时间天气等），构建成 Prompt 发送给 AI，然后解析返回的 JSON 决定下一步行动。

不同的AI模型表现出的智力和思考速度不同，比如深度思考模型智力上有优势，但思考速度很慢，需自行取舍。

支持 11 种动作类型：

动作 说明
MOVE 移动到指定位置
MINE 挖掘方块
ATTACK 攻击实体
CHAT 说话聊天
WAIT 原地等待
EAT 进食
SLEEP 睡觉休息
WAKE_UP 醒来
DROP_ITEM 丢弃物品
USE_ITEM 使用物品
PLACE_BLOCK 放置方块

2. 智能战斗系统

这可能是模组中最复杂的部分：

  • 自动武器选择：检测 16 格内的敌对生物，远距离自动切换弓箭/弩，近距离切换剑/斧
  • 弹道预测：弓箭射击计算抛物线轨迹，考虑重力和空气阻力，实现"神射手"级精度
  • 满弓机制：必须拉满弓（20 tick）才松弦，带视线检测
  • 武器模式锁：避免在距离阈值附近来回切换武器（滞回设计）
  • 低血量撤退：HP 低于 30% 时主动向反方向撤退

3. 饥饿与饱食度系统

完全复刻玩家的饥饿机制：

  • 饥饿值（0-20）：低于 7 时自动进食
  • 饱和度（0-20）：吃东西时恢复，优先于饥饿值消耗
  • 疲劳值（0-4）：移动、跳跃、战斗、挖掘都会增加，满了就消耗饱和度/饥饿值
  • 自然回血：饥饿值 ≥ 18 且饱和度 > 0 时快速回血
  • 饥饿伤害：饥饿值为 0 时开始掉血（困难模式可致死）

4. 自动装备盔甲

  • 每 0.5 秒评估一次背包中的盔甲
  • 自动装备属性（防御值 + 韧性）更好的那一件
  • 头盔、胸甲、护腿、靴子四个槽位全覆盖
  • 盔甲可见地显示在同伴身体上，和玩家一模一样

5. 自动进食

  • 饥饿值低于阈值时，自动从背包拿出食物
  • 完整的进食动画（1.6 秒）+ 咀嚼音效（每 0.25 秒一次）
  • 连续进食有 1 秒冷却，避免"机关枪式"吃饭
  • 背包没有食物时，会在聊天里向你要

6. 死亡与重生

  • 死亡后 10 秒在玩家附近重生（5 秒和 2 秒时通知你）
  • 可配置是否掉落物品（默认不掉落）
  • 重生后恢复满血、满饥饿、背包内容

三种行为模式

空手右键同伴可以切换模式：

模式 行为 适合场景
跟随 (FOLLOW) 距离玩家 > 4 格时自动跟随，空闲时 AI 自主行动 日常冒险
待命 (STAND) 原地不动，不执行 AI 决策，但仍会自动反击和拾取 守家/站岗
自由 (FREE) 完全自主行动，不受玩家位置约束 让 AI 自己探索

Shift + 右键可以打开同伴的 27 格背包 GUI。

兼容任意 LLM 服务

这是这个模组最大的亮点之一 —— 不绑定任何 AI 服务商。

玩家配置存储在本地游戏目录下，不会涉及网络传输等操作，大大保证了密钥的安全性。

支持所有兼容 OpenAI Chat Completions API 格式的服务：

  • OpenAI (GPT-3.5/4/4o)
  • DeepSeek
  • 本地 Ollama (完全免费！)
  • Anthropic (有专门的响应解析逻辑)
  • 其他兼容 API
    在这里插入图片描述

配置文件 config/aicompanion.toml：

[ai]
# API 地址，支持 OpenAI、DeepSeek、本地 Ollama 等
apiUrl = "https://api.openai.com"
apiKey = "your-api-key-here"  # 必填
endpoint = "/v1/chat/completions"
timeout = 30

[model]
modelName = "gpt-3.5-turbo"
temperature = 0.7
maxTokens = 1024
enableJsonMode = true  # Anthropic 等不支持 JSON 模式的请改为 false

[behavior]
systemPrompt = "你是一个友好且乐于助人的 Minecraft AI 同伴。"
dropItemsOnDeath = false  # 死亡是否掉落物品

技术实现亮点

异步 AI 调用

使用 Java HttpClient 异步发送请求，不阻塞游戏主线程。带指数退避重试（429/5xx 错误），支持 Retry-After 响应头。

状态机架构

动作执行采用状态机设计（IDLE → MOVING → MINING/ATTACKING/EATING），每个动作有独立的生命周期管理和清理逻辑。

弹道物理

弓箭射击使用完整的抛物线计算：

水平位移: x = v₀·cos(θ)·t
垂直位移: y = v₀·sin(θ)·t - ½gt²
空气阻力: v = v₀ · drag^t

通过迭代法求解发射角度，实现精准的远程狙击。

原版 API 兼容

所有工具/武器/盔甲判断使用原版 API 和 Tag 系统：

  • ItemTags.SWORDS / ItemTags.AXES 判断武器类型
  • isCorrectToolForDrops 判断正确工具
  • getDestroySpeed 计算挖掘速度
  • ItemAttributeModifiers 读取盔甲属性

这意味着：所有原版机制能自动支持绝大多数 Mod 添加的物品。

安装使用

环境要求

  • Minecraft 1.21.x
  • NeoForge 26.1.2+
  • Java 21+

安装步骤

  1. 下载最新的 aicompanion-x.x.x.jar
  2. 放入 Minecraft 的 mods 文件夹
  3. 修改 config/aicompanion.toml，填入你的 API Key
  4. 启动游戏，进入游戏世界

首次进入时，同伴会自动生成在你附近并进入跟随模式。

常用命令（调试用）

/aicompanion spawn          生成/传送到玩家身边
/aicompanion action <player> mine-below    挖脚下方块
/aicompanion action <player> attack zombie 攻击僵尸
/aicompanion action <player> status        查看当前状态

聊天框中输入 @AI 或同伴名字可以直接和它对话。

项目架构

AICompanion/
├── AICompanion.java              # 主入口，注册实体/菜单/命令
├── Config.java                   # 所有配置项
│
├── entity/
│   ├── AICompanionEntity.java    # 核心实体（背包/饥饿/睡眠/模式）
│   ├── AICompanionRenderer.java  # 客户端渲染（Steve 皮肤 + 盔甲 + 手持物品）
│   ├── CompanionTracker.java     # 服务端追踪同伴状态
│   └── CompanionSpawner.java     # 安全位置生成
│
├── ai/
│   ├── AITickHandler.java        # AI 决策主循环（每 3 秒）
│   ├── AIService.java            # HTTP 客户端 + 多格式响应解析
│   ├── PromptBuilder.java        # 构建 Prompt（系统提示 + 游戏状态）
│   ├── GameState.java            # 采集游戏状态（位置/方块/实体/背包）
│   └── ChatHistory.java          # 聊天记录管理
│
├── action/
│   ├── ActionExecutor.java       # 状态机调度器
│   ├── MovementController.java   # 路径规划 + 到达检测
│   ├── MiningController.java     # 挖掘生命周期 + 自动选工具
│   ├── CombatController.java     # 战斗状态机 + 弹道计算
│   └── ItemController.java       # 进食/睡眠/丢弃等即时动作
│
└── command/
    ├── SpawnCommand.java         # /aicompanion spawn
    └── ActionCommand.java        # /aicompanion action

开发环境

# 编译
./gradlew build

# 在游戏环境中运行
./gradlew runClient

技术栈：

  • NeoForge 26.1.2 (Minecraft 1.21.x)
  • Java 21
  • Gson JSON 序列化
  • Java HttpClient 异步 API 请求

为什么做这个？

一开始只是觉得 Minecraft 的 NPC 太"傻"了 —— 它们只会按照固定脚本行动，没有真正的"思考"。而大语言模型的崛起让我看到了可能性：如果把 LLM 接入游戏，让 NPC 能理解环境并做出合理决策，会是怎样的体验？

这个项目的挑战在于：

  1. 实时性：游戏每 tick 都在变化，AI 需要在毫秒级响应
  2. 安全性：不能让 AI 做出危险操作（比如在岩浆里游泳）
  3. 兼容性：要支持各种 Mod 物品，不能硬编码
  4. 体验感：动作要自然，不能"抽搐"

碍于开发时间较少，还有很多需要添加和优化的东西，最终目标是让AI同伴的行为非常自然，像一个真正会思考的玩家。

未来计划

  • 长期记忆（记住重要的地点和事件）
  • 更多动作类型（建造、种植、养殖）
  • 语音合成（让同伴真正"说话"）

开源协议

本项目仅供学习和非商业用途。

相关链接

如果这篇文章对你有帮助，欢迎 点赞 + 收藏 + 关注，后续会持续更新开发日志和使用教程！

有任何问题或建议，欢迎在评论区交流 ~

# 人工智能 # 游戏 # java
Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

AI编程助手终极对比：ClaudeCode vs OpenCode vs Codex

文章摘要： 本文对比了三大AI编程助手（OpenCode、ClaudeCode、Codex）的优劣，从上手难度、响应速度、费用透明度、模型限制、代码权限等角度进行实测。

avatar DeepSeek技术社区

聊聊最近折腾 AI Agent 的一点心得：都是干活，为啥有的疯狂烧钱，有的却极其省 Token？

本文分析了四种AI智能体的架构设计差异及其对Token消耗效率的影响： Hermes-Agent 采用DSPy提示词压缩和程序化记忆机制，通过算法优化减少冗余，利用KV缓存降低Token消耗； Claude Code 通过子智能体隔离和内存垃圾回收技术，像操作系统般精准管理上下文，隔离噪音并压缩历史记录； OpenClaw 采用全量动态加载环境文件的方式，虽灵活但基础Token成本高且存在安全风险

avatar DeepSeek技术社区
cover

面试官问我：“你了解Claude Code的缓存机制？”，我：“何止了解，我深入研究过”，面试官：“先入职，后面细聊！！”

avatar DeepSeek技术社区