VeryMcProto
一个协议层移植,将仅适用于 Fabric 的协议模组重新实现为纯 Paper 插件。
客户端仍使用原始的 Fabric 模组;服务器从“Fabric 服务器 + 服务端模组”切换为“标准 Paper 服务器 + 此插件”,协议行为保持一致。
Paper 26.2 · Java 25 · paperweight userdev · Version 26.2-b4
Servux · JEI · Syncmatica · Carpet — 所有四个模块均已在 26.2 上实现并测试
目录
1. 简介
VeryMcProto 是一个 Paper 插件,它在标准的 Paper 26.2 服务器上重新实现了多个 Fabric 协议模组所期望的网络协议和数据收集机制,从而使“Fabric 客户端 + Paper 服务器”的组合能够表现出与“Fabric 客户端 + 原版 Fabric 服务器模组”完全相同的行为。
这是一个 协议层移植,而非对 Fabric 模组本身的移植。 客户端继续使用 masa's / endte's / JEI 各自的 Fabric 模组;我们的工作是在 Paper 服务器上实现它们所期望的自定义网络通道 + 服务器到客户端的数据传输 + 服务端行为协作。
为什么需要这样做:
- 这些协议模组的服务端部分严重依赖 NMS(Net Minecraft Server)内部实现 —— 纯 Paper API 无法访问(请参阅常见问题)。
- 它们使用 Mojang 的原版
CustomPacketPayload 机制;Paper 的插件消息通道直接映射到该机制,且 S2C(服务器到客户端)的大数据包可以通过 NMS ClientboundCustomPayloadPacket 发送。
- 服务端协作功能(例如 EasyPlace)在原模组中使用 Mixin;由于 Paper 没有 Mixin 运行时环境,因此通过 PacketEvents 实现了等效功能。
本项目使用 paperweight userdev 在开发时引用完全反混淆的 Mojang NMS。自 MC 26.1 起,Paper 不再支持将插件重映射到 Spigot 映射(Mojang 移除了服务器混淆),因此构建产物是 Mojang 映射的 jar 本身 —— 标准 Paper 26.1+ 可直接加载它。它不依赖任何服务器补丁 / Mixin / 私有分支。
2. 协议模组
| 模组 |
客户端模组 |
性质 |
状态 |
| Servux |
masa's MiniHUD / Litematica / Tweakeroo |
服务器到客户端的单向广播(6 个提供者通过 servux:* 通道) |
完整 |
| JEI |
JEI (mezz/JustEnoughItems 26.2) |
完整服务器协议:配方同步 + 作弊 + 配方传输(fabric:recipe_sync / neoforge:recipe_content + 10 个 jei:* 通道) |
完整 |
| Syncmatica |
endte syncmatica |
双向、有状态、多玩家共享的蓝图仓库(syncmatica:main + 18 种 PacketType + Exchange 会话) |
完整 |
| Carpet |
carpet 客户端(可选;仅限协议功能) |
行为注入模组,便携子集:规则框架 + /carpet shell + 通过 /player 创建假人 + carpet:hello 握手 / 规则同步 + /call 客户端命令 + /log HUD 记录器(tps/mobcaps, tab-list 页脚) + 纯计算命令(/distance /info /perimeterinfo /draw /spawn mobcaps,entities) |
完整 |
Servux 提供世界元数据 / 出生点 / 天气 / TPS / MobCap、结构边界框、实体与方块实体 NBT 查询,以及 Litematica 蓝图粘贴(C2S 上传 + 服务端粘贴)。EasyPlace(Tweakeroo 精确放置)通过 PacketEvents 提供服务。S2C 文件传输路径已被移除 —— 标准的 26.1+ 客户端没有接收器(已在 26.2 上再次确认)。
JEI:配方同步(加载器级通道,通过 RecipeSyncJoinOrderer 处理加入时的数据包顺序)、带有服务端权限模型的 jei:* 作弊/传输通道,以及逐行移植的 BasicRecipeTransferHandlerServer。
Syncmatica:服务器充当中央 .litematic 仓库;玩家通过 Exchange 请求-确认会话上传 / 下载 / 协作修改放置方案,具有 JSON 持久化和上传配额限制。
Carpet(规则框架 + 假玩家 + carpet:hello 协议 + /log HUD 日志记录器 + 纯计算命令):一个基于注解的规则框架,与上游 SettingsManager 同步移植(包含 carpet.conf 纯文本持久化、locked 语义、验证器链)、/carpet list|setDefault|query|removeDefault 命令行 shell、18 个已对接 Paper 等效功能的规则(通过爆炸事件关闭爆炸方块伤害、通过 ping 事件自定义 MOTD、通过 log4j 过滤器实现 cleanLogs、/perf 权限注册表,以及 shell/零行为规则),以及 假玩家子系统 —— 上游 patches/ 三件套(纯 ServerPlayer/Connection/ServerGamePacketListenerImpl 子类,零 Mixin),加上 629 行的动作包状态机和完整的 /player 命令家族(spawn/kill/shadow/mount/sneak/sprint/look/turn/move/attack/use/jump/drop/hotbar ...),均基于 Paper Brigadier API。假玩家出现在标签页列表中,计入睡眠百分比(游戏中已验证跳过夜晚),持久化到 playerdata,并被原版 /tp 和 /ban 识别。carpet:hello 协议层提供带有上游 HI("69")/hello("420") 握手的单一 CompoundTag 通道(版本字符串 = 上游 mod_version 字面量 "26.2" —— 绝非插件版本),全量及增量 Rules 同步以填充 carpet 客户端的规则浏览器,以及通过移植的 SnoopyCommandSource 进行输出捕获的 clientCommand 请求/回复(/call);所有 S2C 帧均通过 NMS DiscardedPayload 发送(carpet 客户端从未注册该通道,因此插件消息在结构上不可达)。/log 订阅框架提供具有上游形态的 LoggerRegistry,包含 tps/mobcaps HUD 日志记录器(直接沿用上游 MSPT/TPS 公式和 17²=289 的 mobcap 除数),每 20 tick 通过 Bukkit API 作为标签页底部信息发送(零协议路径 —— 对原版客户端也有效;carpet 客户端将其渲染为 HUD 面板),支持 /log subscribe|clear(受 commandLog 规则限制,Paper Brigadier API),每次加入时重新评估 defaultLoggers 默认值,并实现跨会话订阅持久化(carpet-logs.json,显式订阅 + 退订墓碑)。纯计算命令家族提供 /distance(两点间的球面/圆柱/曼哈顿距离,带逐玩家的 from/to 工作流)、/info block <pos> [grep](上游方块属性表 —— 注册表键、属性、地图颜色、光照、硬度、红石、游荡概率采样)、/perimeterinfo(±128 可生成点普查,可选特定生物类型计数)、/draw(球体/球状/菱形/金字塔/圆锥/圆柱/长方体形状放置,可选替换过滤器),以及 /spawn mobcaps [dim] / spawn entities <category> [all] —— 所有命令均在其各自的 commandXxx 规则限制下运行于 Paper Brigadier API,上游 Messenger 组件输出(可点击传送坐标)被完整移植,且 /spawn mobcaps 读取与 /log mobcaps 相同的数据源。此端口为最终版本:所有能在 Paper 上完全等效的子系统均已实现;其余部分(Scarpet、TNT/红石/活塞优化、近似规则池等)在没有 Mixin 的情况下技术上无法实现,将永远不会包含在内。构建说明位于 docs/carpet/architecture.md 和 docs/carpet/protocol.md。
26.1 引入了严格的客户端侧门限(协议版本必须完全匹配;servux 握手字符串必须以 servux-fabric-<exact upstream MC id> 开头)、新的 DataTag NBT 传输载体,以及 16MB 的客户端重组上限。所有这些均在 docs/servux/protocol.md §5(版本约束)中实现并记录。
协议深入指南:docs/servux/protocol.md (Servux 网络) · docs/syncmatica/protocol.md (Syncmatica) · docs/jei/protocol.md (JEI)。
3. 需求
服务端
| 项目 |
要求 |
| 服务器 |
Paper 26.2 (api-version: '26.2',源自单一版本源的模板化配置;标准 Paper,无需补丁/分支) |
| Java |
25 |
| 可选 |
PacketEvents 2.14.0(仅用于 EasyPlace;如果缺失则优雅跳过 —— 其他功能不受影响) |
客户端
| 功能家族 |
客户端必须安装 |
| Servux 全部功能(HUD / 结构 / NBT 查询 / 蓝图粘贴 / EasyPlace) |
MiniHUD + Litematica + Tweakeroo (masa 套件,26.2 LTS) |
| JEI 配方同步 + 作弊 + 配方传输 |
JEI (mezz/JustEnoughItems,26.2 系列) |
| 蓝图共享 |
Syncmatica (endte 客户端,26.2 LTS) |
客户端版本必须与服务端的 MC 26.2 系列 匹配。客户端是这些协议的“接收端”;每个字段语义和重组行为均已针对客户端源码进行验证。
4. 安装
- 从项目 Releases 页面获取
VeryMcProto-26.2-b4.jar,或使用 ./gradlew build 构建它(Mojang 映射后的构件可直接加载到标准 Paper 26.1+ 上 —— 不再需要反混淆步骤)。
- 将其放入服务器的
plugins/ 目录。
- (可选,仅限 EasyPlace) 安装 PacketEvents 插件。
- 重启服务器;玩家使用相应的客户端 Fabric 模组加入 —— 握手是自动的。
启动时控制台显示:
[VeryMcProto] starting (MC 26.2, paper)...
[VeryMcProto] registered protocol mod: servux
[VeryMcProto] registered protocol mod: jei
[VeryMcProto] registered protocol mod: syncmatica
[VeryMcProto] registered protocol mod: carpet
[VeryMcProto] server startup complete, RegistryAccess captured and servux.json loaded.
[VeryMcProto] framework ready.
防御性设计:四个模块各自封装在独立的 try-catch 中;任何一个失败仅记录日志并优雅降级 —— 绝不会阻塞服务器启动,也不影响其他模块。
命令(/servux、/syncmatica、/jei、/carpet、/player、/log、/distance、/info、/perimeterinfo、/draw、/spawn)、权限节点(包括 LuckPerms 配方)、所有配置文件键值 servux.json / jei.json / syncmatica-config.json / carpet.conf / carpet-logs.json、磁盘上的数据布局以及故障排除表均位于 docs/operations.md。
5. 架构
包根目录 verymc.top.veryMcProto,拆分为框架层和协议模组层:
verymc.top.veryMcProto
├── VeryMcProto 主类 (JavaPlugin.onEnable 组装框架 + 注册四个模组 + 注册命令)
├── framework/ 框架层 (基础设施与任何特定协议模组解耦)
│ ├── network/ 插件消息通道包装器、字节流编解码器、分片处理、处理器注册表
│ ├── dataproviders/ 提供者注册表 / 调度器 / 配置中心 (Servux 使用)
│ ├── event/ Bukkit 事件 → 提供者生命周期桥接 (ServerLoad/Join/Quit/Respawn/RegisterChannel + tick)
│ ├── debug/ 通用调试日志引擎 (每个模组独立实例;主分类正交;持久化存储)
│ ├── permission/ reflect/ nms/ settings/ util/ 权限工具、NMS 反射、转换、配置系统、JSON 工具
└── mod/ 协议模组层 (每个移植的 Fabric 协议模组占据一个目录单元)
├── servux/ Servux (app/command/dataproviders/network/easyplace/loggers/schematic/scheduler/util)
├── jei/ JEI 完整服务器协议 (配方同步 + jei:* 通道)
├── syncmatica/ Syncmatica (communication/exchange/data/litematica/service/...)
└── carpet/ Carpet 便携子集 (规则框架 + 命令外壳 + 假玩家补丁/动作/命令 + carpet:hello 协议 + /log HUD 日志记录器 + 纯计算命令/工具)
组装过程 (VeryMcProto.onEnable):初始化框架 → 注册 servux → jei → syncmatica → carpet → 注册四个命令;每一步都有独立的 try-catch 保护。
完整的 Fabric→Paper 替换映射(生命周期钩子 → Bukkit 事件、ServerPlayNetworking → 插件消息 + NMS 直接发送、Mixin → 反射/PacketEvents/省略等)、降级矩阵以及可行性论证位于 docs/architecture.md。
维护者与 AI 助手:请先阅读 AGENTS.md —— 这是仓库的标准指南(架构、分支/版本模型、核心设计约束、工作惯例)。
原始实现存档:OriginImpl/ 包含每个已移植模组的原始 Fabric 源代码,用于逐行对比 —— 如有分歧,以真实源码为准。
6. 功能矩阵
原版 Servux 拥有 26 个 Mixins + 2 个 AccessWideners;Syncmatica 拥有 5 个服务端 Mixins。由于 Paper 没有 Mixin 运行时环境,因此根据下表进行处理(完整矩阵见 docs/architecture.md §5):
| 功能 |
处理方式 |
状态 |
| 协议数据收集(读取私有字段) |
反射 / 直接 NMS 访问 |
已实现 |
| 收集触发器 / 生命周期 |
Bukkit 事件 + tick 调度 |
已实现 |
| EasyPlace (Tweakeroo 精确放置) |
PacketEvents 重写编码后的 PLAYER_BLOCK_PLACEMENT 数据包(原版放置不受影响)+ 通过 BlockCanBuildEvent 进行预写否决 + 通过 BlockPlaceEvent 进行放置后修复 |
已实现(需要 PacketEvents) |
| 镜像修复 (箱子/铁轨/楼梯) |
粘贴时内联修复 (fix_chest_mirror / fix_rail_rotations / fix_stairs_mirror) |
已实现(铁轨/楼梯可能不如 Mixin 完美) |
| 通过 servux 任务填充/删除 (26.1 新增) |
PACKET_C2S_TASK_REQUEST 组(类型 14-17):按 tick 预算的填充/删除 + InfoHud 状态同步 |
已实现 (26.1+) |
| UpdateSuppression |
省略(无 Paper 等效方案) |
不可能 |
| 潜影盒堆叠 |
不可能 + 所有代码已移除 (见 FAQ) |
不可能 |
调试 (SharedConstants.IS_RUNNING_IN_IDE) |
省略 |
— |
7. 文档与指南
从 docs/index.md 开始 —— 完整的文档地图和建议的阅读顺序(中文)。快速指引:
| 文档 |
内容 |
AGENTS.md |
仓库标准指南 —— 架构、分支/版本模型、核心约束、惯例 |
docs/architecture.md |
全局架构:框架、网络路径及字节限制、Mixin→Paper 矩阵(标准)、Fabric↔Paper 对比、构建工具链 |
docs/servux/protocol.md |
核心 Servux 网络协议:CustomPacketPayload、PacketSplitter、通道、字节布局、版本约束 |
docs/operations.md |
运维参考:命令、权限、配置键、数据布局、故障排除 + MC 版本升级 SOP |
docs/servux/testing.md / docs/syncmatica/testing.md |
客户端兼容性测试 (Servux / Syncmatica) |
docs/syncmatica/architecture.md + docs/syncmatica/protocol.md |
Syncmatica 实现笔记 (架构 / 协议) |
docs/jei/protocol.md |
完整 JEI 协议 |
docs/carpet/architecture.md + docs/carpet/protocol.md |
Carpet 模块实际构建情况 (规则框架、/carpet 外壳、假玩家子系统、偏差列表 —— 便携子集为最终版) + carpet:hello 协议实际构建情况 |
从源码构建:./gradlew build(Mojang 映射的 jar)· ./gradlew test · ./gradlew runServer —— JDK 25 通过 foojay toolchain plugin 自动解析。开发者所需的一切其他信息(NMS 约束、版本控制与分支模型)均位于 AGENTS.md;MC 升级运行手册位于 docs/operations.md §6。
8. 常见问题 (FAQ)
Q: 为什么我们必须使用 paperweight / NMS 而不是纯 Paper API?
A: 数据采集严重依赖 NMS 内部实现(NaturalSpawner.SpawnState、ServerTickRateManager、ChunkAccess.getAllReferences()、StructureStart.createTag()、Recipe.CODEC + NbtOps、BlockEntity.saveWithFullMetadata());网络层复用原版 FriendlyByteBuf / CompoundTag;而 JEI/Syncmatica 的大包 S2C 依赖于 NMS ClientboundCustomPayloadPacket。纯 Paper API 无法触及这些内容。
Q: 为什么 Syncmatica 默认使用 NMS 直接发送而不是插件消息?
A: 测试表明,纯 Fabric 环境的 syncmatica 客户端无法通过插件消息通道到达,只能通过 NMS DiscardedPayload 直接发送到达。
Q: 潜影盒堆叠 / 更新抑制(UpdateSuppression)有效吗?
A: 无效。前者修改了一个全局 NMS 方法(没有 Mixin / Paper 上无等效项;所有相关代码已移除);后者需要一个向 Level/LevelChunk 添加接口的 Mixin,此处被省略。
Q: 如果未安装 PacketEvents,EasyPlace 会发生什么?
A: EasyPlace 会被自动跳过(EasyPlaceBootstrap 反射加载 + catch(Throwable) 回退机制);所有其他 Servux 通道、JEI 和 Syncmatica 完全不受影响。
Q: permission_level 2 和 3 有什么区别?
A: 在纯 Bukkit op 下没有任何区别(两者都经过 isOp() 二进制判断)。要区分等级,请使用 LuckPerms 显式授予相应的权限节点(参见 docs/operations.md §2)。
Q: 粘贴结构图需要满足什么条件?
A: 玩家需要创造模式以及 servux.provider.litematic_data.paste 权限(由 litematic_data:permission_level_paste 控制,默认为 0 = 所有人)。
9. 致谢
本项目是以下 Fabric 协议模组的 Paper 协议层移植版——完全归功于原作者及使其保持活力的维护者:
- Servux — 最初由 masa 开发(
maruohon/servux);现由 sakura-ryoko 维护(sakura-ryoko/servux)。负责向 MiniHUD / Litematica / Tweakeroo 提供数据的服务器端协议实现。
- Litematica / malilib / MiniHUD / Tweakeroo / Item Scroller — 最初由 masa 开发(
maruohon/*);自 masa 退出活跃开发后,现由 sakura-ryoko 维护,其 26.2 LTS 构建全部位于 sakura-ryoko 名下:
- Syncmatica — 最初由 endte 开发(
End-Tech/syncmatica);现由 sakura-ryoko 维护(sakura-ryoko/syncmatica)。共享的结构图中央存储库。
- JustEnoughItems (JEI) — 由 mezz 开发(
mezz/JustEnoughItems,26.2 分支)。自 2026-09 起的 JEI 上游——完整的服务器协议(通过 loader 通道同步配方 + jei:* 作弊/传输通道)源自于此。
- JEIRecipeBridge — 由 Mrbysco 开发(
Mrbysco/JEIRecipeBridge)。历史性的 JEI 配方同步参考(1.21.11 行仍在使用它;保留在 OriginImpl/ 中作为 neoforge-layer 线参考)。
- Carpet — 由 gnembon & contributors 开发(
gnembon/fabric-carpet,标签 v26.2)。一个行为注入模组;可移植子集(规则框架 + /carpet shell + 假玩家子系统)源自于此。
参考资料
许可证
本项目根据 GNU Lesser General Public License v3.0 only 许可——SPDX 标识符为 LGPL-3.0-only。请参阅 LICENSE 文件。
OriginImpl/ 下的参考归档属于其各自的作者和许可证:servux / litematica / malilib / minihud / tweakeroo / itemscroller(masa → sakura-ryoko)均为 LGPL-3.0;syncmatica(endte → sakura-ryoko)为 CC0。VeryMcProto 是一个独立的 Paper 重新实现(协议层移植),并非它们的衍生作品。
链接
- 作者: Kevin O. Hsu
- GitHub:
- Modrinth:
专为 Paper 26.2 构建 · Java 25 · 无 Mixin / 无补丁 / 无私有分支
协议层移植:客户端使用原始 Fabric 模组;服务器使用标准 Paper + 此插件。
VeryMcProto
A protocol-layer port that re-implements Fabric-only protocol mods as a pure Paper plugin.
The client still uses the original Fabric mods; the server swaps from "Fabric server + server-side mod" to "standard Paper server + this plugin", with identical protocol behavior.
Paper 26.2 · Java 25 · paperweight userdev · Version 26.2-b4
Servux · JEI · Syncmatica · Carpet — all four modules implemented and tested on 26.2
Table of Contents
1. What It Is
VeryMcProto is a Paper plugin that re-implements the network protocols and data collection expected by several Fabric protocol mods on a standard Paper 26.2 server, so that a "Fabric client + Paper server" combination behaves exactly like a "Fabric client + vanilla Fabric server mod" combination.
It is a protocol-layer port, not a port of the Fabric mods themselves. The client keeps using masa's / endte's / JEI's own Fabric mods; our job is to implement on the Paper server the custom network channels + server→client data delivery + server-side behavior cooperation they expect.
Why this is necessary:
- The server-side parts of these protocol mods rely heavily on NMS internals — unreachable via the pure Paper API (see the FAQ).
- They use Mojang's vanilla
CustomPacketPayload mechanism; Paper's plugin messaging channels map directly onto it, and S2C large packets can go via NMS ClientboundCustomPayloadPacket.
- Server-side cooperative features (e.g. EasyPlace) use Mixin in the original; Paper has no Mixin runtime, so an equivalent is implemented via PacketEvents.
This project uses paperweight userdev to reference fully-deobfuscated Mojang NMS at dev time. Since MC 26.1 Paper no longer supports remapping plugins to Spigot mappings (Mojang removed server obfuscation), the build artifact is the Mojang-mapped jar itself — standard Paper 26.1+ loads it directly. It depends on no server patch / Mixin / private fork.
2. Protocol Mods
| Mod |
Client Mod |
Nature |
Status |
| Servux |
masa's MiniHUD / Litematica / Tweakeroo |
Server→client one-way broadcast (6 providers over servux:* channels) |
Full |
| JEI |
JEI (mezz/JustEnoughItems 26.2) |
Full server protocol: recipe sync + cheat + recipe transfer (fabric:recipe_sync / neoforge:recipe_content + 10 jei:* channels) |
Full |
| Syncmatica |
endte syncmatica |
Bidirectional, stateful, multi-player shared schematic repository (syncmatica:main + 18 PacketTypes + Exchange sessions) |
Full |
| Carpet |
carpet client (optional; protocol features only) |
Behavior-injection mod, portable subset: rule framework + /carpet shell + fake players via /player + carpet:hello handshake / rule sync / /call clientCommand + /log HUD loggers (tps/mobcaps, tab-list footer) + pure-compute commands (/distance /info /perimeterinfo /draw /spawn mobcaps,entities) |
Full |
Servux delivers world metadata / spawn / weather / TPS / MobCap, structure bounding boxes, entity & block-entity NBT queries, and Litematica schematic paste (C2S upload + server-side paste). EasyPlace (Tweakeroo precise placement) is served via PacketEvents. The S2C file-transmit path was removed — the stock 26.1+ client has no receiver for it (re-confirmed on 26.2).
JEI: recipe sync (loader-level channels, join-time packet ordering via RecipeSyncJoinOrderer), the jei:* cheat/transfer channels with a server-side permission model, and the line-by-line ported BasicRecipeTransferHandlerServer.
Syncmatica: the server acts as a central .litematic repository; players upload / download / collaboratively modify placements through Exchange request-acknowledgement sessions, with JSON persistence and upload quotas.
Carpet (rule framework + fake players + carpet:hello protocol + /log HUD loggers + pure-compute commands): an annotation-based rule framework ported in lockstep with upstream SettingsManager (carpet.conf plain-text persistence, locked semantics, validator chains), the /carpet list|setDefault|query|removeDefault shell, 18 rules wired to Paper equivalents (explosion block-damage off via explode events, custom MOTD via ping event, cleanLogs via a log4j filter, /perf permission registry, plus shell/zero-behavior rules), and the fake-player subsystem — the upstream patches/ trio (pure ServerPlayer/Connection/ServerGamePacketListenerImpl subclasses, zero Mixin) plus the 629-line action-pack state machine and the full /player command family (spawn/kill/shadow/mount/sneak/sprint/look/turn/move/attack/use/jump/drop/hotbar ...) on the Paper Brigadier API. Fake players occupy the tab list, count toward the sleep percentage (night skip verified in-game), persist to playerdata, and are recognized by vanilla /tp and /ban. The carpet:hello protocol layer provides single-CompoundTag channel with the upstream HI("69")/hello("420") handshake (version string = upstream mod_version literal, "26.2" — never the plugin version), full & incremental Rules sync feeding the carpet client's rule browser, and the clientCommand request/reply (/call) with output capture via the ported SnoopyCommandSource; all S2C frames go via NMS DiscardedPayload (the carpet client never registers the channel, so plugin messaging is structurally unreachable). The /log subscription framework provides an upstream-shaped LoggerRegistry with the tps/mobcaps HUD loggers (upstream MSPT/TPS formula and the 17²=289 mobcap divisor verbatim), delivered as the tab-list footer every 20 ticks via the Bukkit API (zero protocol path — works for vanilla clients too; the carpet client renders it as its HUD panel), /log subscribe|clear on the Paper Brigadier API gated by the commandLog rule, defaultLoggers defaults re-evaluated per join, and cross-session subscription persistence (carpet-logs.json, explicit subscriptions + unsubscribe tombstones). The pure-compute command family provides /distance (two-point spherical/cylindrical/manhattan distances with a per-player from/to workflow), /info block <pos> [grep] (upstream block property sheet — registry key, properties, map colour, light, hardness, redstone, wander-chance sampling), /perimeterinfo (±128 spawnable-spot census with an optional mob-type specific count), /draw (sphere/ball/diamond/pyramid/cone/cylinder/cuboid shape placement with an optional replace filter), and /spawn mobcaps [dim] / spawn entities <category> [all] — all gated by their own commandXxx rules on the Paper Brigadier API, with the upstream Messenger component output (clickable tp coordinates) ported verbatim and /spawn mobcaps reading the same data source as /log mobcaps. The port is final: every subsystem that can be fully equivalent on Paper has been implemented; the remainder (Scarpet, TNT/redstone/piston optimizations, approximate rule pools, etc.) is technically impossible without Mixin and will never be included. As-built notes live in docs/carpet/architecture.md and docs/carpet/protocol.md.
26.1 introduced hard client-side gates (protocol versions must match exactly; the servux handshake string must start with servux-fabric-<exact upstream MC id>), a new DataTag NBT wire carrier, and a 16MB client reassembly cap. All of this is implemented and documented in docs/servux/protocol.md §5 (version constraints).
Protocol deep-dives: docs/servux/protocol.md (Servux network) · docs/syncmatica/protocol.md (Syncmatica) · docs/jei/protocol.md (JEI).
3. Requirements
Server
| Item |
Requirement |
| Server |
Paper 26.2 (api-version: '26.2', templated from the single version source; standard Paper, no patch / fork needed) |
| Java |
25 |
| Optional |
PacketEvents 2.14.0 (only for EasyPlace; if absent it is gracefully skipped — everything else is unaffected) |
Client
| Feature family |
Client must install |
| All of Servux (HUD / structures / NBT query / schematic paste / EasyPlace) |
MiniHUD + Litematica + Tweakeroo (the masa suite, 26.2 LTS) |
| JEI recipe sync + cheat + recipe transfer |
JEI (mezz/JustEnoughItems, 26.2 line) |
| Schematic sharing |
Syncmatica (endte client, 26.2 LTS) |
The client version must match the server's MC 26.2 line. The client is the "receiving end" of these protocols; every field semantic and reassembly behavior is verified against the client sources.
4. Installation
- Get
VeryMcProto-26.2-b4.jar from the project Releases page, or build it with ./gradlew build (the Mojang-mapped artifact loads directly on standard Paper 26.1+ — no reobf step exists anymore).
- Drop it into the server's
plugins/ directory.
- (Optional, only for EasyPlace) Install the PacketEvents plugin.
- Restart the server; players join with the corresponding client Fabric mods — handshake is automatic.
On startup the console shows:
[VeryMcProto] starting (MC 26.2, paper)...
[VeryMcProto] registered protocol mod: servux
[VeryMcProto] registered protocol mod: jei
[VeryMcProto] registered protocol mod: syncmatica
[VeryMcProto] registered protocol mod: carpet
[VeryMcProto] server startup complete, RegistryAccess captured and servux.json loaded.
[VeryMcProto] framework ready.
Defensive design: the four modules are assembled each inside its own try-catch; any one failing only logs and degrades gracefully — it never blocks server startup and never affects the other modules.
Commands (/servux, /syncmatica, /jei, /carpet, /player, /log, /distance, /info, /perimeterinfo, /draw, /spawn), permission nodes (incl. LuckPerms recipes), every config key of servux.json / jei.json / syncmatica-config.json / carpet.conf / carpet-logs.json, the on-disk data layout, and a troubleshooting table live in docs/operations.md.
5. Architecture
Package root verymc.top.veryMcProto, split into a framework layer and a protocol-mod layer:
verymc.top.veryMcProto
├── VeryMcProto Main class (JavaPlugin.onEnable assembles the framework + registers the four modules + registers commands)
├── framework/ Framework layer (infrastructure decoupled from any specific protocol mod)
│ ├── network/ plugin messaging channel wrappers, byte-stream codec, splitting, handler registry
│ ├── dataproviders/ Provider registry / scheduler / config hub (used by Servux)
│ ├── event/ Bukkit event → Provider lifecycle bridge (ServerLoad/Join/Quit/Respawn/RegisterChannel + tick)
│ ├── debug/ Generic debug logging engine (independent instances per mod; master + category orthogonal; persisted)
│ ├── permission/ reflect/ nms/ settings/ util/ permission utility, NMS reflection, conversions, config system, JSON utils
└── mod/ Protocol-mod layer (each ported Fabric protocol mod occupies one directory unit)
├── servux/ Servux (app/command/dataproviders/network/easyplace/loggers/schematic/scheduler/util)
├── jei/ JEI full server protocol (recipe sync + jei:* channels)
├── syncmatica/ Syncmatica (communication/exchange/data/litematica/service/...)
└── carpet/ Carpet portable subset (rule framework + command shells + fake-player patches/actions/commands + carpet:hello protocol + /log HUD loggers + pure-compute commands/utils)
Assembly (VeryMcProto.onEnable): initialize the framework → register servux → jei → syncmatica → carpet → register the four commands; every step is individually try-catch guarded.
The full Fabric→Paper replacement map (lifecycle hooks → Bukkit events, ServerPlayNetworking → plugin messaging + NMS direct send, Mixin → reflection/PacketEvents/omission, etc.), the degradation matrix and the feasibility argument are in docs/architecture.md.
Maintainers & AI assistants: read AGENTS.md first — it is the canonical repo guide (architecture, branch/version model, core design constraints, working conventions).
Original implementation archive: OriginImpl/ holds the original Fabric sources of every ported mod for line-by-line comparison — in case of divergence, the real source wins.
6. Feature Matrix
The original Servux has 26 Mixins + 2 AccessWideners; Syncmatica has 5 server-side Mixins. Paper has no Mixin runtime, so each is handled per the table below (full matrix: docs/architecture.md §5):
| Feature |
Handling |
Status |
| Protocol data collection (reading private fields) |
Reflection / direct NMS access |
Implemented |
| Collection triggers / lifecycle |
Bukkit events + tick scheduling |
Implemented |
| EasyPlace (Tweakeroo precise placement) |
PacketEvents rewrites the encoded PLAYER_BLOCK_PLACEMENT packet (vanilla placement untouched) + pre-write veto via BlockCanBuildEvent + post-place fix via BlockPlaceEvent |
Implemented (needs PacketEvents) |
| Mirror fixes (chest/rail/stairs) |
Inlined fixes on paste (fix_chest_mirror / fix_rail_rotations / fix_stairs_mirror) |
Implemented (rail/stairs may be less perfect than Mixin) |
| Fill/Delete via servux tasks (26.1 new) |
PACKET_C2S_TASK_REQUEST group (types 14-17): per-tick budgeted fill/delete + InfoHud status sync |
Implemented (26.1+) |
| UpdateSuppression |
Omitted (no Paper equivalent) |
Not possible |
| Shulker-box stacking |
Impossible + all code removed (see FAQ) |
Not possible |
Debug (SharedConstants.IS_RUNNING_IN_IDE) |
Omitted |
— |
7. Docs & Guides
Start with docs/index.md — the full doc map and suggested reading order (Chinese). Quick pointers:
| Doc |
Content |
AGENTS.md |
Canonical repo guide — architecture, branch/version model, core constraints, conventions |
docs/architecture.md |
Global architecture: framework, network paths & byte limits, Mixin→Paper matrix (canonical), Fabric↔Paper comparison, build toolchain |
docs/servux/protocol.md |
Core Servux network protocol: CustomPacketPayload, PacketSplitter, channels, byte layouts, version constraints |
docs/operations.md |
Ops reference: commands, permissions, config keys, data layout, troubleshooting + MC version upgrade SOP |
docs/servux/testing.md / docs/syncmatica/testing.md |
Client compatibility testing (Servux / Syncmatica) |
docs/syncmatica/architecture.md + docs/syncmatica/protocol.md |
Syncmatica implementation notes (architecture / protocol) |
docs/jei/protocol.md |
Full JEI protocol |
docs/carpet/architecture.md + docs/carpet/protocol.md |
Carpet module as-built (rule framework, /carpet shell, fake-player subsystem, deviation list — the portable subset is final) + carpet:hello protocol as-built |
Building from source: ./gradlew build (Mojang-mapped jar) · ./gradlew test · ./gradlew runServer — JDK 25 resolves automatically via the foojay toolchain plugin. Everything else a developer needs (NMS constraints, versioning & branch model) lives in AGENTS.md; the MC upgrade runbook lives in docs/operations.md §6.
8. FAQ
Q: Why must we use paperweight / NMS instead of the pure Paper API?
A: Data collection depends heavily on NMS internals (NaturalSpawner.SpawnState, ServerTickRateManager, ChunkAccess.getAllReferences(), StructureStart.createTag(), Recipe.CODEC + NbtOps, BlockEntity.saveWithFullMetadata()); the network layer reuses vanilla FriendlyByteBuf / CompoundTag; and JEI/Syncmatica large-packet S2C relies on NMS ClientboundCustomPayloadPacket. The pure Paper API cannot reach these.
Q: Why does Syncmatica default to NMS direct send instead of plugin messaging?
A: Testing showed the pure Fabric syncmatica client is unreachable over the plugin-messaging wire and only reachable via NMS DiscardedPayload direct send.
Q: Do shulker-box stacking / UpdateSuppression work?
A: No. The former alters a global NMS method (no Mixin / no equivalent on Paper; all code removed); the latter needs a Mixin adding an interface to Level/LevelChunk, and is omitted.
Q: What happens if PacketEvents isn't installed for EasyPlace?
A: EasyPlace is skipped automatically (EasyPlaceBootstrap reflective load + catch(Throwable) fallback); all other Servux channels, JEI, and Syncmatica are completely unaffected.
Q: What's the difference between permission_level 2 and 3?
A: Under pure Bukkit op there is no difference (both go through the isOp() binary). To differentiate levels, use LuckPerms to explicitly grant the corresponding permission node (see docs/operations.md §2).
Q: What does pasting a schematic require?
A: The player needs creative mode + the servux.provider.litematic_data.paste permission (governed by litematic_data:permission_level_paste, default 0 = everyone).
9. Credits
This project is a Paper protocol-layer port of the following Fabric protocol mods — full credit to the original authors and the maintainers who keep them alive:
- Servux — originally by masa (
maruohon/servux); now maintained by sakura-ryoko (sakura-ryoko/servux). The server-side protocol implementation delivering data to MiniHUD / Litematica / Tweakeroo.
- Litematica / malilib / MiniHUD / Tweakeroo / Item Scroller — originally by masa (
maruohon/*); now maintained by sakura-ryoko since masa retired from active development — the 26.2 LTS builds all live under sakura-ryoko:
- Syncmatica — originally by endte (
End-Tech/syncmatica); now maintained by sakura-ryoko (sakura-ryoko/syncmatica). The shared schematic central repository.
- JustEnoughItems (JEI) — by mezz (
mezz/JustEnoughItems, 26.2 branch). The JEI upstream since 2026-09 — the full server protocol (recipe sync via loader channels + jei:* cheat/transfer channels) is ported from it.
- JEIRecipeBridge — by Mrbysco (
Mrbysco/JEIRecipeBridge). The historical JEI recipe-sync reference (1.21.11 line still uses it; kept in OriginImpl/ for the neoforge-layer wire reference).
- Carpet — by gnembon & contributors (
gnembon/fabric-carpet, tag v26.2). A behavior-injection mod; the portable subset (rule framework + /carpet shell + fake-player subsystem) is ported from it.
References
License
This project is licensed under the GNU Lesser General Public License v3.0 only — SPDX identifier LGPL-3.0-only. See the LICENSE file.
The reference archives under OriginImpl/ belong to their respective authors and licenses: servux / litematica / malilib / minihud / tweakeroo / itemscroller (masa → sakura-ryoko) are LGPL-3.0; syncmatica (endte → sakura-ryoko) is CC0. VeryMcProto is an independent Paper re-implementation (a protocol-layer port), not a derivative of their source.
Links
- Author: Kevin O. Hsu
- GitHub:
- Modrinth:
Built for Paper 26.2 · Java 25 · No Mixin / No patch / No private fork
A protocol-layer port: client uses the original Fabric mods; server uses standard Paper + this plugin.
评论 0
登录后参与评分
还没有评论,来抢沙发吧