Skip to content

# LazyContainerAgent v26.2 —— Paper 26.2`

Latest
Latest

Choose a tag to compare

View all tags
@kuohsuanlo kuohsuanlo released this 26 Jun 06:03
· 1 commit to main since this release
v26.2
f6c6bca

LazyContainerAgent v26.2 — Paper 26.2

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 26.2 + Java 25 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-26.2.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-26.2.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).

Verified on Paper 26.2 (real-machine test)

Tested on Paper 26.2-26-dev/26.2@193803d (API 26.2.build.26-alpha) / Java 25 (Temurin 25.0.3+9):

Check Result
ASM injection spliced 2 fields + 7 methods into BaseContainerBlockEntity + Chest / Barrel / ShulkerBox leaves transformed; 0 VerifyError
Data integrity (3-boot round-trip) chest of diamond×42 / diamond_sword{damage:10} / netherite×7 → lazy load → raw write-back → reload → all items + data-component preserved ✅
Shadow on real world 56 real containers, rawSave=56 shadowMismatch=0 → byte-identical to vanilla

Full report → docs/test-reports/26.2.md

Design benchmark (mechanism, measured on 1.21.11)

A player's storage area of ~6,000 chests holding ~750,000 filled maps:

Vanilla This agent
Loading the area main thread frozen 25–30 s no decode freeze
Player login repeatedly kicked 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. The 26.2 build uses the same mechanism (correctness re-verified above; perf benefit is equivalent).

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

LazyContainerAgent v26.2 —— Paper 26.2

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

⚠️ 版本(務必先看)

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

怎麼用(3 步)

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

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

26.2 實機驗證

測試環境 Paper 26.2-26-dev/26.2@193803d(API 26.2.build.26-alpha)/ Java 25(Temurin 25.0.3+9):

項目 結果
ASM 注入 spliced 2 fields + 7 methods into BaseContainerBlockEntity + Chest / Barrel / ShulkerBox 三 leaf 全 transformed;0 VerifyError
資料完整性(3-boot round-trip) 箱子 diamond×42 / diamond_sword{damage:10} / netherite×7 → lazy 載入 → raw 回寫 → 重載 → 物品+data-component 完全保留 ✅
shadow 真實世界 56 個真實容器,rawSave=56 shadowMismatch=0 → 逐位元組與 vanilla 相同

完整報告 → docs/test-reports/26.2.md

設計 benchmark(機制,於 1.21.11 量測)

某玩家約 6000+ 個箱子、內含約 75 萬張地圖畫的儲存區:

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

註:agent 不省磁碟 I/O——第一次冷讀那個 ~33 MB 的 chunk 仍需時間;但「把伺服器拖垮、害玩家斷線」的物品反序列化那一段被完全消滅。26.2 版機制相同(正確性已於上方重新驗證,效能效益等價)。

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

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

Assets 3
Loading