BandwidthOptimizer

Minecraft 版本： 1.21.1

平台： neoforge

标签： optimization

BandwidthOptimizer

BandwidthOptimizer is a client-and-server network bandwidth optimization mod for
heavily modded Minecraft servers. It reduces repeated and compressible PLAY
traffic while trying to preserve the original Minecraft packet stream after
decoding.

It is designed for modpacks and public servers where login sync, custom payloads,
machine networks, storage systems, and repeated chunk visits can generate large
amounts of network traffic. It is not an FPS optimizer, and it should not be
treated as a replacement for normal server, proxy, or network tuning.

Support

• Discord: https://discord.gg/qdMbM9Rq6B
• GitHub: https://github.com/duckgun13476/BandwidthOptimizer

Development Status

BandwidthOptimizer is still under active development. Bugs and mod compatibility
issues are still possible, especially in large modpacks, proxy networks, and
servers with heavy custom payload traffic.

The mod is designed to optimize network packets, not to modify world data or save
files. When a packet, boundary, or mod interaction looks unsafe, BandwidthOptimizer
tries to fall back to direct or bypass behavior instead of forcing optimization.

If you encounter an issue, please report it with client logs, server logs, proxy
logs if applicable, and BandwidthOptimizer report files. Compatibility reports,
suggestions, and contributions are welcome.

What It Does

• Wraps already encoded Minecraft packets into reversible transport frames.
• Compresses suitable packet payloads with streaming Zstd.
• Uses synchronized literal/template mapping for repeated packet structures.
• Batches safe small packet groups while respecting protocol and flush
  boundaries.
• Reuses chunk data through full, ref, and patch transport decisions.
• Keeps reusable chunk cache data across reconnects and compatible proxy server
  switches.
• Bypasses sensitive packets, protocol transitions, and unsafe timing boundaries
  instead of forcing every packet through the same optimization path.
• Provides HUD, server stats, source reports, bypass reports, and decoder dump
  files for debugging and reproducible measurements.

How It Works

BandwidthOptimizer works below normal gameplay logic. On the sending side, it
observes packets after Minecraft or the loader has encoded a complete packet into
bytes. The transport layer may then wrap, batch, compress, or bypass that encoded
packet.

On the receiving side, the transport frame is unwrapped back into the original
encoded packet bytes before normal packet handling continues. The design goal is
packet-stream equivalence: after restoration, the receiver should see the same
packet types, packet contents, and relative order that it would have seen without
BandwidthOptimizer.

Measured Results

Bandwidth reduction depends on the modpack, player activity, proxy setup, and
which packets dominate the traffic. The examples below are from BandwidthOptimizer
report files collected during real heavily modded server testing. They are
examples, not guaranteed results.

The main metric for this mod is the compression ratio of traffic that actually
enters BandwidthOptimizer's transport path. Whole-server raw/actual totals are
useful context, but they also include direct packets, compatibility bypasses,
cache reuse, and traffic from mods that should not or cannot be compressed.
For example, some mod traffic such as WATUT/YSM-style presence or model updates
may be bypassed or may compress poorly, so it should not be mixed into the main
transport-compression claim.

Live HUD snapshots:

Source-report managed transport totals:

High-impact traffic-source examples:

Low-benefit traffic-source examples:

These streams are already compressed, encrypted, or near-random enough that a
second compression layer has little room to help. They are still shown here
because they explain why mixed-server totals can look worse than the high-impact
packet families above.

To reproduce comparable measurements on your own server:

1. Install the same BandwidthOptimizer version on the server and clients.
2. Run the same activity pattern for a fixed period, such as login bursts,
   repeated chunk travel, machine-heavy areas, or normal online play.
3. Prefer the HUD optimized flow line, or filter source reports to rows whose
   path enters transport, such as BATCH_TRANSPORT_*, SINGLE_TRANSPORT, or
   chunk transport rows.
4. Keep direct/bypass rows separate. Do not count bandwidthoptimizer:transport
   carrier packets as new raw source traffic.
5. Include the modpack, loader, Minecraft version, player count, and test
   duration when sharing results.

Important report locations:

bandwidthoptimizer-native/transport-source-report/latest-source-report.md
bandwidthoptimizer-native/transport-bypass-report/latest-bypass-report.md
bandwidthoptimizer-native/decoder-exception-dump/

Mechanomania was also checked with BandwidthOptimizer diagnostic output in the
current test set. The available snapshot contained bypass and packet-rank reports
but not a source raw/actual summary, so it is listed as a tested environment
rather than used as a compression-ratio claim.

Tested Modpack Environments

The author has tested BandwidthOptimizer in several heavily modded environments,
including:

• Create Delight
• Brass Concerto
• Aeronautics
• Mechanomania

This means these environments have been used for compatibility testing. It does
not guarantee that every possible mod combination, proxy topology, or server
configuration is covered.

Supported Versions

Choose the build that matches both your Minecraft version and loader.

Dependencies

• Minecraft and the matching mod loader for the downloaded build.
• Fabric API for Fabric and Quilt builds.
• The same BandwidthOptimizer version on both the server and every client.

Forge and NeoForge builds use loader config files generated under config/.
Fabric and Quilt builds include matching runtime code and still require Fabric
API.

Installation

1. Download the BandwidthOptimizer jar for your loader and Minecraft version.
2. Put the jar into the server mods folder.
3. Put the same BandwidthOptimizer version into each client mods folder.
4. Install Fabric API when using the Fabric or Quilt build.
5. Restart the server and clients.

If client and server versions do not match, the transport channel may be disabled
or fail to negotiate correctly.

Configuration

Main loader-generated config files:

config/bandwidthoptimizer-common.toml
config/bandwidthoptimizer-client.toml

Important areas:

Most servers should start with the default configuration and only change these
options while comparing report output before and after the change.

Commands

Compatibility Scope

BandwidthOptimizer intentionally bypasses or flushes around packets and states
where optimization could change observable timing or ordering. This includes
protocol transitions, strong timing boundaries, stale transport epochs, unsafe
serverbound carrier sizes, selected compatibility cases, and packets where direct
delivery is safer than wrapping.

Velocity proxy setups are supported and tested, but proxy switching and reconnect
behavior can expose timing-sensitive bugs in any transport layer. When reporting a
proxy issue, include client logs, backend server logs, proxy logs, and the
generated BandwidthOptimizer report files.

Limitations

• Both the client and server must install the mod.
• Results vary by modpack, online count, traffic source, and activity pattern.
• Already-compressed, encrypted, or near-random streams such as WATUT/YSM-style
  presence or model data may have little or no additional compression benefit.
• Some packets are deliberately sent directly because optimizing them would cost
  more than it saves or could risk compatibility.
• Large login or reconnect bursts can still create network pressure even when
  compressed.
• BandwidthOptimizer reduces network traffic; it does not directly optimize FPS,
  TPS, world generation, database latency, or proxy routing.

Reporting Issues

When reporting a problem, please include:

• Minecraft version, loader, and BandwidthOptimizer version.
• Whether a proxy such as Velocity is used.
• Client logs and server logs around the issue time.
• Proxy logs when the problem involves server switching or reconnects.
• latest-source-report.md and latest-bypass-report.md if available.
• Decoder dump files if a packet decoder error was reported.
• The modpack name or a short list of major networking-heavy mods.

Acknowledgments

Thanks to the server owners, modpack maintainers, and players who provided logs,
packet dumps, compatibility reports, and real traffic samples from heavily modded
servers. Those reports are what make the optimization and compatibility rules
practical instead of theoretical.

License

This project is licensed under GNU LGPL 2.1-only.