Paper Global Configuration

Paper server-wide configuration options in config/paper-global.yml

Paper’s global configuration file contains server-wide settings that affect all worlds. This file is located at config/paper-global.yml and provides advanced features beyond vanilla Minecraft.

Location

server-root/
└── config/
    └── paper-global.yml

Configuration Reference

Chunk Loading

Basic Chunk Loading

chunk-loading-basic.player-max-chunk-send-rate · double · default: "75.0"

Maximum rate in chunks per second that the server will send to any individual player. Set to -1 to disable.

Lower values reduce bandwidth and CPU usage for players with slow connections.

chunk-loading-basic.player-max-chunk-load-rate · double · default: "100.0"

Maximum rate at which chunks will load for any individual player. This affects chunk generation since a chunk load is issued first to test if a chunk exists. Set to -1 to disable.

chunk-loading-basic.player-max-chunk-generate-rate · double · default: "-1.0"

Maximum rate at which chunks will generate for any individual player. Set to -1 to disable this limit.

Limiting generation can prevent lag spikes when players explore new areas.

Advanced Chunk Loading

chunk-loading-advanced.auto-config-send-distance · boolean · default: "true"

If true, the server will match the chunk send radius that clients have configured in their view distance settings if the client’s setting is less than the server’s send distance.

chunk-loading-advanced.player-max-concurrent-chunk-loads · integer · default: "0"

Maximum amount of concurrent chunk loads per player. Set to 0 to let the server configure it automatically per player, or -1 to disable the limit.

chunk-loading-advanced.player-max-concurrent-chunk-generates · integer · default: "0"

Maximum amount of concurrent chunk generations per player. Set to 0 for automatic configuration, or -1 to disable.

Messages

Kick Messages & Permissions

messages.kick.authentication-servers-down · Component · default: "multiplayer.disconnect.authservers_down"

Message shown when authentication servers are unavailable.

messages.kick.connection-throttle · Component

Message shown when a player is connecting too frequently.

messages.kick.flying-player · Component · default: "multiplayer.disconnect.flying"

Message shown when a player is kicked for flying without permission.

messages.no-permission · Component

Default message shown when a player lacks permission for a command.

messages.use-display-name-in-quit-message · boolean · default: "false"

Use player display names instead of usernames in quit messages.

Proxies

BungeeCord

proxies.bungee-cord.online-mode · boolean · default: "true"

Whether BungeeCord proxy handles authentication.

Ensure your server is properly firewalled when using BungeeCord mode!

Velocity

proxies.velocity.enabled · boolean · default: "false"

Enable Velocity modern forwarding support.

proxies.velocity.online-mode · boolean · default: "true"

Whether Velocity proxy handles authentication.

proxies.velocity.secret · string · default: ""

The secret key from your Velocity configuration. Can also be set via the PAPER_VELOCITY_SECRET environment variable.

This secret must match your Velocity proxy configuration exactly!

Proxy Protocol

proxies.proxy-protocol · boolean · default: "false"

Enable HAProxy PROXY protocol support.

Performance

Chunk System

chunk-system.io-threads · integer · default: "-1"

Number of I/O threads for chunk operations. -1 uses the default calculated value.

Let Paper auto-configure this unless you have specific performance requirements.

chunk-system.worker-threads · integer · default: "-1"

Number of worker threads for chunk processing. -1 uses the default calculated value.

Player Auto Save

player-auto-save.rate · integer · default: "-1"

How often (in ticks) player data should be saved. -1 uses Minecraft’s default (6000 ticks/5 minutes).

player-auto-save.max-per-tick · integer · default: "-1"

Maximum number of players to save per tick. Automatically calculated if set to -1.

Console

Console Settings

console.enable-brigadier-highlighting · boolean · default: "true"

Enable syntax highlighting in the console for commands.

console.enable-brigadier-completions · boolean · default: "true"

Enable tab completions in the console using Brigadier.

console.has-all-permissions · boolean · default: "false"

Whether the console should have all permissions by default.

Spam Limiter

Packet Rate Limiting

spam-limiter.tab-spam-increment · integer · default: "1"

Amount to increment spam counter for tab completion requests.

spam-limiter.tab-spam-limit · integer · default: "500"

Maximum tab completion spam counter before action is taken.

spam-limiter.recipe-spam-increment · integer · default: "1"

Amount to increment spam counter for recipe requests.

spam-limiter.recipe-spam-limit · integer · default: "20"

Maximum recipe spam counter before action is taken.

spam-limiter.incoming-packet-threshold · integer · default: "300"

Maximum incoming packet rate before throttling. Set to -1 to disable.

Commands

Command Settings

commands.suggest-player-names-when-null-tab-completions · boolean · default: "true"

Suggest online player names when a command has no tab completions.

commands.time-command-affects-all-worlds · boolean · default: "false"

Whether the /time command changes time in all worlds or just the executor’s world.

commands.ride-command-allow-player-as-vehicle · boolean · default: "false"

Allow mounting entities to a player in the vanilla /ride command.

Item Validation

Item Text Limits

item-validation.display-name · integer · default: "8192"

Maximum character length for item display names.

item-validation.lore-line · integer · default: "8192"

Maximum character length for each line of item lore.

item-validation.book.title · integer · default: "8192"

Maximum character length for book titles.

item-validation.book.author · integer · default: "8192"

Maximum character length for book authors.

item-validation.book.page · integer · default: "16384"

Maximum character length for book pages.

Book Limits

item-validation.book-size.page-max · integer · default: "2560"

Maximum number of pages in a book. Set to -1 to disable.

item-validation.book-size.total-multiplier · double · default: "0.98"

Multiplier for total book size validation.

item-validation.resolve-selectors-in-books · boolean · default: "false"

Whether to resolve entity selectors in book text.

Enabling this can have security implications!

Watchdog

Watchdog Settings

watchdog.early-warning-every · integer · default: "5000"

Interval in milliseconds between watchdog early warnings.

watchdog.early-warning-delay · integer · default: "10000"

Delay in milliseconds before the watchdog starts issuing warnings.

Miscellaneous

Spark Profiler

spark.enabled · boolean · default: "true"

Enable the built-in Spark profiler.

spark.enable-immediately · boolean · default: "false"

Enable Spark immediately on server startup.

Collisions

collisions.enable-player-collisions · boolean · default: "true"

Enable player-to-player collisions.

collisions.send-full-pos-for-hard-colliding-entities · boolean · default: "true"

Send full position updates for entities with hard collisions.

Scoreboards

scoreboards.track-plugin-scoreboards · boolean · default: "false"

Track scoreboards created by plugins in /paper dumpplugins.

scoreboards.save-empty-scoreboard-teams · boolean · default: "true"

Save scoreboard teams even when they have no members.

Logging

logging.deobfuscate-stacktraces · boolean · default: "true"

Deobfuscate stacktraces to readable Mojang mappings.

This makes error messages much easier to understand!

Miscellaneous Options

misc.region-file-cache-size · integer · default: "256"

Number of region files to keep cached. Minimum value is 4.

misc.use-alternative-luck-formula · boolean · default: "false"

Use an alternative luck formula. See https://luckformula.emc.gs for details.

misc.load-permissions-yml-before-plugins · boolean · default: "true"

Load permissions.yml before plugins are enabled.

misc.enable-nether · boolean · default: "true"

Whether the nether dimension is enabled and will be loaded.

Block Updates

Block Update Optimization

block-updates.disable-noteblock-updates · boolean · default: "false"

Disable note block updates for redstone contraptions.

block-updates.disable-tripwire-updates · boolean · default: "false"

Disable tripwire updates.

block-updates.disable-chorus-plant-updates · boolean · default: "false"

Disable chorus plant updates.

block-updates.disable-mushroom-block-updates · boolean · default: "false"

Disable mushroom block updates.

Example Configuration

chunk-loading-basic:
  player-max-chunk-send-rate: 75.0
  player-max-chunk-load-rate: 100.0
  player-max-chunk-generate-rate: -1.0

proxies:
  velocity:
    enabled: true
    online-mode: true
    secret: "your-secret-here"

chunk-system:
  io-threads: -1
  worker-threads: -1

console:
  enable-brigadier-highlighting: true
  enable-brigadier-completions: true

spark:
  enabled: true

logging:
  deobfuscate-stacktraces: true

Related Configuration

World Configuration

Per-world specific settings

Performance Tuning

Optimize your server performance

Changes to paper-global.yml require a server restart or use the /paper reload command. Some settings may require a full restart.