PaperDocs Documentation Release 1.17.1
PaperMC Team
Sep 23, 2021
CONTENTS
1 Introduction 3 1.1 Running A Paper Server...... 3 1.1.1 Running A Paper Server...... 3 1.1.2 Updating to Java 16...... 35 1.2 Running A Waterfall Proxy...... 48 1.2.1 Running A Waterfall Proxy...... 48 1.3 Contributing to Paper...... 51 1.3.1 Contributing...... 51 1.4 About Paper...... 51 1.4.1 About the PaperMC Project...... 51 1.4.2 The PaperMC Site...... 57
2 Useful Links 61
3 Acknowledgements 63
i ii PaperDocs Documentation, Release 1.17.1
Warning: This documentation is a work in progress. Some things are still missing. If you’d like to see it completed faster, you can contribute to the documentation here.
CONTENTS 1 PaperDocs Documentation, Release 1.17.1
2 CONTENTS CHAPTER ONE
INTRODUCTION
Welcome to PaperDocs, the official documentation source for the PaperMC project. Paper is a high performance fork of the Spigot Minecraft Server that aims to fix gameplay and mechanics inconsistencies as well as to improve performance. Paper contains numerous features, bug fixes, exploit preventions and major performance improvements not found in Spigot. Not sure what you’re looking for? Try our About the PaperMC Project section, which contains a short Introduction, our Frequently Asked Questions and an article about The Structure of PaperMC. Server owners should read our tips and instructions in Running A Paper Server on how to install, run and maintain a Paper based server. The PaperMC project has several main components. Learn more about the project structure here.
1.1 Running A Paper Server
Running a Paper server is easy. This section will cover common tasks such as configuring it, maintaining plugins, and general best practices.
1.1.1 Running A Paper Server
Running a Paper server is easy. Click the links below for more information.
Contents
Getting Started
• Requirements • Migrating From Vanilla • Migrating From CraftBukkit/Spigot • Getting A Server Jar • Running The Server
3 PaperDocs Documentation, Release 1.17.1
• Updating The Server
Requirements
Warning: With the release of Minecraft 1.17, Paper now requires Java 16 to run. If you don’t already have Java 16, it’s easy to download and install.
Paper Release Recommended Java Version Paper 1.8 to 1.11 Java 8 Paper 1.12 to 1.16.4 Java 11 Paper 1.16.5 and newer Java 16
Migrating From Vanilla
Migrating from Vanilla is easy, but there are some differences, namely in world saves. Paper (and CraftBukkit and Spigot) separate out each dimension of a world (nether, the end, etc) into separate world folders. Paper will handle this conversion for you automatically.
Migrating From CraftBukkit/Spigot
Paper is a drop in replacement for both CraftBukkit and Spigot, you don’t need to make any changes.
Getting A Server Jar
Paper provides runnable server jars directly from our website’s downloads page. Click on the build number to download a file.
Running The Server
To run the server, simply start it up like any other Java application. Open your terminal, navigate to the saved location, and then run java -Xms2G -Xmx2G -jar paper-###.jar --nogui
The amount of RAM can be set by changing the numbers in the -Xms and -Xmx arguments. --nogui disables Vanilla’s GUI so you don’t get double interfaces when using the command line.
For more advanced Java tuning, see Aikar’s tuning page. To configure your server, see the Configuration page.
4 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
Updating The Server
To update the server, first stop it safely by executing the stop command and then replace the old paperclip jar with a new one. That’s it.
Configuration
This page details the various configuration settings exposed by Paper.
• Global Settings • World Settings
If you want information on settings in spigot.yml and bukkit.yml you should see their respective documentation pages. • Bukkit Configuration (bukkit.yml) • Spigot Configuration (spigot.yml)
Warning: Configuration values change frequently at times. It is possible for the information here to be incomplete. If you cannot find what you’re looking for or think something may bewrong, Contact Us Last updated Sep 3rd, 2021 for MC 1.17.1, Paper build #249
Global Settings
Global settings affect all worlds on the server as well as the core server functionality itself. use-display-name-in-quit-message
• default: false • description: Sets whether the server should use the player’s display name in quit messages. verbose
• default: false • description: Sets whether the server should dump all configuration values to the server log on startup.
1.1. Running A Paper Server 5 PaperDocs Documentation, Release 1.17.1 load-permissions-yml-before-plugins
• default: true • description: Loads bukkit’s permission.yml file before plugins, allowing them to check permissions immediately on enable. bungee-online-mode
• default: true • description: Instructs the server how to handle player UUIDs and data when behind bungee. Set to match your proxy’s online-mode setting. console-has-all-permissions
• default: false • description: Sets whether or not console command senders have all permissions region-file-cache-size
• default: 256 • description: Sets the maximum size of the region file cache. incoming-packet-spam-threshold
• default: 300 • description: Sets the threshold at which the server will consider incoming packets as spam and ignore them. max-joins-per-tick
• default: 3 • description: Sets the maximum amount of players that may join the server in a single tick. If more players join, they will be postponed until later ticks to join. track-plugin-scoreboards
• default: false • description: Whether the server should track plugin scoreboards with only dummy objectives. This is a break- ing change; however, it provides a much more sensible default value. Enabling this with plugins using many scoreboards will incur a performance degradation.
6 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 suggest-player-names-when-null-tab-completions
• default: true • description: Instructs the server to return a list of players when tab-completing if the plugin has no tab comple- tions of its own. use-alternative-luck-formula
• default: false • description: Use alternative luck formula by Aikar, allowing luck to be applied to items that have no quality defined. Makes major changes to fishing formulas. chunk-tasks-per-tick
• default: 1000 • description: How many chunk tasks may be done in the middle of ticks for all worlds. This is helpful to rendering and chunk generation. enable-player-collisions
• default: true • description: Sets whether the server should allow players to collide with one another. • warning: This setting can be broken by plugins interacting with the scoreboard, double check plugins when troubleshooting this value. player-auto-save-rate
• default: -1 • description: Set how often players should be saved. A value of -1 means it will pick a recommended value for you. max-player-auto-save-per-tick
• default: -1 • description: How many players should be saved at most in a single tick. A value of -1 means it will pick a recommended value for you.
1.1. Running A Paper Server 7 PaperDocs Documentation, Release 1.17.1 save-empty-scoreboard-teams
• default: false • description: Some scoreboard plugins leave hundreds of empty scoreboard teams around, dramatically slowing down login times. This sets whether the server should remove those empty teams automatically. lag-compensate-block-breaking
• default: true • description: Whether the server should use time or TPS to determine block break duration. The client assumes the server is always running at 20 TPS, causing disagreement when a block is broken during server lag. This setting prevents this desync. send-full-pos-for-hard-colliding-entities
• default: true • description: Collisions with boats and minecarts are often subject to client/server disagreement, which may cause glitchy behaviour for players. This setting attempts to mitigate this desync by sending precise locations for entities involved in collisions. Having this enabled will use more bandwidth, however in the majority of cases, this is a worthy tradeoff. velocity-support
• enabled – default: false – description: Set this to true if this server is behind a Velocity proxy. If this is true, do not enable the bungeecord setting in spigot.yml. • online-mode – default: true – description: Instructs the server how to handle player UUIDs and data when behind velocity. Set to match your proxy’s online-mode setting. • secret – default: ‘’ (empty string) – description: The secret string that is shared by your Velocity proxy and this server. This needs to match your proxy’s forwarding-secret setting.
8 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 unsupported-settings
• allow-perm-block-break-exploits – default: false – description: Sets whether unbreakable blocks can be broken with vanilla exploits. This includes bedrock, end portal frames, end portal blocks, and more. • allow-piston-duplication – default: false – description: If set to true, will allow duplication of TNT, carpets and rails. Introduced in 1.15.2, build #358. • allow-headless-pistons – default: false – description: If set to true, pistons may in some cases become headless. This is often used to break permanent blocks. watchdog
• early-warning-every – default: 5000 – description: The interval in milliseconds between printed thread dumps while the server is hanging. • early-warning-delay – default: 10000 – description: The number of milliseconds before the watchdog thread starts printing thread dumps after the server starts hanging. spam-limiter
• tab-spam-increment – default: 1 – description: The number that the internal tab spam counter increases by when a player presses tab in the chat window. • tab-spam-limit – default: 500 – description: The number that the internal tab spam counter can reach until the server kicks the player for spam. • recipe-spam-increment – default: 1 – description: The number that the recipe spam counter increases by when a player presses a recipe. • recipe-spam-limit – default: 20
1.1. Running A Paper Server 9 PaperDocs Documentation, Release 1.17.1
– description: The number that the recipe spam counter can reach until the server kicks the player for spam. book-size
• page-max – default: 2560 – description: The max number of bytes a single page in a book can contribute to the allowed byte total for a book. • total-multiplier – default: 0.98 – description: Each page has this multiple of bytes from the last page as it’s contribution to the allowed byte total for a book (with the first page being having a multiplier of 1.0). async-chunks
• threads – default: -1 – description: The number of threads the server should use for world saving and loading. This is set to (number of processors - 1) by default. messages
• no-permission – default: ‘&cI”m sorry, but you do not have permission to perform this command. Please contact the server administrators if you believe that this is in error.’ – description: The message the server sends to requesters with insufficient permissions. • kick – authentication-servers-down ∗ default: ‘’ (empty string) ∗ note: The default value instructs the server to send the vanilla translatable kick message. ∗ description: Message to kick a player with when they are disconnected because the Mojang authentication servers are down. – connection-throttle ∗ default: Connection throttled! Please wait before reconnecting. ∗ description: Message to use when kicking a player when their connection is throttled. – flying-player ∗ default: Flying is not enabled on this server ∗ description: Message to use when kicking a player for flying. – flying-vehicle
10 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
∗ default: Flying is not enabled on this server ∗ description: Message to use when kicking a player’s vehicle for flying. timings
• enabled – default: true – description: Controls the global enable state of the Timings platform. • verbose – default: true – description: Instructs Timings to provide more specific information in its reports. For example, spe- cific entity types causing lag rather than just “entities”. • url – default: https://timings.aikar.co/ – description: Specifies the URL of the Timings Viewer server where Timings reports should be up- loaded to. • server-name-privacy – default: false – description: Instructs Timings to hide server name information in reports. • hidden-config-entries – default: { database, settings.bungeecord-addresses, settings.velocity-support.secret } – description: Configuration entries to hide in Timings reports. • history-interval – default: 300 – description: The interval in seconds between individual points in the Timings report. • history-length – default: 3600 – description: The total amount of data to keep for a single report. – warning: This value is validated server side, massive reports will be rejected by the report site. • server-name – default: Unknown Server – description: Instructs timings on what to put in for the server name.
1.1. Running A Paper Server 11 PaperDocs Documentation, Release 1.17.1
console
• enable-brigadier-highlighting – default: true – description: Enables Mojang’s Brigadier highlighting in the server console. • enable-brigadier-completions – default: true – description: Enables Mojang’s Brigadier command completions in the server console. item-validation
• display-name – default: 8192 – description: Overrides Spigot’s limit on item display name length. • loc-name – default: 8192 – description: Overrides Spigot’s limit on translatable item name length. • lore-title – default: 8192 – description: Overrides Spigot’s limit on lore title length. • book – title ∗ default: 8192 ∗ description: Overrides Spigot’s limit on book title length. – author ∗ default: 8192 ∗ description: Overrides Spigot’s limit on book author length. – page ∗ default: 16384 ∗ description: Overrides Spigot’s limit on individual book page length.
12 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 chunk-loading
• min-load-radius – default: 2 – description: The radius of chunks around a player that are not throttled for chunk loading. Effectively, this radius will be unaffected by the chunk-loading.max-concurrent-sends setting. The number of chunks affected is actually the configured value plus one, as this config controls the chunks theclient will actually be able to render. A value of -1 will disable this feature. • max-concurrent-sends – default: 2 – description: The maximum number of chunks that will be queued to send at any one time. Lower values will help alleviate server-side networking bottlenecks such as anti-xray or compression, however is unlikely to help users with a poor internet connection. A value of -1 will not disable this limit. Use a large number instead. • autoconfig-send-distance – default: true – description: Whether to use the client’s view distance for the chunk send distance of the server. This will exclusively change the radius of chunks sent to the client, and will have no effect on ticking or non-ticking view distance. Assuming no plugin has explicitly set the send distance and the client’s view distance is less than the server’s send distance, the client’s view distance will be used. • target-player-chunk-send-rate – default: 100.0 – description: The maximum number of chunks ever sent to an invidual player within one second. A value of -1 will disable this limit. • global-max-chunk-send-rate – default: -1 – description: The maximum number of chunks sent per second for the entire server. This may help with server-side peak bandwidth usage. A value of -1 will disable this limit. • enable-frustum-priority – default: false – description: Whether to attempt to load chunks in front of the player before loading chunks to their sides or behind. Due to the client reacting poorly to receiving chunks out of order, this is disabled by default. • global-max-chunk-load-rate – default: 300.0 – description: The maximum number of chunks loaded per second for the whole server. A value of -1 will not disable this. Use a large number instead. • player-max-concurrent-loads – default: 4.0 – description: The maximum number of chunk loads processed per player at one time. A value of -1 will not disable this. Use a large number instead. • global-max-concurrent-loads
1.1. Running A Paper Server 13 PaperDocs Documentation, Release 1.17.1
– default: 500.0 – description: The maximum number of chunk loads processed for the whole server one time. This will override player-max-concurrent-loads if exceeded. A value of -1 will disable this limit. packet-limiter
• kick-message – default: &cSent too many packets – description: The message players are kicked with for sending too many pakcets. • limits – all ∗ description: This section applies for all incoming packets. You may not define an action in this section, it will always kick the player if the limit is violated. ∗ interval · default: 7.0 · description: The interval, in seconds, for which max-packet-rate should apply. ∗ max-packet-rate · default: 500.0 · description: The number of any packet allowed per player within the interval. – PacketPlayInAutoRecipe: ∗ description: This section applies specific limits for each packet, based on the packets name as shown in timings, or it’s class name for more advanced users. PacketPlayInAutoRecipe is used by default because this packet is very expensive to process, and may allow malicious actors to crash your server if unmitigated. ∗ interval · default: 4.0 · description: The interval, in seconds, for which max-packet-rate should apply for this packet. ∗ max-packet-rate · default: 5.0 · description: The number of packets allowed within the interval before action is exe- cuted. ∗ action · default: DROP · description: The action to take once the limit has been violated. Possible values are DROP which will ignore packets over the limit, and KICK which will kick players for exceeding the limit.
14 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
World Settings
World settings are configured on a per-world basis. The child-node default is used for all worlds that do not have their own specific settings. disable-teleportation-suffocation-check
• default: false • description: Disables the suffocation check the server performs before teleporting a player. • note: While useful to keep your players out of walls, leaving this feature on may allow players to teleport through solid materials by logging out in specific locations. max-auto-save-chunks-per-tick
• default: 24 • description: The maximum number of chunks the auto-save system will save in a single tick. per-player-mob-spawns
• default: true • description: Determines whether the mob limit (in bukkit.yml) is counted per-player or for the entire server. Enabling this setting results in roughly the same number of mobs, but with a more even distribution that prevents one player from using the entire mob cap and provides a more single-player like experience. baby-zombie-movement-modifier
• default: 0.5 • description: Modifies the speed that baby zombies move at, where 0.5 is 50% faster than the mob basespeed, and -0.4 would be 40% slower. optimize-explosions
• default: false • description: Instructs the server to cache entity lookups during an explosion, rather than recalculating throughout the process. This speeds up explosions significantly.
1.1. Running A Paper Server 15 PaperDocs Documentation, Release 1.17.1 fixed-chunk-inhabited-time
• default: -1 • description: If 0 or greater, set the chunk inhabited time to a fixed number. • note: The timer is increased when chunks are kept loaded because of player activity. use-vanilla-world-scoreboard-name-coloring
• default: false • description: Instructs the server to use the vanilla scoreboard for player nickname coloring. • note: Useful when playing on adventure maps made for the vanilla server and client. remove-corrupt-tile-entities
• default: false • description: Instructs the server to automatically remove tile entities it detects as broken and cannot fix. experience-merge-max-value
• default: -1 • description: Instructs the server put a maximum value on experience orbs, preventing them all from merging down into 1 single orb. • note: The default value instructs the server to use no max value, allowing them to merge down into a single orb. This is especially noticeable when defeating boss monsters. prevent-moving-into-unloaded-chunks
• default: false • description: Sets whether the server will prevent players from moving into unloaded chunks or not. count-all-mobs-for-spawning
• default: false • description: Determines whether spawner mobs and other misc mobs are counted towards the global mob limit.
16 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
delay-chunk-unloads-by
• default: 10s • description: Delays chunk unloads by the specified time
falling-block-height-nerf
• default: 0 • note: Values less than 1 will disable this feature. • description: The height at which falling blocks will be removed from the server. tnt-entity-height-nerf
• default: 0 • note: Values less than 1 will disable this feature. • description: The height at which Primed TNT entities will be removed from the server. filter-nbt-data-from-spawn-eggs-and-related
• default: true • description: Instructs the server to remove certain NBT data from spawn-eggs, falling-blocks, and other often abused items in creative mode. • note: Some adventure maps may require this be turned off to function correctly, but we do not recommend turning it off on a public server. max-entity-collisions
• default: 8 • description: Instructs the server to stop processing collisions after this value is reached. disable-creeper-lingering-effect
• default: false • description: Disables creepers randomly leaving behind a lingering area effect cloud.
1.1. Running A Paper Server 17 PaperDocs Documentation, Release 1.17.1
duplicate-uuid-resolver
• default: saferegen • description: Specifies the method the server uses to resolve entities with duplicate UUIDs. This can beoneof the following values: – saferegen: Regenerate a UUID for the entity, or delete it if they are close. – delete: Delete the entity. – silent: Does nothing, not printing logs. – warn: Does nothing, printing logs. duplicate-uuid-saferegen-delete-range
• default: 32 • description: If multiple entities with duplicate UUIDs are within this many blocks, saferegen will delete all but 1 of them.
phantoms-do-not-spawn-on-creative-players
• default: true • description: Disables spawning of phantoms on players in creative mode phantoms-only-attack-insomniacs
• default: true • description: Prevents phantoms from attacking players who have slept water-over-lava-flow-speed
• default: 5 • description: Sets the speed at which water flows while over lava. grass-spread-tick-rate
• default: 1 • description: Sets the delay, in ticks, at which the server attempts to spread grass. Higher values will result in slower spread.
18 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 use-faster-eigencraft-redstone
• default: false • description: Instructs the server to use a faster redstone implementation, which may drastically help with per- formance in redstone. nether-ceiling-void-damage-height
• default: 0 • description: Sets the level above which players in the nether will take void damage. This is a vanilla-friendly way to restrict players using the nether ceiling as buildable area. Setting to 0 disables this feature. keep-spawn-loaded
• default: true • description: Instructs the server to keep the spawn chunks loaded at all times. armor-stands-do-collision-entity-lookups
• default: true • description: Instructs armor stand entities to do entity collision checks. parrots-are-unaffected-by-player-movement
• default: false • description: Makes parrots “sticky” so they do not fall off a player’s shoulder when they move. Use crouch to shake them off. only-players-collide
• default: false • description: Only calculate collisions if a player is one of the two entities colliding. allow-vehicle-collisions
• default: false • description: Whether vehicles should also be able to collide while only-players-collide is enabled.
1.1. Running A Paper Server 19 PaperDocs Documentation, Release 1.17.1 allow-non-player-entities-on-scoreboards
• default: false • description: Instructs the server to treat non-player entities as if they are never on a scoreboard. • note: Enabling this value may increase the amount of time the server spends calculating entity collisions. portal-search-radius
• default: 128 • description: The maximum range the server will use to look for an existing nether portal. If it can’t find one in that range, it will generate a new one. portal-create-radius
• default: 16 • description: The maximum range the server will try to create a portal around when generating a new portal portal-search-vanilla-dimension-scaling
• default: true • description: Whether to apply vanilla dimension scaling to portal-search-radius. disable-thunder
• default: false • description: Disables thunderstorms. skeleton-horse-thunder-spawn-chance
• default: 0.01 • description: Sets the chance that a “Skeleton Trap” (4 skeleton horsemen) will spawn in a thunderstorm. disable-ice-and-snow
• default: false • description: Disables ice and snow formation.
20 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
disable-explosion-knockback
• default: false • description: Instructs the server to completely block any knockback that occurs as a result of an explosion.
keep-spawn-loaded-range
• default: 10 • description: The range in chunks around spawn to keep loaded.
container-update-tick-rate
• default: 1 • description: The rate, in ticks, at which the server updates containers and inventories.
map-item-frame-cursor-update-interval
• default: 10 • description: The interval in ticks at which cursors on maps in item frames are updated. Setting this to a number less than 1 will disable updates altogether.
fix-items-merging-through-walls
• default: false • description: Whether items should be prevented from merging through walls. Enabling this will incur a per- formance degradation.This is only necessary when merge-radius.item (spigot.yml) is large enough to merge items through walls.
prevent-tnt-from-moving-in-water
• default: false • description: Instructs the server to keep Primed TNT entities from moving in flowing water. show-sign-click-command-failure-msgs-to-player
• default: false • description: Whether commands executed by sign click should show failure messages to players.
1.1. Running A Paper Server 21 PaperDocs Documentation, Release 1.17.1 spawner-nerfed-mobs-should-jump
• default: false • description: Determines if spawner nerfed mobs should attempt to float (jump) in water. enable-treasure-maps
• default: true • description: Allows villagers to trade treasure maps. treasure-maps-return-already-discovered
• default: false • description: Instructs the server to target the first treasure location found, rather than the first undiscovered one. Vanilla mechanics normally find the first undiscovered location, which may lead to structures that were notfully looted, and can also fail with a world border set. Enabling this will make the map simply find the closest target structure, regardless if it has been loaded or not already. iron-golems-can-spawn-in-air
• default: false • description: Sets whether iron golems can spawn in the air. Iron farms may break depending on this setting armor-stands-tick
• default: true • description: Disable to prevent armor stands from ticking. Can improve performance with many armor stands. non-player-arrow-despawn-rate
• default: -1 • note: The default value instructs the server to use the same default arrow despawn rate from spigot.yml that is used for all arrows. • description: The rate, in ticks, at which arrows shot from non-player entities are despawned.
22 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 creative-arrow-despawn-rate
• default: -1 • description: The rate, in ticks, at which arrows shot from players in creative mode are despawned. entities-target-with-follow-range
• default: false • description: Sets whether the server should use follow range when targeting entities zombies-target-turtle-eggs
• default: true • description: Sets whether zombies and zombified piglins should target turtle eggs. Setting this to false mayhelp with performance, as they won’t search for nearby eggs. zombie-villager-infection-chance
• default: -1.0 • description: Sets the change for villager conversion to zombie villager Set to -1.0 for default behavior based on game difficulty Set to 0.0 to always have villagers die when killed by zombies Set to 100.0 to always convert villagers to zombie villagers all-chunks-are-slime-chunks
• default: false • description: Instructs the server to treat all chunks like slime chunks, allowing them to spawn in any chunk. • note: This may actually decrease your chances of running into a Slime as they now have a much larger potential spawn area. mob-spawner-tick-rate
• default: 1 • description: How often mob spawners should tick to calculate available spawn areas and spawn new entities into the world.
1.1. Running A Paper Server 23 PaperDocs Documentation, Release 1.17.1 light-queue-size
• default: 20 • description: Sets how large the queue of light updates off the main thread for each world should be. Vanilla uses 5, but this causes issues especially with plugins such as WorldEdit. auto-save-interval
• default: -1 • note: Default value instructs the world to use Bukkit’s default. • description: Instructs this world to use a specific value for auto-save instead of bukkit’s global value. game-mechanics
• scan-for-legacy-ender-dragon – default: true – description: Determines whether the server searches for the ender dragon when loading older worlds. • disable-pillager-patrols – default: false – description: Disables Pillager patrols and associated AI. • disable-unloaded-chunk-enderpearl-exploit: – default: true – description: Prevent enderpearls from storing the thrower when in an unloaded chunk. • disable-chest-cat-detection – default: false – description: Allows you to open chests even if they have a cat sitting on top of them. • nerf-pigmen-from-nether-portals – default: false – description: Removes AI from pigmen spawned via nether portals • disable-player-crits – default: false – description: Instructs the server to disable critical hits in PvP, instead treating them as normal hits. • disable-sprint-interruption-on-attack – default: false – description: Determines if the server will interrupt a sprinting player if they are attacked. • shield-blocking-delay – default: 5 – description: The number of ticks between a player activating their shield and it actually blocking damage.
24 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
• disable-end-credits – default: false – description: Instructs the server to never send the end game credits when leaving the end. • disable-relative-projectile-velocity – default: false – description: Instructs the server to ignore shooter velocity when calculating the velocity of a fired arrow. • disable-mob-spawner-spawn-egg-transformation – default: false – description: Whether to block players from changing the type of mob spawners with a spawn egg. • fix-curing-zombie-villager-discount-exploit – default: true – description: Fixes the exploit used to gain massive discounts by infecting and curing a zombie villager. pillager-patrols
• spawn-chance – default: 0.2 – description: Modify the spawn changes for patrols. • spawn-delay – per-player ∗ default: false ∗ description: Makes spawn-delay per player. – ticks ∗ default: 12000 ∗ description: Delay in ticks between spawn chance. • start – per-player ∗ default: false ∗ description: Makes days per player. – day ∗ default: 5 ∗ description: Days between raid spawns.
1.1. Running A Paper Server 25 PaperDocs Documentation, Release 1.17.1 max-growth-height
• cactus – default: 3 – description: Maximum height cactus blocks will naturally grow to. • reeds – default: 3 – description: Maximum height sugar cane / reeds blocks will naturally grow to. • bamboo – max ∗ default: 16 ∗ description: Maximum height bamboo will naturally grow to. – min ∗ default: 11 ∗ description: Minimum height bamboo will naturally grow to. fishing-time-range
• MinimumTicks – default: 100 – description: The minimum number of RNG ticks needed to catch a fish. • MaximumTicks – default: 600 – description: The maximum number of RNG ticks before catching a fish. despawn-ranges
• soft – default: 32 – description: The number of blocks away from a player in which entities will be randomly selected to be despawned. • hard – default 128 – description: The number of blocks away from a player in which entities will be forcibly despawned.
26 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 frosted-ice
• enabled – default: true – description: Instructs the server to enable (and tick) frosted ice blocks. • delay – min ∗ default: 20 ∗ description: Minimum RNG value to apply frosted-ice effects at. – max ∗ default: 40 ∗ description: Maximum RNG value to apply frosted-ice effects at. lootables
• auto-replenish – default: false – description: Instructs the server to automatically replenish lootable containers. – note: This feature is useful for long-term worlds in which players are not expected to constantly explore to generate new chunks. • restrict-player-reloot – default: true – description: Prevents the same players from coming back and re-looting the same containers over and over. • reset-seed-on-fill – default: true – description: Resets the loot seed each time the lootable is refilled. Effectively randomizing the new loot items on each refill. • max-refills – default: -1 – description: Sets the maximum number of times a lootable may be refilled. – note: The default value will allow a lootable to refilled an infinite number of times. • refresh-min – default: 12h – description: The minimum amount of time that must pass before a lootable will be eligible to be refilled. – note: This field uses time-based values. 12s = 12 seconds, 3h = 3 hours, 4d=4days. • refresh-max – default: 2d
1.1. Running A Paper Server 27 PaperDocs Documentation, Release 1.17.1
– description: The maximum amount of time that can pass before a lootable is refilled. – note: This field uses time-based values. 12s = 12 seconds, 3h = 3 hours, 4d=4days. alt-item-despawn-rate
• enabled – default: false – description: Determines if items will have different despawn rates. • items – default: { COBBLESTONE: 300 } (a list of mappings) – description: Determines how long each respective item despawns in ticks. You can use item names from the Material enum.
spawn-limits
• monsters: – default: -1 – description: The number of monsters that can spawn per world. This is identical to the value set in bukkit.yml, except that it can be configured per world. A value of -1 will use the value in bukkit.yml. • animals: – default: -1 – description: The number of animals that can spawn per world. This is identical to the value set in bukkit.yml, except that it can be configured per world. A value of -1 will use the value in bukkit.yml. • water-animals: – default: -1 – description: The number of water animals that can spawn per world. This is identical to the value set in bukkit.yml, except that it can be configured per world. A value of -1 will use the valuein bukkit.yml. • water-ambient: – default: -1 – description: The number of ambient water creatures that can spawn per world. This is identical to the value set in bukkit.yml, except that it can be configured per world. A value of -1 will usethe value in bukkit.yml. • ambient: – default: -1 – description: The number of ambient creatures that can spawn per world. This is identical to the value set in bukkit.yml, except that it can be configured per world. A value of -1 will use the value in bukkit.yml.
28 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 hopper
• cooldown-when-full – default: true – description: Instructs the server to apply a short cooldown when the hopper is full, instead of con- stantly trying to pull new items. • disable-move-event – default: false – description: Completely disables the InventoryMoveItemEvent for hoppers. Dramatically improves hopper performance but will break protection plugins and any others that depend on this event. anti-xray
Note: More in depth anti-xray documentation as well as recommended configuration for both engine modes can be found in this guide by stonar96.
• enabled – default: false – description: Controls the on/off state for the Anti-Xray system. • engine-mode – default: 1 – description: Sets the Anti-Xray engine mode. Where 1 is to replace hidden blocks with stone and 2 is to replace all blocks with random block data. • max-block-height – default: 64 – description: Sets the maximum height at which anti-xray will attempt to hide ores. Only multiples of 16 are allowed. Other values will be rounded down to a multiple of 16. • update-radius – default: 2 – description: Controls the distance in blocks from air or water that hidden-blocks are hidden by the anti-xray engine. The maximum allowed value is 2. • lava-obscures – default: false – description: Whether or not to obfuscate blocks touching lava. • use-permission – default: false – description: Whether or not to allow players with the paper.antixray.bypass permission to bypass anti-xray. Checking this permission is disabled by default as legacy permission plugins may struggle with the number of checks made. This should only be used with modern permission plugins. • hidden-blocks
1.1. Running A Paper Server 29 PaperDocs Documentation, Release 1.17.1
– default: [copper_ore, deepslate_copper_ore, gold_ore, deepslate_gold_ore, iron_ore, deeps- late_iron_ore, coal_ore, deepslate_coal_ore, lapis_ore, deepslate_lapis_ore, mossy_cobblestone, ob- sidian, chest, diamond_ore, deepslate_diamond_ore, redstone_ore, deepslate_redstone_ore, clay, emerald_ore, deepslate_emerald_ore, ender_chest] – description: List of blocks to be hidden in engine mode 1. – note: This list is using Mojang server names not bukkit names. • replacement-blocks: – default: [stone, oak_planks] – description: List of blocks that should be replaced by hidden-blocks in engine mode 2. – note: This list is using Mojang server names not bukkit names. viewdistances
• no-tick-view-distance – default: -1 – description: Sets the no-tick view distance. This is the total view distance of the player: a ‘normal’ view distance of 5 and a no-tick view distance of 10 would mean 5 view distance is ticked, has mobs moving, etc., but the extra 5 (therefore 10 in total) is only visible. A value of -1 disables this feature. squid-spawn-height
• maximum – default: 0.0 – description: The maximum height at which squids will spawn. – note: The default value defers to Minecraft’s default setting, which as of 1.12 is the sea-level of the world (usually Y: 64). generator-settings
• flat-bedrock – default: false – description: Instructs the server to generate bedrock as a single flat layer. should-remove-dragon
• default: false • description: Sets whether or not to remove the dragon if it exists without a portal.
30 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 wandering-trader
• spawn-minute-length – default: 1200 – description: The length of the wandering trader spawn minute in ticks. • spawn-day-length – default: 24000 – description: Time between wandering trader spawn attempts in ticks. • spawn-chance-failure-increment – default: 25 – description: How much the spawn chance will be increased on every failed wandering trader spawn. • spawn-chance-min – default: 25 – description: The minimum chance that a wandering trader will be spawned. • spawn-chance-max – default: 75 – description: The maximum chance that a wandering trader will be spawned. fix-climbing-bypassing-cramming-rule
• default: false • description: Sets whether climbing should bypass the entity cramming limit. fix-entity-position-desync
• default: true • description: Fixes the issue in which an items position is desynchronized between the client and the server. update-pathfinding-on-block-update
• default: true • description: Controls whether the pathfinding of mobs is updated when a block is updated in the world. Dis- abling this option can improve the server performancy significantly while there is almost no noticeable effecton the game mechanics. This is recommended when there are lots of entities loaded and you have automated farms or redstone clocks.
1.1. Running A Paper Server 31 PaperDocs Documentation, Release 1.17.1 ender-dragons-death-always-places-dragon-egg
• default: false • description: Controls whether ender dragons should always drop dragon eggs on death. max-leash-distance
• default: 10.0 • description: Configure the maximum distance of a leash. If the distance to the leashed entity is greater, theleash will break. entity-per-chunk-save-limit
• experience_orb – default: -1 – description: Limits the number of experience orbs that are saved/loaded per chunks. A value of -1 disables this limit • snowball – default: -1 – description: Limits the number of snowballs that are saved/loaded per chunks. A value of -1 disables this limit • ender_pearl – default: -1 – description: Limits the number of ender pearls that are saved/loaded per chunks. A value of -1 disables this limit • arrow – default: -1 – description: Limits the number of arrows that are saved/loaded per chunks. A value of -1 disables this limit unsupported-settings
• fix-invulnerable-end-crystal-exploit – default: true – description: If set to false, the creation of invulnerable end crystals will be allowed. Fixes MC- 108513.
32 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 portal-search-radius
• default: 128 • description: portal-create-radius
• default: 16 • description: door-breaking-difficulty
• zombie – default: [‘HARD’] – description: Takes a list of difficulties at which zombies are able to break doors • vindicator – default: [‘NORMAL’, ‘HARD’] – description: Takes a list of difficulties at which vindicators are able to break doors mobs-can-always-pick-up-loot
• zombies – default: false – description: Controls whether zombies always pick up loot. If set to false, the probability that a zombie picks up items depends on the world’s difficulty. • skeletons – default: false – description: Controls whether skeletons always pick up loot. If set to false, the probability that a skeleton picks up items depends on the world’s difficulty. fix-wither-targeting-bug
• default: false • description: Fixes the wither’s targeting of players. See MC-29274.
1.1. Running A Paper Server 33 PaperDocs Documentation, Release 1.17.1
map-item-frame-cursor-limit
• default: 128 • description: The number of cursors (markers) allowed per map. A large number of cursors may be used to lag clients.
seed-based-feature-search
• default: true • description: Whether the server should check if a chunk’s biome (determined by world seed) can support the desired feature before loading it during feature searches. This dramatically reduces the number of chunks loaded during feature searches. • note: This assumes the seed and generator have remained unchanged. If your seed or world generator has been changed, features will be located incorrectly.
seed-based-feature-search-loads-chunks
• default: true • description: When set to false, seed-based-feature-search will not load the target chunk. Instead, it will return the center of the chunk. The more precise location of the feature will be returned as the player loads the target chunk. While disabling this will increase performance, it may lead to incorrect feature locations being returned. This will impact both the /locate command, buried treasure maps, and any other game mechanic that relies on feature searches. allow-using-signs-inside-spawn-protection
• default: false • description: Allows players to use signs while inside spawn protection. allow-player-cramming-damage
• default: false • description: Allows players to take damage from cramming when colliding with more entities than set in the maxEntityCramming gamerule. tick-rates
• sensor –
34 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
· default: 40 · description: Sets the tick rate of the secondarypoisensor sensor of Villager entities • behavior –
feature-seeds
• generate-random-seeds-for-all – default: false – description: Enables auto-filling random seeds for all available features you haven’t already seta seed to. Using this in a controlled environemnt is also a good way of receiving a full list of features you can set seeds for. •
1.1.2 Updating to Java 16
As of Minecraft 1.17, Paper will only support Java 16 and above. This is in line with our new policy of only supporting the last two long-term-support (LTS) versions of the Java runtime. Although Minecraft 1.17 requires a Java version that is too new for any LTS, we will maintain our policy as far as possible. We will only support Java 16 and above because of Mojang Studios deciding to bump their own Java requirement with 1.17. If you’re a developer or want to be on the safe side, pick the JDK options in the guides instead of a generic JRE. The JDK contains the JRE, in addition to development material (sources, documentation, a reference compiler, and more). To update, please find the appropriate header for you in the table of contents.
• Shared hosts – Apex Hosting – Aternos – Bloom.Host – Creeper.Host – DedicatedMC – EnviroMC – MCProHosting
1.1. Running A Paper Server 35 PaperDocs Documentation, Release 1.17.1
– Minehub – Nitrado – PebbleHost – ServerFlex – Server.pro – WinterNode • Pterodactyl • Debian/Ubuntu • RPM-Based • Arch Linux • Linux (Generic) – SDKMAN! – Adoptium • Windows 10 – Checking version – Modifying your PATH • macOS / OS X
Shared hosts
If you cannot find your host in the following list, you should open a support ticket with your host’s website toaskhow to update.
Apex Hosting
Apex Hosting is already on Java 16 for both Paper and Waterfall. You don’t need to do anything to update.
Aternos
If you run Paper, you should have Java 16 selected automatically. If you run Minecraft 1.16 or earlier, you can change this in the server configuration panel on their website to Java 8, 11, or16:
36 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
Bloom.Host
You can select Java 16 from the server configuration panel by selecting the Java version option ending in openjdk-16:
Creeper.Host
CreeperHost has some terrific documentation on how to do this on their website: Changing Java Version.
DedicatedMC
When loading Minecraft 1.17, the server will automatically be set to Java 16, and you don’t need to do anything whatsoever. If you wish to test Java 16 before updating, you can set this yourself in the Startup Settings panel:
For more information, feel free to read the How to change your server’s Java version guide on their wiki.
1.1. Running A Paper Server 37 PaperDocs Documentation, Release 1.17.1
EnviroMC
EnviroMC defaults to Java 16 if you select Paper as your server jar. To manually change your Java version, please navigate to the Startup -> Docker Image option, and select Java 16, as shown below.
MCProHosting
When loading 1.17, the server will automatically be set to Java 16 and you don’t have to do anything whatsoever. If you want to test Java 16 on Minecraft 1.16 or earlier, you will need to set the server type to Snapshot, then put Paper back on the server manually.
Minehub
Minehub will automatically set the Java version to Java 16 when selecting 1.17. You can also set the Java version yourself under Select Java version.
38 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
Nitrado
If you create a 1.17 server the Java version will be set to Java 16 out of the box. However if it doesn’t (because e.g. you upgraded the server manually) you can set the Java version under “General” -> “Java”
PebbleHost
PebbleHost’s knowledgebase has a great article Does PebbleHost support Java 16? on their website to show how to change the Java version, along with incompatibilities with certain versions.
ServerFlex
ServerFlex defaults to Java 8, but will automatically select Java 16 where appropriate. To manually configure the java version, navigate to the settings page, and select Java Version. More information can be found in ServerFlex’s support article.
1.1. Running A Paper Server 39 PaperDocs Documentation, Release 1.17.1
Server.pro
Creating a server on 1.17 automatically selects Java 16. To manually set the Java version, navigate to the control panel, select Advanced Settings and select Java 16 - HotSpot on the dropdown menu. Save the changes by clicking Save Changes at the bottom of the page.
40 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
WinterNode
WinterNode’s Help Center has an helpful article Java Version Selector showing how to change the Java version, along with recommendations per Minecraft version. If you do nothing, it will automatically select the version that fits best for your server.
Pterodactyl
Note: To switch the Java version on Pterodactyl, you will require an administrator account.
Note: The names of options will be different depending on the language you use.
Assuming you are already logged in on your administrator account, open the administrator control panel, go to the Servers tab, click on your server (this has to be repeated for every server you wish to switch the Java version of), and press the Startup tab. Proceed by selecting ghcr.io/pterodactyl/yolks:java_16 from the Image dropdown under Docker Container Configuration. If you are running an older panel version, manually enter the image url in the custom image field. For Java 11, select it from the dropdown instead or replace 16 with 11.
1.1. Running A Paper Server 41 PaperDocs Documentation, Release 1.17.1
Debian/Ubuntu
To install Java 16 on Debian, Ubuntu, and the plethora of other distributions based on these, execute the following commands to add the AdoptOpenJDK APT repository and to install AdoptOpenJDK Hotspot: $ sudo apt update $ sudo apt install apt-transport-https software-properties-common gnupg wget $ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-
˓→key add - $ sudo add-apt-repository https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/ $ sudo apt update $ sudo apt install adoptopenjdk-16-hotspot
You can also replace 16 with 11 for Java 11.
RPM-Based
To install Java 16 on CentOS, RHEL, Fedora, openSUSE, SLES and many other RPM-based distributions, execute the following commands to add Amazon Corretto’s RPM repository and install Java 16. DNF zypper yum $ sudo rpm --import https://yum.corretto.aws/corretto.key $ sudo curl -Lo /etc/yum.repos.d/corretto.repo https://yum.corretto.aws/corretto.repo $ sudo dnf -y install java-16-amazon-corretto-devel
$ sudo zypper addrepo https://yum.corretto.aws/corretto.repo $ sudo zypper install java-16-amazon-corretto-devel
$ sudo rpm --import https://yum.corretto.aws/corretto.key $ sudo curl -Lo /etc/yum.repos.d/corretto.repo https://yum.corretto.aws/corretto.repo $ sudo yum -y install java-16-amazon-corretto-devel
Arch Linux
To install Java 16 on Arch Linux, you will need to install the jre-openjdk package. $ sudo pacman -Syu jre-openjdk
To switch between available Java versions on the system with the archlinux-java tool, see the wiki on Switching between JVMs.
42 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1
Linux (Generic)
Note: You should check with your distribution’s package manager(s) before using this section of the guide. It is very likely you can find a suitable Java version if you search its repositories for java, openjdk, and jre.
SDKMAN!
Install SDKs with ease! Wa-pow! Luckily SDKMAN! is written in bash, so you can use this on practically any Linux (and BSD!) environment. Follow the installation instructions on their website. You can then proceed to install one of their many Java distributions with the simple commands on their website.
Adoptium
Note: This assumes an intermediate to advanced Linux user. Ask for help if you need it; we don’t want you to harm your system. #paper-help on Discord is a fitting channel for asking, and remember: don’t ask to ask, just ask.
Note: You are going to require the tar and sha256sum tools to do this install.
First, select an appropriate tar.gz file from Adoptium’s website, and copy the download URL. Next, figure out which directory you want to install Java to; this is commonly a subdirectory within /usr/lib/jvm. The tar file you copied the URL to has an inner directory, so you don’t need to create oneyourself. Download the file with one of the following commands: • With curl: curl -LJO "replace this text with the URL" • With wget: wget "replace this text with the URL" And get the signature from pressing the Checksum (SHA256) button next to the .tar.gz download button. This should be the same as displayed in the second column, output from running sha256sum "the downloaded file path goes here". If they are not the same, delete the files and re-download them. Next up, extract the file with: tar xzf "the downloaded file path goes here". There should now be a direc- tory named something like jdk-16.0.1+1/. You can safely delete the tar.gz file if this is the case. Now you should add an environment variable called JAVA_HOME pointing to the directory you created (e.g. /usr/lib/ jvm/jdk-16.0.1+1; note there is no trailing slash here): # cat < Note: The # at the start means this has to be run as either root, or an account that has access to the /etc/profile.d/ directory. To avoid this, you can replace tee with sudo tee (or doas tee on BSD), and replace chmod with sudo chmod (or doas chmod on BSD). 1.1. Running A Paper Server 43 PaperDocs Documentation, Release 1.17.1 You must now source the new file you created, which is usually done at the start of a shell, so you can just re-openthe shell. Alternatively, run source /etc/profile.d/java.sh. Windows 10 If you’re on Windows 10, you will want Adoptium’s JRE. You can find the msi file you should install on their website. Remember to reboot your computer after installing. Checking version If you now open a new PowerShell prompt and do java -version, it should say something along the lines of: openjdk version"16.0.1" 2021-04-20 OpenJDK Runtime Environment Temurin-16.0.2+7 (build 16.0.2+7) OpenJDK 64-Bit Server VM Temurin-16.0.2+7 (build 16.0.2+7, mixed mode, sharing) It is the version "16.0.1" part that is important – if the first number is not 16, you need to modify your PATH. Modifying your PATH Press your Windows button and search (just start typing) environment variable. The Edit the system environment variables result is the one you want. 44 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 Press the Environment Variables... button: 1.1. Running A Paper Server 45 PaperDocs Documentation, Release 1.17.1 Select the JAVA_HOME variable in the System variables section in the bottom half of the window and press Edit. .., OR if the variable is not present, create a new variable with New... in the lower half of the window, and name it JAVA_HOME. You now want to Browse Directory... and find the Java directory under C:\Program Files\ Eclipse Foundation in the Windows Explorer window: 46 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 Now go to your Path variable in the System variables section in the bottom half of the window and press Edit.... If there is already a %JAVA_HOME%\bin entry in the list, skip this step. Otherwise, press the New button at the top and enter %JAVA_HOME%\bin: If you now open a new PowerShell window, you should have the correct output. If not, restart your computer and try again. If it is still wrong, ask for help in #paper-help on Discord to get further assistance. 1.1. Running A Paper Server 47 PaperDocs Documentation, Release 1.17.1 macOS / OS X If you’re on macOS, you can use a tool called Homebrew to install Java. Follow the instructions on their website for how to install it. To now install Java, open your Terminal app and run the following command: $ brew install --cask temurin If you used AdoptOpenJDK previously, uninstall and untap it. $ brew uninstall adoptopenjdk16-jre $ brew untap AdoptOpenJDK/openjdk 1.2 Running A Waterfall Proxy Running a Waterfall proxy is also easy. This section will cover common tasks such as configuring it, maintaining plugins, and general best practices. 1.2.1 Running A Waterfall Proxy Running a Waterfall proxy is easy. Click the links below for more information. Contents Getting Started • What is Waterfall? • Requirements • Migrating From BungeeCord • Getting A Proxy Jar • Running The Proxy • Updating The Proxy What is Waterfall? Waterfall is a fork of BungeeCord, a proxy used primarily to teleport players between multiple Minecraft servers. Waterfall focuses on three main areas: • Stability: Waterfall aims to be stable. We will achieve this through making the code base testable and discour- aging practices that lead to proxy lag. • Features: Waterfall aims to include more features than canonical BungeeCord. 48 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 • Scalability: Waterfall should be able to handle a large number of concurrent players, given a reasonably modern CPU, memory, and good network connection. Requirements Waterfall requires Java 8 or newer to run. The Paper team recommends you run on Java 11 or higher. Generally, LTS versions of Java are targeted, though you may have luck on newer versions. Migrating From BungeeCord Waterfall is a drop in replacements for BungeeCord, you don’t need to make any changes to your configuration. Getting A Proxy Jar Paper provides runnable proxy jars directly from our website’s downloads page. Click on the build number to download a file. Running The Proxy To run the proxy, simply start it up like any other Java application. Open your terminal, navigate to the saved location, and then run java -Xms512M -Xmx512M -jar waterfall-###.jar Aikar’s recommended flags for Waterfall are as follows: java -Xms512M -Xmx512M -XX:+UseG1GC -XX:G1HeapRegionSize=4M -XX:+UnlockExperimentalVMOptions -XX:+ParallelRefProcEnabled -XX:+AlwaysPreTouch -jar waterfall-###.jar For further explanation about advanced Java tuning, see Aikar’s tuning page. The amount of memory can be set by changing the numbers in the -Xms and -Xmx flags. To configure your proxy, see the Configuration page. Updating The Proxy To update the proxy, first stop it safely by executing the end command and then replace the old proxy jar with a new one. That’s it. Configuration This page details the various configuration settings exposed by Waterfall. These settings can be found in waterfall.yml. If you want information on settings in BungeeCord’s config.yml you should see its respective documentation pages. • BungeeCord Configuration (config.yml) 1.2. Running A Waterfall Proxy 49 PaperDocs Documentation, Release 1.17.1 Warning: Configuration values change frequently at times. It is possible for the information here to be incomplete. If you cannot find what you’re looking for or think something may bewrong, Contact Us Last updated October 4th, 2020 for Waterfall build #379 use_netty_dns_resolver • default: true • description: Sets whether Netty’s async DNS resolver is used for account authentication. disable_modern_tab_limiter • default: true • description: Disables the tab completion limit for 1.13+ clients. log_initial_handler_connections • default: true • description: Sets whether to log InitialHandler connections. throttling • tab_complete – default: 1000 – description: How often tab-complete packets can be sent in milliseconds. game_version • default: ‘ ‘ (empty string) • description: The supported versions displayed to the client. Default is a comma separated list of supported versions. For example 1.8.x, 1.9.x, 1.10.x disable_entity_metadata_rewrite • default: false • description: This setting disables entity metadata rewriting in favor of sending a join packet to the client. It offers a more robust solution for modded environments but can cause plugins tobreak. 50 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 disable_tab_list_rewrite • default: false • description: This setting disables tablist rewriting, which may resolve issues setting player profiles when Wa- terfall is in offline mode. 1.3 Contributing to Paper It’s great to see new contributors to the project! Here are some documents which provide further information to get you started: 1.3.1 Contributing This page has yet to be written. It will contain information about contributing to the PaperMC project. For now see our main repository’s contributing information. 1.4 About Paper Paper is a fork of Spigot with certain goals in mind. The following links explain more about the purpose, rationale and structure of the PaperMC project. 1.4.1 About the PaperMC Project This section provides basic information about the project, as well as covering asset information, frequently asked questions, and contact information. Contents Introduction What is Paper? Paper, and the PaperMC project behind it, exist to expand the platforms upon which it is built. Paper has a relatively small team, despite that, we have received a large amount of attention and a great showing of support from both server administrators and fellow developers. As such, we focus on a few things: • A performant server is paramount. • Giving back to the community matters. • Mojang’s decisions and assumptions are not necessarily the best for everyone. Paper is largely composed of two projects: • Paper-API, An enhanced version of the Bukkit API. 1.3. Contributing to Paper 51 PaperDocs Documentation, Release 1.17.1 • Paper-Server, usually just referred to as Paper, Paper-Server is an enhanced implementation of the server that goes hand-in-hand with our enhanced API. There are also other, more technical, projects that support the above two projects. For more information on that see The Structure of PaperMC. Where can I download Paper? A complete list of available builds can be obtained from our site’s download page. Frequently Asked Questions • General – What is Paper? – What do I need to run it? – Where do I get it? • Server Administrators – What can I expect from switching to Paper? – Will players be able to tell? – Can I run Bukkit plugins on Paper? – Can I run Spigot plugins on Paper too? – Is there anywhere to get plugins for Paper? – Does Paper support Forge Mods? • Developers – What can I do with Paper? – Does Paper make any breaking changes to the API? General What is Paper? Paper is a fork of the Spigot server implementation (which is itself a fork of CraftBukkit). Paper strives to bring improved performance, more features, and more APIs for developers to build awesome plugins with. 52 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 What do I need to run it? Paper requires the Java Runtime Environment to run. Specifically, it requires at least Java version 16. Once thatis installed you’re all good to go! If you don’t already have a Java 16 Runtime, it’s easy to download and install. See our docs on starting out: Getting Started Where do I get it? Builds of Paper are already available on our site’s download page. Alternatively, for more automated access, builds are available via a RESTful Downloads API Server Administrators What can I expect from switching to Paper? When migrating your CraftBukkit or Spigot server to Paper, it is not uncommon to see a noticeable performance improvement. Note: Though you may see an improvement, Paper is not a silver bullet. Ultimately, you are responsible for the performance of your server, good or bad, on any platform. Tailoring your server to best fit your players and gamemodes is ultimately the key to great performance. Your plugins and worlds will not be changed and both should work just fine after the change. Will players be able to tell? That depends. Your players may see a benefit to gameplay because of the performance improvement, assuming yousee one. On a properly maintained server, your players may not even be able to tell the difference. Can I run Bukkit plugins on Paper? Yep! You absolutely can. Paper takes care to maintain compatibility with Bukkit plugins made by the community. Can I run Spigot plugins on Paper too? Yes you can! We don’t like to break things most of the time. Sometimes there are plugin authors who do, but we can usually make things work. 1.4. About Paper 53 PaperDocs Documentation, Release 1.17.1 Is there anywhere to get plugins for Paper? Many plugins that work with, and are made for, Paper are available on the forum’s resource section. Sometimes you’ll also see them elsewhere, you just have to keep your eyes open. Does Paper support Forge Mods? No, Paper does not support Forge mods of any kind. While there have been attempts to merge the Forge and Bukkit platforms in the past, it has never been a wonderful experience for developers or administrators. If this is something you’re after, we’d point you towards the Sponge Project instead. Developers What can I do with Paper? Paper provides additional APIs ontop of Bukkit, exposing new vanilla elements and even some of its own for you to play with. Developer JavaDocs Does Paper make any breaking changes to the API? Fortunately, Paper does not make breaking API changes so it can maintain plugin compatibility with upstream Spigot and CraftBukkit. At the same time, this means we are also sometimes limited with what we can do and how we can do it. It’s a double-edged sword. The Structure of PaperMC Project Description Paper Shared API & Server repository Waterfall A principles fork of the Bungeecord software suite PaperDocs All documentation for the project Paperclip A wrapper around Paper-Server to make it easy to distribute and easy to use PaperTestServer A skeleton test server we use for testing plugin compatibility Paper This is our main repository. Changes to Spigot-API and Spigot-Server are maintained as a (large) set of individual patch files in this repository. This repository contains only bash scripts and patch files. The bash scripts present inthis repo will then take the patches to Spigot-API and to Spigot-Server and apply them. From this process comes a proper, buildable, Paper-API and Paper-Server that we can then build as a standard maven project. Paper-API is then compiled and sent to up to our maven server for developers to build their plugins against. 54 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 Paper-Server is compiled, then handed off to the Paperclip launcher tool. More on that in a second. From there,we distribute it to you! Paperclip Paperclip is a binary patch distribution system for Paper-Server. We give it a normal, compiled, Paper-Server jar file. From there, Paperclip generates a binary patch of the difference between that Paper-Server jar and the vanilla Minecraft server. It then takes that binary patch and includes it in a separate jar file along with some information about the version of Minecraft it came from, stored as a JSON file, and some minimal code to launch it. When an end-user runs Paperclip for the first time a few things happen. 1. Paperclip checks the JSON file it stores internally to see what version of Minecraft it was built against. 2. Paperclip downloads a vanilla minecraft jar for that particular version directly from Mojang. 3. Paperclip checks to see that the vanilla jar it just downloaded is the same as the one it was built against using a SHA-256 hash. 4. Paperclip applies the included binary patch of Paper changes to the vanilla jar. 5. Paperclip verifies that the final patched version of the server is the same as the one we originally builtusinga SHA-256 hash. 6. Paperclip does some java classloader magic and starts the server right then and there. It only does this on the first run, after this first run, it will skip parts of that process as it deems necessary. For example, when Paper pushes a new build of Paper for a specific Minecraft version, Paperclip will not re-download the vanilla jar, it’ll simply re-patch it and start up. If there is a Minecraft version change (like 1.9 to 1.10), only then will Paperclip re-download the vanilla Minecraft jar. Art Assets This page provides the official PaperMC logomark and the terms under which you mayuseit. Attention: The PaperMC logo is subject to its own separate licensing terms and does not inherit any from the projects it represents. You may: • Use the PaperMC logomark to represent the project in blogposts and other places in order to bring attention to the project. • Use the PaperMC logomark to represent Paper-Server in downloads, server selectors, and similar places. • Crop out extra transparent canvas space behind the PaperMC logomark so it fits better next to other content. You may not: • Alter any of the colors used in the PaperMC logomark. • Change the dimensions of the PaperMC logomark. • Create modified versions of the PaperMC logomark or derivative works ofit. • Add your own project images or branding to the PaperMC logomark. • Claim the logomark as your own work or use it as a representation of your own projects. 1.4. About Paper 55 PaperDocs Documentation, Release 1.17.1 • Sell the PaperMC logomark on its own or as part of other products without explicit permission. • Alter the transparency of any of the elements in the PaperMC logomark Note: The logomark is available in higher resolution and vector formats. If you need a higher resolution version please contact us. The official PaperMC logomark 56 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 Contact Us • IRC • Discord • Twitter IRC The Paper project handles most of our communication via IRC. You can join us on either of these two servers: • #paper on irc.esper.net Discord Our IRC presence is also bridged to a Discord server, you can use the following link to join it. • https://discord.gg/papermc Twitter We often tweet out version release notes, update notices, and other information via our Twitter page. • @PaperPowered You should not DM or @ this account for support. It is not checked as regularly as the above locations. 1.4.2 The PaperMC Site The articles below document certain features of the site. Contents Downloads API Warning: Version 1 of the API has been deprecated as of November 24th, 2020. We encourage everyone to use the new version of the API as the previous one will soon be removed. After months of requests (years in the case of a few hosting providers), PaperMC has added a downloads API to standardize download links and finding specific versions of our software for specific versions of Minecraft. It is a simple RESTful JSON API. Like most APIs it uses versioned endpoints; the current version is v2. If any breaking changes are made it will be incremented to v3 and announced, with the old version continuing to function for some time until further announcements are made. 1.4. About Paper 57 PaperDocs Documentation, Release 1.17.1 I just want to download the latest jar Unlike the v1 API, there is no API endpoint to simply fetch the latest jar. This is intentional, as it had been primarily used to auto-update servers, which is highly discouraged. Downloading from the command line Because the filenames given by the API include version numbers, start scripts will have to continuously changeto match the filename. For this reason, it is recommended that you choose a consistent name, suchas paperclip.jar or waterfall.jar, and save your downloads to that file. This also has the advantage of not cluttering up your server directories with unneeded previous versions. If you’re using curl you can use the -o flag by itself to specify your own name for the downloaded file(ex: curl -o paperclip.jar http://someurl). For more information, please see curl’s own documentation. If you’re using wget, you can use the -O flag to specify your own name for the downloaded file.(ex: wget http:// someurl -O paperclip.jar) For more information, please see wget’s own documentation. Other tools may not use the above options, and may even choose their own names. You will have to consult those specific tools’ documentation to determine how that is handled. You can always simply rename the file immediately after download if your preferred tool does not allow you to set the file name for some reason. Endpoint Documentation Swagger docs To view the full v2 documentation, including example responses for all below-documented endpoints and an interactive request generator, please go to https://papermc.io/api/docs/ Overview The downloads API is project-based, and downloads can be obtained via the following format: https://papermc. io/api/v2/projects/{PROJECT}/versions/{VERSION}/builds/{BUILD}/downloads/{DOWNLOAD} Example getting a listing of available project versions for Waterfall: https://papermc.io/api/v2/projects/ waterfall Hint: The parent (https://papermc.io/api) does not currently enumerate the available API versions and will instead redirect to a usage page on the current version of the API. Project • paper - The PaperMC server implementation • waterfall - The Waterfall server proxy • travertine - The Travertine proxy; Waterfall, but supporting Minecraft 1.7. Now deprecated. The parent (https://papermc.io/api/v2/projects) will return a list of all available projects if accessed directly. 58 Chapter 1. Introduction PaperDocs Documentation, Release 1.17.1 Version This will vary from project to project above. By accessing the API using just the project name (ex: https://papermc. io/api/v2/projects/paper), the API will return an array of available versions (which includes minor releases) and version groups (which do not). These versions correspond to the version of Minecraft the software is targeting. For example, https://papermc.io/ api/v2/projects/paper/versions/1.16.5 will return all build IDs targeting the 1.16.5 version of Minecraft. Build A specific build of the given project. These build versions correspond with the build IDs specified by thebackend continuous integration tools. As of v2 of the API they will always be integers. For example, https://papermc.io/api/v2/projects/paper/versions/1.16.5/builds/435 will return in- formation about the build for 1.16.5 with the ID of 435. Download Finally, if you want to download a version of something, you must append the name of the file to download to the URL format in the example above. For example, to download build 430 of the Waterfall project for 1.16, you would access the following URL: https://papermc.io/api/v2/projects/waterfall/versions/1.16/builds/430/downloads/ waterfall-1.16-430.jar The final piece of the URL, waterfall-1.16-430.jar can be found by using the previously documented endpoint to obtain information about a build. Note that filenames are not guaranteed to follow the same naming format, and you must query the API properly toget the name of each build. Downloads served in this way will include content-type, content-length, and content-disposition headers for proper identification, progress, and naming of resources. content-type: application/java-archive content-length: 17759028 cache-control: public, max-age=14400, s-maxage=604800 content-disposition: attachment; filename*=UTF-8''waterfall-1.16-430.jar API Versions v1 - The initial launch version of the API, now deprecated. v2 - The current version of the API recommended for all usage. 1.4. About Paper 59 PaperDocs Documentation, Release 1.17.1 60 Chapter 1. Introduction CHAPTER TWO USEFUL LINKS • Main site • Discord • IRC • Docs • GitHub • Forums • Javadocs • Issue Tracker • Organization GitHub 61 PaperDocs Documentation, Release 1.17.1 62 Chapter 2. Useful Links CHAPTER THREE ACKNOWLEDGEMENTS YourKit, makers of the outstanding java profiler, support open source projects of all kinds with their fully featured Java and .NET application profilers. We thank them for granting Paper an OSS license so that we can make our software the best it can be. 63