Skip to content

# LazyContainerAgent v1.0 —— Paper 1.21.11

Choose a tag to compare

View all tags
@kuohsuanlo kuohsuanlo released this 24 Jun 09:47
· 4 commits to main since this release
v1.0
718d0ad

LazyContainerAgent v1.0 — Paper 1.21.11

A Java agent that lazily deserializes container items and writes untouched containers back byte-for-byte. It removes two pieces of wasted work: unpacking every chest's items from NBT on chunk load, and re-packing them on unload. Containers nobody opens are never decoded; untouched ones are written back as-is.

⚠️ Version (read first)

  • Paper 1.21.11 + Java 21 only. Do not use it on any other Minecraft or Java version — a mismatch throws on boot or on the first container load (VerifyError / NoSuchMethodError). This is a deliberate fail-stop: it never silently corrupts or loses data, but the node won't start.
  • This is a Java agent, NOT a plugin — attach it with -javaagent:. Do not drop it in plugins/.

How to use (3 steps)

  1. Put LazyContainerAgent-1.21.11.jar somewhere the node can see it (next to your server jar is easiest).
  2. On the java line, before -jar, add (use shadow-validation mode the first time): 
    -javaagent:LazyContainerAgent-1.21.11.jar -Dlazycontainer.shadow=true -Dlazycontainer.verbose=true
  3. Run a few days at shadowMismatch=0 (output is byte-identical to vanilla → zero data risk), then remove -Dlazycontainer.shadow=true and restart for real performance.

Rollback: remove the flags and restart — back to 100% vanilla, no data migration (the on-disk format was never changed).

Real-world test (extreme case)

A player's storage area of ~6,000 chests holding ~750,000 filled maps, copied to a test server:

Vanilla This agent
Loading the area main thread frozen 25–30 s no decode freeze
Player login repeatedly kicked (lost connection) single clean login
Item deserialization all 750k maps decoded → crash ensure=0 — not a single one decoded

The agent doesn't save disk I/O — the first cold read of a ~33 MB chunk still takes time; what's removed is the item deserialization that drags the server down and disconnects players.

Full usage, design, and benchmarks → README (中文 / English).

LazyContainerAgent v1.0 —— Paper 1.21.11

容器物品「延遲反序列化 + 沒碰過就原樣寫回」的 Java agent：把「載入 chunk 就把每個箱子拆包、卸載又重新打包」這兩筆白工砍掉。沒人碰過的箱子,載入不拆、卸載原樣寫回。

⚠️ 版本(務必先看)

  • 僅適用於 Paper 1.21.11 + Java 21。 其他 Minecraft / Java 版本一律不要直接套用——版本不符會在開機或首次載入箱子時直接拋例外、安全停機(不會弄壞或弄丟資料,但該節點起不來)。
  • 這是 Java agent,不是外掛:用 -javaagent: 掛上,不要丟進 plugins/。

怎麼用(3 步)

  1. 把 LazyContainerAgent-1.21.11.jar 放到節點看得到的位置(跟伺服器 jar 同層即可)。
  2. 在 java 那行、-jar 前面加上(第一次請先開 shadow 驗證): 
    -javaagent:LazyContainerAgent-1.21.11.jar -Dlazycontainer.shadow=true -Dlazycontainer.verbose=true
  3. 跑數天 shadowMismatch=0(代表輸出與原版逐位元組相同、資料零風險)→ 再把 -Dlazycontainer.shadow=true 拿掉、重啟,換真效能。

回滾:把旗標拿掉重啟即可,硬碟格式從頭到尾沒被改過,不需任何資料遷移。

實測(極端案例)

把某玩家約 6000+ 個箱子、內含約 75 萬張地圖畫的儲存區搬到測試服,用玩家登入該區來比較:

原版(無 agent) 本 agent
載入時主執行緒 凍結 25–30 秒(watchdog 連噴) 不再因解包而凍結
玩家登入 反覆被踢(連線中斷),進不去 單次乾淨登入
物品反序列化 75 萬張地圖全硬解 → 崩 ensure=0,一張都沒解

註:agent 不省磁碟 I/O——第一次冷讀那個 ~33 MB 的 chunk 仍需時間;但「把伺服器拖垮、害玩家斷線」的物品反序列化那一段被完全消滅。

詳細原理、安全驗證、benchmark → 見 README。

—— Crafted by 廢土貓大 LogoCat · mcfallout.net

Assets 3
Loading