VeryMcProto

插件

· 作者 Kevin-O-Hsu

为 PaperMC 服务器提供 Servux、JEI、Syncmatica 和 Carpet 协议支持的服务端插件。

0 本站下载 0 关注 更新于 2 周前

需要前置:PacketEvents

最新 1.21.11-b8 · 1.21.11 · Paper / Purpur

一键开服(送7天)

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. 安装

  1. 从项目 Releases 页面获取 VeryMcProto-26.2-b4.jar,或使用 ./gradlew build 构建它(Mojang 映射后的构件可直接加载到标准 Paper 26.1+ 上 —— 不再需要反混淆步骤)。
  2. 将其放入服务器的 plugins/ 目录。
  3. (可选,仅限 EasyPlace) 安装 PacketEvents 插件。
  4. 重启服务器;玩家使用相应的客户端 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 + 此插件。

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源