![\"Discord](\"https:\/\/cdn.jsdelivr.net\/npm\/@intergrav\/devins-badges@3.2.0\/assets\/cozy\/social\/discord-singular_vector.svg\")
\n
![\"GitHub](\"https:\/\/cdn.jsdelivr.net\/npm\/@intergrav\/devins-badges@3.2.0\/assets\/cozy\/social\/github-singular_vector.svg\")
\n<\/p>\n# BandwidthOptimizer<\/p>\n
BandwidthOptimizer is a client-and-server network bandwidth optimization mod for
\nheavily modded Minecraft servers. It reduces repeated and compressible PLAY
\ntraffic while trying to preserve the original Minecraft packet stream after
\ndecoding.<\/p>\n
It is designed for modpacks and public servers where login sync, custom payloads,
\nmachine networks, storage systems, and repeated chunk visits can generate large
\namounts of network traffic. It is not an FPS optimizer, and it should not be
\ntreated as a replacement for normal server, proxy, or network tuning.<\/p>\n
\n
\n\n<\/p>\n
<\/p>\n
## Support<\/p>\n
– Discord: https:\/\/discord.gg\/qdMbM9Rq6B
\n– GitHub: https:\/\/github.com\/duckgun13476\/BandwidthOptimizer<\/p>\n
## Development Status<\/p>\n
BandwidthOptimizer is still under active development. Bugs and mod compatibility
\nissues are still possible, especially in large modpacks, proxy networks, and
\nservers with heavy custom payload traffic.<\/p>\n
The mod is designed to optimize network packets, not to modify world data or save
\nfiles. When a packet, boundary, or mod interaction looks unsafe, BandwidthOptimizer
\ntries to fall back to direct or bypass behavior instead of forcing optimization.<\/p>\n
If you encounter an issue, please report it with client logs, server logs, proxy
\nlogs if applicable, and BandwidthOptimizer report files. Compatibility reports,
\nsuggestions, and contributions are welcome.<\/p>\n
## What It Does<\/p>\n
– Wraps already encoded Minecraft packets into reversible transport frames.
\n– Compresses suitable packet payloads with streaming Zstd.
\n– Uses synchronized literal\/template mapping for repeated packet structures.
\n– Batches safe small packet groups while respecting protocol and flush
\n boundaries.
\n– Reuses chunk data through `full`, `ref`, and `patch` transport decisions.
\n– Keeps reusable chunk cache data across reconnects and compatible proxy server
\n switches.
\n– Bypasses sensitive packets, protocol transitions, and unsafe timing boundaries
\n instead of forcing every packet through the same optimization path.
\n– Provides HUD, server stats, source reports, bypass reports, and decoder dump
\n files for debugging and reproducible measurements.<\/p>\n
## How It Works<\/p>\n
BandwidthOptimizer works below normal gameplay logic. On the sending side, it
\nobserves packets after Minecraft or the loader has encoded a complete packet into
\nbytes. The transport layer may then wrap, batch, compress, or bypass that encoded
\npacket.<\/p>\n
On the receiving side, the transport frame is unwrapped back into the original
\nencoded packet bytes before normal packet handling continues. The design goal is
\npacket-stream equivalence: after restoration, the receiver should see the same
\npacket types, packet contents, and relative order that it would have seen without
\nBandwidthOptimizer.<\/p>\n
| Layer | Purpose |
\n| — | — |
\n| Transparent transport | Carries already encoded packet bytes without rewriting gameplay logic. |
\n| Streaming Zstd | Compresses packet bodies that benefit from byte-level compression. |
\n| Literal\/template mapping | Reduces repeated packet structures while keeping sender and receiver state synchronized. |
\n| Light batch path | Uses cheaper batch encoding for sensitive flush paths where full template work is too expensive. |
\n| Chunk transport | Chooses `full`, `ref`, `patch`, or `bypass` for chunk-related traffic based on available cache state and safety checks. |
\n| Boundary control | Forces flush, bypass, warmup, or reset around protocol transitions, login\/config\/play changes, proxy switches, and stale epochs. |
\n| Reports | Records raw traffic, optimized traffic, bypass causes, packet ranks, and decoder failures for troubleshooting. |<\/p>\n
## Measured Results<\/p>\n
Bandwidth reduction depends on the modpack, player activity, proxy setup, and
\nwhich packets dominate the traffic. The examples below are from BandwidthOptimizer
\nreport files collected during real heavily modded server testing. They are
\nexamples, not guaranteed results.<\/p>\n
The main metric for this mod is the compression ratio of traffic that actually
\nenters BandwidthOptimizer’s transport path. Whole-server raw\/actual totals are
\nuseful context, but they also include direct packets, compatibility bypasses,
\ncache reuse, and traffic from mods that should not or cannot be compressed.
\nFor example, some mod traffic such as WATUT\/YSM-style presence or model updates
\nmay be bypassed or may compress poorly, so it should not be mixed into the main
\ntransport-compression claim.<\/p>\n
Live HUD snapshots:<\/p>\n
| Environment | Client optimized flow | Server raw to actual | Server optimized flow | Direct flow | Players | Source |
\n| — | —: | —: | —: | —: | —: | — |
\n| Create Delight Remake server 1 | `23.21 MB -> 3.93 MB` (`16.9%`) | `305.35 GB -> 51.12 GB` (`16.7%`) | `40.28 GB` (`13.2%`) | `49.46 GB` (`16.2%`) | 13 | HUD snapshot, v2.7.6.10. |
\n| Create Delight Remake server 2 | `24.51 MB -> 4.15 MB` (`16.9%`) | `516.70 GB -> 83.24 GB` (`16.1%`) | `57.57 GB` (`11.1%`) | `57.01 GB` (`11.0%`) | 15 | HUD snapshot, v2.7.6.10. |<\/p>\n
Source-report managed transport totals:<\/p>\n
| Environment | Managed transport | Without WATUT\/YSM-like streams | Notes |
\n| — | —: | —: | — |
\n| Create-focused core server | `38976.09 MiB -> 9455.03 MiB` (`24.3%`) | `34580.44 MiB -> 5236.56 MiB` (`15.1%`) | Real mixed traffic with large already-compressed\/poorly-compressible sources. |
\n| Create-focused mirror server | `1046.16 MiB -> 253.89 MiB` (`24.3%`) | `902.82 MiB -> 113.55 MiB` (`12.6%`) | Smaller mixed sample; WATUT-like traffic is visible. |
\n| Create-focused test server | `1174.31 MiB -> 112.24 MiB` (`9.6%`) | same sample | No WATUT\/YSM exception in this TopN sample. |
\n| Create Delight | `7865.72 MiB -> 1622.43 MiB` (`20.6%`) | `7774.54 MiB -> 1539.90 MiB` (`19.8%`) | Public modpack source-report snapshot. |
\n| Create Delight secondary snapshot | `4567.66 MiB -> 603.15 MiB` (`13.2%`) | not separated | Earlier report snapshot. |<\/p>\n
High-impact traffic-source examples:<\/p>\n
| Source | Environment | Raw observed | Actual transmitted | Actual\/raw ratio |
\n| — | — | —: | —: | —: |
\n| `ClientboundLevelChunkWithLightPacket` | Create-focused core server | `9062.88 MiB` | `481.85 MiB` | `5.3%` |
\n| `ClientboundLevelChunkWithLightPacket` | Create-focused test server | `713.65 MiB` | `16.84 MiB` | `2.4%` |
\n| `ClientboundTabListPacket` | Create-focused core server | `6354.97 MiB` | `655.45 MiB` | `10.3%` |
\n| `lightmanscurrency:network` | Create-focused core server | `8206.80 MiB` | `593.69 MiB` | `7.2%` |
\n| `create:deployer` block entity data | Create Delight | `510.41 MiB` | `71.61 MiB` | `14.0%` |<\/p>\n
Low-benefit traffic-source examples:<\/p>\n
| Source | Environment | Raw observed | Actual transmitted | Actual\/raw ratio | Path |
\n| — | — | —: | —: | —: | — |
\n| `watut:main` | Create-focused core server | `4157.94 MiB` | `3974.80 MiB` | `95.6%` | `BATCH_DIRECT_FALLBACK` |
\n| `yes_steve_model:2_6_0` | Create-focused core server | `514.63 MiB` | `510.50 MiB` | `99.2%` | `BATCH_TRANSPORT_SHARE` |
\n| `watut:main` | Create-focused mirror server | `146.07 MiB` | `143.07 MiB` | `97.9%` | `BATCH_TRANSPORT_SHARE` |
\n| `watut:main` | Create Delight | `91.18 MiB` | `82.53 MiB` | `90.5%` | `BATCH_TRANSPORT_SHARE` |<\/p>\n
These streams are already compressed, encrypted, or near-random enough that a
\nsecond compression layer has little room to help. They are still shown here
\nbecause they explain why mixed-server totals can look worse than the high-impact
\npacket families above.<\/p>\n
To reproduce comparable measurements on your own server:<\/p>\n
1. Install the same BandwidthOptimizer version on the server and clients.
\n2. Run the same activity pattern for a fixed period, such as login bursts,
\n repeated chunk travel, machine-heavy areas, or normal online play.
\n3. Prefer the HUD `optimized flow` line, or filter source reports to rows whose
\n path enters transport, such as `BATCH_TRANSPORT_*`, `SINGLE_TRANSPORT`, or
\n chunk transport rows.
\n4. Keep direct\/bypass rows separate. Do not count `bandwidthoptimizer:transport`
\n carrier packets as new raw source traffic.
\n5. Include the modpack, loader, Minecraft version, player count, and test
\n duration when sharing results.<\/p>\n
Important report locations:<\/p>\n
“`text
\nbandwidthoptimizer-native\/transport-source-report\/latest-source-report.md
\nbandwidthoptimizer-native\/transport-bypass-report\/latest-bypass-report.md
\nbandwidthoptimizer-native\/decoder-exception-dump\/
\n“`<\/p>\n
Mechanomania was also checked with BandwidthOptimizer diagnostic output in the
\ncurrent test set. The available snapshot contained bypass and packet-rank reports
\nbut not a source raw\/actual summary, so it is listed as a tested environment
\nrather than used as a compression-ratio claim.<\/p>\n
## Tested Modpack Environments<\/p>\n
The author has tested BandwidthOptimizer in several heavily modded environments,
\nincluding:<\/p>\n
– Create Delight
\n– Brass Concerto
\n– Aeronautics
\n– Mechanomania<\/p>\n
This means these environments have been used for compatibility testing. It does
\nnot guarantee that every possible mod combination, proxy topology, or server
\nconfiguration is covered.<\/p>\n
## Supported Versions<\/p>\n
Choose the build that matches both your Minecraft version and loader.<\/p>\n
| Loader | Minecraft | Notes |
\n| — | — | — |
\n| Forge | 1.19.2 | Forge 43.x target. |
\n| Forge | 1.20.1 | Forge 47.x target. |
\n| Fabric \/ Quilt | 1.20.1 | Requires Fabric API. Published for Fabric and Quilt loaders. |
\n| Fabric \/ Quilt | 1.21.1 | Requires Fabric API. Published for Fabric and Quilt loaders. |
\n| NeoForge | 1.21.1 | NeoForge 21.x target. |<\/p>\n
## Dependencies<\/p>\n
– Minecraft and the matching mod loader for the downloaded build.
\n– Fabric API for Fabric and Quilt builds.
\n– The same BandwidthOptimizer version on both the server and every client.<\/p>\n
Forge and NeoForge builds use loader config files generated under `config\/`.
\nFabric and Quilt builds include matching runtime code and still require Fabric
\nAPI.<\/p>\n
## Installation<\/p>\n
1. Download the BandwidthOptimizer jar for your loader and Minecraft version.
\n2. Put the jar into the server `mods` folder.
\n3. Put the same BandwidthOptimizer version into each client `mods` folder.
\n4. Install Fabric API when using the Fabric or Quilt build.
\n5. Restart the server and clients.<\/p>\n
If client and server versions do not match, the transport channel may be disabled
\nor fail to negotiate correctly.<\/p>\n
## Configuration<\/p>\n
Main loader-generated config files:<\/p>\n
“`text
\nconfig\/bandwidthoptimizer-common.toml
\nconfig\/bandwidthoptimizer-client.toml
\n“`<\/p>\n
Important areas:<\/p>\n
| Area | Purpose |
\n| — | — |
\n| PLAY batch options | Controls reference deduplication, SHA-256 dictionary, template dictionary, Zstd, streaming Zstd, and async batch encoding. |
\n| Template dictionary limits | Caps packet size, entry count, payload bytes, diff runs, and changed bytes for mapping work. |
\n| Chunk cache budget | Controls client-side chunk cache memory and persistent backup behavior. |
\n| Debug analysis | Enables heavier manual analysis commands such as transport reports and packet ranks. |
\n| Decoder dump | Writes detailed packet dumps when decoder failures are detected. |
\n| Runtime properties | Advanced overrides such as `bandwidthoptimizer.transport.batchWindowMillis`, `bandwidthoptimizer.transport.mappingEnabled`, and `bandwidthoptimizer.transport.zstdEnabled`. |<\/p>\n
Most servers should start with the default configuration and only change these
\noptions while comparing report output before and after the change.<\/p>\n
## Commands<\/p>\n
| Command | Description |
\n| — | — |
\n| `\/bandwidthoptimizer` | Shows available BandwidthOptimizer commands. |
\n| `\/bandwidthoptimizer hud` | Toggles the client HUD. |
\n| `\/bandwidthoptimizer stats` | Shows server bandwidth totals. |
\n| `\/bandwidthoptimizer stats total` | Shows persisted total server bandwidth stats. |
\n| `\/bandwidthoptimizer stats players [limit]` | Shows top player\/channel bandwidth stats. |
\n| `\/bandwidthoptimizer stats reset` | Resets persisted server bandwidth stats. |
\n| `\/bandwidthoptimizer test transportreport run [ticks]` | Starts a short transport compression report. Requires debug analysis. |
\n| `\/bandwidthoptimizer test transportreport status` | Shows transport report capture status. |
\n| `\/bandwidthoptimizer test packetrank run [ticks]` | Starts a packet-rank capture. Requires debug analysis. |
\n| `\/bandwidthoptimizer test packetrank status` | Shows packet-rank capture status. |<\/p>\n
## Compatibility Scope<\/p>\n
BandwidthOptimizer intentionally bypasses or flushes around packets and states
\nwhere optimization could change observable timing or ordering. This includes
\nprotocol transitions, strong timing boundaries, stale transport epochs, unsafe
\nserverbound carrier sizes, selected compatibility cases, and packets where direct
\ndelivery is safer than wrapping.<\/p>\n
Velocity proxy setups are supported and tested, but proxy switching and reconnect
\nbehavior can expose timing-sensitive bugs in any transport layer. When reporting a
\nproxy issue, include client logs, backend server logs, proxy logs, and the
\ngenerated BandwidthOptimizer report files.<\/p>\n
## Limitations<\/p>\n
– Both the client and server must install the mod.
\n– Results vary by modpack, online count, traffic source, and activity pattern.
\n– Already-compressed, encrypted, or near-random streams such as WATUT\/YSM-style
\n presence or model data may have little or no additional compression benefit.
\n– Some packets are deliberately sent directly because optimizing them would cost
\n more than it saves or could risk compatibility.
\n– Large login or reconnect bursts can still create network pressure even when
\n compressed.
\n– BandwidthOptimizer reduces network traffic; it does not directly optimize FPS,
\n TPS, world generation, database latency, or proxy routing.<\/p>\n
## Reporting Issues<\/p>\n
When reporting a problem, please include:<\/p>\n
– Minecraft version, loader, and BandwidthOptimizer version.
\n– Whether a proxy such as Velocity is used.
\n– Client logs and server logs around the issue time.
\n– Proxy logs when the problem involves server switching or reconnects.
\n– `latest-source-report.md` and `latest-bypass-report.md` if available.
\n– Decoder dump files if a packet decoder error was reported.
\n– The modpack name or a short list of major networking-heavy mods.<\/p>\n
## Acknowledgments<\/p>\n
Thanks to the server owners, modpack maintainers, and players who provided logs,
\npacket dumps, compatibility reports, and real traffic samples from heavily modded
\nservers. Those reports are what make the optimization and compatibility rules
\npractical instead of theoretical.<\/p>\n
## License<\/p>\n
This project is licensed under GNU LGPL 2.1-only.<\/p>\n","protected":false},"excerpt":{"rendered":"
Save your MC bandwidth with big quantities.<\/p>\n","protected":false},"featured_media":25358,"template":"","meta":{"_minecraft_slug":"bandwidthoptimizer","_minecraft_project_id":"9fzjUecF","_minecraft_author":"PInk_Cats","_minecraft_license":"LGPL-2.1-or-later","_minecraft_downloads":183,"_minecraft_follows":4,"_minecraft_client_side":"required","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"bandwidthoptimizer.zip","_minecraft_size_bytes":286358930,"_minecraft_version_count":29,"_minecraft_updated_at":"2026-05-16T16:18:06.493052Z","_minecraft_date_created":"2026-05-16T00:10:43.604099Z","_minecraft_date_modified":"2026-05-14T14:00:11.767493Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/bandwidthoptimizer","_minecraft_icon_attachment_id":25358,"_minecraft_imported_at":"2026-06-01T09:04:35+00:00","_minecraft_import_hash":"66ecebbd43fd73d0da03547c939c407e","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[97,104,158,90,98],"mod_loader":[99,106,160,100],"minecraft_version":[56,36,37],"class_list":["post-25357","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-fabric","mod_category-forge","mod_category-neoforge","mod_category-optimization","mod_category-quilt","mod_loader-fabric","mod_loader-forge","mod_loader-neoforge","mod_loader-quilt","minecraft_version-1-19-2","minecraft_version-1-20-1","minecraft_version-1-21-1"],"yoast_head":"\n