zstdnet-minekuai

Minecraft 版本： 26.1 26.1.1 26.1.2

平台： neoforge

? ZstdNet — transparent ZSTD compression for Minecraft multiplayer

In one line: ZstdNet runs a transparent proxy that compresses the client ↔ server traffic with ZSTD in real time. On high-repetition servers it drops public-network bandwidth to roughly 1/20 of the original, and players notice almost nothing.

(中文说明见下方 「中文介绍」。)

⚡ TL;DR

?️ Compresses multiplayer bandwidth down to ~5–20%, cutting public-network usage by 80%+. With auto-takeover on, players keep typing the same IP and port — nothing new to learn. Vanilla players with no mod installed still connect normally and are unaffected.

? Who benefits most

? How dramatic is it, really

Below is a real server-side sample from the large modpack server 齿轮盛宴 ("Gear Feast"). Over the same window the raw traffic had already reached 189 GB, while only 10 GB was actually transmitted after compression:

Raw: 189.06 GB (3.6MB/s) | Zstd: 10.28 GB (252.7KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.06 GB (5.0MB/s) | Zstd: 10.28 GB (234.3KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.07 GB (4.8MB/s) | Zstd: 10.28 GB (303.7KB/s) | Ratio: 5.44% | Conns: 8

? Ratio = 5.44% means only about 1/20 of the original traffic actually crosses the public network. Bandwidth bills, FRP traffic and tunnel rate limits all drop with it.

✨ Core features

• ? Auto-takeover, zero learning curve for players — with the default auto_takeover=true, the mod takes over the original public port and quietly moves the backend MC server to a local port; players keep connecting to the same address.
• ?️ Covers client / dedicated server / solo-to-LAN — dedicated servers, the plugin build, and the host of a singleplayer world "Open to LAN" can all use it.
• ? Built-in live HUD — see at a glance in-game whether ZSTD is active, plus live rate, cumulative traffic, compression ratio and connection count.
• ? Vanilla status-ping passthrough — server lists ping normally and show player count / MOTD.
• ? Same-port UDP passthrough — compatible with mods that rely on Minecraft's same-port UDP, like Sable / Create: Aeronautics.
• ?️ Zero-config voice-mod compatibility — auto-detects the dedicated UDP port of backend Simple Voice Chat / Plasmo Voice and takes it over too; players auto-open the listener on join, the host fills in nothing (works for both mod servers and the plugin). In the default tunnel mode, voice reuses the single entry port, so FRP / NAT-traversal only has to forward one port.

? Headline: Chunk Reference Cache (CRC, on by default)

For servers that re-send the same chunk over and over (walking in and out of chunks, cross-dimension round-trips, reload after reconnect — very common on Create and big modpacks), ZSTD's sliding window can only fold "recent" repetition. ZstdNet adds a Chunk Reference Cache that stacks on top of ZSTD:

• In-session REF — when the same chunk is sent again this session, only an 8-byte reference token is sent; the client replays the locally cached bytes.
• Cross-session WARM_REF — fully-sent chunks are persisted to disk; chunks still held after a reconnect are sent as a 16-byte token, saving across game sessions.
• Byte-level PATCH — when a chunk changed only slightly, a delta against the held baseline is sent instead of the whole block.

CRC and ZSTD are multiplicative, not either/or: CRC removes the count of repeated chunks, ZSTD compresses the bytes of what remains. It is on by default (chunk_cache=auto) but only ever touches bytes once the connection negotiates support — unsupported / un-upgraded clients get byte-for-byte passthrough, and any runtime anomaly is fail-closed (reconnect, never a wrong packet).

? Advanced compression (all opt-in, off by default)

• ? Long-Distance Matching (LDM) — for servers where "the same big structure recurs within minutes", squeeze the ratio further.
• ? One-switch automatic dictionary — set dictionary_auto=true on the server: it auto-samples live traffic → trains in the background → hot-enables and pushes the dictionary to players, no restart, no manual distribution. Biggest win on the login registry / tag / recipe burst and on floods of tiny packets.
• ? Entity packet-stream transform — for heavy-entity scenes (Create contraptions, mob farms, raids), reversibly de-interleaves entity movement / metadata before compression to lift the ratio on these scenes.

✅ These are off by default and opt-in. The default config is byte-for-byte identical to historical behavior and stays wire-compatible with un-upgraded clients — if one side hasn't enabled it, that connection silently falls back to plain passthrough.

? Built-in premium (Mojang) verification — no extra mod

ZstdNet can verify genuine accounts itself during login (the access token never leaves the client), so you keep real premium UUIDs/skins on an offline backend while compression stays on — no need to also install TrueUUID. Config premium_verification defaults to auto (follows server.properties online-mode). Available on Fabric / Forge / NeoForge across 1.18.2 ~ 26.1. (The Bukkit/Spigot plugin build does not support this — keep the backend online-mode=false there.)

? Supported versions & platforms

Installing on both client and server is recommended.

(The 26.1 build covers the whole 26.1.x line and needs Java 25; 1.18.2 is Forge-only.)

? Plugin build (no mod loader): drop the zstdnet-bukkit jar into plugins/. Compression needs both ends — players who want compression still install the ZstdNet client mod; vanilla players without it connect normally and are unaffected.

⚙️ Required setup (dedicated server)

Before using the built-in ZstdNet server entry on a dedicated server, set at least this in the backend server.properties:

online-mode=false

Want premium identity preserved while relaying offline? Use the built-in premium verification above (mod builds), or on the plugin build pair it with TrueUUID.

? Common commands

Runtime config lives in Minecraft's config/: client zstdnet-client.toml, server zstdnet-server.properties (auto-maintained, hot-reloadable).

? What this build adds over the original

This build is a deep fork by xuenai · 麦块联机 (MineKuai) of the original wish131400/zstdnet (MIT). The original already had the ZSTD proxy, auto-takeover, same-port UDP passthrough, HUD and multi-loader support, but only covered 1.20.1 / 1.21.1. On top of that, this build adds:

• ? Far wider versions & platforms — adds Forge 1.18.2 / 1.19.2 and Minecraft 26.1 (26.1.1 / 26.1.2), plus a plugin / hybrid build (Bukkit / Spigot / Paper / Purpur, Arclight / Mohist), one jar across 1.20.1 and 1.21.x, with Folia support.
• ?️ Stronger compression — Long-Distance Matching, and a trained dictionary with zero-config auto-distribution (dictionary_auto=true).
• ? Chunk Reference Cache (on by default) and ? entity packet-stream transform (opt-in) — both negotiated, wire-compatible and fail-closed.
• ?️ Zero-config voice-mod compatibility — auto-detects backend Simple Voice Chat / Plasmo Voice UDP ports (tunnel / bridge transports).
• ? Built-in premium verification — premium UUIDs on an offline backend without an extra mod.

CRC is on by default; LDM / dictionary / entity transform are off by default and opt-in, all wire-compatible with un-upgraded clients.

? Credits & license

Built on wish's wish131400/zstdnet (MIT) — that upstream copyright & permission notice is retained inside every jar. Maintained and extended by xuenai · 麦块联机 / MineKuai (minekuai.com).

This build's own source code is currently closed-source (All Rights Reserved); it may be open-sourced under an updated license later.

Bundled third-party components, whose full notices ship inside every jar (LICENSE / NOTICE): zstd-jni (BSD 2-Clause, containing Meta's Zstandard, BSD 2-Clause). The Chunk Reference Cache's full / ref / patch idea is inspired by BandwidthOptimizer (LGPL 2.1) — ZstdNet's implementation is a clean-room rewrite using none of its code.

?? 中文介绍

一句话：把客户端 ↔ 服务端之间的转发流量实时用 ZSTD 压一遍，公网带宽直接砍到原来的 二十分之一 左右，而玩家几乎完全无感。

ZstdNet 用 ZSTD 算法实时压缩客户端与服务端之间的转发流量。在「数据高度重复」的联机场景下大幅削减公网带宽占用。开启自动接管后，玩家继续填原来那个 IP 和端口就行；没装模组的原版玩家也能照常进服，互不影响。

? 它尤其适合谁

? 实际效果有多夸张

大型整合包「齿轮盛宴」服务器侧的一组真实统计 —— 同一段时间内原始流量已经跑到 189 GB，压缩后实际只传输了 10 GB：

Raw: 189.06 GB (3.6MB/s) | Zstd: 10.28 GB (252.7KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.06 GB (5.0MB/s) | Zstd: 10.28 GB (234.3KB/s) | Ratio: 5.44% | Conns: 8
Raw: 189.07 GB (4.8MB/s) | Zstd: 10.28 GB (303.7KB/s) | Ratio: 5.44% | Conns: 8

? Ratio = 5.44%，意味着公网上实际只跑了原始流量的 二十分之一 左右。

✨ 核心特性

• ? 自动接管，玩家零学习成本 —— 默认 auto_takeover=true，模组接管原公网端口、把后端 MC 悄悄挪到本地端口，玩家继续连原地址即可。
• ?️ 客户端 / 服务端 / 单机开房全覆盖 —— 专用服、插件端、以及单机「对局域网开放」的房主都能用。
• ? 内置实时 HUD —— 游戏里一眼看清当前是否在走 ZSTD、实时速率、累计流量、压缩率、连接数。
• ? 原版状态查询透传 —— 服务器列表能正常 ping、显示在线人数和 MOTD。
• ? 同端口 UDP 原样透传 —— 兼容 Sable / 机械动力：航空学这类依赖同端口 UDP 的模组。
• ?️ 语音模组零配置兼容 —— 自动探测后端 Simple Voice Chat / Plasmo Voice 的独立 UDP 端口并一起接管，玩家进服自动开监听，服主无需手填端口。默认 tunnel 模式下语音也复用入口端口这一个口。

? 区块引用缓存（CRC，默认开启）

针对「同一个区块被反复下发」的场景（反复进出区块、跨维度往返、重连后重新加载 —— Create 系与大型整合包尤为常见），在 ZSTD 之前把客户端已持有的相同区块换成 8/16 字节令牌（会话内 REF / 跨会话 WARM_REF）或字节级增量（PATCH），与 ZSTD 叠加进一步压低带宽。默认 chunk_cache=auto、协商生效、fail-closed 不损坏数据 —— 不支持的客户端逐字节透传。

? 进阶压缩能力（全部可选，默认关闭）

• ? 长距离匹配（LDM） —— 面向「同样的大结构几分钟内反复出现」的服务器，进一步榨干压缩率。
• ? 一键全自动字典 —— 服务端设 dictionary_auto=true 即可：自动采样 → 后台训练 → 热插启用并下发玩家，无需重启、无需手动分发。
• ? 实体包流变换 —— 面向大量实体 / 生物场景（机械动力契约体、刷怪塔、怪潮），在压缩前做可逆去交错。

✅ 以上选项默认关闭、可选开启；默认配置与历史行为逐字节一致，并对未升级客户端保持线兼容 —— 一端没开就自动回退原样转发。

? 内置正版验证（无需额外装 mod）

ZstdNet 可在登录阶段内置正版账号验证（access token 不出客户端），在离线后端上也能保留真实正版 UUID/皮肤，压缩照常 —— 无需再装 TrueUUID。premium_verification 默认 auto（跟随 server.properties 的 online-mode）。Fabric / Forge / NeoForge（1.18.2 ~ 26.1）全已内置；Bukkit/Spigot 插件端暂不支持，请保持后端 online-mode=false。

? 支持的版本与平台

推荐客户端和服务端都安装。

（26.1 构建覆盖整个 26.1.x 线，需要 Java 25；1.18.2 为 Forge 专属。）

? 插件端（无需 mod 加载器）：把 zstdnet-bukkit 的 jar 丢进 plugins/ 即可。压缩需要两端配合：想要压缩的玩家仍需安装 ZstdNet 客户端 mod；没装的原版玩家照常直连，不受影响。

⚙️ 必要准备（专用服）

在专用服上使用内置 ZstdNet 服务端入口前，请在后端 server.properties 中至少设置 online-mode=false。如需在离线转发的同时保留正版身份：mod 版用上面的内置正版验证；插件版可搭配 TrueUUID。

? 常用指令

• /zstdhud —— 查看 / 切换游戏内 HUD（on / off / toggle）。
• /zstdport —— 单机 / 局域网开房时查看或修改端口（show / game / zstd / voice / zstdvoice）。

运行时配置文件位于 config/：客户端 zstdnet-client.toml、服务端 zstdnet-server.properties（自动维护、支持热重载）。

? 致谢与来源

本项目基于原作者 wish 的开源项目 wish131400/zstdnet（MIT License）二次开发，上游的 MIT 版权与许可声明随每个 jar 一同保留；由 xuenai · 麦块联机（minekuai.com） 维护与扩展。

本二次开发版本的源代码目前未开源（保留所有权利 / All Rights Reserved），后续可能在确定协议后开源。

随每个 jar 打包的第三方组件完整声明（LICENSE / NOTICE）：zstd-jni（BSD 2-Clause，内含 Meta 的 Zstandard）。「区块引用缓存」的 full / ref / patch 思路借鉴参考 BandwidthOptimizer（LGPL 2.1），但净室自研、未使用其代码。