Features

Features

Each feature has its switch in paperstream.yml, see Configuration.

Chunk loading

Directional loading. Chunks in front of a player load and get sent before the ones behind. The player's view and movement direction decide the order (bias), chunks very close by always come first (inner-radius). Flying with an elytra, the world appears where you are heading.

Generation boost. A player who moves fast may have more chunks generating at once (generation-boost, 2 times by default). Only while the world is not lagging.

Lag generation factor. While a world lags, players may generate only half as many chunks at once (lag-generation-factor). The main thread then has less to finish per tick.

Worker priority (Linux). The chunk worker threads run a few nice steps below the main thread (worker-priority.nice). On a server with 2 to 4 cores, generation then uses only the CPU time the main thread leaves over. On a server with free cores nothing changes.

More chunk workers. With worker-threads: -1 in paper-global.yml, PaperStream uses all cores but two for chunk work (Paper uses a quarter). The performance profile uses about half of that.

LZ4 region files. New chunks are written with LZ4 instead of zlib, which is much cheaper to read back. Old chunks stay readable, Paper and vanilla read LZ4 too.

Unload delay and rate. Chunks a player left stay loaded for 30 seconds (Paper: 10), so turning around does not read them from disk again. How many chunks get unloaded per tick can be set too.

Fresh chunks. In a chunk that was just loaded and has no player within 2 chunks, block entities, leaf updates and mob spawning wait a few seconds. Mobs loaded from the world file follow the activation range at once, in Paper they tick fully for their first 10 seconds after every load.

Off by default: chunk send budget (send-budget-ms), prefetch ahead of fast players, fast travel (smaller simulation distance while flying fast). They change how the game feels, so you decide.

Entities

Idle mob throttling. Idle mobs further than 32 blocks from every player tick every 2nd tick, further than 56 blocks every 4th. Never throttled: mobs that fight, are ridden, leashed, hurt or falling, and villagers in danger or at night.

Villager brain. A villager that has not moved for 10 seconds runs its AI every 20 ticks. Never throttled: trading, sleeping or hurt villagers, villagers at night, villagers that see a hostile mob or panic, villagers next to a player, and villagers that recently saw an iron golem (iron farms keep working).

Pathfinding budget. At most 80 new paths per world and tick. A mob that hits the limit tries again a moment later. Chasing mobs get twice the budget.

Item piles. More than 64 dropped items in one block tick only once per second. Nothing is removed: picking up, hoppers and despawning keep working. Death drops (at most 41 stacks) never reach the limit.

Stack guard. No more than 8 armor stands, minecarts or boats of one kind in one block, 96 per chunk. Only placing is refused, the player keeps the item. Plugins, /summon and marker armor stands are never limited.

World

Redstone clock guard. A chunk with more than 400 redstone updates per second for 10 seconds in a row is slowed down to 40 updates per second for 60 seconds. Nothing is broken. Ops with paperstream.notify.redstone get a message with the coordinates. Farm clocks and piston doors never reach the limit.

Explosion limit. At most 32 explosions per chunk and tick, the rest is dropped.

Lag protection. A world that averages more than 45 ms per tick gets half the pathfinding budget and spawns mobs only every 2nd tick, for that world only.

Idle mode. With nobody online, worlds tick once per second after 60 seconds. Plugins keep running normally.

Per world MSPT. /paperstream mspt shows how long each world takes per tick.

Measured

Local test servers with bots.

Test	Result
1,000 unmergeable items in one block, player next to it	5.1 / 4.2 ms per tick without item piles, 2.0 / 2.0 ms with it. A hopper below still collects.
128 observer clocks in one chunk, about 1,700 updates per second	slowed down after 10 seconds, a single farm clock next to it keeps running
14 minecarts on one rail, 14 armor stands from a dispenser	8 of each are placed, /summon still works
2 cores, 2 players flying through new terrain, worker priority 0 vs 10	10.8 ms vs 7.4 ms main thread per tick, chunks arrive about a quarter slower