MC Matrix Bridge: 连接Minecraft服务器和Matrix房间的Forge/NeoForge模组

MC Matrix Bridge是一个Forge/NeoForge的纯服务端mod，可以把Minecraft服务器里的聊天和一个Matrix房间双向连接起来。代码发布在GitHub上，项目地址，也可以在Modrinth和CurseForge上下载。

背景

之前和朋友联机玩GTL(GregTech Leisure)整合包，版本是Forge 1.20.1。自己平时聊天用的是Matrix，所以希望能把Matrix和游戏内服务器的聊天对接起来。这样的话，有的时候自己没有在游戏里，也可以通过Matrix和游戏里的玩家进行交流。

然后去找了一下现有的mod:

• Matrix Bridge^[1]: 支持高版本，但是只有Fabric
• Matrix Bridge(Forge)^[2]: Forge版本的只支持1.7.10，而且已经好几年没有更新了
• MatterLink^[3]: 支持到1.15.2，并且需要另外部署一个Matterbridge作为中转

所以Forge这边只有非常老的版本，高版本只有Fabric实现了。既然如此，那就自己在Forge上也实现一个。一开始只考虑了1.20.1，但是后来发现之后的新版本基本上都是基于NeoForge的，所以又把NeoForge也做了。

功能

Fig. 1. 游戏内的效果，第一行是从Minecraft发出去的消息，第二行是从Matrix发进来的消息

一开始想做的功能就是把聊天的部分搞定，后续又加上了一些和服务器交互的部分。目前主要有以下功能:

• 双向聊天: 游戏内玩家的聊天会转发到Matrix房间，Matrix房间里的文字消息也会转发到游戏里，并且带上[MC]和[Matrix]的前缀。
• 纯服务端: 只需要服主在服务器上安装，玩家用原版客户端就可以直接进服，不需要额外下载安装。
• 连接提示: 玩家进服的时候会提示Matrix房间已连接，这个提示会根据每个玩家的客户端语言显示，目前支持英文和中文。
• 服务器事件: 可以选择把玩家进出服务器、服务器启动和关闭的消息发到Matrix，默认是关闭的。
• Matrix指令: 在Matrix里发送!mc list可以查看服务器目前在线的玩家，!mc help可以查看帮助。
• Event Taps: 在运行时订阅任意一个Forge/NeoForge的事件，然后把事件转发到Matrix，可以用来调试和监控服务器。

各个版本的更新如下:

使用方法

安装

首先需要一个Forge或者NeoForge的服务器，以及一个没有开启端到端加密的Matrix房间。然后根据服务器的加载器和Minecraft版本选择对应的jar，目前一共有9个:

• Forge 1.18.x / 1.19.x / 1.20.x: Java 17
• Forge 1.21.x，NeoForge 1.21.x: Java 21
• Forge 26.1.x / 26.2.x，NeoForge 26.1.x / 26.2.x: Java 25

把jar放到服务器的mods/文件夹里，然后启动一次服务器，就会生成配置文件config/minecraftmatrixbridge.toml。

配置

配置文件里必须要填的是以下三项:

• matrix.homeserver: Matrix服务器的地址，比如https://matrix.example.com
• matrix.roomId: 房间的id!abcdef:example.com，或者别名#myroom:example.com
• matrix.accessToken: 机器人账号的access token，也可以用环境变量MATRIX_ACCESS_TOKEN

其他的选项都有默认值，比如bridge.enableJoinLeaveToMatrix控制是否转发玩家进出服务器的消息，bridge.matrixBotPrefix是Matrix指令的前缀(默认是!mc)，完整的列表可以看GitHub上的README。如果机器人账号只是被邀请进了房间，还没有加入，启动的时候也会自动接受邀请。

指令

游戏内的指令需要OP权限:

• /matrix status: 查看桥接的状态
• /matrix reload: 重新加载配置
• /matrix test: 发一条测试消息到Matrix

Event Taps

Event Taps可以在游戏内用/matrix event，或者在Matrix里用!mc event来控制。在Matrix里使用的话，要求发送者在房间里的权限等级至少是50(也就是moderator)。

1
2
3
4
5
6
7
8
9

# 监听一次聊天事件
/matrix event on ServerChatEvent
# 监听10分钟的玩家登录事件
/matrix event on PlayerLoggedInEvent "" 10m
# 一直监听包含diamond的方块事件
/matrix event on BlockEvent diamond permanent
# 在Matrix里查看和关闭
!mc event list
!mc event off ServerChatEvent

为了防止刷屏，同时最多只能开10个，转发的间隔默认至少是1秒，每条消息也会截断到2048个字符以内。

实现

整体架构

Fig. 2. MC Matrix Bridge的整体架构

如上图所示，整个mod分成两层。外面一层是版本兼容层，每个Minecraft版本一个，负责监听游戏事件、注册指令和向玩家广播消息。里面一层是core，包含了和Minecraft版本无关的全部逻辑。游戏里的聊天会先进入发送队列，再由单独的发送线程交给MatrixClient发到Matrix。Matrix那边的消息则通过sync长轮询拿回来，去掉重复的和机器人自己发的消息之后，再回到服务器主线程广播给玩家。Event Taps监听到的事件也会进入同一个发送队列，sync的进度则保存在世界存档里。

多版本

一般来说，Minecraft的mod都是基于单一的一个版本来开发的。但是这个mod涉及的Minecraft API比较少，更多的还是和Matrix进行交互，所以和Minecraft版本的依赖性并不是很强。大部分代码都可以复用，只需要为每个版本写一个很小的兼容层，就可以交叉编译到多个Minecraft版本。

对于这种小型的mod来说，个人认为这一点是非常重要的。这样就可以让它支持尽可能多的版本，成为一个基础设施。所以整个仓库是这样组织的:

1
2
3
4
5
6
7
8
9
10
11
12
13

├── core               # 纯Java，不依赖Minecraft，包括Matrix客户端、消息队列、去重、Event Taps等
├── forge-shared       # 多个Forge版本共用的代码
├── neoforge-shared    # 多个NeoForge版本共用的代码
├── forge-1.18
├── forge-1.19
├── forge-1.20
├── forge-1.21
├── forge-26.1
├── forge-26.2
├── neoforge-1.21
├── neoforge-26.1
├── neoforge-26.2
└── scripts            # 打包和测试的脚本

每个forge-*和neoforge-*都只是一层很薄的兼容层，负责监听Minecraft的事件和注册指令，然后调用core里的逻辑。

这里有一个比较麻烦的地方是Gradle。老版本的Forge需要Gradle 8，而26.x的Forge和NeoForge需要Gradle 9，两个大版本是不兼容的。所以仓库里放了两套Gradle wrapper，通过-Pomx_modern_26这个参数决定这一次构建包含哪一组版本。

另外，同一个大版本里面的小版本也会有API的变化，比如1.20.6改了映射，Forge 1.21换了新的EventBus，NeoForge 1.21.11改了权限相关的API。为了让同一个jar能在所有的小版本上运行，调用这些API的地方都改成了用反射，其他地方还是直接调用。如果权限检查出了问题，就按照没有权限处理。

Matrix客户端

这里没有用Matrix的SDK，直接用了JDK自带的HttpClient，加上Minecraft本身就带有的Gson，调用了大概8个Matrix Client-Server API^[4]的接口。因为只需要连接一个没有加密的房间，用到的接口很少，自己写反而更简单，jar里面也不用打包额外的依赖。

网络请求都在单独的线程里进行，游戏内的聊天事件只是把消息放进一个队列，所以不会卡住服务器的主线程。接收消息则是通过sync接口长轮询，sync的进度保存在存档的<world>/data/minecraftmatrixbridge/state.json里，这样服务器重启之后，也不会把之前的消息重新刷一遍。

AI开发

这个项目基本上是纯AI开发的。从2026年1月开始，自己就已经不怎么看代码的具体内容了，而之前的项目还是会尽可能去看代码是怎么组织的。

工具和模型

开发的工具和模型在不同阶段也不太一样。一开始Cursor和Codex都拿来尝试过，Cursor里面尽量用的是Claude的模型，Codex则是因为有ChatGPT的订阅，就顺便拿来用了。从Event Taps开始，主力换成了OpenCode加上oh-my-opencode^[6]。大概是这样的:

分工

自己负责的是设计整个mod的框架，包括如何跨版本、仓库的文件组织和交叉编译的思路。具体的做法是先和agent讨论各种想法，讨论出结果之后，再让agent把结果整理到AGENTS.md里，里面包括项目要做什么、必须满足的要求(纯服务端、尽量少的依赖、不能阻塞主线程等)和不做的东西(端到端加密、多房间等)。这个文件就是在一次次讨论中慢慢积累起来的，一直没有提交到仓库里。之后Gradle的细节和代码的编写就全部交给agent来做了，做新功能的时候也是一样，先讨论，把计划写进AGENTS.md，再开始实现。

oh-my-opencode是OpenCode上的一个多agent编排层，一个主agent负责写代码，其他的活分给不同的子agent:

• Sisyphus / Hephaestus: 主agent，负责规划和写代码，1月用的是Sisyphus，4月和5月用的是Hephaestus
• explore: 在代码库里搜索代码
• librarian: 查Forge和NeoForge的文档
• oracle: 做可行性分析，最后检查任务有没有完成

在提示词里加上ultrawork，主agent就会自己并行地开几个子agent去调研，再把结果汇总起来。

开发过程

做Event Taps的时候，先让它基于AGENTS.md里之前讨论的结果做一个更详细的计划，分析一下可行性。它会开几个子agent去查代码和文档，然后和自己一起把计划定下来，写回AGENTS.md，再开始写代码。中间需要自己来定的是设计上的选择。事件的索引放在运行时扫描，Matrix端的权限直接用房间里的权限等级，不另外做管理员白名单。另外还专门问了一下启动时扫描事件会不会卡住主线程。写完之后，agent会自己跑构建和单元测试，再把各个版本的服务器真的跑起来看看。

4月份适配26.x的时候，先用Codex加上oh-my-codex写了第一版，再让OpenCode里的Hephaestus去审查这份代码，把审查出来的问题都修掉。修的时候用的是ULTRAWORK Loop，oracle检查通过了才会停下来，中间被oracle打回了6次。

5月份发布v0.1.4，用的是Hephaestus加上GPT-5.5，还开了几个只读的agent专门做审查。agent写出来的东西也不是每次都对，这个阶段自己纠正了好几次:

• NeoForge的代码还是有很多重复，让它把重复的部分抽到neoforge-shared里
• 自己手动跑了一次Gradle构建，发现了报错
• 把失败的CI链接贴给它，让它一直修到GitHub Actions通过

9月份做v0.1.5用的是Codex，前期是GPT-6 Astra，后期是GPT-5.6 Sol，也用Claude Code处理了一部分。这次做的是让同一个jar兼容各个小版本，并且把真实Synapse的端到端测试加进了CI。后面提到的CurseForge版本标签的坑也是这个时候遇到的。

测试

测试方面，也是尽可能让agent把自动化测试写好，包括单元测试、用模拟的Matrix服务器启动真实的Minecraft服务器进行测试，以及后来在CI里用真实的Synapse^[5]服务器，对45个Minecraft版本和加载器的组合做端到端的测试。但是每次发布新版本之前，自己都还会用真实的Matrix服务器和真实的Minecraft服务器人工测试一次，确保它能跑。

一些坑

客户端语言

连接提示需要根据玩家的客户端语言显示。由于这是一个纯服务端的mod，原版客户端里面并没有这个mod的语言文件，所以文本只能在服务端根据玩家的语言翻译好再发过去。

问题是，玩家刚登录的时候，服务器其实还不知道玩家的语言，这个时候读到的都是默认的en_us，客户端的设置要过一会儿才会发过来。一开始的做法是固定等20个tick再发提示，但是不稳定。后来改成每个tick检查一次，如果客户端的设置看起来已经收到了(视距不是默认的2，或者语言不是en_us)就发送，最多等5秒。

CurseForge的版本标签

Minecraft从26.1开始改成了按年份的版本号，CurseForge那边的版本标签也和之前不太一样。发布v0.1.5的时候，发布流程在查找Minecraft 26.2这个标签的时候，先是一个都找不到，修好之后又找到了两个，一共失败了4次，对应修了4个commit。

好在发布流程是先校验所有平台的版本标签，然后才开始上传的，所以失败的时候也不会出现只发布了一半的情况。

除此之外还有一些小问题，比如Forge用的NightConfig的文件监听线程会让服务器在stop之后关不掉，以及超时重试的时候没有复用Matrix的transaction id，导致同一条消息发了两遍，这些都在v0.1.5里修好了。

以后的计划

• 端到端加密: 目前还没有实现。Matrix的端到端加密实现起来过于复杂，还需要考虑设备验证之类的东西，不管是软件依赖方面还是交互方面，用起来都很不舒服。如果以后能找到一个不错的UX，可以比较方便地完成验证，再考虑去做。
• 跟进新版本: 这个mod需要一直跟进Minecraft的版本，尽可能让它在所有的版本里都能跑。现在已经做了不少版本兼容性的改进，但是后续26.2的新小版本、26.3以及之后的版本，还需要慢慢跟进。

总结

本文介绍了MC Matrix Bridge，一个把Minecraft服务器和Matrix房间连接起来的Forge/NeoForge纯服务端mod。它的核心逻辑和Minecraft版本无关，通过很薄的兼容层支持了从1.18到26.2的Forge和NeoForge。这也是自己第一个基本上纯靠AI开发的项目，自己负责架构和人工测试，代码交给agent来写。

参考文献

• [1] "Matrix Bridge", Modrinth, 2026. https://modrinth.com/mod/matrix-bridge
• [2] "Matrix Bridge", CurseForge, 2022. https://www.curseforge.com/minecraft/mc-mods/matrix-minecraft-bridge
• [3] "MatterLink", CurseForge, 2020. https://www.curseforge.com/minecraft/mc-mods/matterlink
• [4] "Client-Server API", Matrix Specification, 2026. https://spec.matrix.org/latest/client-server-api/
• [5] "element-hq/synapse", GitHub, 2026. https://github.com/element-hq/synapse
• [6] "code-yeongyu/oh-my-openagent (原oh-my-opencode)", GitHub, 2026. https://github.com/code-yeongyu/oh-my-openagent