Описание
# 🚀 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
| Scenario | Why it wins |
| :--- | :--- |
| ⚙️ Create-based servers | Tons of repetitive kinetic data — extremely high compression ratio |
| 📦 Large modpack servers | The login registry / tag / recipe burst can be squashed further by the trained dictionary |
| 🌐 FRP / NAT-traversal / tunneled hosting | Directly saves public traffic and dodges tunnel rate limits |
| 🏠 Solo host opening to LAN | Give friends a more bandwidth-friendly entry point |
---
## 📊 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:
```text
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.
| Loader | Versions |
| :--- | :--- |
| 🟧 **Forge** | 1.18.2 / 1.19.2 / 1.20.1 |
| 🟨 **NeoForge** | 1.20.1 / 1.21.1 / 26.1 |
| 🟦 **Fabric** | 1.20.1 / 1.21.1 / 26.1 |
| 🟩 **Plugin / hybrid** | Bukkit / Spigot / Paper / Purpur, plus Arclight / Mohist / CatServer (one jar spans 1.20.1 and the latest 1.21.x) |
*(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`:
```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](https://www.curseforge.com/minecraft/mc-mods/trueuuid).
---
## 🎮 Common commands
| Command | What it does |
| :--- | :--- |
| `/zstdhud` | View / toggle the in-game HUD (`on` / `off` / `toggle`) |
| `/zstdport` | View or change ports when hosting solo / LAN (`show` / `game` / `zstd` / `voice` / `zstdvoice`) |
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](https://github.com/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](https://github.com/wish131400/zstdnet) (MIT) — that upstream copyright & permission notice is retained inside every jar. Maintained and extended by **xuenai · [麦块联机 / MineKuai (minekuai.com)](https://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](https://github.com/luben/zstd-jni) (BSD 2-Clause, containing Meta's [Zstandard](https://github.com/facebook/zstd), BSD 2-Clause). The Chunk Reference Cache's full / ref / patch idea is **inspired by** [BandwidthOptimizer](https://github.com/duckgun13476/BandwidthOptimizer) (LGPL 2.1) — ZstdNet's implementation is a **clean-room rewrite using none of its code**.
---
---
# 🇨🇳 中文介绍
> **一句话**：把客户端 ↔ 服务端之间的转发流量实时用 **ZSTD** 压一遍，公网带宽直接砍到原来的 **二十分之一** 左右，而玩家**几乎完全无感**。
**ZstdNet** 用 ZSTD 算法实时压缩客户端与服务端之间的转发流量。在「数据高度重复」的联机场景下大幅削减公网带宽占用。开启自动接管后，玩家继续填**原来那个 IP 和端口**就行；没装模组的原版玩家也能照常进服，互不影响。
## 🎯 它尤其适合谁
| 场景 | 为什么受益 |
| :--- | :--- |
| ⚙️ 机械动力（Create）类服务器 | 大量重复的机械运转数据，压缩率极高 |
| 📦 大型整合包服务器 | 登录初始的 registry / tag / recipe 爆发可被字典进一步压扁 |
| 🌐 FRP / 内网穿透 / 隧道转发 | 直接省下公网流量与穿透限速 |
| 🏠 单机开房的房主 | 想给朋友一个更省带宽的入口 |
## 📊 实际效果有多夸张
大型整合包「齿轮盛宴」服务器侧的一组**真实统计** —— 同一段时间内原始流量已经跑到 **189 GB**，压缩后实际只传输了 **10 GB**：
```text
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`。
## 📦 支持的版本与平台
> 推荐**客户端和服务端都安装**。
| 加载器 | 支持版本 |
| :--- | :--- |
| 🟧 **Forge** | 1.18.2 / 1.19.2 / 1.20.1 |
| 🟨 **NeoForge** | 1.20.1 / 1.21.1 / 26.1 |
| 🟦 **Fabric** | 1.20.1 / 1.21.1 / 26.1 |
| 🟩 **插件端 / 混合端** | Bukkit / Spigot / Paper / Purpur，以及 Arclight / Mohist / CatServer（一个 jar 跨 1.20.1 与 1.21.x） |
*（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](https://www.curseforge.com/minecraft/mc-mods/trueuuid)。
## 🎮 常用指令
- `/zstdhud` —— 查看 / 切换游戏内 HUD（`on` / `off` / `toggle`）。
- `/zstdport` —— 单机 / 局域网开房时查看或修改端口（`show` / `game` / `zstd` / `voice` / `zstdvoice`）。
运行时配置文件位于 `config/`：客户端 `zstdnet-client.toml`、服务端 `zstdnet-server.properties`（自动维护、支持热重载）。
## 🙏 致谢与来源
本项目基于原作者 **wish** 的开源项目 [wish131400/zstdnet](https://github.com/wish131400/zstdnet)（MIT License）二次开发，**上游的 MIT 版权与许可声明随每个 jar 一同保留**；由 **xuenai · [麦块联机（minekuai.com）](https://minekuai.com)** 维护与扩展。
> 本二次开发版本的源代码目前**未开源（保留所有权利 / All Rights Reserved）**，后续可能在确定协议后开源。
随每个 jar 打包的第三方组件完整声明（`LICENSE` / `NOTICE`）：[zstd-jni](https://github.com/luben/zstd-jni)（BSD 2-Clause，内含 Meta 的 [Zstandard](https://github.com/facebook/zstd)）。「区块引用缓存」的 full / ref / patch 思路**借鉴参考** [BandwidthOptimizer](https://github.com/duckgun13476/BandwidthOptimizer)（LGPL 2.1），但**净室自研、未使用其代码**。
---
**🎉 Cut your server's public bandwidth to ~1/20. 让你的联机服务器公网带宽省下二十分之一！**