MinecraftNetOptimizer

MinecraftNetOptimizer

Conservative Paper diagnostics and bounded network optimizations for evidence-based server tuning.

Server-side only: no client-side mod is required.

MinecraftNetOptimizer helps Paper server administrators inspect packet workload, latency-sensitive behavior, outbound bursts, Netty backpressure, main-thread handoff, and virtual-entity activity while keeping critical gameplay traffic conservative and fail-open.

English

What it is
A conservative diagnostics and bounded optimization toolkit for Paper servers. It is designed to provide evidence before server tuning and to preserve gameplay correctness.

Key features

• Safe ENTITY_METADATA and changed-only logical UI deduplication.
• Raw versus forwarded packet profiling, workload categories, and outbound burst detection.
• Combat-sensitive Latency Guardian diagnostics.
• Netty backpressure and main-thread handoff observation.
• Virtual Entity diagnostics and entity packet tracing.
• Bounded global and per-player optimizer caches with fail-open saturation.
• Automatic lifecycle cleanup for players, worlds, entities, traces, and plugin disable.
• Passive JVM heap and garbage-collection metrics through /netdebug lifecycle.

Safety boundaries
MinecraftNetOptimizer does not:

• Call System.gc().
• Change JVM GC settings or Netty watermarks.
• Inspect third-party plugin internals.
• Change TCP ordering.
• Actively throttle, drop, coalesce, or reorder critical gameplay traffic.

Compatibility

• Platform: Paper
• Compatibility target (not an individual test matrix): Paper 1.20–26.2
• Compile baseline: Paper 1.20.4
• Java: 17
• PacketEvents: Soft dependency at startup; 2.13.0 is the v0.8.0 build-verified version for packet-level features
• Permission: twnetoptimizer.admin, retained for upgrade compatibility
• Not formally supported by v0.8.0: Minecraft 26.3

PacketEvents dependency
PacketEvents is optional for plugin startup, but required for packet-level profiling, safe packet optimization, and Latency Guardian packet observations. Install the PacketEvents API. PacketEvents 2.13.0 is the version used by this v0.8.0 build. Another PacketEvents version may work, but it is not guaranteed by this release; validate the exact Paper, PacketEvents, and plugin combination on a staging server first.

Installation

1. Stop the server.
2. Place MinecraftNetOptimizer-0.8.0.jar and PacketEvents API 2.13.0 in the server plugins folder.
3. Start the server.
4. Grant twnetoptimizer.admin to administrators as needed.
5. Run the initial checks below.

Initial checks
Command reference for v0.8.0
Support, source, and license

• Discord community
• GitHub Release v0.8.0
• Source code
• License: GPL-3.0

繁體中文

MinecraftNetOptimizer 是一套面向 Paper 伺服器的保守型診斷與有限網路最佳化工具，協助管理員檢查封包工作量、延遲敏感行為、輸出突發、Netty 背壓、主執行緒交接與虛擬實體活動，同時維持關鍵遊戲流量的保守與 fail-open 行為。

伺服器端專用：玩家端不需要安裝任何模組或客戶端插件。

功能

• 安全的 ENTITY_METADATA 與僅在內容變更時進行的邏輯 UI 去重。
• 原始封包與轉送封包剖析、工作量分類與輸出突發偵測。
• 針對戰鬥敏感情境的 Latency Guardian 延遲診斷。
• Netty 背壓與主執行緒交接觀察。
• Virtual Entity 診斷與實體封包追蹤。
• 有界的全域與玩家最佳化快取，容量飽和時採 fail-open。
• 玩家、世界、實體、追蹤資料與插件停用時的自動生命週期清理。
• 透過 /netdebug lifecycle 提供被動式 JVM heap 與垃圾回收指標。

安全邊界
MinecraftNetOptimizer 不會：

• 呼叫 System.gc()。
• 修改 JVM GC 設定或 Netty watermarks。
• 檢查第三方插件內部。
• 改變 TCP ordering。
• 主動節流、丟棄、合併或重新排序關鍵遊戲流量。

相容性

• 平台： Paper
• 相容性目標（不是逐版本測試矩陣）： Paper 1.20–26.2
• 編譯基準： Paper 1.20.4
• Java： 17
• PacketEvents： 啟動時為選用依賴，2.13.0 是 v0.8.0 的建置驗證版本
• 權限： twnetoptimizer.admin，為維持升級相容性而保留
• v0.8.0 未正式支援： Minecraft 26.3

PacketEvents 依賴
PacketEvents 在插件啟動時是選用依賴，但封包層分析、安全封包最佳化與 Latency Guardian 封包觀察需要它。請安裝 PacketEvents API。v0.8.0 使用 2.13.0 建置。其他 PacketEvents 版本可能可以運作，但本版本不保證，請先在 staging 驗證實際的 Paper、PacketEvents 與插件組合。

安裝

1. 停止伺服器。
2. 將 MinecraftNetOptimizer-0.8.0.jar 與 PacketEvents API 2.13.0 放入伺服器的 plugins 資料夾。
3. 啟動伺服器。
4. 視需要授予管理員 twnetoptimizer.admin。
5. 執行下方的初次檢查指令。

安裝後先檢查
v0.8.0 指令參考
支援、原始碼與授權

• Discord 社群
• GitHub v0.8.0 Release
• 原始碼
• 授權：GPL-3.0