?
Host a serverModrinth App
Sign in
ModsResource PacksData PacksShadersModpacksPluginsServers
Settings
VeryMcProto

VeryMcProto

Serverside plugins that add servux&JEI&syncmatica&carpet protocol support for papermc servers.

367downloads
3followers
367downloads
3followers

Compatibility

Minecraft: Java Edition

26.2
26.1.2
1.21.11

Platforms

Links

Report issues View source

Tags

Creators

Details

Licensed LGPL-3.0-only
Published 2 months ago
Updated 2 days ago

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)
Carpet 🔧 Phase 1+2+3+4+5     (rule framework + /carpet shell + fake players via /player + carpet:hello protocol + /log HUD loggers + pure-compute command family /distance /info /perimeterinfo /draw /spawn; later phases planned)

Author: Kevin O. Hsu · GitHub: https://github.com/Kevin-O-Hsu/VeryMcProto · Modrinth: https://modrinth.com/plugin/verymcproto

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) 🔧 Phase 5

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 (Phase 1 foundation + Phase 2 fake players + Phase 3 carpet:hello protocol + Phase 4 /log HUD loggers + Phase 5 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. Phase 3 adds the carpet:hello protocol: 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). Phase 4 adds the /log subscription framework — 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). Phase 5 adds the pure-compute command family: /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

  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, Phase 1+2+3+4+5 (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 ✅
Collection triggers / lifecycle Bukkit events + tick scheduling ✅
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 ✅ needs PacketEvents
Mirror fixes (chest/rail/stairs) Inlined fixes on paste (fix_chest_mirror / fix_rail_rotations / fix_stairs_mirror) ✅ (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 ✅ (26.1+)
UpdateSuppression ⛔ Omitted (no Paper equivalent) ❌
Shulker-box stacking ⛔ Impossible + all code removed (see FAQ) ❌
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.

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.