Skip to main content

​
Compression Configuration

Gate supports packet compression to reduce bandwidth usage between the proxy and connected clients. Configure compression thresholds and levels to balance bandwidth savings against CPU usage.

​
Overview

Minecraft protocol supports packet compression using zlib. When enabled, packets larger than a threshold are compressed before transmission, reducing network bandwidth at the cost of CPU resources.
Important: These settings apply to Gate ↔ Client connections only. Compression between Gate and backend servers is controlled by the backend server’s configuration.

​
Configuration

​
config.compression
object
Packet compression settings
compression:
  threshold: 256  # Minimum packet size to compress (bytes)
  level: -1       # Compression level (-1 to 9)

​
Compression Threshold

​
config.compression.threshold
integer
default:"256"
The minimum size (in bytes) a packet must be before Gate compresses it. The vanilla Minecraft server uses 256 by default.
compression:
  threshold: 256

​
How Threshold Works

  • Packets ≥ threshold: Compressed before sending
  • Packets < threshold: Sent uncompressed (compression overhead not worth it)

​
Threshold Values

compression:
  threshold: 256  # Vanilla Minecraft default
Best for: Most servers
  • Balanced bandwidth/CPU tradeoff
  • Same as vanilla Minecraft
  • Good for typical gameplay
  • Recommended starting point
Setting threshold: 0 compresses all packets including tiny ones, significantly increasing CPU usage with minimal bandwidth benefit. Only use in extreme bandwidth-constrained scenarios.

​
Compression Level

​
config.compression.level
integer
default:"-1"
The zlib compression level. Goes from -1 to 9 where:
  • -1 = Default (zlib chooses, usually equivalent to 6)
  • 0 = No compression
  • 1 = Fastest, least compression
  • 6 = Balanced (zlib default)
  • 9 = Slowest, most compression
compression:
  level: -1

​
Level Comparison

LevelSpeedCompressionCPU UsageUse Case
-1DefaultDefaultMediumRecommended - Let zlib decide
0InstantNoneMinimalTesting only
1Very FastLowLowHigh throughput priority
3FastGoodLow-MedGood balance
6MediumGoodMediumZlib default
9SlowBestHighBandwidth priority

​
Choosing Compression Level

compression:
  level: -1  # Let zlib choose optimal level
Recommendation: Use level: -1 (default) unless you have specific needs. The zlib library automatically chooses optimal settings.

​
Validation Warnings

Gate validates compression settings on startup:

​
Level Validation

# ❌ Invalid level
compression:
  level: 15
# Error: "Unsupported compression level 15: must be -1..9"

# ⚠️ Warning: No compression
compression:
  level: 0
# Warning: "All packets going through the proxy will be uncompressed, 
#           this increases bandwidth usage."

​
Threshold Validation

# ❌ Invalid threshold
compression:
  threshold: -5
# Error: "Invalid compression threshold -5: must be >= -1"

# ⚠️ Warning: Compress everything
compression:
  threshold: 0
# Warning: "All packets going through the proxy will be compressed, 
#           this lowers bandwidth, but has lower throughput and 
#           increases CPU usage."

​
Configuration Examples

config.yml
config:
  bind: 0.0.0.0:25565
  
  servers:
    lobby: localhost:25566
    survival: localhost:25567
  
  try:
    - lobby
  
  # Vanilla Minecraft compression settings
  compression:
    threshold: 256  # Same as vanilla
    level: -1       # Let zlib decide

​
High-Performance Server

Optimized for low latency and high throughput:
config.yml
config:
  compression:
    threshold: 512  # Compress fewer packets
    level: 1        # Fast compression
  
  # These settings prioritize:
  # - Lower CPU usage
  # - Higher throughput  
  # - Lower latency
  # At the cost of higher bandwidth usage

​
Bandwidth-Constrained Server

Optimized for minimal bandwidth usage:
config.yml
config:
  compression:
    threshold: 64   # Compress more packets
    level: 9        # Maximum compression
  
  # These settings prioritize:
  # - Lower bandwidth usage
  # At the cost of:
  # - Higher CPU usage
  # - Lower throughput
  # - Slightly higher latency

​
LAN Server

No compression needed on fast local network:
config.yml
config:
  bind: 0.0.0.0:25565
  
  compression:
    threshold: -1   # Disable compression
    level: -1
  
  # Appropriate for:
  # - LAN parties
  # - Local network play
  # - Development/testing

​
Large Network

Balanced settings for large server with many players:
config.yml
config:
  compression:
    threshold: 256  # Standard vanilla threshold
    level: 3        # Lower level to save CPU with many players
  
  # Balances:
  # - CPU usage (important with 100+ players)
  # - Bandwidth usage
  # - Throughput

​
Performance Considerations

​
CPU Impact

Every compressed packet requires CPU time:
  • Higher level = More CPU per packet
  • Lower threshold = More packets compressed
  • More players = More total packets
Monitor CPU usage and adjust accordingly.
Compression happens per-player connection:
Total CPU = Players × Packets/sec × Compression Cost
With many players, even small per-packet overhead adds up.
  • Lower threshold + higher level = Less bandwidth, more CPU
  • Higher threshold + lower level = More bandwidth, less CPU
Choose based on your bottleneck (bandwidth or CPU).

​
Bandwidth Impact

Typical compression ratios for Minecraft packets:
  • Chunk data: 3:1 to 5:1 ratio (excellent compression)
  • Entity updates: 1.5:1 to 2:1 ratio (moderate compression)
  • Small packets: Less than 1.5:1 ratio (poor compression, overhead not worth it)
Most bandwidth savings come from compressing large chunk packets.

​
Throughput Impact

Compression/decompression takes time:
  • Level 1: ~0.1ms per packet
  • Level 6: ~0.5ms per packet
  • Level 9: ~2ms per packet
Usually negligible but can add up with high packet rates.

​
Benchmarking

Test different settings to find optimal configuration:

​
Monitor CPU Usage

# Monitor Gate process CPU
top -p $(pgrep gate)

# Or use htop
htop -p $(pgrep gate)

​
Monitor Bandwidth

# Monitor network bandwidth
iftop -i eth0

# Or use nload
nload eth0

# Check data transfer
netstat -i

​
Testing Methodology

1

Baseline test

Start with default settings and measure:
  • CPU usage
  • Bandwidth usage
  • Player experience (lag)
2

Adjust one setting

Change either threshold OR level (not both):
compression:
  threshold: 128  # Test lower threshold
  level: -1       # Keep default level
3

Measure impact

Monitor for at least 30 minutes with typical player load
4

Compare results

Did CPU/bandwidth/experience improve?
5

Iterate

Test other values and compare

​
Best Practices

compression:
  threshold: 256
  level: -1
Only change if you have measurable issues with bandwidth or CPU.
  • CPU constrained: Higher threshold (512-1024), lower level (1-3)
  • Bandwidth constrained: Lower threshold (64-128), higher level (6-9)
  • Balanced: Use defaults
# Small server (1-20 players)
compression:
  threshold: 256
  level: 6  # Can afford higher compression

# Large server (100+ players)  
compression:
  threshold: 256
  level: 1  # Save CPU with more players
Always test compression changes during peak hours with real player load. Synthetic tests don’t reflect real-world usage.
Watch CPU and bandwidth for at least a few hours after changing settings to see the true impact.

​
Troubleshooting

Symptoms: Gate process using excessive CPUSolutions:
  1. Increase threshold: threshold: 512 or threshold: 1024
  2. Lower compression level: level: 1 or level: 3
  3. Check if issue persists with compression disabled: threshold: -1
Verify it’s compression:
# Profile Gate process
perf top -p $(pgrep gate)

# Look for zlib/compression functions
Symptoms: Excessive network trafficSolutions:
  1. Lower threshold: threshold: 128 or threshold: 64
  2. Increase compression level: level: 6 or level: 9
  3. Verify backend servers also use compression
Monitor impact:
# Watch bandwidth before and after
iftop -i eth0
Symptoms: High latency, rubber-bandingCheck if compression related:
# Temporarily disable compression
compression:
  threshold: -1
If lag improves, compression was the issue. Otherwise, problem is elsewhere (backend servers, network, etc.).
Issue: Changed settings but no effectSolutions:
  1. Restart Gate (config reload may not apply compression settings)
  2. Check for validation errors in logs
  3. Verify YAML syntax is correct
# Restart Gate
systemctl restart gate

# Check logs
journalctl -u gate -f

​
Backend Server Compression

Gate’s compression settings only apply to Gate ↔ Client connections. The Gate ↔ Backend compression is controlled by backend server settings.

​
Backend Configuration

In backend server’s server.properties: 
# Vanilla server compression
network-compression-threshold=256
This controls compression between Gate and the backend. Consider:
  • LAN backends: Disable compression (threshold=-1) to save CPU
  • Remote backends: Keep compression enabled to save bandwidth
  • Match Gate settings: Use same threshold for consistency

Overview

Complete configuration overview

Servers

Configure backend servers and timeouts

Forwarding

Player info forwarding configuration

Performance

Performance tuning and optimization

Build docs developers (and LLMs) love

Get started for freeTalk to us