Hassium

Hassium — high-performance chunk compression and client-side caching for Minecraft.
Smaller world saves and bandwidth than vanilla, local chunk reuse, and smoother joins. Supports Fabric / Forge / NeoForge across Minecraft 1.20.1–1.21.11.

Hassium · 高性能区块压缩与客户端缓存模组
相对原版缩小存档与带宽、复用本地区块、减轻进服卡顿。支持 Fabric / Forge / NeoForge，覆盖 Minecraft 1.20.1–1.21.11。

Repository: github.com/limuqy/Hassium

English

What is Hassium?

Hassium replaces vanilla Zlib with ZSTD for three things that matter on multiplayer servers and large worlds:

1. World save compression — chunks on disk stay in the familiar Anvil / Region (.mca) layout, but the payload uses a higher compression ratio (type 126).
2. Network compression — custom hassium:* channels plus optional global packet compression so chunk traffic and general packets use less bandwidth.
3. Client chunk cache — chunks you already loaded are kept locally; when you return to the same area, the client compares a content hash (chunkHash) and can skip a full download if nothing changed.

Vanilla clients can still connect by default. Install Hassium on both client and server to get negotiated compression and cache hits.

Features

Support matrix

Dependencies: Fabric needs Fabric API. Forge / NeoForge have no required extras.

How to use (defaults)

After first launch, config is created at config/hassium/hassium-client.toml and config/hassium/hassium-common.toml.

Enabled by default:

• Hassium channel compression and global packet compression
• Client chunk cache (section delta + beyond-view render when client RD > server view distance)
• World storage compression (storage.enabled = true)

Backup your world before first use. Storage compression rewrites on-disk chunk payloads. Vanilla clients can still join (compat.requireClientMod = false).

Typical setups:

Feature usage in practice

Storage (server world)
With storage.enabled = true, the server writes Region files with ZSTD payloads. Outer Anvil layout is unchanged, so tools that only care about .mca structure usually still see regions. Always keep a backup before enabling on an existing world.

Network compression
When both sides have the mod and complete the handshake, chunk data is sent over Hassium channels with ZSTD. Optional global packet compression replaces the vanilla Zlib pipeline for broader traffic savings. Control packets (handshake, hash sync, etc.) stay on a compression blacklist so they are not delayed by aggregation.

Client chunk cache
Flow in short:

1. Server intercepts vanilla full-chunk sends after handshake.
2. Server computes a content chunkHash and pushes it to the client.
3. Client compares with its local Region / metadata.
4. Hit → load from local cache under a main-thread time budget.
5. Mismatch (and sectionDeltaEnabled) → request section hashes / deltas, merge into disk NBT, then apply; fallback to full chunk on failure.
6. Miss → request a full compressed chunk payload, then apply and persist.

Block entities are requested after a real (non–beyond-view) chunk is applied. Client disk cache uses an NBT snapshot format; it is not guaranteed across major Minecraft versions.

Section delta
Default on. When the whole-chunk hash no longer matches but you still have a local copy, only changed vertical sections are transferred and merged — less bandwidth than re-downloading the entire chunk every time terrain edits.

Beyond-view render
On multiplayer, if your client render distance is larger than the server’s view-distance, Hassium can show historical terrain from hassium_cache in the outer ring (render-only). It does not ask the server for those out-of-range chunks or block entities. Stale snapshots are intentional. Mutually exclusive with Bobby. Toggle with clientCache.viewDistanceExtensionEnabled; cap with maxRenderDistance (default 32).

World export
/hassiumc export [serverIp] [seed] writes a minimal vanilla Anvil world under saves/ from your client cache (blocks + BE NBT you have visited). No entities, no player inventory; empty holes regenerate. Same mods / similar MC version recommended for modded blocks.

Light optimization With network.lightStrip = true (default on server), the server omits light data from chunk payloads. When clientCache.lightCacheEnabled = true (default), the client recomputes lighting locally on first load and caches the result. Subsequent cache hits apply pre-computed lighting directly, skipping the expensive synchronous recomputation. Both switches work independently: server-side stripping saves bandwidth, client-side caching saves CPU.

Smooth loading
clientCache.mainThreadChunkBudgetMs (default 15) limits how much chunk-apply work runs per client frame. During the first ~10 seconds after join, a short “JoinBoost” raises the budget (from ~30ms, linearly down to the normal budget) so the world fills in faster without long freezes. On the server, maxChunksPerTick caps how many chunks are serialized per player per tick.

Benchmark

ROUND1 (VD=20, cold cache): Hassium ZSTD saves ~43% bandwidth vs vanilla Zlib on 1.20.1 (12.3 MB Zlib est. → 7.0 MB ZSTD wire); ~20–21% on 1.21.x (7.1–7.3 MB Zlib → 5.7 MB ZSTD). Fabric and NeoForge show consistent results.

ZSTD level 3 (Hassium default) compresses 4–17× faster than vanilla Zlib level 6, with decompression 20–40% faster, while delivering better compression ratios on real chunk data.

Config summary

Files: config/hassium/hassium-client.toml, config/hassium/hassium-common.toml

Commands

When metrics are disabled, related stats commands are unavailable.

Tips

• Prefer matching loader + Minecraft version jars from the Files tab.
• For existing production worlds: backup → enable storage → verify before relying on it long-term.
• If joins feel heavy, lower maxChunksPerTick or keep mainThreadChunkBudgetMs modest; if the world fills too slowly, raise them carefully.
• Use /hassium stats and /hassiumc stats to confirm compression and cache hits after a normal play session.

License: GPL-3.0-or-later

简体中文

Hassium 是什么？

Hassium 用 ZSTD 替代原版 Zlib，主要优化三件事：

1. 世界存档压缩 — 外层仍是熟悉的 Anvil / Region（.mca）布局，区块 payload 使用更高压缩率（type 126）。
2. 网络传输压缩 — 自定义 hassium:* 通道，并可选开启全局包压缩，降低区块与常规数据包带宽。
3. 客户端区块缓存 — 曾加载过的区块写入本地；再次进入同一区域时用内容哈希（chunkHash）比对，未变化则可跳过全量下载。

未安装本模组的客户端默认仍可连接。要吃满协商压缩与缓存命中，请双端都安装。

特性

支持矩阵

依赖： Fabric 需要 Fabric API；Forge / NeoForge 无额外前置。

用法与默认行为

首次启动后生成配置：config/hassium/hassium-client.toml 与 config/hassium/hassium-common.toml。

默认启用：

• Hassium 通道压缩与全局包压缩
• 客户端区块缓存（含 分段增量；多人且 RD > 服务端视距时启用 超视渲染）
• 存档存储压缩（storage.enabled = true）

首次使用前请备份世界。 启用存储会改写区块落盘格式。未装模组的客户端默认可连接（compat.requireClientMod = false）。

常见用法：

功能怎么用

存档压缩（服务端世界）
storage.enabled = true 时，服务端以 ZSTD payload 写入 Region。外层 Anvil 布局不变。对已有世界启用前务必备份。

网络压缩
双端安装并完成握手后，区块数据经 Hassium 通道以 ZSTD 传输。可选全局包压缩会替换原版 Zlib 管线，进一步省流量。握手、哈希同步等控制面在压缩黑名单中，不会被聚合缓冲拖慢。

客户端区块缓存
简要流程：

1. 握手后服务端拦截原版全量区块包。
2. 服务端计算内容 chunkHash 并推送给客户端。
3. 客户端与本地 Region / 元数据比对。
4. 命中 → 在主线程时间预算内从本地缓存加载。
5. 过期（MISMATCH）且开启分段增量 → 仅拉变更分段合并写盘再 apply；失败回退全量。
6. 未命中 → 请求全量压缩区块，应用后写入本地缓存。

真实区块 apply 后再请求方块实体。磁盘缓存为 NBT 快照格式，不保证跨 MC 大版本兼容。

分段增量
默认开启。整块 hash 不再匹配但仍有本地副本时，只传输变更的竖直分段并合并，比每次整块重下更省流量。

超视渲染
多人服中，客户端渲染距离大于服务端 view-distance 时，可用 hassium_cache 历史区块回填外侧环带（仅渲染）。不会向服务器请求视距外区块或 BE；过期快照按设计接受。与 Bobby 互斥。开关：clientCache.viewDistanceExtensionEnabled；上限：maxRenderDistance（默认 32）。

世界导出
/hassiumc export [服务器IP] [seed] 把客户端缓存写成 saves/ 下可进单机的最小 Anvil 世界（方块 + 已缓存的 BE）。无实体、无玩家背包；空洞由世界生成补全。模组方块需相同模组与相近 MC 版本。

光照优化 network.lightStrip = true（默认）时，服务端发包可剥离光照数据。clientCache.lightCacheEnabled = true（默认）时，客户端首次加载本地重算光照并缓存结果。后续缓存命中直接应用预计算光照，跳过耗时的同步重算。两个开关独立控制：服务端剥离省带宽，客户端缓存省 CPU。

平滑加载
clientCache.mainThreadChunkBudgetMs（默认 15）限制客户端每帧用于 apply 的时间。进服约前 10 秒有短暂 JoinBoost（从约 30ms 线性退坡到正常预算），以加快填图、减少长时间卡死。服务端用 maxChunksPerTick 限制每玩家每 tick 序列化区块数。

基准测试

ROUND1（VD=20，冷缓存）：1.20.1 上 Hassium ZSTD 比原版 Zlib 节省 ~43% 带宽（Zlib 估算 12.3 MB → ZSTD 线缆实测 7.0 MB）；1.21.x 节省 ~20–21%（7.1–7.3 MB Zlib → 5.7 MB ZSTD）。Fabric 与 NeoForge 表现一致。

Hassium 默认 ZSTD 级别 3 的压缩速度比原版 Zlib 级别 6 快 4–17 倍，解压快 20–40%，同时在实际区块数据上压缩率更优。

配置摘要

文件：config/hassium/hassium-client.toml、config/hassium/hassium-common.toml

热路径日志（包大小、命中/未命中等）默认关闭，需要时再开对应 debug.*。ERROR / WARN 始终输出。

命令

指标关闭时，相关 stats 命令不可用。

使用建议

• 从 Files 页选择与你的加载器 + Minecraft 版本匹配的 JAR。
• 已有正式世界：先备份 → 启用存储 → 验证，再长期依赖。
• 进服偏卡可适当降低 maxChunksPerTick 或保持较小的 mainThreadChunkBudgetMs；填图过慢再谨慎上调。
• 正常游玩一段时间后用 /hassium stats 与 /hassiumc stats 确认压缩与缓存是否生效。

许可证：GPL-3.0-or-later