Paper.yml Configuration Guide: View-Distance, Simulation-Distance & TPS

# Paper.yml Configuration Guide: View-Distance, Simulation-Distance & TPS

Paper.yml is the primary configuration file for Paper servers, controlling chunk loading, entity processing, and performance optimizations. This guide explains critical settings: view-distance controls how many chunks are sent to players (default 10), simulation-distance controls which chunks are actively processed (default 10), and async-chunks offloads chunk generation to background threads. Proper tuning maintains 20 TPS while supporting more players.

Understanding Paper.yml Structure

Paper.yml is located in your server root directory. It contains world-specific and global settings that override Bukkit/Spigot defaults with aggressive performance optimizations.

Configuration Hierarchy:

• Global settings (apply to all worlds)
• Per-world settings (override global for specific worlds)
• Default world (template for new worlds)

Critical Settings Categories:

• Chunk loading and generation
• Entity activation and AI processing
• Network packet optimization
• Redstone and hopper mechanics
• Anti-cheat and exploit prevention

Critical Performance Settings

View-Distance vs Simulation-Distance

These two settings are commonly confused but serve different purposes.

View-Distance:

world-settings:
  default:
    view-distance: 8  # How many chunks to send to players

Controls how many chunks the server sends to each player's client. Default is 10 chunks (160 blocks).

Simulation-Distance:

world-settings:
  default:
    simulation-distance: 6  # How many chunks are actively ticking

Controls how many chunks around each player are actively processed (mob AI, crops growing, redstone).

The Difference:

• View-Distance 10, Simulation-Distance 6: Player sees 160 blocks but only chunks within 96 blocks are "active"
• Mobs beyond simulation-distance are frozen
• Crops/farms beyond simulation-distance don't grow
• Redstone beyond simulation-distance doesn't tick

Recommended Values:

• Vanilla Survival: view-distance: 8, simulation-distance: 6
• Modded/Skyblock: view-distance: 6, simulation-distance: 4
• Minigames: view-distance: 5, simulation-distance: 3

Lower simulation-distance saves TPS. Lower view-distance reduces network bandwidth.

Chunk Loading Configuration

chunk-loading:
  # Offload chunk generation to background threads
  async-chunks: true

  # Minimum chunks loaded around player before sending them to world
  min-load-radius: 2

  # Maximum chunks sent per tick (prevents network saturation)
  max-concurrent-sends: 2

  # Prevent chunk loading from player movement spam
  player-max-chunk-load-rate: 100.0

async-chunks: true is critical. It prevents chunk generation from blocking the main thread, eliminating worldgen lag.

player-max-chunk-load-rate: Limits how fast players can force chunk loads by flying/sprinting. Default 100 chunks/second. Lower to 50 if players cause lag by flying too fast.

Entity Activation Ranges

Controls how far entities must be from players before their AI stops processing.

entity-activation-range:
  animals: 32    # Cows, pigs, chickens
  monsters: 32   # Zombies, skeletons, creepers
  raiders: 48    # Pillagers, vindicators (need larger range for raids)
  misc: 16       # Armor stands, minecarts
  water: 16      # Fish, dolphins
  villagers: 32  # Villagers (trading, breeding)
  flying-monsters: 32  # Phantoms, ghasts

How It Works:

• Entity beyond its activation range "sleeps" (no AI, pathfinding, or collision)
• Entity wakes when player gets within range
• Reduces entity processing overhead by ~60% on populated servers

Tuning Guidelines:

• Mob Farms: Increase monsters: 48 if mob farms are far from AFK spots
• Lag Reduction: Decrease all to 24 if entity processing is bottleneck (/spark profiler will show)
• Villagers: Never set below 32 - trading and iron farms break

Anti-Lag Optimizations

# Prevent tick loops from crashing server
max-tick-time:
  tile: 50  # Milliseconds for block entities (chests, furnaces)
  entity: 50  # Milliseconds for entity processing

# Disable watchdog timeout (prevents crash during heavy worldgen)
watchdog:
  early-warning-every: 5000
  early-warning-delay: 10000

max-tick-time: If a single chunk's entities/blocks exceed this time, server skips processing them that tick. Prevents lag cascades.

watchdog: -1 (disable entirely): Use this for modded servers or heavy worldgen. The watchdog will crash your server thinking it's frozen when it's actually just generating chunks.

Hopper Optimization

Hoppers are notorious lag sources. Paper includes aggressive optimizations:

hopper:
  # Disable hoppers moving items into full containers
  disable-move-event: false

  # Don't check for items if no items exist above hopper
  ignore-occluding-blocks: false

Best Practice: Use disable-move-event: true if you have 100+ hoppers. This disables some plugin inventory events but drastically reduces hopper lag.

Redstone Configuration

# Prevent infinite redstone loops from lagging server
redstone-implementation: vanilla  # or 'alternate' for paper's faster impl

# Limit update depth (prevents crash from redstone contraptions)
max-auto-save-chunks-per-tick: 24

redstone-implementation: alternate uses Paper's optimized redstone engine (15% faster) but may break extremely complex contraptions. Test before switching on production servers.

World-Specific Overrides

Apply different settings to different worlds:

world-settings:
  # Default settings for all worlds
  default:
    view-distance: 8
    simulation-distance: 6

  # Override for specific world
  world_nether:
    view-distance: 6  # Nether is smaller, reduce view distance
    simulation-distance: 4

  world_the_end:
    view-distance: 10  # End islands need higher view distance
    simulation-distance: 8

Common Overrides:

• Nether: Lower view-distance (players don't need to see far through netherrack)
• End: Higher view-distance (islands separated by void, players need to see farther)
• Minigame Arenas: Minimal simulation-distance (no mobs, no farms)

The MANAfuel Difference

The manual configuration above requires understanding Minecraft server internals, profiling TPS bottlenecks, and iterative testing. On MANAfuel, Bob AI analyzes your server's actual load patterns.

You: "Bob, optimize my paper.yml. The server lags when 15+ players are online."

Bob: "Analyzing server load. TPS drops occur when chunk loading exceeds 80ms per tick. I've set view-distance to 7, simulation-distance to 5, and enabled async-chunks. I also reduced entity activation ranges for animals to 24 (you have 1,200 passive mobs loaded). Server now maintains 20 TPS with 20 players online."

Bob monitors your server's actual bottlenecks using profiling data, not generic recommendations. He adjusts settings dynamically based on player count, loaded chunks, and entity density.

Claim Your Founder Spot →

Frequently Asked Questions

# Install Spark plugin
# Run profiler during peak player activity
/spark profiler start

# Let it run for 5 minutes
/spark profiler stop

# View results
/spark profiler info