为期两周的 Minecraft 热潮

2025 年 12 月,我和朋友们陷入了臭名昭著的"两周 Minecraft 热潮"。这次,我的一位朋友是 Minecraft 新手,我想让她尽可能感到受欢迎。虽然我们玩的是一台一直在线的服务器,但她只在我们其他人都在线的时候才登录,她告诉我,这是因为她不想在我们没有一起玩的时候,拿游戏问题来打扰我们。

"14 块楼梯需要多少原木?"、"点燃传送门需要什么?"、"怎么做床?"——这些对老玩家来说都是相对简单的问题,但对新手来说并不是一目了然的。其实都很简单。我想找个办法帮她,但又不用我一直在场。我想要一个能让她在任何时候都玩得自在的东西,即使我们不在线,也不会让她在难免遇到问题时觉得自己在打扰别人。

想法

我以前在私人 MC 服务器上玩过,其中很多都装有连接 Discord 的模组:在 Minecraft 聊天里输入的内容会被发送到某个 Discord 频道。这给了我一个想法:如果我做一个 Minecraft 模组,让它充当 Minecraft 聊天和任何其他服务之间的双向桥梁会怎样?这样,我就能把我的 Minecraft 服务器连接到,比如说 n8n(我最近一直在试用的自动化工具),再搭配一个 LLM,自动回答我朋友的问题。

它会暴露一个 HTTP 端点,供其他应用向它发送消息,同时也会把 Minecraft 聊天消息发送到另一个 HTTP 端点。这样,我就可以在 n8n 里设置一个 webhook 来监听 Minecraft 聊天消息,并做出相应回应。

架构

由于服务器本来就在运行 Neoforge,所以我就用了它。HookRaft 被构建为仅服务端的模组,在 Minecraft 聊天和外部 webhook 服务之间架起桥梁。它由两个主要组件组成:一个监听传入 webhook 请求的内嵌 HTTP 服务器,以及一个把 Minecraft 聊天消息转发到已配置端点的出站 HTTP 客户端。该模组还包含一个聊天事件处理器,监听 Minecraft 聊天消息,并根据可配置的过滤模式(例如全部消息、正则表达式匹配,或仅命令模式)进行转发。

主要功能

• 双向通信:将消息从 Minecraft 发送到外部服务,并接收回复
• 远程命令执行:通过 HTTP 执行 Minecraft 命令,并带有安全控制
• 灵活的过滤:使用正则表达式或仅命令模式,控制转发哪些消息
• 游戏内管理:用 /hook 发送消息,用 /hookraft 进行配置
• 异步架构:非阻塞的 HTTP 操作确保不会影响性能
• 实时配置:无需重启服务器即可修改设置

核心组件

InboundWebhookServer:使用 Java 内置的 com.sun.net.httpserver.HttpServer 实现的内嵌 HTTP 服务器,监听传入的 webhook 请求。它暴露了三个端点:

• POST /api/receive - 接收来自外部服务的消息,并在 Minecraft 聊天中广播
• POST /api/command - 远程执行 Minecraft 命令,并带有安全过滤
• GET /api/health - 健康检查端点

OutboundWebhookClient:使用 Java 21 的 java.net.http.HttpClient 向外部 webhook 发送非阻塞的 HTTP 请求。它会把 Minecraft 聊天消息和命令调用转发到已配置的端点。

ChatEventHandler:监听 Minecraft 的 ServerChatEvent,并根据可配置的过滤模式(ALL、REGEX 或 COMMAND_ONLY)转发消息。COMMAND_ONLY 模式只转发通过 /hook 命令发送的消息。

安全与配置

该模组包含一些安全功能:

• 远程命令执行的白名单/黑名单
• 出站消息的正则表达式过滤
• 所有 Minecraft 交互都在服务器主线程上执行
• HTTP 请求是非阻塞的,以防止服务器卡顿

配置通过 NeoForge 的配置系统处理,生成一个支持实时重载的 hookraft-server.toml 文件。

使用示例

借助 n8n 自动化,我搭建了一个工作流:

1. 接收来自 HookRaft 的聊天消息
2. 结合 Minecraft 相关的上下文,查询一个 LLM(本地 Ollama 服务器)
3. 如有需要,LLM 会调用网页搜索、计算器或 Hookraft 命令执行工具等工具。
4. 把回复发回 HookRaft,在游戏内广播

这就创造了一个自动化的帮助系统,即使我们不在线,也能回答我朋友的问题!

结语

HookRaft 解决了我让 Minecraft 对新手更友好的问题。它起初只是为了朋友的游戏体验,后来演变成一个强大且注重安全的模组,可以让任何 Minecraft 服务器社区受益。它现已在 CurseForge↗ 和我的 Git 服务器↗上公开提供。如果你想为你的 Minecraft 服务器添加 webhook 功能,不妨试试 HookRaft!