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
• 2. Protocol Mods
• 3. Requirements
• 4. Installation
• 5. Architecture
• 6. Feature Matrix
• 7. Docs & Guides
• 8. FAQ
• 9. Credits
• License
• Links

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

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

Client

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

1. 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).
2. Drop it into the server's plugins/ directory.
3. (Optional, only for EasyPlace) Install the PacketEvents plugin.
4. 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):

7. Docs & Guides

Start with docs/index.md — the full doc map and suggested reading order (Chinese). Quick pointers:

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:
  • sakura-ryoko/litematica · sakura-ryoko/malilib · sakura-ryoko/minihud · sakura-ryoko/tweakeroo · sakura-ryoko/itemscroller
  • These are the client-side receivers of the protocols.
• 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

• Paper dev docs · plugin messaging · PaperWeight guide
• Minecraft Protocol Wiki (Custom Payload packet structure) · Fabric networking docs
• FabricMC Discussion #4430 (Spigot/Paper ↔ Fabric custom-channel evidence)
• Full link registry: docs/references.md

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: https://github.com/Kevin-O-Hsu/VeryMcProto
• Modrinth: https://modrinth.com/plugin/verymcproto

_{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.}