diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4ca76e6a0..279a0a304 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -151,12 +151,14 @@ of a few ways: %%_MAJ_MIN_PAT_USERDEV_%% - Latest Paperweight-Userdev Version (E.g. 1.7.3) ```` -When the major version of the software changes, the docs will still need to have a "snapshot" created to keep documentation -for older versions. This is done by using Docusaurus's `version` command: +### Manual Version Tagging -```bash -pnpm docusaurus docs:version:paper "1.20" -``` +All of our documentation which is potentially relevant to a specific version of the software should be tagged with the +`targetVersion` frontmatter. This allows the user to see which version of the software the documentation was written for. + +It is important to keep this up to date, as it allows users to see if the documentation is still relevant to the version +however it is not required for all documentation. For example, a page about the history of the project would not need a +`targetVersion` tag. ## Magic Value Handling diff --git a/_redirects b/_redirects index 71d9f81b8..312669364 100644 --- a/_redirects +++ b/_redirects @@ -8,3 +8,5 @@ /paper/configuration /paper/reference/configuration /paper/reference/vanilla-command-permissions /paper/reference/permissions /paper/dev/commands /paper/dev/command-api/commands +/paper/:version/* /paper/* +/paper/:version /paper diff --git a/config/navbar.config.ts b/config/navbar.config.ts index ba00f173a..9821589c4 100644 --- a/config/navbar.config.ts +++ b/config/navbar.config.ts @@ -82,11 +82,6 @@ const navbar: Omit = { label: "Misc", position: "left", }, - { - type: "docsVersionDropdown", - docsPluginId: "paper", - position: "right", - }, { to: "https://papermc.io/downloads", label: "Downloads", diff --git a/docs/folia/admin/reference/faq.md b/docs/folia/admin/reference/faq.md index d1ba1f535..3e1dc88a1 100644 --- a/docs/folia/admin/reference/faq.md +++ b/docs/folia/admin/reference/faq.md @@ -2,6 +2,7 @@ slug: /faq title: FAQ description: Questions frequently asked by our community, answered by us! +targetVersion: 1.21 --- # FAQ diff --git a/docs/folia/admin/reference/overview.md b/docs/folia/admin/reference/overview.md index 03b08aadd..edbaf13e6 100644 --- a/docs/folia/admin/reference/overview.md +++ b/docs/folia/admin/reference/overview.md @@ -2,6 +2,7 @@ slug: /reference/overview title: Overview description: An overview of how Folia works. +targetVersion: 1.21 --- # Project overview diff --git a/docs/folia/admin/reference/region-logic.md b/docs/folia/admin/reference/region-logic.md index a60248714..d85a03d5c 100644 --- a/docs/folia/admin/reference/region-logic.md +++ b/docs/folia/admin/reference/region-logic.md @@ -2,13 +2,14 @@ slug: /reference/region-logic title: Region Logic description: An overview to how Folia's regionizer works. +targetVersion: 1.21 --- ## Fundamental regionizing logic ## Region -A region is simply a set of owned chunk positions and implementation +A region is simply a set of owned chunk positions and implementation defined unique data object tied to that region. It is important to note that for any non-dead region x, that for each chunk position y it owns that there is no other non-dead region z such that @@ -16,13 +17,13 @@ the region z owns the chunk position y. ## Regionizer -Each world has its own regionizer. The regionizer is a term used +Each world has its own regionizer. The regionizer is a term used to describe the logic that the class `ThreadedRegionizer` executes -to create, maintain, and destroy regions. Maintenance of regions is -done by merging nearby regions together, marking which regions -are eligible to be ticked, and finally by splitting any regions -into smaller independent regions. Effectively, it is the logic -performed to ensure that groups of nearby chunks are considered +to create, maintain, and destroy regions. Maintenance of regions is +done by merging nearby regions together, marking which regions +are eligible to be ticked, and finally by splitting any regions +into smaller independent regions. Effectively, it is the logic +performed to ensure that groups of nearby chunks are considered a single independent region. ## Guarantees the regionizer provides @@ -37,12 +38,12 @@ has one, and only one, corresponding region. ### Second invariant -The second invariant is that for every _existing_ chunk holder x that is -contained in a region that every each chunk position within the -"merge radius" of x is owned by the region. Effectively, this invariant +The second invariant is that for every _existing_ chunk holder x that is +contained in a region that every each chunk position within the +"merge radius" of x is owned by the region. Effectively, this invariant guarantees that the region is not close to another region, which allows the region to assume while ticking it can create data for chunk holders -"close" to it. +"close" to it. ### Third invariant @@ -51,16 +52,16 @@ the chunk positions it owns as it ticks. The third invariant is important as it prevents ticking regions from "fighting" over non-owned nearby chunks, to ensure that they truly tick in parallel, no matter what chunk loads they may issue while -ticking. +ticking. -To comply with the first invariant, the regionizer will -create "transient" regions _around_ ticking regions. Specifically, -around in this context means close enough that would require a merge, +To comply with the first invariant, the regionizer will +create "transient" regions _around_ ticking regions. Specifically, +around in this context means close enough that would require a merge, but not far enough to be considered independent. The transient regions -created in these cases will be merged into the ticking region +created in these cases will be merged into the ticking region when the ticking region finishes ticking. -Both of the second invariant and third invariant combined allow +Both of the second invariant and third invariant combined allow the regionizer to guarantee that a ticking region may create and then access chunk holders around it (i.e. sync loading) without the possibility that it steps on another region's toes. @@ -68,7 +69,7 @@ the possibility that it steps on another region's toes. ### Fourth invariant The fourth invariant is that a region is only in one of four -states: "transient", "ready", "ticking", or "dead." +states: "transient", "ready", "ticking", or "dead." The "ready" state allows a state to transition to the "ticking" state, while the "transient" state is used as a state for a region that may @@ -90,22 +91,22 @@ The regionizer does not operate on chunk coordinates, but rather on "region section coordinates." Region section coordinates simply represent a grouping of NxN chunks on a grid, where N is some power of two. The actual number is left ambiguous, as region section coordinates -are only an internal detail of how chunks are grouped. -For example, with N=16 the region section (0,0) encompasses all -chunks x in [0,15] and z in [0,15]. This concept is similar to how -the chunk coordinate (0,0) encompasses all blocks x in [0, 15] -and z in [0, 15]. Another example with N=16, the chunk (17, -5) is -contained within region section (1, -1). +are only an internal detail of how chunks are grouped. +For example, with N=16 the region section (0,0) encompasses all +chunks x in [0,15] and z in [0,15]. This concept is similar to how +the chunk coordinate (0,0) encompasses all blocks x in [0, 15] +and z in [0, 15]. Another example with N=16, the chunk (17, -5) is +contained within region section (1, -1). Region section coordinates are used only as a performance tradeoff in the regionizer, as by approximating chunks to their region coordinate allows it to treat NxN chunks as a single unit for regionizing. This means that regions do not own chunks positions, -but rather own region section positions. The grouping of NxN chunks -allows the regionizing logic to be performed only on +but rather own region section positions. The grouping of NxN chunks +allows the regionizing logic to be performed only on the creation/destruction of region sections. For example with N=16 this means up to NxN-1=255 possible -less operations in areas such as addChunk/region recalculation +less operations in areas such as addChunk/region recalculation assuming region sections are always full. ### Implementation variables @@ -119,33 +120,33 @@ The recalculation count is the minimum number of region sections that a region must own to allow it to re-calculate. Note that a recalculation operation simply calculates the set of independent regions that exist within a region to check if a split can be -performed. -This is a simple performance knob that allows split logic to be -turned off for small regions, as it is unlikely that small regions +performed. +This is a simple performance knob that allows split logic to be +turned off for small regions, as it is unlikely that small regions can be split in the first place. #### Max dead section percent -The max dead section percent is the minimum percent of dead +The max dead section percent is the minimum percent of dead sections in a region that must exist before a region can run re-calculation logic. #### Empty section creation radius The empty section creation radius variable is used to determine -how many empty region sections are to exist around _any_ -region section with at least one chunk. +how many empty region sections are to exist around _any_ +region section with at least one chunk. Internally, the regionizer enforces the third invariant by preventing ticking regions from owning new region sections. -The creation of empty sections around any non-empty section will +The creation of empty sections around any non-empty section will then enforce the second invariant. #### Region section merge radius The merge radius variable is used to ensure that for any existing region section x that for any other region section y within -the merge radius are either owned by region that owns x +the merge radius are either owned by region that owns x or are pending a merge into the region that owns x or that the region that owns x is pending a merge into the region that owns y. @@ -160,15 +161,15 @@ region coordinate = chunk coordinate >> region section chunk shift. The regionizer is operated by invoking `ThreadedRegionizer#addChunk(x, z)` or `ThreadedRegionizer#removeChunk(x, z)` when a chunk holder is created -or destroyed. +or destroyed. Additionally, `ThreadedRegion#tryMarkTicking` can be used by a caller that attempts to move a region from the "ready" state to the "ticking" -state. It is vital to note that this function will return false if +state. It is vital to note that this function will return false if the region is not in the "ready" state, as it is possible that even a region considered to be "ready" in the past (i.e. scheduled to tick) may be unexpectedly marked as "transient." Thus, the caller -needs to handle such cases. The caller that successfully marks +needs to handle such cases. The caller that successfully marks a region as ticking must mark it as non-ticking by using `ThreadedRegion#markNotTicking`. @@ -184,12 +185,12 @@ may additionally be considered "non-empty" if it contains at least one chunk position, and "empty" otherwise. A region section is considered "dead" if and only if the region section -is also "empty" and that there exist no other "empty" sections within the -empty section creation radius. +is also "empty" and that there exist no other "empty" sections within the +empty section creation radius. The existence of the dead section state is purely for performance, as it allows the recalculation logic of a region to be delayed until the region -contains enough dead sections. However, dead sections are still +contains enough dead sections. However, dead sections are still considered to belong to the region that owns them just as alive sections. ### Addition of chunks (`addChunk`) @@ -219,7 +220,7 @@ and no region state is modified, and the sections are added to this Merge logic needs to occur when there are more than 1 region in the set X. From the set X, a region x is selected that is not ticking. If -no such x exists, then a region x is created. Every region section +no such x exists, then a region x is created. Every region section created is added to the set x, as it is the section that is known to not be ticking - this is done to adhere to invariant third invariant. @@ -229,7 +230,7 @@ logic into y. ### Merge later logic -A merge later operation may only take place from +A merge later operation may only take place from a non-ticking, non-dead region x into a ticking region y. The merge later logic relies on maintaining a set of regions to merge into later per region, and another set of regions @@ -237,19 +238,19 @@ that are expected to merge into this region. Effectively, a merge into later operation from x into y will add y into x's merge into later set, and add x into y's expecting merge from set. -When the ticking region finishes ticking, the ticking region +When the ticking region finishes ticking, the ticking region will perform the merge logic for all expecting merges. ### Merge logic A merge operation may only take place between a dead region x -and another region y which may be either "transient" +and another region y which may be either "transient" or "ready." The region x is effectively absorbed into the region y, as the sections in x are moved to the region y. -The merge into later is also forwarded to the region y, +The merge into later is also forwarded to the region y, such so that the regions x was to merge into later, y will -now merge into later. +now merge into later. Additionally, if there is implementation specific data on region x, the region callback to merge the data into the @@ -258,8 +259,8 @@ region y is invoked. The state of the region y may be updated after a merge operation completes. For example, if the region x was "transient", then the region y should be downgraded to transient as well. Specifically, -the region y should be marked as transient if region x contained -merge later targets that were not y. The downgrading to transient is +the region y should be marked as transient if region x contained +merge later targets that were not y. The downgrading to transient is required to adhere to the second invariant. ### Removal of chunks (`removeChunk`) @@ -272,20 +273,20 @@ any region state, and nor will it purge region sections. ### Region tick start (`tryMarkTicking`) The tick start simply migrates the state to ticking, so that -invariants #2 and #3 can be met. +invariants #2 and #3 can be met. ### Region tick end (`markNotTicking`) At the end of a tick, the region's new state is not immediately known. -First, tt first must process its pending merges. +First, tt first must process its pending merges. -After it processes its pending merges, it must then check if the -region is now pending merge into any other region. If it is, then -it transitions to the transient state. +After it processes its pending merges, it must then check if the +region is now pending merge into any other region. If it is, then +it transitions to the transient state. -Otherwise, it will process the removal of dead sections and attempt -to split into smaller regions. Note that it is guaranteed +Otherwise, it will process the removal of dead sections and attempt +to split into smaller regions. Note that it is guaranteed that if a region can be possibly split, it must remove dead sections, -otherwise, this would contradict the rules used to build the region +otherwise, this would contradict the rules used to build the region in the first place. diff --git a/docs/paper/admin/getting-started/adding-plugins.md b/docs/paper/admin/getting-started/adding-plugins.md index 133e30dcb..cfd04b3a7 100644 --- a/docs/paper/admin/getting-started/adding-plugins.md +++ b/docs/paper/admin/getting-started/adding-plugins.md @@ -2,6 +2,7 @@ toc_max_heading_level: 4 slug: /adding-plugins description: Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files. +targetVersion: 1.21 --- # Adding Plugins diff --git a/docs/paper/admin/getting-started/getting-started.mdx b/docs/paper/admin/getting-started/getting-started.mdx index 75e382a71..28843b287 100644 --- a/docs/paper/admin/getting-started/getting-started.mdx +++ b/docs/paper/admin/getting-started/getting-started.mdx @@ -1,6 +1,7 @@ --- slug: /getting-started description: How to get started with downloading and setting up a Paper server. +targetVersion: 1.21 --- # Getting Started diff --git a/docs/paper/admin/getting-started/migration.md b/docs/paper/admin/getting-started/migration.md index be41c82bd..3097d45d9 100644 --- a/docs/paper/admin/getting-started/migration.md +++ b/docs/paper/admin/getting-started/migration.md @@ -2,6 +2,7 @@ slug: /migration title: Migrating to or from Paper description: It's simple to migrate your server to or from Paper. This page will help you get started. +targetVersion: 1.21 --- It's simple to migrate your server to or from Paper. The steps below will help you get started. diff --git a/docs/paper/admin/getting-started/setup-next-steps.md b/docs/paper/admin/getting-started/setup-next-steps.md index ce52d6e0e..ab5542efb 100644 --- a/docs/paper/admin/getting-started/setup-next-steps.md +++ b/docs/paper/admin/getting-started/setup-next-steps.md @@ -1,6 +1,7 @@ --- slug: /next-steps description: How to proceed after starting your server. +targetVersion: 1.21 --- # Next Steps diff --git a/docs/paper/admin/how-to/aikars-flags.md b/docs/paper/admin/how-to/aikars-flags.md index 1904e0afc..2a542be7e 100644 --- a/docs/paper/admin/how-to/aikars-flags.md +++ b/docs/paper/admin/how-to/aikars-flags.md @@ -1,6 +1,7 @@ --- slug: /aikars-flags description: Aikar's flags are a set of JVM flags designed to improve the performance of your Paper server. +targetVersion: 1.21 --- # Aikar's Flags diff --git a/docs/paper/admin/how-to/anti-xray.mdx b/docs/paper/admin/how-to/anti-xray.mdx index a1b9228f5..13f33f872 100644 --- a/docs/paper/admin/how-to/anti-xray.mdx +++ b/docs/paper/admin/how-to/anti-xray.mdx @@ -1,6 +1,7 @@ --- slug: /anti-xray description: Paper ships an obfuscation-based Anti-Xray system by default. Learn how to configure it here. +targetVersion: 1.21 --- # Configuring Anti-Xray diff --git a/docs/paper/admin/how-to/basic-troubleshooting.md b/docs/paper/admin/how-to/basic-troubleshooting.md index a8b83950c..bffa1f5a8 100644 --- a/docs/paper/admin/how-to/basic-troubleshooting.md +++ b/docs/paper/admin/how-to/basic-troubleshooting.md @@ -1,6 +1,7 @@ --- slug: /basic-troubleshooting description: This guide will help you diagnose your server's problem before reporting it to PaperMC or the plugin's author. +targetVersion: 1.21 --- # Basic Troubleshooting diff --git a/docs/paper/admin/how-to/get-to-vanilla.mdx b/docs/paper/admin/how-to/get-to-vanilla.mdx index fa99fe5a6..85c286258 100644 --- a/docs/paper/admin/how-to/get-to-vanilla.mdx +++ b/docs/paper/admin/how-to/get-to-vanilla.mdx @@ -1,6 +1,7 @@ --- slug: /vanilla description: This page lists all changes that result in a different experience than Vanilla. +targetVersion: 1.21 --- # Vanilla-like Experience diff --git a/docs/paper/admin/how-to/profiling.md b/docs/paper/admin/how-to/profiling.md index b51808ccd..dad9291ba 100644 --- a/docs/paper/admin/how-to/profiling.md +++ b/docs/paper/admin/how-to/profiling.md @@ -1,6 +1,7 @@ --- slug: /profiling description: How to profile your Paper server. +targetVersion: 1.21 --- # Profiling diff --git a/docs/paper/admin/how-to/update.md b/docs/paper/admin/how-to/update.md index a6a77157b..0e8e083df 100644 --- a/docs/paper/admin/how-to/update.md +++ b/docs/paper/admin/how-to/update.md @@ -1,6 +1,7 @@ --- slug: /updating description: Paper has new features and fixes coming every day, this guide explains the updating process. +targetVersion: 1.21 --- # Updating Paper diff --git a/docs/paper/admin/misc/faq.md b/docs/paper/admin/misc/faq.md index edafad1c2..fdd9bd483 100644 --- a/docs/paper/admin/misc/faq.md +++ b/docs/paper/admin/misc/faq.md @@ -1,13 +1,14 @@ --- slug: /faq description: Questions frequently asked by our community, answered by us! +targetVersion: 1.21 --- # Frequently Asked Questions ## Unsupported Java detected, what do I do?! -Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken. +Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken. As such, we cannot provide support for servers running such versions. You should install a supported version of Java as explained [here](/misc/java-install). diff --git a/docs/paper/admin/misc/paper-bug-fixes.md b/docs/paper/admin/misc/paper-bug-fixes.md index 41d479a0e..20e2204ca 100644 --- a/docs/paper/admin/misc/paper-bug-fixes.md +++ b/docs/paper/admin/misc/paper-bug-fixes.md @@ -1,6 +1,7 @@ --- slug: /misc/paper-bug-fixes description: An explanation of which Vanilla bugs we fix in Paper. +targetVersion: 1.21 --- # Paper Bug Fixes diff --git a/docs/paper/admin/reference/configuration/README.mdx b/docs/paper/admin/reference/configuration/README.mdx index a83366ed2..1289f3e56 100644 --- a/docs/paper/admin/reference/configuration/README.mdx +++ b/docs/paper/admin/reference/configuration/README.mdx @@ -1,5 +1,6 @@ --- slug: /reference/configuration +targetVersion: 1.21 --- # Paper Configuration diff --git a/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx b/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx index 450dc73c7..92ad60681 100644 --- a/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx +++ b/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx @@ -1,5 +1,6 @@ --- slug: /reference/bukkit-commands-configuration +targetVersion: 1.21 --- # Bukkit Commands Configuration diff --git a/docs/paper/admin/reference/configuration/bukkit-configuration.mdx b/docs/paper/admin/reference/configuration/bukkit-configuration.mdx index 1116f171c..8cbb0f2eb 100644 --- a/docs/paper/admin/reference/configuration/bukkit-configuration.mdx +++ b/docs/paper/admin/reference/configuration/bukkit-configuration.mdx @@ -1,6 +1,7 @@ --- slug: /reference/bukkit-configuration description: An explanation of Bukkit's configuration file. +targetVersion: 1.21 --- # Bukkit Configuration diff --git a/docs/paper/admin/reference/configuration/global-configuration.mdx b/docs/paper/admin/reference/configuration/global-configuration.mdx index 60ae08b4d..6cc7a0c4c 100644 --- a/docs/paper/admin/reference/configuration/global-configuration.mdx +++ b/docs/paper/admin/reference/configuration/global-configuration.mdx @@ -1,6 +1,7 @@ --- slug: /reference/global-configuration description: An explanation of Paper's global configuration file. +targetVersion: 1.21 --- # Global Configuration diff --git a/docs/paper/admin/reference/configuration/server-properties.mdx b/docs/paper/admin/reference/configuration/server-properties.mdx index 82382e4c4..9a74bb126 100644 --- a/docs/paper/admin/reference/configuration/server-properties.mdx +++ b/docs/paper/admin/reference/configuration/server-properties.mdx @@ -1,6 +1,7 @@ --- slug: /reference/server-properties description: An explanation of Minecraft's server.properties file. +targetVersion: 1.21 --- # Server Properties diff --git a/docs/paper/admin/reference/configuration/spigot-configuration.mdx b/docs/paper/admin/reference/configuration/spigot-configuration.mdx index 54c59c621..0d97909f0 100644 --- a/docs/paper/admin/reference/configuration/spigot-configuration.mdx +++ b/docs/paper/admin/reference/configuration/spigot-configuration.mdx @@ -1,6 +1,7 @@ --- slug: /reference/spigot-configuration description: An explanation of Spigot's configuration file. +targetVersion: 1.21 --- # Spigot Configuration diff --git a/docs/paper/admin/reference/configuration/world-configuration.mdx b/docs/paper/admin/reference/configuration/world-configuration.mdx index 750fe4096..71aaacadb 100644 --- a/docs/paper/admin/reference/configuration/world-configuration.mdx +++ b/docs/paper/admin/reference/configuration/world-configuration.mdx @@ -1,6 +1,7 @@ --- slug: /reference/world-configuration description: An explanation of Paper's world configuration file. +targetVersion: 1.21 --- # World Configuration diff --git a/docs/paper/admin/reference/paper-plugins.md b/docs/paper/admin/reference/paper-plugins.md index 52d527c09..3e0c97e6e 100644 --- a/docs/paper/admin/reference/paper-plugins.md +++ b/docs/paper/admin/reference/paper-plugins.md @@ -1,6 +1,7 @@ --- slug: /reference/paper-plugins description: A guide to the ins and outs of Paper plugins. +targetVersion: 1.21 --- # Paper Plugins diff --git a/docs/paper/admin/reference/system-properties.md b/docs/paper/admin/reference/system-properties.md index d39fb27b7..ee7fa975a 100644 --- a/docs/paper/admin/reference/system-properties.md +++ b/docs/paper/admin/reference/system-properties.md @@ -1,6 +1,7 @@ --- slug: /reference/system-properties description: Documentation for the system properties and environment variables Paper may check. +targetVersion: 1.21 --- # Paper System Properties diff --git a/docs/paper/admin/reference/vanilla-command-permissions.mdx b/docs/paper/admin/reference/vanilla-command-permissions.mdx index 5b1dadea8..6766c8e93 100644 --- a/docs/paper/admin/reference/vanilla-command-permissions.mdx +++ b/docs/paper/admin/reference/vanilla-command-permissions.mdx @@ -1,6 +1,7 @@ --- slug: /reference/permissions description: All permissions available in the default Paper server. +targetVersion: 1.21 --- # Permissions diff --git a/docs/paper/dev/api/command-api/arguments.mdx b/docs/paper/dev/api/command-api/arguments.mdx index 06aae8d24..22b763200 100644 --- a/docs/paper/dev/api/command-api/arguments.mdx +++ b/docs/paper/dev/api/command-api/arguments.mdx @@ -1,6 +1,7 @@ --- slug: /dev/command-api/arguments description: A guide to arguments in Paper's Brigadier command API. +targetVersion: 1.21 --- # Arguments diff --git a/docs/paper/dev/api/command-api/commands.mdx b/docs/paper/dev/api/command-api/commands.mdx index e6040d5f5..313dc2e73 100644 --- a/docs/paper/dev/api/command-api/commands.mdx +++ b/docs/paper/dev/api/command-api/commands.mdx @@ -1,6 +1,7 @@ --- slug: /dev/command-api/commands description: A guide to Paper's Brigadier command API. +targetVersion: 1.21 --- # Commands diff --git a/docs/paper/dev/api/component-api/audiences.mdx b/docs/paper/dev/api/component-api/audiences.mdx index d562eb522..1daf809c7 100644 --- a/docs/paper/dev/api/component-api/audiences.mdx +++ b/docs/paper/dev/api/component-api/audiences.mdx @@ -2,6 +2,7 @@ slug: /dev/component-api/audiences description: How to use Adventure's Audiences. title: Audiences +targetVersion: 1.21 --- Audiences wrap a collection of recipients that can receive messages. They can be used to send messages to individual diff --git a/docs/paper/dev/api/component-api/i18n.mdx b/docs/paper/dev/api/component-api/i18n.mdx index 0be99e29d..bd0026c9a 100644 --- a/docs/paper/dev/api/component-api/i18n.mdx +++ b/docs/paper/dev/api/component-api/i18n.mdx @@ -2,6 +2,7 @@ slug: /dev/component-api/i18n description: How to use Adventure's internationalization. title: Internationalization +targetVersion: 1.21 --- Generally it's a good idea to support translations in your plugin, especially if you want to diff --git a/docs/paper/dev/api/component-api/intro.mdx b/docs/paper/dev/api/component-api/intro.mdx index a7d6b5d13..296cc0314 100644 --- a/docs/paper/dev/api/component-api/intro.mdx +++ b/docs/paper/dev/api/component-api/intro.mdx @@ -2,6 +2,7 @@ slug: /dev/component-api/introduction description: An introduction to how components work. title: Introduction +targetVersion: 1.21 --- :::note diff --git a/docs/paper/dev/api/custom-inventory-holder.mdx b/docs/paper/dev/api/custom-inventory-holder.mdx index 61fbb5f66..8bccc1bf2 100644 --- a/docs/paper/dev/api/custom-inventory-holder.mdx +++ b/docs/paper/dev/api/custom-inventory-holder.mdx @@ -1,6 +1,7 @@ --- slug: /dev/custom-inventory-holder description: How to use a custom InventoryHolder to identify custom inventories. +targetVersion: 1.21 --- # Custom `InventoryHolder` diff --git a/docs/paper/dev/api/entity-api/display-entities.mdx b/docs/paper/dev/api/entity-api/display-entities.mdx index 6a0e6a454..2ead9e634 100644 --- a/docs/paper/dev/api/entity-api/display-entities.mdx +++ b/docs/paper/dev/api/entity-api/display-entities.mdx @@ -1,6 +1,7 @@ --- slug: /dev/display-entities description: The display entity API and how to use it. +targetVersion: 1.21 --- # Display Entities diff --git a/docs/paper/dev/api/entity-api/entity-teleport.mdx b/docs/paper/dev/api/entity-api/entity-teleport.mdx index c833c01f8..c85972982 100644 --- a/docs/paper/dev/api/entity-api/entity-teleport.mdx +++ b/docs/paper/dev/api/entity-api/entity-teleport.mdx @@ -1,6 +1,7 @@ --- slug: /dev/entity-teleport description: The entity teleportation API and how to use it. +targetVersion: 1.21 --- # Teleportation diff --git a/docs/paper/dev/api/event-api/chat-event.mdx b/docs/paper/dev/api/event-api/chat-event.mdx index aff0c8be6..5916f0170 100644 --- a/docs/paper/dev/api/event-api/chat-event.mdx +++ b/docs/paper/dev/api/event-api/chat-event.mdx @@ -1,6 +1,7 @@ --- slug: /dev/chat-events description: An outline on AsyncChatEvent and how to handle it. +targetVersion: 1.21 --- # Chat Events diff --git a/docs/paper/dev/api/event-api/custom-events.mdx b/docs/paper/dev/api/event-api/custom-events.mdx index 4908b0387..c0ab627a2 100644 --- a/docs/paper/dev/api/event-api/custom-events.mdx +++ b/docs/paper/dev/api/event-api/custom-events.mdx @@ -1,11 +1,12 @@ --- slug: /dev/custom-events description: A guide to show you how to add custom events to your plugin. +targetVersion: 1.21 --- # Custom Events -Creating custom events is a great way to add functionality to your plugin. +Creating custom events is a great way to add functionality to your plugin. This will allow other plugins to listen to your custom events and add functionality to your plugin. ## Creating a custom event @@ -40,7 +41,7 @@ public class PaperIsCoolEvent extends Event { } ``` -Now that we have created our event, we can add some functionality to it. +Now that we have created our event, we can add some functionality to it. Perhaps this will contain a message that will be broadcast to the server when the event is called. ```java title="PaperIsCoolEvent.java" @@ -85,7 +86,7 @@ public class ExamplePlugin extends JavaPlugin { PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); coolEvent.callEvent(); // Plugins could have changed the message from inside their listeners here. So we need to get the message again. - // This event structure allows for other plugins to change the message to their taste. + // This event structure allows for other plugins to change the message to their taste. // Like, for example, a plugin that adds a prefix to all messages. Bukkit.broadcast(coolEvent.getMessage()); } diff --git a/docs/paper/dev/api/event-api/event-listeners.mdx b/docs/paper/dev/api/event-api/event-listeners.mdx index 522d2f606..f48cf1959 100644 --- a/docs/paper/dev/api/event-api/event-listeners.mdx +++ b/docs/paper/dev/api/event-api/event-listeners.mdx @@ -1,6 +1,7 @@ --- slug: /dev/event-listeners description: Developer guide for how to listen to the broadcasted events. +targetVersion: 1.21 --- # Event Listeners diff --git a/docs/paper/dev/api/event-api/handler-lists.mdx b/docs/paper/dev/api/event-api/handler-lists.mdx index 511bb2c77..b225e551d 100644 --- a/docs/paper/dev/api/event-api/handler-lists.mdx +++ b/docs/paper/dev/api/event-api/handler-lists.mdx @@ -1,6 +1,7 @@ --- slug: /dev/handler-lists description: An explanation to what an event's HandlerList is. +targetVersion: 1.21 --- # Handler Lists @@ -21,9 +22,9 @@ public class ExampleListener implements Listener { HandlerList handlerList = event.getHandlerList(); // ... } - + // Or: - + public ExampleListener() { // Access the handler list through the static getter HandlerList handlerList = PlayerJoinEvent.getHandlerList(); @@ -45,9 +46,9 @@ public class ExampleListener implements Listener { handlerList.unregister(this); // ... } - + // Or: - + public ExampleListener() { // Access the handler list through the static getter HandlerList handlerList = PlayerJoinEvent.getHandlerList(); diff --git a/docs/paper/dev/api/folia-support.mdx b/docs/paper/dev/api/folia-support.mdx index d105db95f..e1ab831ff 100644 --- a/docs/paper/dev/api/folia-support.mdx +++ b/docs/paper/dev/api/folia-support.mdx @@ -1,13 +1,14 @@ --- slug: /dev/folia-support description: How to support both Folia and Paper within your plugin. +targetVersion: 1.21 --- # Supporting Paper and Folia ![](/img/folia.png) -[Folia](https://github.com/PaperMC/Folia) is a fork of Paper, which is currently maintained by the PaperMC team. +[Folia](https://github.com/PaperMC/Folia) is a fork of Paper, which is currently maintained by the PaperMC team. It adds the ability to split the world into regions as outlined [here](/folia/reference/overview) in more depth. # Checking for Folia @@ -28,7 +29,7 @@ private static boolean isFolia() { ## Schedulers -In order to support Paper and Folia, you must use the correct scheduler. Folia has different types of schedulers +In order to support Paper and Folia, you must use the correct scheduler. Folia has different types of schedulers that can be used for different things. They are: - [Global](#global-scheduler) @@ -47,7 +48,7 @@ GlobalRegionScheduler globalScheduler = server.getGlobalRegionScheduler(); ``` ### Region scheduler -The region scheduler will be in charge of running tasks for the region that owns a certain location. Do not use this scheduler for +The region scheduler will be in charge of running tasks for the region that owns a certain location. Do not use this scheduler for operations on entities, as this scheduler is tied to the region. Each entity has its [own scheduler](#entity-scheduler) which will follow it across regions. As an example, let's say I want to set a block to a beehive: ```java diff --git a/docs/paper/dev/api/lifecycle.mdx b/docs/paper/dev/api/lifecycle.mdx index 68a138ec4..c4cde9cfe 100644 --- a/docs/paper/dev/api/lifecycle.mdx +++ b/docs/paper/dev/api/lifecycle.mdx @@ -1,6 +1,7 @@ --- slug: /dev/lifecycle description: A guide to Paper's Lifecycle API +targetVersion: 1.21 --- # Lifecycle API diff --git a/docs/paper/dev/api/pdc.mdx b/docs/paper/dev/api/pdc.mdx index 2b50268f9..d5593249f 100644 --- a/docs/paper/dev/api/pdc.mdx +++ b/docs/paper/dev/api/pdc.mdx @@ -1,6 +1,7 @@ --- slug: /dev/pdc description: A guide to the PDC API for storing data. +targetVersion: 1.21 --- # Persistent Data Container (PDC) diff --git a/docs/paper/dev/api/plugin-configs.mdx b/docs/paper/dev/api/plugin-configs.mdx index 9d6705b9a..48d1ae3a9 100644 --- a/docs/paper/dev/api/plugin-configs.mdx +++ b/docs/paper/dev/api/plugin-configs.mdx @@ -1,6 +1,7 @@ --- slug: /dev/plugin-configurations description: How to create configuration files for your plugins to customize behavior. +targetVersion: 1.21 --- # Plugin Configurations diff --git a/docs/paper/dev/api/plugin-messaging.mdx b/docs/paper/dev/api/plugin-messaging.mdx index ba92e98ba..222b2d4af 100644 --- a/docs/paper/dev/api/plugin-messaging.mdx +++ b/docs/paper/dev/api/plugin-messaging.mdx @@ -1,6 +1,7 @@ --- slug: /dev/plugin-messaging description: How to communicate with clients or proxies. +targetVersion: 1.21 --- # Plugin Messaging diff --git a/docs/paper/dev/api/recipes.mdx b/docs/paper/dev/api/recipes.mdx index e669e178f..b4fe6ebee 100644 --- a/docs/paper/dev/api/recipes.mdx +++ b/docs/paper/dev/api/recipes.mdx @@ -1,6 +1,7 @@ --- slug: /dev/recipes description: How to create and manage recipes. +targetVersion: 1.21 --- # Recipe API diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 0c282415c..9940b73af 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -1,6 +1,7 @@ --- slug: /dev/registries description: A guide to registries and their modification on Paper. +targetVersion: 1.21 --- # Registries diff --git a/docs/paper/dev/api/roadmap.mdx b/docs/paper/dev/api/roadmap.mdx index d6d0003fb..33fa6de4f 100644 --- a/docs/paper/dev/api/roadmap.mdx +++ b/docs/paper/dev/api/roadmap.mdx @@ -1,13 +1,14 @@ --- slug: /dev/roadmap description: Outlines the future intents and plans of the Paper project. +targetVersion: 1.21 --- # Roadmap Paper offers a rich API with a wide range of features that can help you unlock the full potential of your server. -However, in order to make room for new features and improvements, some of the older APIs will be phased out. This page -is intended to document any future API changes that are planned or possible deprecations that may be coming up. +However, in order to make room for new features and improvements, some of the older APIs will be phased out. This page +is intended to document any future API changes that are planned or possible deprecations that may be coming up. ## Future plans @@ -61,7 +62,7 @@ public void exampleMethod(); // Example deprecated method In addition to being marked as `@Deprecated`, API may be marked as `forRemoval` with a given [`@ApiStatus.ScheduledForRemoval`](https://javadoc.io/doc/org.jetbrains/annotations/latest/org/jetbrains/annotations/ApiStatus.ScheduledForRemoval.html) version. API scheduled for removal should only occur within major release versions of Minecraft. -It is highly recommended you migrate away from API scheduled for removal. +It is highly recommended you migrate away from API scheduled for removal. It should be noted, that API scheduled for removal will be given adequate time to allow plugin developers to migrate away from said API. @@ -85,15 +86,15 @@ therefore it may be scheduled for removal. ### Duplicate API -As Paper continues to upstream Spigot, it can occasionally include APIs that clash with what Paper already has. -Typically, Paper will deprecate Spigot’s API in favor of their own API. +As Paper continues to upstream Spigot, it can occasionally include APIs that clash with what Paper already has. +Typically, Paper will deprecate Spigot’s API in favor of their own API. However, in cases where upstream offers a more powerful API, Paper’s may be deprecated instead. While Paper is still upstreaming Spigot, any API introduced by Spigot will continue to function, and will not be removed. ### Obsolete API -Paper strives to improve on APIs that may already be included. There may be some cases where we have built new +Paper strives to improve on APIs that may already be included. There may be some cases where we have built new APIs to offer as a replacement to another. Obsolete API is expected for function for the far future and may not be scheduled for removal diff --git a/docs/paper/dev/api/scheduler.mdx b/docs/paper/dev/api/scheduler.mdx index 090d7a5d4..8254e62a8 100644 --- a/docs/paper/dev/api/scheduler.mdx +++ b/docs/paper/dev/api/scheduler.mdx @@ -1,6 +1,7 @@ --- slug: /dev/scheduler description: A guide on how to use BukkitScheduler to run code at specific times. +targetVersion: 1.21 --- # Using the Scheduler @@ -19,7 +20,7 @@ Every game runs something called a game loop ,which essentially executes all the A single execution of that loop in Minecraft is called a 'tick'. In Minecraft, there are 20 ticks per second or in other words, one tick every 50 milliseconds. This means that the game loop is executed -20 times per second. A tick taking more than 50ms to execute is the moment when your server starts to fall behind on +20 times per second. A tick taking more than 50ms to execute is the moment when your server starts to fall behind on its work and lag. A task that should run after 100 ticks will run after 5 seconds (100 ticks / 20 ticks per second = 5 seconds). However, @@ -30,14 +31,14 @@ seconds. Every method of the scheduler that takes a delay or period uses ticks as a unit of time. -Converting from human units to ticks and back is as simple as: -- `ticks = seconds * 20` +Converting from human units to ticks and back is as simple as: +- `ticks = seconds * 20` - `seconds = ticks / 20` You can make your code more readable by using the `TimeUnit` -enum, e.g. to convert 5 minutes to ticks and back: -- `TimeUnit.MINUTES.toSeconds(5) * 20` +enum, e.g. to convert 5 minutes to ticks and back: +- `TimeUnit.MINUTES.toSeconds(5) * 20` - `TimeUnit.SECONDS.toMinutes(ticks / 20)` You can also use the `Tick` class from Paper to convert between human units and ticks, e.g. to convert 5 minutes to ticks: @@ -83,7 +84,7 @@ your server's performance. :::warning -**Large portions of the Bukkit API are not safe to use from within asynchronous tasks**. If a method changes or +**Large portions of the Bukkit API are not safe to use from within asynchronous tasks**. If a method changes or accesses the world state, it is not safe to be used from an asynchronous task. ::: @@ -112,11 +113,11 @@ You can either implement it in a separate class, e.g.: public class MyRunnableTask implements Runnable { private final MyPlugin plugin; - + public MyRunnableTask(MyPlugin plugin) { this.plugin = plugin; } - + @Override public void run() { this.plugin.getServer().broadcast(Component.text("Hello, World!")); @@ -214,7 +215,7 @@ public class CustomRunnable extends BukkitRunnable { } ``` -This simply adds a potion effect until the entity dies. +This simply adds a potion effect until the entity dies. #### Using a delay of 0 ticks diff --git a/docs/paper/dev/getting-started/how-do-plugins-work.mdx b/docs/paper/dev/getting-started/how-do-plugins-work.mdx index be0419d78..1de268995 100644 --- a/docs/paper/dev/getting-started/how-do-plugins-work.mdx +++ b/docs/paper/dev/getting-started/how-do-plugins-work.mdx @@ -1,6 +1,7 @@ --- slug: /dev/how-do-plugins-work description: How plugins work in Paper. +targetVersion: 1.21 --- # How Plugins Work diff --git a/docs/paper/dev/getting-started/paper-plugins.mdx b/docs/paper/dev/getting-started/paper-plugins.mdx index b24fbec07..d276cc7d9 100644 --- a/docs/paper/dev/getting-started/paper-plugins.mdx +++ b/docs/paper/dev/getting-started/paper-plugins.mdx @@ -1,6 +1,7 @@ --- slug: /dev/getting-started/paper-plugins description: A development guide for how to write Paper-specific plugins. +targetVersion: 1.21 --- # Paper Plugins (Experimental) diff --git a/docs/paper/dev/getting-started/plugin-yml.mdx b/docs/paper/dev/getting-started/plugin-yml.mdx index 909a9a640..b3f276c89 100644 --- a/docs/paper/dev/getting-started/plugin-yml.mdx +++ b/docs/paper/dev/getting-started/plugin-yml.mdx @@ -1,6 +1,7 @@ --- slug: /dev/plugin-yml description: A guide to Bukkit's plugin.yml file. +targetVersion: 1.21 --- # Bukkit Plugin YML diff --git a/docs/paper/dev/getting-started/project-setup.mdx b/docs/paper/dev/getting-started/project-setup.mdx index ecdb23024..2e76e8c93 100644 --- a/docs/paper/dev/getting-started/project-setup.mdx +++ b/docs/paper/dev/getting-started/project-setup.mdx @@ -1,6 +1,7 @@ --- slug: /dev/project-setup description: Step-by-step instructions on how to set up a plugin development environment. +targetVersion: 1.21 --- import Tabs from '@theme/Tabs'; diff --git a/docs/paper/dev/getting-started/userdev.mdx b/docs/paper/dev/getting-started/userdev.mdx index 87e42331e..0364673f9 100644 --- a/docs/paper/dev/getting-started/userdev.mdx +++ b/docs/paper/dev/getting-started/userdev.mdx @@ -2,6 +2,7 @@ slug: /dev/userdev sidebar_label: Paperweight Userdev description: A guide on how to use the paperweight-userdev Gradle plugin to access internal code. +targetVersion: 1.21 --- # paperweight-userdev diff --git a/docs/paper/dev/misc/databases.mdx b/docs/paper/dev/misc/databases.mdx index 3a8e86c64..625364869 100644 --- a/docs/paper/dev/misc/databases.mdx +++ b/docs/paper/dev/misc/databases.mdx @@ -1,6 +1,7 @@ --- slug: dev/using-databases description: Databases are the recommended way to store a large amount of data. This guide outlines a few key details. +targetVersion: 1.21 --- # Using Databases diff --git a/docs/paper/dev/misc/debugging.mdx b/docs/paper/dev/misc/debugging.mdx index dba3b4379..0cd23b5c1 100644 --- a/docs/paper/dev/misc/debugging.mdx +++ b/docs/paper/dev/misc/debugging.mdx @@ -1,6 +1,7 @@ --- slug: /dev/debugging description: Debugging is common when writing code. This guide outlines the common ways to debug your plugin. +targetVersion: 1.21 --- # Debugging Your Plugin diff --git a/docs/paper/dev/misc/internal-code.mdx b/docs/paper/dev/misc/internal-code.mdx index ca0d4f81d..5b110e418 100644 --- a/docs/paper/dev/misc/internal-code.mdx +++ b/docs/paper/dev/misc/internal-code.mdx @@ -1,6 +1,7 @@ --- slug: /dev/internals description: A brief overview of how to use internals in your plugin. +targetVersion: 1.21 --- # Minecraft Internals diff --git a/docs/paper/dev/misc/reading-stacktraces.mdx b/docs/paper/dev/misc/reading-stacktraces.mdx index c32dbe9b3..474a76ddd 100644 --- a/docs/paper/dev/misc/reading-stacktraces.mdx +++ b/docs/paper/dev/misc/reading-stacktraces.mdx @@ -1,6 +1,7 @@ --- slug: /dev/reading-stacktraces description: Stacktraces are produced by the JVM when an exception occurs. This guide will discuss the basics of how to read them. +targetVersion: 1.21 --- # Reading Stacktraces diff --git a/docs/velocity/admin/getting-started/README.mdx b/docs/velocity/admin/getting-started/README.mdx index e63e6d571..9d65f77cc 100644 --- a/docs/velocity/admin/getting-started/README.mdx +++ b/docs/velocity/admin/getting-started/README.mdx @@ -1,5 +1,6 @@ --- slug: /getting-started +targetVersion: 1.21 --- # Getting Started diff --git a/docs/velocity/admin/getting-started/faq.mdx b/docs/velocity/admin/getting-started/faq.mdx index 039fa36f7..f68b674b6 100644 --- a/docs/velocity/admin/getting-started/faq.mdx +++ b/docs/velocity/admin/getting-started/faq.mdx @@ -1,6 +1,7 @@ --- slug: /faq description: Frequently asked Velocity administration questions. +targetVersion: 1.21 --- # Frequently Asked Questions diff --git a/docs/velocity/admin/getting-started/forwarding.md b/docs/velocity/admin/getting-started/forwarding.md index 05a3c52cb..dfa585534 100644 --- a/docs/velocity/admin/getting-started/forwarding.md +++ b/docs/velocity/admin/getting-started/forwarding.md @@ -1,6 +1,7 @@ --- slug: /player-information-forwarding description: How to configure information forwarding on Velocity. +targetVersion: 1.21 --- # Configuring player information forwarding diff --git a/docs/velocity/admin/getting-started/why-velocity.md b/docs/velocity/admin/getting-started/why-velocity.md index 7da487af5..ecfdfdb73 100644 --- a/docs/velocity/admin/getting-started/why-velocity.md +++ b/docs/velocity/admin/getting-started/why-velocity.md @@ -1,6 +1,7 @@ --- slug: /why-velocity description: An explanation for why you should run Velocity. +targetVersion: 1.21 --- # What Does Velocity Do For Me? diff --git a/docs/velocity/admin/how-to/migration.md b/docs/velocity/admin/how-to/migration.md index a331c636c..f1de3098f 100644 --- a/docs/velocity/admin/how-to/migration.md +++ b/docs/velocity/admin/how-to/migration.md @@ -1,6 +1,7 @@ --- slug: /migration description: How to migrate your proxy between different Velocity versions. +targetVersion: 1.21 --- # Migration Guide diff --git a/docs/velocity/admin/how-to/security.md b/docs/velocity/admin/how-to/security.md index 3cf1b92bc..174e2b928 100644 --- a/docs/velocity/admin/how-to/security.md +++ b/docs/velocity/admin/how-to/security.md @@ -1,6 +1,7 @@ --- slug: /security description: An explanation of how to secure your servers. +targetVersion: 1.21 --- # Securing Your Servers diff --git a/docs/velocity/admin/how-to/tuning.md b/docs/velocity/admin/how-to/tuning.md index 866aed535..ad9dca950 100644 --- a/docs/velocity/admin/how-to/tuning.md +++ b/docs/velocity/admin/how-to/tuning.md @@ -1,6 +1,7 @@ --- slug: /tuning description: How to tune Velocity to allow for even better performance. +targetVersion: 1.21 --- # Tuning Velocity diff --git a/docs/velocity/admin/reference/commands.md b/docs/velocity/admin/reference/commands.md index 5597b8a24..8cde3e33a 100644 --- a/docs/velocity/admin/reference/commands.md +++ b/docs/velocity/admin/reference/commands.md @@ -1,6 +1,7 @@ --- slug: /built-in-commands description: A list of the built-in commands with explanations. +targetVersion: 1.21 --- # Built-In Commands diff --git a/docs/velocity/admin/reference/comparison.md b/docs/velocity/admin/reference/comparison.md index 66e657af3..0c775cd81 100644 --- a/docs/velocity/admin/reference/comparison.md +++ b/docs/velocity/admin/reference/comparison.md @@ -1,6 +1,7 @@ --- slug: /comparisons-to-other-proxies description: A comparison of Velocity to other proxies. +targetVersion: 1.21 --- # Comparing With Other Proxies @@ -72,7 +73,7 @@ Meet [Hyrum's Law](https://www.hyrumslaw.com/): Here's Hyrum's law in comic format, in case that eases getting the point across: -> [![xkcd #1172](https://imgs.xkcd.com/comics/workflow.png)](https://xkcd.com/1172/) +> [![xkcd #1172](https://imgs.xkcd.com/comics/workflow.png)](https://xkcd.com/1172/) > ["Workflow"](https://xkcd.com/1172/) from [xkcd](https://xkcd.com/) by Randal Munroe, > [licensed](https://xkcd.com/license.html) under > [CC BY-NC 2.5](https://creativecommons.org/licenses/by-nc/2.5/) diff --git a/docs/velocity/admin/reference/configuration.md b/docs/velocity/admin/reference/configuration.md index a23df55de..90f4b3049 100644 --- a/docs/velocity/admin/reference/configuration.md +++ b/docs/velocity/admin/reference/configuration.md @@ -1,6 +1,7 @@ --- slug: /configuration description: Velocity is designed to be easy to configure and this guide will walk you through how to do so. +targetVersion: 1.21 --- # Configuring Velocity diff --git a/docs/velocity/admin/reference/libraries.md b/docs/velocity/admin/reference/libraries.md index aea776137..5281062fa 100644 --- a/docs/velocity/admin/reference/libraries.md +++ b/docs/velocity/admin/reference/libraries.md @@ -1,6 +1,7 @@ --- slug: /credits description: The credits for all the different libraries used by Velocity. +targetVersion: 1.21 --- # Libraries Used diff --git a/docs/velocity/admin/reference/server-compatibility.mdx b/docs/velocity/admin/reference/server-compatibility.mdx index 9dca66f90..b9e8f9127 100644 --- a/docs/velocity/admin/reference/server-compatibility.mdx +++ b/docs/velocity/admin/reference/server-compatibility.mdx @@ -1,6 +1,7 @@ --- slug: /server-compatibility description: A guide to the server compatibility for Velocity. +targetVersion: 1.21 --- # Server Compatibility diff --git a/docs/velocity/admin/reference/system-properties.md b/docs/velocity/admin/reference/system-properties.md index 58520eb7e..d0a1ea03f 100644 --- a/docs/velocity/admin/reference/system-properties.md +++ b/docs/velocity/admin/reference/system-properties.md @@ -1,6 +1,7 @@ --- slug: /reference/system-properties description: Documentation for the system properties Velocity may check. +targetVersion: 1.21 --- # Velocity System Properties diff --git a/docs/velocity/dev/api/command.mdx b/docs/velocity/dev/api/command.mdx index 9a75a0460..bae79e0d9 100644 --- a/docs/velocity/dev/api/command.mdx +++ b/docs/velocity/dev/api/command.mdx @@ -1,6 +1,7 @@ --- slug: /dev/command-api description: How to create commands within Velocity. +targetVersion: 1.21 --- # The Command API diff --git a/docs/velocity/dev/api/component-api/audiences.mdx b/docs/velocity/dev/api/component-api/audiences.mdx index 06effac73..e7e075759 100644 --- a/docs/velocity/dev/api/component-api/audiences.mdx +++ b/docs/velocity/dev/api/component-api/audiences.mdx @@ -2,6 +2,7 @@ slug: /dev/component-api/audiences description: How to use Adventure's Audiences. title: Audiences +targetVersion: 1.21 --- import Audiences from "@site/docs/paper/dev/api/component-api/audiences.mdx"; diff --git a/docs/velocity/dev/api/component-api/i18n.mdx b/docs/velocity/dev/api/component-api/i18n.mdx index 097edcf09..7f9f44589 100644 --- a/docs/velocity/dev/api/component-api/i18n.mdx +++ b/docs/velocity/dev/api/component-api/i18n.mdx @@ -2,6 +2,7 @@ slug: /dev/component-api/i18n description: How to use Adventure's internationalization. title: Internationalization +targetVersion: 1.21 --- import Internationalization from "@site/docs/paper/dev/api/component-api/i18n.mdx"; diff --git a/docs/velocity/dev/api/component-api/intro.mdx b/docs/velocity/dev/api/component-api/intro.mdx index 81eae823f..6302445a6 100644 --- a/docs/velocity/dev/api/component-api/intro.mdx +++ b/docs/velocity/dev/api/component-api/intro.mdx @@ -2,6 +2,7 @@ slug: /dev/component-api/introduction description: An introduction to how components work. title: Introduction +targetVersion: 1.21 --- import Introduction from "@site/docs/paper/dev/api/component-api/intro.mdx"; diff --git a/docs/velocity/dev/api/event.mdx b/docs/velocity/dev/api/event.mdx index c06211bd3..36ca432ff 100644 --- a/docs/velocity/dev/api/event.mdx +++ b/docs/velocity/dev/api/event.mdx @@ -1,6 +1,7 @@ --- slug: /dev/event-api description: How to listen for events in Velocity. +targetVersion: 1.21 --- # Working With Events @@ -35,7 +36,7 @@ and _not_ in `com.google.common.eventbus`. Every listener has a `priority`. When an event is fired, the order in which listeners are invoked is defined by their `priority`. -The higher the priority, the earlier the event handler will be called. +The higher the priority, the earlier the event handler will be called. State the desired order in the `@Subscribe` annotation: diff --git a/docs/velocity/dev/api/plugin-messaging.mdx b/docs/velocity/dev/api/plugin-messaging.mdx index e3fe5c3ec..177c3d7e3 100644 --- a/docs/velocity/dev/api/plugin-messaging.mdx +++ b/docs/velocity/dev/api/plugin-messaging.mdx @@ -1,6 +1,7 @@ --- slug: /dev/plugin-messaging description: How to handle and send plugin messages on Velocity. +targetVersion: 1.21 --- # Plugin Messaging diff --git a/docs/velocity/dev/api/scheduler.mdx b/docs/velocity/dev/api/scheduler.mdx index bbc15e042..8bb31570c 100644 --- a/docs/velocity/dev/api/scheduler.mdx +++ b/docs/velocity/dev/api/scheduler.mdx @@ -1,6 +1,7 @@ --- slug: /dev/scheduler-api description: A guide to the Scheduler API within Velocity allowing tasks to be run. +targetVersion: 1.21 --- # Using the Scheduler diff --git a/docs/velocity/dev/getting-started/api-basics.mdx b/docs/velocity/dev/getting-started/api-basics.mdx index 141ed978d..646b4afa1 100644 --- a/docs/velocity/dev/getting-started/api-basics.mdx +++ b/docs/velocity/dev/getting-started/api-basics.mdx @@ -1,6 +1,7 @@ --- slug: /dev/api-basics description: How to get started with the Velocity API. +targetVersion: 1.21 --- # Velocity Plugin Basics diff --git a/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx b/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx index c2dfbaae0..10fcee3a4 100644 --- a/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx @@ -1,6 +1,7 @@ --- slug: /dev/creating-your-first-plugin description: How to create your first plugin with the Velocity API. +targetVersion: 1.21 --- import Tabs from '@theme/Tabs'; diff --git a/docs/velocity/dev/getting-started/pitfalls.mdx b/docs/velocity/dev/getting-started/pitfalls.mdx index 3de5853ec..9e680dd58 100644 --- a/docs/velocity/dev/getting-started/pitfalls.mdx +++ b/docs/velocity/dev/getting-started/pitfalls.mdx @@ -1,6 +1,7 @@ --- slug: /dev/pitfalls description: How to avoid common pitfalls within Velocity. +targetVersion: 1.21 --- # Common Pitfalls diff --git a/docs/velocity/dev/how-to/dependencies.mdx b/docs/velocity/dev/how-to/dependencies.mdx index 03c262a5e..e1af1ce5e 100644 --- a/docs/velocity/dev/how-to/dependencies.mdx +++ b/docs/velocity/dev/how-to/dependencies.mdx @@ -1,6 +1,7 @@ --- slug: /dev/dependency-management description: How to handle dependencies within your Velocity plugin. +targetVersion: 1.21 --- # Dependency Management diff --git a/docs/velocity/dev/how-to/porting-from-velocity-1.mdx b/docs/velocity/dev/how-to/porting-from-velocity-1.mdx index 1af91d5d2..2c6079c41 100644 --- a/docs/velocity/dev/how-to/porting-from-velocity-1.mdx +++ b/docs/velocity/dev/how-to/porting-from-velocity-1.mdx @@ -1,6 +1,7 @@ --- slug: /dev/porting-plugins-from-velocity-1 description: How to port your plugin from Velocity 1.x.x to modern API. +targetVersion: 1.21 --- # Porting Your Plugin from Velocity 1.x.x diff --git a/docs/versioned/paper.json b/docs/versioned/paper.json deleted file mode 100644 index 30191e2e9..000000000 --- a/docs/versioned/paper.json +++ /dev/null @@ -1,5 +0,0 @@ -[ - "1.20", - "1.19", - "1.18" -] diff --git a/docs/versioned/paper/content/1.18/README.md b/docs/versioned/paper/content/1.18/README.md deleted file mode 100644 index 695105c6c..000000000 --- a/docs/versioned/paper/content/1.18/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Welcome to the Paper Docs - -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. diff --git a/docs/versioned/paper/content/1.18/admin/README.mdx b/docs/versioned/paper/content/1.18/admin/README.mdx deleted file mode 100644 index c5d37505e..000000000 --- a/docs/versioned/paper/content/1.18/admin/README.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -slug: /admin ---- - -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Paper Server Administration - -Welcome to the Paper Server Administration Guide! This guide includes information and tutorials -regarding the administration of a Paper server. - ---- - - diff --git a/docs/versioned/paper/content/1.18/admin/getting-started/adding-plugins.md b/docs/versioned/paper/content/1.18/admin/getting-started/adding-plugins.md deleted file mode 100644 index b6e476ec8..000000000 --- a/docs/versioned/paper/content/1.18/admin/getting-started/adding-plugins.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -toc_max_heading_level: 4 -slug: /adding-plugins ---- - -# Adding Plugins - -Plugins are the most powerful way to extend the functionality of Paper beyond the configuration -files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow, -to adding entirely new and original game modes or items. - -:::danger[Malicious Plugins] - -Ensure you fully trust the source of any plugin before installing it. Plugins are given **full and -unrestricted** access to not only your server but also the machine that it runs on. Because of this, -it is imperative that plugins only be installed from trusted sources. Be careful! - -::: - -## Finding Plugins - -Before installing a plugin, you'll need to find what you want to install. Most plugins can be found -on [SpigotMC](https://www.spigotmc.org/resources/), -[BukkitDev](https://dev.bukkit.org/bukkit-plugins), or the -[PaperMC Forums](https://forums.papermc.io/forums/paper-plugin-releases/), while other plugins may -release on [GitHub](https://github.com). One of the best ways to find plugins isn't to browse any of -these sites directly but to search for plugins using a search engine. Searching for the function you -desire followed by `Minecraft plugin` will often yield good results. - -:::tip[Spigot and Bukkit Plugins] - -Paper is compatible with both Spigot and Bukkit plugins. It's okay if a plugin does not explicitly -mention Paper compatibility. It'll still work. - -::: - -## Installing Plugins - -1. Once you've found the plugin you'd like to install, download it. Ensure the file you have - downloaded ends in `.jar`. Some plugins also distribute as `.zip` files, in which case you will - need to extract the file and locate the `.jar` for your platform, often labelled `bukkit` or - `paper`. -2. Once you have the plugin downloaded locally, locate the `plugins` folder from the root directory - of your Paper server. -3. Drag and drop the plugin file (`.jar`) into the `plugins` folder. If you are using a shared - hosting service, you may need to use their web panel or SFTP to upload the plugin; however, the - procedure will be the same. -4. Restart your server. The plugin should load. -5. Check your work. Once the server has finished loading, run the `/plugins` command in-game or type - `plugins` into the console. You should see your freshly installed plugin listed in green. If it - is not listed or is colored red, continue to [troubleshooting](#troubleshooting). A plugin listed - in red means that it is not currently enabled. For a freshly installed plugin, this often means - that the plugin failed to load. - -## Troubleshooting - -### Check your logs - -The first step to troubleshooting installing plugins is to check the log of your server. Your -server's most recent logs will be stored to the `logs/latest.log` file. You may need to scroll near -the beginning of this file to see when plugins were loaded. - -#### Missing Dependencies - -If you see something like this: - -```log -Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' -org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. -``` - -This means that the plugin you tried to install is missing a dependency. A dependency, in this case, -is another plugin that you must install for the first to function. While you will get a big scary -error, the important line to look at is - -```log -Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. -``` - -This is telling you that in order to load `MyAwesomePlugin`, you must first install `Vault`. - -#### Invalid plugin.yml - -If you see something closer to this: - -```log -Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' -org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml -``` - -This means that what you have downloaded isn't a valid Paper plugin. This is generally caused by one -of the following: - -1. The plugin you downloaded isn't a plugin at all, but instead a mod for Forge, Fabric, or similar. - These will not run on Paper. -2. The plugin failed to download completely. Especially when using tools such as `curl` or `wget`, - you can easily download error pages rather than the plugin you intended. This may also be caused - by a network issue. Attempt to download the plugin again. If you are using FTP (not SFTP or a web - panel) to upload your plugin to a shared hosting service, ensure your FTP client is in `binary` - and not `ASCII` mode. Consult the documentation for your FTP client for details. - -#### Ambiguous plugin name - -If you see something like this: - -```log -Ambiguous plugin name `Essentials' for files `plugins/EssentialsX-2.19.4.jar' and `plugins/Essentialsx-2.20.0-dev.jar' in `plugins' -``` - -This means you have two plugins with the same name, which is not supported. In this case, two -versions of EssentialsX are installed. Both the release `2.19.4`, and a development build of -`2.20.0`. Ensure you only have one version of each plugin installed at one time. Delete the older -version of the duplicate plugin, and restart your server. - -[//]: # "To prevent accidentally installing two versions of one plugin while updating, you can use" -[//]: # "the `update` folder as described in the [Update Guide](/paper/how-to/update)." - -#### Something Else - -If you see an error, but it isn't similar to one of the above, attempt to read it yourself. While -the full error may be large and scary, you likely only have to read the first one or two lines to -understand what is going on. If you're not sure, do not hesitate to reach out for support on our -[Discord](https://discord.gg/papermc) in the `#paper-help` channel. - -### If nothing is logged - -If nothing is logged, your server is likely not attempting to load any plugins. The conditions -needed for the server to load a plugin are as follows: - -1. The file is at the root of the `plugins` folder, relative to its working directory. This is - usually the same folder as the server JAR file. **Subdirectories of the `plugins` folder will not - be checked.** All plugins must be in the root folder. -2. The file ends in `.jar`. If your plugin does not end in `.jar`, what you have downloaded may not - be a plugin. Note that some plugins distribute multiple jars as `.zip` files. If this is the - case, you have to extract them before installing the plugin. - -If both of these are true and you still see no logs please reach out for support on our -[Discord](https://discord.gg/papermc) server in the `#paper-help` channel. We will be happy to -assist you. diff --git a/docs/versioned/paper/content/1.18/admin/getting-started/getting-started.md b/docs/versioned/paper/content/1.18/admin/getting-started/getting-started.md deleted file mode 100644 index e0725d3ce..000000000 --- a/docs/versioned/paper/content/1.18/admin/getting-started/getting-started.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -slug: /getting-started ---- - -# Getting Started - -## Requirements - -:::tip - -With the release of Minecraft 1.18, Paper now requires **Java 17** to run. If you don't already have -Java 17, [it's easy to download and install](/misc/java-install). - -::: - -| Paper Version | Recommended Java Version | -| -------------- | ------------------------ | -| 1.8 to 1.11 | Java 8 | -| 1.12 to 1.16.4 | Java 11 | -| 1.16.5 | Java 16 | -| 1.17.1-1.18.1+ | Java 17 | - -## Migrating to Paper - -### 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. No additional consideration is required. - -### From Craftbukkit or Spigot - -Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes. - -## Downloading Paper - -Paper provides runnable server jars directly from our -[website's downloads page](https://papermc.io/downloads). - -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`. Ensure you replace `paper.jar` with the name of the jar -you have downloaded. - -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 Flags](../how-to/aikars-flags.md). - -To configure your server, see the [Global Configuration](../reference/paper-global-configuration.md) -and [Per World Configuration](../reference/paper-per-world-configuration.md) pages. - -## Updating The Server - -Updating Paper is simple! See our [Update Tutorial](../how-to/update.md) for more information. diff --git a/docs/versioned/paper/content/1.18/admin/getting-started/migration.md b/docs/versioned/paper/content/1.18/admin/getting-started/migration.md deleted file mode 100644 index 33eac47af..000000000 --- a/docs/versioned/paper/content/1.18/admin/getting-started/migration.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -slug: /migration -title: Migrating to or from Paper ---- - -It's simple to migrate your server to or from Paper. The steps below will help you get started. - -:::caution[Backup your data before you start!] - -Before you begin, please ensure you have a full backup of your server. - -[//]: # "See our [Backup Guide](/backup) for more information." - -::: - -## Migrating to Paper - -### From CraftBukkit or Spigot - -It's easy to migrate from CraftBukkit or Spigot to Paper. Follow the steps below. - -1. Stop your server if it is running, and create a full backup. -2. Download Paper from [our downloads page](https://papermc.io/downloads). -3. Replace your existing server jar with your freshly downloaded Paper jar. -4. Start your new server. - -Paper retains full compatibility with all Spigot plugins, allowing a seamless transition. - -:::info - -Your new Paper server will still use `bukkit.yml` and `spigot.yml`, only adding new configuration -options in `paper.yml`. - -::: - -If you have any issues migrating from CraftBukkit or Spigot, do not hesitate to reach out for -support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel). - -### From Vanilla - -When migrating to Paper from Vanilla, the way worlds are stored will automatically be changed. -Should you ever want to go back to Vanilla, follow the [Vanilla Migration Guide](#to-vanilla) -closely, as manual changes will be required. - -1. Stop your Vanilla server if it is running, and create a full backup. -2. Downloads Paper from [our downloads page](https://papermc.io/downloads) and replace your Vanilla - server jar with your freshly downloaded Paper jar. -3. Start your new Paper server. - -You have now successfully migrated to Paper. If you encounter any issues, do not hesitate to reach -out for support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel). - -### From Fabric/Forge - -Because both Fabric and Forge use the Vanilla world directory structure, the same steps as the -[Vanilla Migration Guide](#from-vanilla) may be used, with one caveat. If your Fabric or Forge -server used mods that added new blocks, items, or other data to the game, Paper will be unable to -load these features. - -Additionally, note that Paper does not support Fabric or Forge mods. You will need to find plugin -replacements. Any hybrids that attempt to support both mods and plugins are fundamentally flawed and -not recommended for use. - -## Migrating From Paper - -### To Vanilla - -Because Paper stores worlds slightly differently than Vanilla, manual work is required to migrate. -If these steps are not taken, your nether and end will look like they have been reset. Don't worry! -Even if this has happened, you haven't lost any data. The Vanilla server just doesn't know where to -find it. - -Here is a chart to show the difference between how Vanilla and Paper store worlds. - -| Server Software | Overworld | Nether | End | -| --------------- | --------- | --------------------- | --------------------- | -| Vanilla | `/world` | `/world/DIM-1` | `/world/DIM1` | -| Paper | `/world` | `/world_nether/DIM-1` | `/world_the_end/DIM1` | - -Follow these steps to migrate from Paper to Vanilla: - -:::note - -These steps assume a `level-name` (as set in `server.properties`) of `world`. If this is not the -case for you, replace `world` with your `level-name` for all steps below. - -::: - -1. Stop your Paper server, if it is running. -2. If you have already started your server with Vanilla, enter the `world` folder and delete both - the `DIM-1` and `DIM1` folders. This step is only necessary should you have started your server - with Vanilla. -3. Copy the `/world_nether/DIM-1` folder into the `/world` folder. -4. Copy the `/world_the_end/DIM1` folder into the `/world` folder. -5. Delete both the `/world_nether` and `/world_the_end` folders. -6. Replace your Paper jar with a Vanilla server jar. -7. Start your Vanilla server. - -### To CraftBukkit or Spigot - -Paper does **not** support migration to either CraftBukkit or Spigot! While you may find success -(both CraftBukkit and Spigot use the same directory structure as Paper), **do not** reach out for -support with issues you encounter and note that data loss is possible. - -### To Fabric/Forge - -Because both Fabric and Forge use the same directory structure for world storage as Vanilla, follow -the [Vanilla Migration Guide](#to-vanilla) for this process. Note that neither Fabric nor Forge will -support Paper plugins! You will be required to find replacement mods. diff --git a/docs/versioned/paper/content/1.18/admin/how-to/aikars-flags.md b/docs/versioned/paper/content/1.18/admin/how-to/aikars-flags.md deleted file mode 100644 index acceb499a..000000000 --- a/docs/versioned/paper/content/1.18/admin/how-to/aikars-flags.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -slug: /aikars-flags ---- - -# Aikar's Flags - -## Recommended JVM Startup Flags - -Use these flags exactly, only changing Xmx and Xms. These flags work and scale accordingly to any -size of memory, even 500MB but modern Minecraft versions will not do well with such low memory. - -```bash -java -Xms10G -Xmx10G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar --nogui -``` - -:::caution[Do not allocate all of your available memory on a shared host!] - -When setting the Xms and Xmx values, if your host says you have 8000M memory, DO NOT USE 8000M! -Minecraft (and Java) needs additional memory on top of that Xmx parameter. It is recommended to -reduce your Xmx/Xms by about **1000-1500M** to avoid running out of memory or "OOMKiller" hitting -your server. This also leaves room for the Operating System to use memory too. **Have 8000M memory? -Use 6500M for safety.** _But you may also ask your host if they will cover this overhead for you and -give you 9500M instead. Some hosts will! Just ask._ - -::: - -## Recommended Memory - -**We recommend using at least 6-10GB**, no matter how few players! If you can't afford 10GB of -memory, give as much as you can, but ensure you leave the operating system some memory too. G1GC -operates better with more memory. - -However, more memory does not mean better performance above a certain point. Eventually you will hit -a point of diminishing returns. Going out and getting 32GB of RAM for a server will only waste your -money with minimal returns. - -If you are running with 12GB or less memory for MC, you should not adjust these parameters. - -### If you are using an Xmx value greater than 12G - -If you have and use more than 12GB of memory, adjust the following: - -- `-XX:G1NewSizePercent=40` -- `-XX:G1MaxNewSizePercent=50` -- `-XX:G1HeapRegionSize=16M` -- `-XX:G1ReservePercent=15` -- `-XX:InitiatingHeapOccupancyPercent=20` - -:::tip - -If you see increase in old generation collections after this, revert to the base flags! - -::: - -Explanation of these changes: - -- Base flag set aims for 30/40 to reduce risk of to space issues. With more memory, less of an - issue. We can give more to new generation with 40/50, as well as reduce reserve percent since the - default reserve will already be larger. -- Region Size increase helps reduce humongous allocations, and speeds up remarking. We need a - smaller region size at smaller heaps to ensure an adequate amount of regions available -- We can start looking for old generation memory to reclaim with more of a delay with IHOP at 20 - since we have more old generation available to space on CPU. - -## Java GC Logging - -Are you having old gen issues with these flags? Add the following flags based on your java version -to enable GC Logging: - -**Java 8-10** - -```bash --Xloggc:gc.log -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps --XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=1M -``` - -**Java 11+** - -```bash --Xlog:gc*:logs/gc.log:time,uptime:filecount=5,filesize=1M -``` - -GC logging does not hurt your performance and can be left on at all times. The files will not take -up much space (5MB) - -## Technical Explanation of the Flags - -1. **-Xms matching -Xmx -- Why:** You should never run your server with the case that -Xmx can run - the system completely out of memory. Your server should always be expected to use the entire - -Xmx! You should then ensure the OS has extra memory on top of that Xmx for non MC/OS level - things. Therefore, you should never run MC with -Xmx settings you can't support if java uses it - all. Now, that means if -Xms is lower than -Xmx **YOU HAVE UNUSED MEMORY! Unused memory is - wasted memory.** G1 operates better with the more memory it's given. G1 adaptively chooses how - much memory to give to each region to optimize pause time. If you have more memory than it needs - to reach an optimal pause time, G1 will simply push that extra into the old generation, and it - will not hurt you The fundamental idea of improving GC behavior is to ensure short-lived objects - die young and never get promoted. With the more memory G1 has, the better assurance you will get - that objects are not getting prematurely promoted to the old generation. G1 Operates differently - than previous collectors and is able to handle larger heaps more efficiently. - - If it does not need the memory given to it, it will not use it. The entire engine operates - differently and does not suffer from too large of heaps, and this is industry-wide accepted - information that under G1 to keep Xms and Xmx the same! - -2. **UnlockExperimentalVMOptions** -- needed for some the below options - -3. **G1NewSizePercent:** These are the important ones. You now can specify percentages of an - overall desired range for the new generation. With these settings, we tell G1 to not use its - default 5% for new gen, and instead give it 40%! **Minecraft has an extremely high a memory - allocation rate, ranging to at least 800 Megabytes a second on a 30 player server! And this is - mostly short-lived objects (Block Position).** - - Now, this means MC REALLY needs more focus on New Generation to be able to even support this - allocation rate. If your new gen is too small, you will be running new gen collections 1-2+ - times per second, which is awful. You will have so many pauses that TPS has risk of suffering, - and the server will not be able to keep up with the cost of GC's. Then combine the fact that - objects will now promote faster, resulting in your Old Gen growing faster. Given more New Gen, - we are able to slow down the intervals of Young Gen collections, resulting in more time for - short-lived objects to die young and overall more efficient GC behavior. - -4. **G1MixedGCLiveThresholdPercent:** Controls when to include regions in Mixed GC's in the Young - GC collection, keeping Old Gen tidy without doing a normal Old Gen GC collection. When your - memory is less than this percent, old gen won't even be included in 'mixed' collections. Mixed - are not as heavy as a full old collection, so having small incremental cleanups of old keeps - memory usage light. - - Default is 65 to 85 depending on Java Version, we are setting to 90 to ensure we reclaim garbage - in old gen as fast as possible to retain as much free regions as we can. - -5. **G1ReservePercent=20:** MC Memory allocation rate in up-to-date versions is really insane. We - run the risk of a dreaded "to-space exhaustion" not having enough memory free to move data - around. This ensures more memory is waiting to be used for this operation. Default is 10, so we - are giving another 10 to it. - -6. **MaxTenuringThreshold=1:** Minecraft has a really high allocation rate of memory. Of that - memory, most is reclaimed in the eden generation. However, transient data will overflow into - survivor. Initially played with completely removing Survivor and had decent results, but does - result in transient data making its way to Old which is not good.Max Tenuring 1 ensures that we - do not promote transient data to old generation, but anything that survives 2 passes of Garbage - Collection is just going to be assumed as longer-lived. - - Doing this greatly reduces pause times in Young Collections as copying data up to 15 times in - Survivor space for a tenured object really takes a lot of time for actually old memory. Ideally - the GC engine would track average age for objects instead and tenure out data faster, but that - is not how it works. - - Considering average GC rate is 10s to the upwards of minutes per young collection, this does not - result in any 'garbage' being promoted, and just delays longer lived memory to be collected in - Mixed GC's. - -7. **SurvivorRatio=32:** Because we drastically reduced MaxTenuringThreshold, we will be reducing - use of survivor space drastically. This frees up more regions to be used by Eden instead. - -8. **AlwaysPreTouch:** AlwaysPreTouch gets the memory setup and reserved at process start ensuring - it is contiguous, improving the efficiency of it more. This improves the operating systems - memory access speed. Mandatory to use Transparent Huge Pages - -9. **+DisableExplicitGC:** Many plugins think they know how to control memory, and try to invoke - garbage collection. Plugins that do this trigger a full garbage collection, triggering a massive - lag spike. This flag disables plugins from trying to do this, protecting you from their bad - code. - -10. **MaxGCPauseMillis=200:** This setting controls how much memory is used in between the Minimum - and Maximum ranges specified for your New Generation. This is a "goal" for how long you want - your server to pause for collections. 200 is aiming for at most loss of 4 ticks. This will - result in a short TPS drop, however the server can make up for this drop instantly, meaning it - will have no meaningful impact to your TPS. 200ms is lower than players can recognize. In - testing, having this value constrained to an even lower number results in G1 not recollecting - memory fast enough and potentially running out of old gen triggering a Full collection. Just - because this number is 200 does not mean every collection will be 200. It means it can use up to - 200 if it really needs it, and we need to let it do its job when there is memory to collect. - -11. **+ParallelRefProcEnabled:** Optimizes the GC process to use multiple threads for weak reference - checking. Not sure why this isn't default... - -12. **G1RSetUpdatingPauseTimePercent=5:** Default is 10% of time spent during pause updating Rsets, - reduce this to 5% to make more of it concurrent to reduce pause durations. - -13. **G1MixedGCCountTarget=4:** Default is 8. Because we are aiming to collect slower, with less old - gen usage, try to reclaim old gen memory faster to avoid running out of old. - -14. **G1HeapRegionSize=8M+:** Default is auto calculated. SUPER important for Minecraft, especially - 1.15, as with low memory situations, the default calculation will in most times be too low. Any - memory allocation half of this size (4MB) will be treated as "Humongous" and promote straight to - old generation and is harder to free. If you allow java to use the default, you will be - destroyed with a significant chunk of your memory getting treated as Humongous. - -15. **+PerfDisableSharedMem:** Causes GC to write to file system which can cause major latency if - disk IO is high -- See https://www.evanjones.ca/jvm-mmap-pause.html - -## Using Large Pages - -For Large Pages -- It's even more important to use -Xms = -Xmx! Large Pages needs to have all the -memory specified for it, or you could end up without the gains. This memory will not be used by the -OS anyway, so use it. - -Additionally, use these flags (Metaspace is Java 8 Only, don't use it for Java7): -`-XX:+UseLargePagesInMetaspace` - -### Transparent Huge Pages - -Controversial feature but may be usable if you can not configure your host for real HugeTLBFS. Try -adding `-XX:+UseTransparentHugePages` but it's extremely important you also have AlwaysPreTouch set. -Otherwise, THP will likely hurt you. We have not measured how THP works for MC or its impact with -AlwaysPreTouch, so this section is for the advanced users who want to experiment. diff --git a/docs/versioned/paper/content/1.18/admin/how-to/anti-xray.md b/docs/versioned/paper/content/1.18/admin/how-to/anti-xray.md deleted file mode 100644 index 6d6181910..000000000 --- a/docs/versioned/paper/content/1.18/admin/how-to/anti-xray.md +++ /dev/null @@ -1,249 +0,0 @@ ---- -slug: /anti-xray ---- - -# Configuring Anti-Xray - -> Originally written and maintained by [stonar96](https://github.com/stonar96). - -Paper includes an obfuscation-based Anti-Xray with two modes, configurable per world in paper.yml. - -:::info[Per World Configuration] - -If you aren't already familiar with per world configuration, please take a moment to familiarize -yourself with the [Per World Configuration Guide](per-world-configuration.md). - -::: - -This guide is a step-by-step walk-through for configuring Anti-Xray. For reference documentation, -refer to the Anti-Xray section of the -[Per-World Configuration Reference](../reference/paper-per-world-configuration.md#anti-xray). - -Anti-Xray has two different modes. `engine-mode: 1` replaces specified blocks (`hidden-blocks`) with -other "fake" blocks, `stone` (`deepslate` at y < 0), `netherrack`, or `end_stone` based on the -dimension. In contrast, `engine-mode: 2` will replace both `hidden-blocks` and `replacement-blocks` -with randomly generated `hidden-blocks`. - -The following images[^1] show how each mode will look for a player using Xray with the recommended -configuration in both the overworld and nether. - -[^1]: - Image design by `Oberfail`, initially posted in the - [PaperMC Discord](https://discord.gg/papermc). ​ - -![Overworld Anti-Xray Comparison](assets/anti-xray-overworld.png) -![Nether Anti-Xray Comparison](assets/anti-xray-nether.png) - -Especially on the client side, `engine-mode: 1` is much less computationally intensive, while -`engine-mode: 2` may better prevent Xray. With `engine-mode: 1`, only ores that are entirely covered -by solid blocks will be hidden. Ores exposed to air in caves or water from a lake will not be -hidden. With `engine-mode: 2`, fake ores obstruct the view of real blocks. If `air` is added to -`hidden-blocks`, `engine-mode: 2` will effectively hide all ores, even those exposed to air. - -:::caution[Anti-Xray Bypasses] - -**Range Extension**: While Anti-Xray alone will prevent the majority of users from Xraying on your -server, it is not by any means infallible. Because of how Anti-Xray is (and has to be) implemented, -it is possible to, on a default server, extend the range of real ores you can see by a not -insignificant amount. This can be mitigated by any competent anti-cheat plugin; however, this is not -included out of the box. - -**Seed Reversing**: Another attack vector is the deterministic nature of Minecraft's world -generation. If the client is able to obtain the world seed, it is able to know the real location of -every generated ore, completely bypassing Anti-Xray. This can be partially worked around by making -it harder for the client to reverse the world seed with the -[`feature-seeds` configuration](../reference/paper-per-world-configuration.md#feature-seeds), in -conjunction with the structure seed options in `spigot.yml`. Note that this is not a complete -solution, and it may still be possible for a client to obtain the server's world seed. Using a -different seed for each world may also be beneficial. - -**Ores Exposed to Air**: In both `engine-mode: 1` and `engine-mode: 2`, it is possible for a client -to view ores that are exposed to air. This can be mitigated in `engine-mode: 2` by adding `air` to -the `hidden-blocks` list. However, doing this may cause client performance issues (FPS drops) for -some players. - -::: - -## Recommended Configuration - -The recommended configuration for both `engine-mode: 1` and `engine-mode: 2` is as follows: - -:::tip[Spacing] - -YAML cares about whitespace! The example configuration below is already formatted correctly. Ensure -formatting remains unchanged by using the "copy" button in the top right of each example. - -::: - -### `engine-mode: 1` - -
- Overworld Configuration - -Replace the existing `anti-xray` block in `paper.yml` (under `world-settings.default`) with the -following: - - -```yaml title="paper.yml" - anti-xray: - enabled: true - engine-mode: 1 - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - update-radius: 2 - lava-obscures: false - use-permission: false - hidden-blocks: - # There's no chance to hide dungeon chests as they are entirely surrounded by air, but buried treasures will be hidden. - - chest - - coal_ore - - deepslate_coal_ore - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - emerald_ore - - deepslate_emerald_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - replacement-blocks: - # The replacement-blocks list is not used in engine-mode: 1. Changing this will have no effect. - - stone - - oak_planks - - deepslate -``` - -
- -
- End and Nether Configuration - -Copy and paste this at the very bottom of `paper.yml`. See the -[Per-World Configuration Guide](per-world-configuration.md) for more information. Remember to change -the world names if your worlds are named differently! - - -```yml title="paper.yml" - world_nether: - anti-xray: - max-block-height: 128 - hidden-blocks: - - ancient_debris - - nether_gold_ore - - nether_quartz_ore - world_the_end: - anti-xray: - enabled: false -``` - -
- -### `engine-mode: 2` - -
- Overworld Configuration - -Replace the existing `anti-xray` block in `paper.yml` (under `world-settings.default`) with the -following: - - -```yaml title="paper.yml" - anti-xray: - enabled: true - engine-mode: 2 - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - update-radius: 2 - lava-obscures: false - use-permission: false - hidden-blocks: - # You can add air here such that many holes are generated. - # This works well against cave finders but may cause client FPS drops for all players. - - air - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - replacement-blocks: - # Chest is a tile entity and can't be added to hidden-blocks in engine-mode: 2. - # But adding chest here will hide buried treasures, if max-block-height is increased. - - chest - - amethyst_block - - andesite - - budding_amethyst - - calcite - - coal_ore - - deepslate_coal_ore - - deepslate - - diorite - - dirt - - emerald_ore - - deepslate_emerald_ore - - granite - - gravel - - oak_planks - - smooth_basalt - - stone - - tuff -``` - -
- -
- End and Nether Configuration - -Copy and paste this at the very bottom of `paper.yml`. See the -[Per-World Configuration Guide](per-world-configuration.md) for more information. Remember to change -the world names if your worlds are named differently! - - -```yml title="paper.yml" - world_nether: - anti-xray: - max-block-height: 128 - hidden-blocks: - # See note about air and possible client performance issues above. - - air - - ancient_debris - - bone_block - - glowstone - - magma_block - - nether_bricks - - nether_gold_ore - - nether_quartz_ore - - polished_blackstone_bricks - replacement-blocks: - - basalt - - blackstone - - gravel - - netherrack - - soul_sand - - soul_soil - world_the_end: - anti-xray: - enabled: false -``` - -
diff --git a/docs/versioned/paper/content/1.18/admin/how-to/assets/anti-xray-nether.png b/docs/versioned/paper/content/1.18/admin/how-to/assets/anti-xray-nether.png deleted file mode 100644 index 3783ef88f..000000000 Binary files a/docs/versioned/paper/content/1.18/admin/how-to/assets/anti-xray-nether.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.18/admin/how-to/assets/anti-xray-overworld.png b/docs/versioned/paper/content/1.18/admin/how-to/assets/anti-xray-overworld.png deleted file mode 100644 index e470af9c9..000000000 Binary files a/docs/versioned/paper/content/1.18/admin/how-to/assets/anti-xray-overworld.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.18/admin/how-to/per-world-configuration.md b/docs/versioned/paper/content/1.18/admin/how-to/per-world-configuration.md deleted file mode 100644 index bf47ac8d7..000000000 --- a/docs/versioned/paper/content/1.18/admin/how-to/per-world-configuration.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -slug: /per-world-configuration -id: configuration ---- - -# Per World Configuration - -One of the most powerful yet least understood features of the Paper configuration is setting -configuration options per world. While not every config option can be set per world, everything -under `world-settings` in either `paper.yml` or `spigot.yml` can be configured differently on a per -world basis. - -## Default Values - -The only world generated out of the box is `default`. Any configuration option set here will apply -to **all** loaded worlds, unless explicitly overridden. Any configuration change that does not need -to be separated by world should be made in this section. - -:::info[The main world] - -The `default` section also serves as the place to configure per world settings for the main world -(`level-name` in server.properties). An additional section created for the main world will not -supersede `default`. - -::: - -## Per World Values - -A new section must be manually added to the bottom of the configuration file for each world which -requires a unique configuration. This section will not be automatically generated; it must be added. -Remember! YAML (the configuration format used by Paper) cares about spaces. When adding a new world, -ensure there are two spaces behind it. - -For example, to disable loading the spawn chunks in `world_nether` and `world_the_end`, -configuration would be added like this: - -```yaml title="paper.yml" -world-settings: - default: - keep-spawn-loaded: true - world_nether: - keep-spawn-loaded: false - world_the_end: - keep-spawn-loaded: false -``` - -This is a very stripped-down example. In reality, the `default` section will be much more extensive -as it contains all possible configuration options. This may look overwhelming at first, but always -remember to put new worlds at the very bottom of the configuration file. - -### Inheritance - -All configuration not explicitly defined for a world is inherited from the `default` section. This -means there is no need to repeat configuration options with the same value between sections, so -there is no need to copy and paste the entire `default` section into each new world created. - -For a more complex real-world example: setting both different `spawn-limits` and `keep-spawn-loaded` -in two worlds. - -```yaml title="paper.yml" -world-settings: - default: - spawn-limits: - monster: 70 - creature: 10 - ambient: 15 - axolotls: 5 - underground_water_creature: 5 - water_creature: 5 - water_ambient: 20 - keep-spawn-loaded: true - world_nether: - spawn-limits: - monster: 90 - resource_world: - spawn-limits: - monster: 2 - creature: 15 - axolotls: 8 - keep-spawn-loaded: false -``` - -This example demonstrates the concept of inheritance. For each world, this is the effective -configuration which will be applied: - -| Configuration Key | world | world_nether | world_the_end | resource_world | -| ----------------------------------------- | ------ | ------------ | ------------- | -------------- | -| `spawn-limits.monster` | `70` | `90` | `70` | `2` | -| `spawn-limits.creature` | `10` | `10` | `10` | `15` | -| `spawn-limits.ambient` | `15` | `15` | `15` | `15` | -| `spawn-limits.axolotls` | `5` | `5` | `5` | `8` | -| `spawn-limits.underground_water_creature` | `5` | `5` | `5` | `5` | -| `spawn-limits.water_creature` | `5` | `5` | `5` | `5` | -| `spawn-limits.water_ambient` | `20` | `20` | `20` | `20` | -| `keep-spawn-loaded` | `true` | `true` | `true` | `false` | - -Notice that `world_the_end` was never specified in this configuration. Because of this, it inherits -all the configuration options from the `default` section. Additionally, `keep-spawn-loaded` was only -disabled in `resource_world` because in the `default` section, `keep-spawn-loaded` is set to `true`. diff --git a/docs/versioned/paper/content/1.18/admin/how-to/update.md b/docs/versioned/paper/content/1.18/admin/how-to/update.md deleted file mode 100644 index b9d3bf693..000000000 --- a/docs/versioned/paper/content/1.18/admin/how-to/update.md +++ /dev/null @@ -1,76 +0,0 @@ ---- -slug: /updating ---- - -# Updating Paper - -Updating Paper is an important part of running every server. With new features and fixes coming -every day, we recommend updating at least once per week to keep your server patched for the latest -bugs. Installing updates is very simple, but it's important to know how to do it correctly. - -:::caution[Don't replace any JAR in a running server] - -Unless you know exactly what and why you're doing what you're doing, it's never a good idea to -replace any JAR in a running server, be that plugins, or Paper itself. - -::: - -## Step 1. Backup - -This is the most important step, and yet the most frequently skipped. While it is unlikely that -updating Paper itself will cause any issues requiring you to restore from a backup, plugin -malfunctions or other accidents might! Updating is a great time to work in a backup. Having -functioning backups is essential to every server, big or small. - -If you don't already have a backup plan in place, see [Backup and Recovery] where we walk through -multiple different backup or recovery strategies. - -## Step 2. Update Plugins - -Just like it's important to update Paper, it's equally important to keep plugins up to date. You -never know what plugin authors may be working on, be it bugfixes or new features. - -A little known feature of Paper servers is the `update` folder. Here's how you use it. - -1. Create a folder called `update` within the `plugins` folder. -2. One by one, download plugins you would like to update and put them in the `update` folder. -3. Restart your server, do not remove or modify any plugins outside the `update` folder. - -By doing this, you are able to update all of your plugins at the same time without having the server -off, or replacing plugin JARs while the server is running. You do not need to restart your server -before updating Paper itself. This feature allows you to update both Paper and plugins all at the -same time, without needing any additional downtime. - -## Step 3. Update Paper - -:::tip - -If you are using a shared host, your host may provide a built-in way to update! Consult their -documentation before continuing. - -::: - -Updating Paper itself is very simple. - -1. Download a new JAR from [our downloads page](https://papermc.io/downloads) -2. Stop your server. It is not recommended and may cause issues to replace your Paper JAR while the - server is running. -3. Replace your old Paper JAR file with the new one. -4. Start your server. Watch the startup log to ensure everything goes to plan. If there are any - plugin conflicts or issues, you will see them here. - -To minimize downtime caused by updates, some server owners will, rather than replacing their server -JAR, upload a new one and set their start script to use the new one on the next restart. Both of -these are valid update strategies. - -:::caution[Automatic Updates] - -While it may be convenient to install updates automatically (and Paper's [downloads api] allows you -to with ease), doing so is not recommended by Paper due to the possibility of plugin conflicts or -other issues that you may not know about. Always be present during updates, and keep a careful watch -on your server's log after the fact. - -If you do choose to automatically install updates, ensure you have a functioning backup strategy in -place! - -::: diff --git a/docs/versioned/paper/content/1.18/admin/reference/paper-global-configuration.md b/docs/versioned/paper/content/1.18/admin/reference/paper-global-configuration.md deleted file mode 100644 index f7d727343..000000000 --- a/docs/versioned/paper/content/1.18/admin/reference/paper-global-configuration.md +++ /dev/null @@ -1,463 +0,0 @@ ---- -slug: /reference/paper-global-configuration -keywords: - - paper.yml - - paper.yml settings -id: global-configuration ---- - -# Paper Global Config - -Global configuration options exposed by Paper will affect all worlds on a server, or the server -function itself. For per-world configuration, see the -[Per World Configuration Reference](paper-per-world-configuration.md) - -### 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. - -### 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 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 breaking change; however, it provides a much more sensible default value. Enabling this - with plugins using many scoreboards will incur a performance degradation. - -### 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 completions of its own. - -### use-alternative-luck-formula - -- **default**: false -- **description**: Use an alternative - [luck formula by Aikar](https://gist.github.com/aikar/40281f6c73ec9b6fef7588e6461e1ba9), allowing - luck to be applied to items that have no quality defined. Makes major changes to fishing formulas. - -### 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**: How often player data should be saved in ticks. A value of `-1` will use - `ticks-per.autosave` in `bukkit.yml`. - -### 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` will - set a recommended value based on `player-auto-save-rate`. - -### 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 behavior 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](https://www.velocitypowered.com/) 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. - -### 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. - -- perform-username-validation - - **default**: true - - **description**: If set to false, usernames will not be validated. While this may allow users - with special characters in their name to join, it can also cause issues with commands and - plugins. - -### 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 - - **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 its 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. The - default `-1` indicates that Paper will utilize half your system's threads for chunk loading - unless otherwise specified. There is also a maximum default of 4 threads used for saving and - loading chunks. This can be overridden by adding `-Dpaper.maxChunkThreads=[number of threads]` - to your JVM flags (and of course replacing `[number of threads]` with the number of threads you - desire). - -### 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 - - **default**: Flying is not enabled on this server - - **description**: Message to use when kicking a player's vehicle for flying. - -### timings - -- enabled - - - **default**: false - - **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, specific entity types causing lag rather than just "entities". - -- url - - - **default**: `https://timings.aikar.co/` - - **description**: Specifies the URL of the [Timings Viewer](https://github.com/aikar/timings) - server where Timings reports should be uploaded 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. - -### 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. - -### 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 the client 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, it 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 not affect - 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 individual 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**: -1.0 - - **description**: The maximum number of chunks loaded per second for the whole server. A value of - -1 will disable this limit. Takes priority over `player-max-chunk-load-rate`. - -- 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 - - - **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. - -- player-max-chunk-load-rate - - - **default**: -1.0 - - **description**: The maximum number of chunks loaded per player per second. - -### packet-limiter - -- kick-message - - - **default**: &cSent too many packets - - **description**: The message players are kicked with for sending too many packets. - -- limits - - all - - **description**: This section applies to 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 its 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 - executed. - - 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. - -### log-player-ip-addresses - -- **default**: true -- **description**: When set to false, player IP addresses in the server logs will be replaced with - ``. This doesn't affect log messages generated by plugins. - -### proxy-protocol - -:::caution - -This setting is unrelated to BungeeCord IP Forwarding, BungeeGuard, or Velocity Modern Forwarding. -Leave this setting off unless you are using HAProxy or another proxy implementing PROXY Protocol. - -::: - -- **default**: false -- **description**: Whether Paper should receive HAProxy PROXY messages - ([PROXY Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt)). diff --git a/docs/versioned/paper/content/1.18/admin/reference/paper-per-world-configuration.md b/docs/versioned/paper/content/1.18/admin/reference/paper-per-world-configuration.md deleted file mode 100644 index 330a10874..000000000 --- a/docs/versioned/paper/content/1.18/admin/reference/paper-per-world-configuration.md +++ /dev/null @@ -1,1010 +0,0 @@ ---- -slug: /reference/paper-per-world-configuration -keywords: - - paper.yml - - paper.yml world-settings -id: world-configuration ---- - -# Paper Per World Config - -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. For more information about how per world configuration -of Paper works, see the [Per World Configuration Guide](../how-to/per-world-configuration.md). For -global config, see the [Paper Global Configuration Reference](paper-global-configuration.md) - -### 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 base speed, 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. - -### 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. - -### experience-merge-max-value - -- **default**: -1 -- **description**: Instructs the server to 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. - -### 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 to 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. - -### duplicate-uuid-resolver - -- **default**: saferegen - -- **description**: Specifies the method the server uses to resolve entities with duplicate UUIDs. - This can be one of 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 a slower spread. - -### redstone-implementation - -:::caution - -Alternative implementations are ultimately experimental, and as such, could be removed between -updates or even permanently if issues are found. - -::: - -- **default**: vanilla -- **description**: Specifies the redstone implementation that the server uses. Alternative - implementations can greatly reduce the lag caused by redstone dust by optimizing power - calculations and reducing the number of block and shape updates emitted. The following - implementations are available: - - **vanilla**: The Vanilla redstone implementation. - - **eigencraft**: The Eigencraft redstone implementation by theosib. - - **alternate-current**: The Alternate Current redstone implementation by Space Walker. -- **note:** Both the Eigencraft and Alternate Current implementations change the behavior of - redstone dust. You can read about how behavior is changed in each implementation's respective - documention: - - Eigencraft: No official documentation available. However, - [theosib's comments](https://bugs.mojang.com/browse/MC-81098?focusedCommentId=420777#comment-420777) - on the Mojira bug tracker give an overview of the Eigencraft implementation. - - [Alternate Current](https://github.com/SpaceWalkerRS/alternate-current/blob/main/README.md) - -### 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 from using the nether ceiling as a 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. - -### 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. This also causes cauldrons to no longer be - filled by rain or snow. - -### 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 performance 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. - -### 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-find-already-discovered - -- **description**: Options for overriding vanilla and datapack treasure map mechanics. In some cases - the server may try and look for an undiscovered location when creating a treasure map. The options - below allow configuring the default behavior of maps obtained in different ways. - -- villager-trade - - - **default**: false - - **description**: Vanilla defaults to skipping discovered locations for maps obtained via villager trading. This - option, if set to true, reverses that letting vanilla return the first structure it finds. - -- loot-tables - - **default**: default - - **description**: Overrides the loot table-configured check for undiscovered structures. - `default` allows loot tables to individually determine if the map should allow discovered - locations in its search. All vanilla loot tables default to finding discovered locations so - changing this to `false` would override that behavior and force them to search for undiscovered - locations. - -### 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. - -### 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 may help 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. - -### slime-spawn-height - -- swamp-biome - - maximum - - **default**: 70 - - **description**: Sets the maximum Y position for natural Slime spawn in Swamp Biomes. - - minimum - - **default**: 50 - - **description**: Sets the minimum Y position for natural Slime spawn in Swamp Biomes. -- slime-chunk - - maximum - - **default**: 40 - - **description**: Sets the maximum Y position for natural Slime spawn in Slime Chunks. - -### 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. A value of -1 will disable all spawners. - -### 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 -- **description**: Configures the world saving interval in ticks. Overrides `ticks-per.autosave` in - `bukkit.yml` for this world. -- **note**: `-1` will use the global `ticks-per.autosave` in `bukkit.yml`. - -### 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, treating them as normal - hits instead. - -- 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. - -- 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](https://bugs.mojang.com/browse/MC-181190) 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. - -### 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 - -- monster - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which monsters will be randomly - selected to be despawned. - - hard - - **default**: 128 - - **description**: The number of blocks away from a player in which monsters will be forcibly - despawned. -- creature - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which creatures will be randomly - selected to be despawned. - - hard - - **default**: 128 - - **description**: The number of blocks away from a player in which creatures will be forcibly - despawned. -- ambient - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which ambient entities will be - randomly selected to be despawned. - - hard - - **default**: 128 - - **description**: The number of blocks away from a player in which ambient entities will be - forcibly despawned. -- underground_water_creature - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which underground water creatures - will be randomly selected to be despawned. - - hard - - **default**: 128 - - **description**: The number of blocks away from a player in which underground water creatures - will be forcibly despawned. -- water_creature - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which water creatures will be - randomly selected to be despawned. - - hard - - **default**: 128 - - **description**: The number of blocks away from a player in which water creatures will be - forcibly despawned. -- water_ambient - - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which water ambient entities will - be randomly selected to be despawned. - - hard - - **default**: 64 - - **description**: The number of blocks away from a player in which water ambient entities will - be forcibly despawned. - -- misc - - soft - - **default**: 32 - - **description**: The number of blocks away from a player in which misc entities will be - randomly selected to be despawned. - - hard - - **default**: 128 - - **description**: The number of blocks away from a player in which misc entities will be - forcibly despawned. - -### 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 refill 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 = 4 days. -- refresh-max - - **default**: 2d - - **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 = 4 days. - -### 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. The item ids are - the same as those used in the /give command. They can be viewed by enabling advanced item - tooltips in-game by pressing **F3 + H**; the item id will appear at the bottom of the tooltip - that appears when you hover over an item. - -### spawn-limits - -- monster - - **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. -- creature - - **default**: -1 - - **description**: The number of animals that can spawn per world. This is identical to the value - set for _animals_ in bukkit.yml, except that it can be configured per world. A value of -1 will - use the value in bukkit.yml. -- water_creature - - **default**: -1 - - **description**: The number of water animals that can spawn per world. This is identical to the - value set for _water-animals_ in bukkit.yml, except that it can be configured per world. A value - of -1 will use the value in bukkit.yml. -- underground_water_creature - - **default**: -1 - - **description**: The number of water animals that can spawn per world. This is identical to the - value set for _water-underground-creature_ in bukkit.yml, except that it can be configured per - world. A value of -1 will use the value in 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 for _water-ambient_ in bukkit.yml, except that it can be configured - per world. A value of -1 will use the 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. - -### hopper - -- cooldown-when-full - - **default**: true - - **description**: Instructs the server to apply a short cooldown when the hopper is full, instead - of constantly 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. -- ignore-occluding-blocks - - **default**: false - - **description**: Determines if hoppers will ignore containers inside occluding blocks, like a - hopper minecart inside a sand block. Enabling this will improve performance for hoppers checking - where to insert items. - -### anti-xray - -:::tip - -Recommended configuration for both `engine-mode` `1` and `2` can be found in the -[Configuring Anti-Xray](../how-to/anti-xray.md) guide. - -::: - -- 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. `1` replaces specified blocks (`hidden-blocks`) - with other "fake" blocks, `stone` (`deepslate` at y < 0), `netherrack`, or `end_stone` based on - the dimension. In contrast, `2` will replace both `hidden-blocks` and `replacement-blocks` with - randomly generated `hidden-blocks`. -- max-block-height - - **default**: 64 - - **description**: Sets the maximum height (`y` coordinate, starting from the bottom of the world) - to which anti-xray will operate. Only integer multiples of 16 are accepted. All other values - will be rounded down. The [Minecraft Wiki page about Ore](https://minecraft.wiki/w/Ore) - may be helpful in determining the best value for you. -- update-radius - - **default**: 2 - - **description**: Radius for block updates which will be sent containing real block data when the - client interacts with a block. Only values `0`, `1`, and `2` are accepted. Values smaller than - `0` will be rounded up to `0`, while values larger than `2` will be rounded down to `2`. `0` is - only designed for testing purposes. Do not use it in production. -- lava-obscures - - **default**: false - - **description**: Whether to obfuscate blocks touching lava. Does not work well with - non-stone-like ore textures. This is because lava, while being mostly opaque, does not cover - blocks fully at the surface. -- use-permission - - **default**: false - - **description**: Whether 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 - - - **default**: [copper_ore, deepslate_copper_ore, gold_ore, deepslate_gold_ore, iron_ore, - deepslate_iron_ore, coal_ore, deepslate_coal_ore, lapis_ore, deepslate_lapis_ore, - mossy_cobblestone, obsidian, chest, diamond_ore, deepslate_diamond_ore, redstone_ore, - deepslate_redstone_ore, clay, emerald_ore, deepslate_emerald_ore, ender_chest] - - **description**: With `engine-mode: 1`, these blocks will be replaced by `stone` (`deepslate` at - y < 0), `netherrack`, or `end_stone`, based on the dimension. All types of air blocks are - ignored on this list. - - With `engine-mode: 2`, these blocks will be randomly placed in the world, replacing both - `hidden-blocks` and `replacement-blocks`. Tile entities, such as chests or spawners, are not - allowed on this list. Individual blocks may be added multiple times, increasing their chance of - being placed. The default block states are placed. - -- replacement-blocks: - - - **default**: [stone, oak_planks, deepslate] - - **description**: With `engine-mode: 1`, replacement blocks are not used. Changing this list will - have no effect. - - With `engine-mode: 2`, both `replacement-blocks` and `hidden-blocks` are randomly replaced by - `hidden-blocks.` While tile entities are ignored in the `hidden-blocks` list, they may be added - to the `replacement-blocks` list. All types of air blocks are ignored here. - -### viewdistances - -:::tip - -`no-tick-view-distance` has been replaced by `simulation-distance` in 1.18! - -| 1.17 | 1.18 | -| ------------------------------------- | ------------------------------------------- | -| `view-distance` (`server.proporties`) | `simulation-distance` (`server.properties`) | -| `no-tick-view-distance` (`paper.yml`) | `view-distance` (`server.proporties`) | - -::: - -- 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 to remove the dragon if it exists without a portal. - -### 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 item's 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. Disabling this option can improve the server performance significantly, while there is - almost no noticeable effect on the game mechanics. This is recommended when there are lots of - entities loaded, and you have automated farms or redstone clocks. - -### 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, the leash 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 chunk. A value of -1 - disables this limit -- ender_pearl - - **default**: -1 - - **description**: Limits the number of ender pearls that are saved/loaded per chunk. A value of - -1 disables this limit -- arrow - - **default**: -1 - - **description**: Limits the number of arrows that are saved/loaded per chunk. 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](https://bugs.mojang.com/browse/MC-108513). - -### 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 will attempt to break doors -- zombie_villager - - **default**: ['HARD'] - - **description**: Takes a list of difficulties at which zombie villagers will attempt to break - doors -- zombified_piglin - - **default**: ['HARD'] - - **description**: Takes a list of difficulties at which zombified piglins will attempt to break - doors -- husk - - **default**: ['HARD'] - - **description**: Takes a list of difficulties at which husks will attempt to break doors -- vindicator - - **default**: ['NORMAL', 'HARD'] - - **description**: Takes a list of difficulties at which vindicators will attempt 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. - -### 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. - -### anticheat - -- obfuscation - - items - - hide-itemmeta - - **default**: false - - **description**: Controls whether unnecessary item information (such as enchantments, items - in a shulker box/bundle, etc.) that can give cheat clients an advantage should be sent to - other players' clients. This may break resource packs that rely on information such as - enchantments, lore or item names when observing other players. - - hide-durability - - **default**: false - - **description**: Controls whether durability information is sent to other players' clients. - This may break resource packs that rely on durability values when observing other players. - -### tick-rates - -- sensor - - `` - - ``: Sets the sensor tick rate of an entity. -1 uses Vanilla. See timings for the - names. Might change between updates! - - villager - - secondarypoisensor - - **default**: 40 - - **description**: Sets the tick rate of the `secondarypoisensor` sensor of Villager entities -- behavior - - `` - - ``: Sets the behavior tick rate of an entity. -1 uses Vanilla. See timings for - the names. Might change between updates! - - villager - - validatenearbypoi - - **default**: -1 - - **description**: Sets the tick rate of the `validatenearbypoi` behavior. of Villager - entities - -### feature-seeds - -- generate-random-seeds-for-all - - **default**: false - - **description**: Enables autofilling random seeds for all available features you haven't already - set a seed to. Using this in a controlled environment is also a good way of receiving a full - list of features you can set seeds for. -- ``: Sets the population seed for the specified feature. If set to -1, the - Vanilla population seed stays unchanged and will not be overridden by the autofill option either. - -### split-overstacked-loot - -- **default**: true -- **description**: When set to false, loot tables will not attempt to split items with a stack size - higher than the maximum into items of smaller stack sizes. This will prevent overstacked items - from being lost or causing a chunk to become uninhabitable (due to players getting constantly - kicked because of oversized packets) when a shulker box is broken in survival. - -### monster-spawn-max-light-level - -- **default**: -1 -- **description**: When set to -1, the Vanilla default will be used (=0). Set to 15 or greater to - revert to pre-1.18 behavior. diff --git a/docs/versioned/paper/content/1.18/dev/README.mdx b/docs/versioned/paper/content/1.18/dev/README.mdx deleted file mode 100644 index f75f79230..000000000 --- a/docs/versioned/paper/content/1.18/dev/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Development Guide - -Welcome to the Paper Development Guide! This guide includes information and tutorials for developers -to create and expand on Paper plugins. - ---- - - diff --git a/docs/versioned/paper/content/1.19/README.md b/docs/versioned/paper/content/1.19/README.md deleted file mode 100644 index 6330399a7..000000000 --- a/docs/versioned/paper/content/1.19/README.md +++ /dev/null @@ -1,5 +0,0 @@ -# Welcome to the Paper Docs - -Paper is a high performance fork of the Spigot Minecraft Server that aims to fix gameplay and -mechanic inconsistencies as well as to improve performance. Paper contains numerous features, bug -fixes, exploit preventions and major performance improvements not found in Spigot. diff --git a/docs/versioned/paper/content/1.19/admin/README.mdx b/docs/versioned/paper/content/1.19/admin/README.mdx deleted file mode 100644 index c5d37505e..000000000 --- a/docs/versioned/paper/content/1.19/admin/README.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -slug: /admin ---- - -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Paper Server Administration - -Welcome to the Paper Server Administration Guide! This guide includes information and tutorials -regarding the administration of a Paper server. - ---- - - diff --git a/docs/versioned/paper/content/1.19/admin/getting-started/adding-plugins.md b/docs/versioned/paper/content/1.19/admin/getting-started/adding-plugins.md deleted file mode 100644 index bd3c1f87d..000000000 --- a/docs/versioned/paper/content/1.19/admin/getting-started/adding-plugins.md +++ /dev/null @@ -1,139 +0,0 @@ ---- -toc_max_heading_level: 4 -slug: /adding-plugins ---- - -# Adding Plugins - -Plugins are the most powerful way to extend the functionality of Paper beyond the configuration -files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow, -to adding entirely new and original game modes or items. - -:::danger[Malicious Plugins] - -Ensure you fully trust the source of any plugin before installing it. Plugins are given **full and -unrestricted** access to not only your server but also the machine that it runs on. Because of this, -it is imperative that plugins only be installed from trusted sources. Be careful! - -::: - -## Finding Plugins - -Before installing a plugin, you'll need to find what you want to install. The best place to find plugins is [Hangar](https://hangar.papermc.io), Paper's plugin repository, but you can also find many plugins -on [SpigotMC](https://www.spigotmc.org/resources/), -[BukkitDev](https://dev.bukkit.org/bukkit-plugins), or the -[PaperMC Forums](https://forums.papermc.io/forums/paper-plugin-releases/), while other plugins may -release on [GitHub](https://github.com). One of the best ways to find plugins isn't to browse any of -these sites directly but to search for plugins using a search engine. Searching for the function you -desire followed by `Minecraft plugin` will often yield good results. - -:::tip[Spigot and Bukkit Plugins] - -Paper is compatible with both Spigot and Bukkit plugins. It's okay if a plugin does not explicitly -mention Paper compatibility. It'll still work. - -::: - -## Installing Plugins - -1. Once you've found the plugin you'd like to install, download it. Ensure the file you have - downloaded ends in `.jar`. Some plugins also distribute as `.zip` files, in which case you will - need to extract the file and locate the `.jar` for your platform, often labelled `bukkit` or - `paper`. -2. Once you have the plugin downloaded locally, locate the `plugins` folder from the root directory - of your Paper server. -3. Drag and drop the plugin file (`.jar`) into the `plugins` folder. If you are using a shared - hosting service, you may need to use their web panel or SFTP to upload the plugin; however, the - procedure will be the same. -4. Restart your server. The plugin should load. -5. Check your work. Once the server has finished loading, run the `/plugins` command in-game or type - `plugins` into the console. You should see your freshly installed plugin listed in green. If it - is not listed or is colored red, continue to [troubleshooting](#troubleshooting). A plugin listed - in red means that it is not currently enabled. For a freshly installed plugin, this often means - that the plugin failed to load. - -## Troubleshooting - -### Check your logs - -The first step to troubleshooting installing plugins is to check the log of your server. Your -server's most recent logs will be stored to the `logs/latest.log` file. You may need to scroll near -the beginning of this file to see when plugins were loaded. - -#### Missing Dependencies - -If you see something like this: - -```log -Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' -org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. -``` - -This means that the plugin you tried to install is missing a dependency. A dependency, in this case, -is another plugin that you must install for the first to function. While you will get a big scary -error, the important line to look at is - -```log -Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. -``` - -This is telling you that in order to load `MyAwesomePlugin`, you must first install `Vault`. - -#### Invalid plugin.yml - -If you see something closer to this: - -```log -Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' -org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml -``` - -This means that what you have downloaded isn't a valid Paper plugin. This is generally caused by one -of the following: - -1. The plugin you downloaded isn't a plugin at all, but instead a mod for Forge, Fabric, or similar. - These will not run on Paper. -2. The plugin failed to download completely. Especially when using tools such as `curl` or `wget`, - you can easily download error pages rather than the plugin you intended. This may also be caused - by a network issue. Attempt to download the plugin again. If you are using FTP (not SFTP or a web - panel) to upload your plugin to a shared hosting service, ensure your FTP client is in `binary` - and not `ASCII` mode. Consult the documentation for your FTP client for details. - -#### Ambiguous plugin name - -If you see something like this: - -```log -Ambiguous plugin name `Essentials' for files `plugins/EssentialsX-2.19.4.jar' and `plugins/Essentialsx-2.20.0-dev.jar' in `plugins' -``` - -This means you have two plugins with the same name, which is not supported. In this case, two -versions of EssentialsX are installed. Both the release `2.19.4`, and a development build of -`2.20.0`. Ensure you only have one version of each plugin installed at one time. Delete the older -version of the duplicate plugin, and restart your server. - -[//]: # "To prevent accidentally installing two versions of one plugin while updating, you can use" -[//]: # "the `update` folder as described in the [Update Guide](/paper/how-to/update)." - -#### Something Else - -If you see an error, but it isn't similar to one of the above, attempt to read it yourself. While -the full error may be large and scary, you likely only have to read the first one or two lines to -understand what is going on. If you're not sure, do not hesitate to reach out for support on our -[Discord](https://discord.gg/papermc) in the `#paper-help` channel. - -### If nothing is logged - -If nothing is logged, your server is likely not attempting to load any plugins. The conditions -needed for the server to load a plugin are as follows: - -1. The file is at the root of the `plugins` folder, relative to its working directory. This is - usually the same folder as the server JAR file. **Subdirectories of the `plugins` folder will not - be checked.** All plugins must be in the root folder. -2. The file ends in `.jar`. If your plugin does not end in `.jar`, what you have downloaded may not - be a plugin. Note that some plugins distribute multiple jars as `.zip` files. If this is the - case, you have to extract them before installing the plugin. - -If both of these are true and you still see no logs please reach out for support on our -[Discord](https://discord.gg/papermc) server in the `#paper-help` channel. We will be happy to -assist you. diff --git a/docs/versioned/paper/content/1.19/admin/getting-started/getting-started.md b/docs/versioned/paper/content/1.19/admin/getting-started/getting-started.md deleted file mode 100644 index 8f3eb64ed..000000000 --- a/docs/versioned/paper/content/1.19/admin/getting-started/getting-started.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -slug: /getting-started ---- - -# Getting Started - -## Requirements - -:::tip - -With the release of Minecraft 1.18, Paper now requires **Java 17** to run. If you don't already have -Java 17, [it's easy to download and install](/misc/java-install). - -::: - -| Paper Version | Recommended Java Version | -| -------------- | ------------------------ | -| 1.8 to 1.11 | Java 8 | -| 1.12 to 1.16.4 | Java 11 | -| 1.16.5 | Java 16 | -| 1.17.1-1.18.1+ | Java 17 | - -## Migrating to Paper - -### 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. No additional consideration is required. - -### From Craftbukkit or Spigot - -Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes. - -## Downloading Paper - -Paper provides runnable server jars directly from our -[website's downloads page](https://papermc.io/downloads). - -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`. Ensure you replace `paper.jar` with the name of the jar -you have downloaded. - -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 Flags](../how-to/aikars-flags.md). - -To configure your server, see the [Global Configuration](../reference/global-configuration.md) and -[Per World Configuration](../reference/world-configuration.md) pages. - -## Updating The Server - -Updating Paper is simple! See our [Update Tutorial](../how-to/update.md) for more information. diff --git a/docs/versioned/paper/content/1.19/admin/getting-started/migration.md b/docs/versioned/paper/content/1.19/admin/getting-started/migration.md deleted file mode 100644 index 33eac47af..000000000 --- a/docs/versioned/paper/content/1.19/admin/getting-started/migration.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -slug: /migration -title: Migrating to or from Paper ---- - -It's simple to migrate your server to or from Paper. The steps below will help you get started. - -:::caution[Backup your data before you start!] - -Before you begin, please ensure you have a full backup of your server. - -[//]: # "See our [Backup Guide](/backup) for more information." - -::: - -## Migrating to Paper - -### From CraftBukkit or Spigot - -It's easy to migrate from CraftBukkit or Spigot to Paper. Follow the steps below. - -1. Stop your server if it is running, and create a full backup. -2. Download Paper from [our downloads page](https://papermc.io/downloads). -3. Replace your existing server jar with your freshly downloaded Paper jar. -4. Start your new server. - -Paper retains full compatibility with all Spigot plugins, allowing a seamless transition. - -:::info - -Your new Paper server will still use `bukkit.yml` and `spigot.yml`, only adding new configuration -options in `paper.yml`. - -::: - -If you have any issues migrating from CraftBukkit or Spigot, do not hesitate to reach out for -support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel). - -### From Vanilla - -When migrating to Paper from Vanilla, the way worlds are stored will automatically be changed. -Should you ever want to go back to Vanilla, follow the [Vanilla Migration Guide](#to-vanilla) -closely, as manual changes will be required. - -1. Stop your Vanilla server if it is running, and create a full backup. -2. Downloads Paper from [our downloads page](https://papermc.io/downloads) and replace your Vanilla - server jar with your freshly downloaded Paper jar. -3. Start your new Paper server. - -You have now successfully migrated to Paper. If you encounter any issues, do not hesitate to reach -out for support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel). - -### From Fabric/Forge - -Because both Fabric and Forge use the Vanilla world directory structure, the same steps as the -[Vanilla Migration Guide](#from-vanilla) may be used, with one caveat. If your Fabric or Forge -server used mods that added new blocks, items, or other data to the game, Paper will be unable to -load these features. - -Additionally, note that Paper does not support Fabric or Forge mods. You will need to find plugin -replacements. Any hybrids that attempt to support both mods and plugins are fundamentally flawed and -not recommended for use. - -## Migrating From Paper - -### To Vanilla - -Because Paper stores worlds slightly differently than Vanilla, manual work is required to migrate. -If these steps are not taken, your nether and end will look like they have been reset. Don't worry! -Even if this has happened, you haven't lost any data. The Vanilla server just doesn't know where to -find it. - -Here is a chart to show the difference between how Vanilla and Paper store worlds. - -| Server Software | Overworld | Nether | End | -| --------------- | --------- | --------------------- | --------------------- | -| Vanilla | `/world` | `/world/DIM-1` | `/world/DIM1` | -| Paper | `/world` | `/world_nether/DIM-1` | `/world_the_end/DIM1` | - -Follow these steps to migrate from Paper to Vanilla: - -:::note - -These steps assume a `level-name` (as set in `server.properties`) of `world`. If this is not the -case for you, replace `world` with your `level-name` for all steps below. - -::: - -1. Stop your Paper server, if it is running. -2. If you have already started your server with Vanilla, enter the `world` folder and delete both - the `DIM-1` and `DIM1` folders. This step is only necessary should you have started your server - with Vanilla. -3. Copy the `/world_nether/DIM-1` folder into the `/world` folder. -4. Copy the `/world_the_end/DIM1` folder into the `/world` folder. -5. Delete both the `/world_nether` and `/world_the_end` folders. -6. Replace your Paper jar with a Vanilla server jar. -7. Start your Vanilla server. - -### To CraftBukkit or Spigot - -Paper does **not** support migration to either CraftBukkit or Spigot! While you may find success -(both CraftBukkit and Spigot use the same directory structure as Paper), **do not** reach out for -support with issues you encounter and note that data loss is possible. - -### To Fabric/Forge - -Because both Fabric and Forge use the same directory structure for world storage as Vanilla, follow -the [Vanilla Migration Guide](#to-vanilla) for this process. Note that neither Fabric nor Forge will -support Paper plugins! You will be required to find replacement mods. diff --git a/docs/versioned/paper/content/1.19/admin/how-to/aikars-flags.md b/docs/versioned/paper/content/1.19/admin/how-to/aikars-flags.md deleted file mode 100644 index acceb499a..000000000 --- a/docs/versioned/paper/content/1.19/admin/how-to/aikars-flags.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -slug: /aikars-flags ---- - -# Aikar's Flags - -## Recommended JVM Startup Flags - -Use these flags exactly, only changing Xmx and Xms. These flags work and scale accordingly to any -size of memory, even 500MB but modern Minecraft versions will not do well with such low memory. - -```bash -java -Xms10G -Xmx10G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar --nogui -``` - -:::caution[Do not allocate all of your available memory on a shared host!] - -When setting the Xms and Xmx values, if your host says you have 8000M memory, DO NOT USE 8000M! -Minecraft (and Java) needs additional memory on top of that Xmx parameter. It is recommended to -reduce your Xmx/Xms by about **1000-1500M** to avoid running out of memory or "OOMKiller" hitting -your server. This also leaves room for the Operating System to use memory too. **Have 8000M memory? -Use 6500M for safety.** _But you may also ask your host if they will cover this overhead for you and -give you 9500M instead. Some hosts will! Just ask._ - -::: - -## Recommended Memory - -**We recommend using at least 6-10GB**, no matter how few players! If you can't afford 10GB of -memory, give as much as you can, but ensure you leave the operating system some memory too. G1GC -operates better with more memory. - -However, more memory does not mean better performance above a certain point. Eventually you will hit -a point of diminishing returns. Going out and getting 32GB of RAM for a server will only waste your -money with minimal returns. - -If you are running with 12GB or less memory for MC, you should not adjust these parameters. - -### If you are using an Xmx value greater than 12G - -If you have and use more than 12GB of memory, adjust the following: - -- `-XX:G1NewSizePercent=40` -- `-XX:G1MaxNewSizePercent=50` -- `-XX:G1HeapRegionSize=16M` -- `-XX:G1ReservePercent=15` -- `-XX:InitiatingHeapOccupancyPercent=20` - -:::tip - -If you see increase in old generation collections after this, revert to the base flags! - -::: - -Explanation of these changes: - -- Base flag set aims for 30/40 to reduce risk of to space issues. With more memory, less of an - issue. We can give more to new generation with 40/50, as well as reduce reserve percent since the - default reserve will already be larger. -- Region Size increase helps reduce humongous allocations, and speeds up remarking. We need a - smaller region size at smaller heaps to ensure an adequate amount of regions available -- We can start looking for old generation memory to reclaim with more of a delay with IHOP at 20 - since we have more old generation available to space on CPU. - -## Java GC Logging - -Are you having old gen issues with these flags? Add the following flags based on your java version -to enable GC Logging: - -**Java 8-10** - -```bash --Xloggc:gc.log -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps --XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=1M -``` - -**Java 11+** - -```bash --Xlog:gc*:logs/gc.log:time,uptime:filecount=5,filesize=1M -``` - -GC logging does not hurt your performance and can be left on at all times. The files will not take -up much space (5MB) - -## Technical Explanation of the Flags - -1. **-Xms matching -Xmx -- Why:** You should never run your server with the case that -Xmx can run - the system completely out of memory. Your server should always be expected to use the entire - -Xmx! You should then ensure the OS has extra memory on top of that Xmx for non MC/OS level - things. Therefore, you should never run MC with -Xmx settings you can't support if java uses it - all. Now, that means if -Xms is lower than -Xmx **YOU HAVE UNUSED MEMORY! Unused memory is - wasted memory.** G1 operates better with the more memory it's given. G1 adaptively chooses how - much memory to give to each region to optimize pause time. If you have more memory than it needs - to reach an optimal pause time, G1 will simply push that extra into the old generation, and it - will not hurt you The fundamental idea of improving GC behavior is to ensure short-lived objects - die young and never get promoted. With the more memory G1 has, the better assurance you will get - that objects are not getting prematurely promoted to the old generation. G1 Operates differently - than previous collectors and is able to handle larger heaps more efficiently. - - If it does not need the memory given to it, it will not use it. The entire engine operates - differently and does not suffer from too large of heaps, and this is industry-wide accepted - information that under G1 to keep Xms and Xmx the same! - -2. **UnlockExperimentalVMOptions** -- needed for some the below options - -3. **G1NewSizePercent:** These are the important ones. You now can specify percentages of an - overall desired range for the new generation. With these settings, we tell G1 to not use its - default 5% for new gen, and instead give it 40%! **Minecraft has an extremely high a memory - allocation rate, ranging to at least 800 Megabytes a second on a 30 player server! And this is - mostly short-lived objects (Block Position).** - - Now, this means MC REALLY needs more focus on New Generation to be able to even support this - allocation rate. If your new gen is too small, you will be running new gen collections 1-2+ - times per second, which is awful. You will have so many pauses that TPS has risk of suffering, - and the server will not be able to keep up with the cost of GC's. Then combine the fact that - objects will now promote faster, resulting in your Old Gen growing faster. Given more New Gen, - we are able to slow down the intervals of Young Gen collections, resulting in more time for - short-lived objects to die young and overall more efficient GC behavior. - -4. **G1MixedGCLiveThresholdPercent:** Controls when to include regions in Mixed GC's in the Young - GC collection, keeping Old Gen tidy without doing a normal Old Gen GC collection. When your - memory is less than this percent, old gen won't even be included in 'mixed' collections. Mixed - are not as heavy as a full old collection, so having small incremental cleanups of old keeps - memory usage light. - - Default is 65 to 85 depending on Java Version, we are setting to 90 to ensure we reclaim garbage - in old gen as fast as possible to retain as much free regions as we can. - -5. **G1ReservePercent=20:** MC Memory allocation rate in up-to-date versions is really insane. We - run the risk of a dreaded "to-space exhaustion" not having enough memory free to move data - around. This ensures more memory is waiting to be used for this operation. Default is 10, so we - are giving another 10 to it. - -6. **MaxTenuringThreshold=1:** Minecraft has a really high allocation rate of memory. Of that - memory, most is reclaimed in the eden generation. However, transient data will overflow into - survivor. Initially played with completely removing Survivor and had decent results, but does - result in transient data making its way to Old which is not good.Max Tenuring 1 ensures that we - do not promote transient data to old generation, but anything that survives 2 passes of Garbage - Collection is just going to be assumed as longer-lived. - - Doing this greatly reduces pause times in Young Collections as copying data up to 15 times in - Survivor space for a tenured object really takes a lot of time for actually old memory. Ideally - the GC engine would track average age for objects instead and tenure out data faster, but that - is not how it works. - - Considering average GC rate is 10s to the upwards of minutes per young collection, this does not - result in any 'garbage' being promoted, and just delays longer lived memory to be collected in - Mixed GC's. - -7. **SurvivorRatio=32:** Because we drastically reduced MaxTenuringThreshold, we will be reducing - use of survivor space drastically. This frees up more regions to be used by Eden instead. - -8. **AlwaysPreTouch:** AlwaysPreTouch gets the memory setup and reserved at process start ensuring - it is contiguous, improving the efficiency of it more. This improves the operating systems - memory access speed. Mandatory to use Transparent Huge Pages - -9. **+DisableExplicitGC:** Many plugins think they know how to control memory, and try to invoke - garbage collection. Plugins that do this trigger a full garbage collection, triggering a massive - lag spike. This flag disables plugins from trying to do this, protecting you from their bad - code. - -10. **MaxGCPauseMillis=200:** This setting controls how much memory is used in between the Minimum - and Maximum ranges specified for your New Generation. This is a "goal" for how long you want - your server to pause for collections. 200 is aiming for at most loss of 4 ticks. This will - result in a short TPS drop, however the server can make up for this drop instantly, meaning it - will have no meaningful impact to your TPS. 200ms is lower than players can recognize. In - testing, having this value constrained to an even lower number results in G1 not recollecting - memory fast enough and potentially running out of old gen triggering a Full collection. Just - because this number is 200 does not mean every collection will be 200. It means it can use up to - 200 if it really needs it, and we need to let it do its job when there is memory to collect. - -11. **+ParallelRefProcEnabled:** Optimizes the GC process to use multiple threads for weak reference - checking. Not sure why this isn't default... - -12. **G1RSetUpdatingPauseTimePercent=5:** Default is 10% of time spent during pause updating Rsets, - reduce this to 5% to make more of it concurrent to reduce pause durations. - -13. **G1MixedGCCountTarget=4:** Default is 8. Because we are aiming to collect slower, with less old - gen usage, try to reclaim old gen memory faster to avoid running out of old. - -14. **G1HeapRegionSize=8M+:** Default is auto calculated. SUPER important for Minecraft, especially - 1.15, as with low memory situations, the default calculation will in most times be too low. Any - memory allocation half of this size (4MB) will be treated as "Humongous" and promote straight to - old generation and is harder to free. If you allow java to use the default, you will be - destroyed with a significant chunk of your memory getting treated as Humongous. - -15. **+PerfDisableSharedMem:** Causes GC to write to file system which can cause major latency if - disk IO is high -- See https://www.evanjones.ca/jvm-mmap-pause.html - -## Using Large Pages - -For Large Pages -- It's even more important to use -Xms = -Xmx! Large Pages needs to have all the -memory specified for it, or you could end up without the gains. This memory will not be used by the -OS anyway, so use it. - -Additionally, use these flags (Metaspace is Java 8 Only, don't use it for Java7): -`-XX:+UseLargePagesInMetaspace` - -### Transparent Huge Pages - -Controversial feature but may be usable if you can not configure your host for real HugeTLBFS. Try -adding `-XX:+UseTransparentHugePages` but it's extremely important you also have AlwaysPreTouch set. -Otherwise, THP will likely hurt you. We have not measured how THP works for MC or its impact with -AlwaysPreTouch, so this section is for the advanced users who want to experiment. diff --git a/docs/versioned/paper/content/1.19/admin/how-to/anti-xray.mdx b/docs/versioned/paper/content/1.19/admin/how-to/anti-xray.mdx deleted file mode 100644 index 28311d657..000000000 --- a/docs/versioned/paper/content/1.19/admin/how-to/anti-xray.mdx +++ /dev/null @@ -1,355 +0,0 @@ ---- -slug: /anti-xray ---- - -# Configuring Anti-Xray - -> Originally written and maintained by [stonar96](https://github.com/stonar96). - -Paper includes an obfuscation-based Anti-Xray with two modes, configurable on a per world basis. - -:::info[Per World Configuration] - -If you aren't already familiar with per world configuration, please take a moment to familiarize -yourself with the [Configuration Guide](configuration.md). - -::: - -This guide is a step-by-step walk-through for configuring Anti-Xray. For reference documentation, -refer to the Anti-Xray section of the -[Per-World Configuration Reference](../reference/world-configuration.md#anti-xray). - -Anti-Xray has two different modes. `engine-mode: 1` replaces specified blocks (`hidden-blocks`) with -other "fake" blocks, `stone` (`deepslate` at y < 0), `netherrack`, or `end_stone` based on the -dimension. In contrast, `engine-mode: 2` will replace both `hidden-blocks` and `replacement-blocks` -with randomly generated `hidden-blocks`. - -The following images[^1] show how each mode will look for a player using Xray with the recommended -configuration in both the overworld and nether. - -[^1]: - Image design by `Oberfail`, initially posted in the - [PaperMC Discord](https://discord.gg/papermc). - -![Overworld Anti-Xray Comparison](assets/anti-xray-overworld.png) -![Nether Anti-Xray Comparison](assets/anti-xray-nether.png) - -Especially on the client side, `engine-mode: 1` is much less computationally intensive, while -`engine-mode: 2` may better prevent Xray. With `engine-mode: 1`, only ores that are entirely covered -by solid blocks will be hidden. Ores exposed to air in caves or water from a lake will not be -hidden. With `engine-mode: 2`, fake ores obstruct the view of real blocks. If `air` is added to -`hidden-blocks`, `engine-mode: 2` will effectively hide all ores, even those exposed to air. - -:::caution[Anti-Xray Bypasses] - -**Range Extension**: While Anti-Xray alone will prevent the majority of users from Xraying on your -server, it is not by any means infallible. Because of how Anti-Xray is (and has to be) implemented, -it is possible to, on a default server, extend the range of real ores you can see by a not -insignificant amount. This can be mitigated by any competent anti-cheat plugin; however, this is not -included out of the box. - -**Seed Reversing**: Another attack vector is the deterministic nature of Minecraft's world -generation. If the client is able to obtain the world seed, it is able to know the real location of -every generated ore, completely bypassing Anti-Xray. This can be partially worked around by making -it harder for the client to reverse the world seed with the -[`feature-seeds` configuration](../reference/world-configuration.md#feature-seeds), in conjunction -with the structure seed options in `spigot.yml`. Note that this is not a complete solution, and it -may still be possible for a client to obtain the server's world seed. Using a different seed for -each world may also be beneficial. - -**Ores Exposed to Air**: In both `engine-mode: 1` and `engine-mode: 2`, it is possible for a client -to view ores that are exposed to air. This can be mitigated in `engine-mode: 2` by adding `air` to -the `hidden-blocks` list. However, doing this may cause client performance issues (FPS drops) for -some players. - -::: - -## Recommended Configuration - -The recommended configuration for both `engine-mode: 1` and `engine-mode: 2` is as follows: - -:::tip[Spacing] - -YAML cares about whitespace! The example configuration below is already formatted correctly. Ensure -formatting and indentation remains unchanged by using the "copy" button in the top right of each -example. Especially ensure that no tabulators are accidentally inserted. Check your editor's options -for using spaces instead of tabulators for indentation. If your configuration file already contains -other important changes, it is recommended to make a backup before editing it. - -::: - -### `engine-mode: 1` - -
- Default World Configuration - -Replace the existing `anticheat.anti-xray` block in `paper-world-defaults.yml` with the following: - -{/* prettier-ignore */} -```yaml title="paper-world-defaults.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 1 - hidden-blocks: - # There's no chance to hide dungeon chests as they are entirely surrounded by air, but buried treasures will be hidden. - - chest - - coal_ore - - deepslate_coal_ore - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - emerald_ore - - deepslate_emerald_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - lava-obscures: false - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - # The replacement-blocks list is not used in engine-mode: 1. Changing this will have no effect. - replacement-blocks: [] - update-radius: 2 - use-permission: false - -``` - -
- -
- Nether Configuration - -Copy and paste into your `paper-world.yml` within your nether world folder. See the -[Configuration Guide](configuration.md) for more information. - -{/* prettier-ignore */} -```yml title="world_nether/paper-world.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 1 - hidden-blocks: - - ancient_debris - - nether_gold_ore - - nether_quartz_ore - lava-obscures: false - max-block-height: 128 - # The replacement-blocks list is not used in engine-mode: 1. Changing this will have no effect. - replacement-blocks: [] - update-radius: 2 - use-permission: false - -``` - -
- -
- End Configuration - -Copy and paste into your `paper-world.yml` within your end world folder. See the -[Configuration Guide](configuration.md) for more information. - -{/* prettier-ignore */} -```yml title="world_the_end/paper-world.yml" -anticheat: - anti-xray: - enabled: false - -``` - -
- -### `engine-mode: 2` - -
- Default World Configuration - -Replace the existing `anticheat.anti-xray` block in `paper-world-defaults.yml` with the following: - -{/* prettier-ignore */} -```yaml title="paper-world-defaults.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 2 - hidden-blocks: - # You can add air here such that many holes are generated. - # This works well against cave finders but may cause client FPS drops for all players. - - air - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - lava-obscures: false - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - replacement-blocks: - # Chest is a tile entity and can't be added to hidden-blocks in engine-mode: 2. - # But adding chest here will hide buried treasures, if max-block-height is increased. - - chest - - amethyst_block - - andesite - - budding_amethyst - - calcite - - coal_ore - - deepslate_coal_ore - - deepslate - - diorite - - dirt - - emerald_ore - - deepslate_emerald_ore - - granite - - gravel - - oak_planks - - smooth_basalt - - stone - - tuff - update-radius: 2 - use-permission: false - -``` - -
- -
- Nether Configuration - -Copy and paste into your `paper-world.yml` within your nether world folder. See the -[Configuration Guide](configuration.md) for more information. - -{/* prettier-ignore */} -```yml title="world_nether/paper-world.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 2 - hidden-blocks: - # See note about air and possible client performance issues above. - - air - - ancient_debris - - bone_block - - glowstone - - magma_block - - nether_bricks - - nether_gold_ore - - nether_quartz_ore - - polished_blackstone_bricks - lava-obscures: false - max-block-height: 128 - replacement-blocks: - - basalt - - blackstone - - gravel - - netherrack - - soul_sand - - soul_soil - update-radius: 2 - use-permission: false - -``` - -
- -
- End Configuration - -Copy and paste into your `paper-world.yml` within your end world folder. See the -[Configuration Guide](configuration.md) for more information. - -{/* prettier-ignore */} -```yml title="world_the_end/paper-world.yml" -anticheat: - anti-xray: - enabled: false - -``` - -
- -## FAQ, Common Pitfalls and Support - -
- I can still see (some) ores / use X-ray - -As described above, there are several reasons why you might still see (some) ores even though you -have enabled Anti-Xray: - -* The ores are above the configured `max-block-height` value. -* Anti-Xray cannot hide ores exposed to air or other transparent blocks (in caves for example). In - principle this is also the case for `engine-mode: 2`, however, usually the fake ores obstruct the - view of real blocks. Hiding those exposed ores too requires additional plugins. -* The `use-permission` option is enabled and you have the Anti-Xray bypass permission or you have - operator status. -* The block type is missing in the configured block lists. This can be the result of using an - outdated configuration file. - -
- -
- I have added fake blocks but X-ray doesn't show them - -If you use `engine-mode: 2` and you have added fake blocks to the `hidden-blocks` list but you can't -see them in-game using X-ray, this can have the following reasons: - -* The added block types are tile entities. Anti-Xray can hide (replace) tile entities (such as - chests), provided that they are not exposed to air or other transparent blocks. However, Anti-Xray - can't place tile entities as fake blocks into the chunk. -* The block is disabled in your client's X-ray mod or not shown by your X-ray resource pack. - -
- -
- It doesn't work below y = 0 or in certain other places. - -* Your configuration file is probably outdated and missing important blocks in the - `replacement-blocks` list, such as `deepslate` or biome-specific blocks, such as `basalt`. You - might also want to check if the `hidden-blocks` list includes all important ores and their - `deepslate` variants. -* If it doesn't work above a certain y-level, check your `max-block-height` setting. - -
- -
- It still doesn't work, further troubleshooting - -* Make sure to always restart your server after making changes to the Anti-Xray configuration. - Changes won't be applied automatically. -* Do not use the `/reload` command. To apply Anti-Xray configuration changes a restart is required. -* After restarting the server, verify that the configuration is applied correctly by inspecting the - config sections with timings or spark. - -
- -
- How and where do I ask for support if it still doesn't work? - -If the above bullet points don't solve your problem or if you have further questions about -Anti-Xray, please don't hesitate to ask us on the [PaperMC Discord](https://discord.gg/papermc) -using the #paper-help channel. Please try to provide as much detail as possible about your problem. -"It doesn't work" isn't very helpful when asking for support. Describe what you want to achieve, -what you have tried, what you expect and what you observe. Ideally include a timings or spark link -and a picture what you observe in-game. - -
diff --git a/docs/versioned/paper/content/1.19/admin/how-to/assets/anti-xray-nether.png b/docs/versioned/paper/content/1.19/admin/how-to/assets/anti-xray-nether.png deleted file mode 100644 index 3783ef88f..000000000 Binary files a/docs/versioned/paper/content/1.19/admin/how-to/assets/anti-xray-nether.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.19/admin/how-to/assets/anti-xray-overworld.png b/docs/versioned/paper/content/1.19/admin/how-to/assets/anti-xray-overworld.png deleted file mode 100644 index e470af9c9..000000000 Binary files a/docs/versioned/paper/content/1.19/admin/how-to/assets/anti-xray-overworld.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.19/admin/how-to/basic-troubleshooting.md b/docs/versioned/paper/content/1.19/admin/how-to/basic-troubleshooting.md deleted file mode 100644 index d24b3ec32..000000000 --- a/docs/versioned/paper/content/1.19/admin/how-to/basic-troubleshooting.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -slug: /basic-troubleshooting ---- - -# Basic Troubleshooting - -This guide will help you diagnose your server's problem before reporting it to PaperMC or the plugin's author. - -:::caution[Stop Your Server And Take A Backup] - -Before following this guide, stop your server first. Modifying server files while it is still running will corrupt them. -Only a full server shutdown can prevent this. - -Also, if you don't follow this guide carefully or make a mistake while following this guide, you might corrupt your server. It is highly advised to backup your server before following this guide. -It would be ideal to create a test server by copying your production server's file, but that's not always possible. - -::: - -## Read The Error Message - -If your server encounters a problem, it will either print an error message on the server console, create a crash report and close itself, or do both. - -If your server crashes, the crash report will be saved in the `crash-report` directory. -If your server didn't crash, those error messages will be stored in the `log` directory along with other messages. - -Note that the logs older than the latest will be compressed and not stored as plain text files. - -The first thing you have to do is diagnose those messages. - -### Case 01: Paper Watchdog Thread Dump - -If your error message looks like this, **do not blindly report it to PaperMC** as it says: - -```plaintext -[00:00:00] [Paper Watchdog Thread/ERROR]: --- DO NOT REPORT THIS TO PAPER - THIS IS NOT A BUG OR A CRASH - git-Paper-366 (MC: 1.19.3) --- -[00:00:00] [Paper Watchdog Thread/ERROR]: The server has not responded for 10 seconds! Creating thread dump -[00:00:00] [Paper Watchdog Thread/ERROR]: ------------------------------ -``` - -This can be caused by various things. Maybe your server's hardware is not capable of running Minecraft server. Maybe one of the plugins you use is causing lag on your server. - -The thread dump from Paper Watchdog can be found below that line. If you find any plugin's name in there, talk to the plugin's author about that, not PaperMC. - -### Case 02: Stack Trace - -Almost every problem you encounter will print error message lines, which are called "stack trace", on the server console. Examining the stack trace will help you find out what is causing problems on your server. - -The stack trace starts with the error message, exception type, and exception message. - -Both error messages and exception messages were put there by the developer of either your plugin or paper server. These messages tell you what problem your server experienced. -An exception type like `java.lang.RuntimeException` tells you the type of the exception. This will help the developer (and you) understand the type of problem. - -Many lines beginning with `at` may appear beneath the exception message. These are the body of the stack trace. These lines tell you where the problem starts. The top line of the body of the stack trace will tell you exactly where the problem occurred and, if possible, display where it came from. - -If you find any plugin's name in the stack trace, head to [Check Plugin Updates](#check-plugin-updates) and read from there. In most cases, the plugin, whose name is found on the stack trace, is causing the problem. If not, continue reading. - -Here are some examples of stack trace. - -
- Example 01: Server attempted to load chunk saved with newer version of minecraft! - -```plaintext -[00:00:00 WARN]: java.lang.RuntimeException: Server attempted to load chunk saved with newer version of minecraft! 3218 > 3120 -``` - -You tried to load the world generated with a higher version of Minecraft. You cannot do this. -If you don't have any backup of your world before the chunk version update, you must use your updated world with a higher version of Minecraft. - -
- - - -## Find Out What Plugin Is Causing The Problem - -If you can't find the name of any plugin in the thread dump or stack trace, try these steps. - -### Disable All Plugins - -To determine if it is a plugin or the paper itself that is causing problems, disable all of your plugins first. - -You can disable all of your plugins by renaming the `plugins` directory to something else, such as `plugins-disabled`, or by archiving the `plugins` directory and deleting it. - -After that, try to run your server. - -If the problem is resolved after removing the plugins, you know that it was a plugin that caused the issue. -If you still experience problems, head to [Paper Documentation](#paper-documentation). Maybe your paper server is misconfigured, and that is creating issues. - -### Binary Search - -To efficiently search for the plugin that is causing the issue, you can do the following: - -1. **Split your plugins into two groups** - The size of the two groups can be different, but it is ideal if the difference is minimal. -2. **Disable one of the two groups of plugins** - You can disable them by changing their extension from `.jar` to `.jar-disabled`. -3. **Run your server and check if the problem still exists** - If the problem is resolved, the plugin that caused the issue is one of the disabled plugins. - If the problem is not resolved, the plugin that is causing the issue is one of the active plugins. -4. **Repeat from the start with the suspect plugin group** - Repeat the steps above with groups that have the plugin that is causing the issue. - -## Check Plugin Updates - -There is a chance that your problem is already fixed in the latest release or latest build of the plugin. - -Head to your plugin's official download page and check if you are using the latest build or the latest release of the plugin. If not, update it to the latest version and try to run your server again to see if the problem is resolved. - -### Update Library Plugin Too - -Many plugins use library plugins like ProtocolLib, and you have to download them and put them in `plugins` directory. - -If you don't update them to the latest version or latest build, you might experience problems related to plugins that use the library plugin. - -Some library plugins tell their users to use their latest development build for support of the latest Minecraft version. You should look carefully at the requirements of your plugin. - -## Check Documentation - -If you misconfigured your plugin or your server, it can also cause problems on your server. - -### Plugin Documentation - -Many plugins provide their own documentation about how to set them up properly. Read those documents carefully and check if there is something wrong with the plugin's configuration. - -### Paper Documentation - -Paper can also be configured in a variety of ways. Check these documents for detailed explanations about each configuration. - -* [Paper Global Config](../reference/global-configuration.md) -* [Paper Per World Configuration](../reference/world-configuration.md) - -## Consult With Developer - -If your problem is related to a plugin you use and you still don't know how to solve it, you can try to reach out to the plugin's author. -Many plugins have a way to contact their author, like a GitHub issue tracker, Discord support guild, Gitter, IRC, etc. - -If your problem isn't related to any plugin, you can come to PaperMC's Discord server and ask for help, or create a new issue on our GitHub issue tracker. diff --git a/docs/versioned/paper/content/1.19/admin/how-to/configuration.md b/docs/versioned/paper/content/1.19/admin/how-to/configuration.md deleted file mode 100644 index 21b38f6a0..000000000 --- a/docs/versioned/paper/content/1.19/admin/how-to/configuration.md +++ /dev/null @@ -1,116 +0,0 @@ ---- -slug: /configuration ---- - -# Configuration - -:::note - -This guide currently only covers per-world configuration in `paper-world-defaults.yml`. Information -about general configuration will be added in the future. In the meantime, please refer to the -information in the [1.19 announcement forum post](https://forums.papermc.io/threads/paper-1-19.344). - -::: - - - -## Per World Configuration - -One of the most powerful yet least understood features of the Paper configuration is setting -configuration options per world. While you can not override every config option per world, -everything stored within `paper-world-defaults.yml` can be. - -### Default Values - -Paper sets no per-world overrides out of the box, storing all default values in -`config/paper-world-defaults.yml`. Everything in this file can be overridden per world but isn't by -default. Changing something in `paper-world-defaults.yml` will change the value for all worlds where -you have not manually overridden it. - -### Per World Values - -To set a value for a specific world, edit `paper-world.yml` within the world folder. For example, if -you wanted to disable `spawn.keep-spawn-loaded` for a world named `resource`, you would edit -`paper-world.yml` within the `resource` folder like so: - -```yaml title=resource/paper-world.yml -_version: 28 - -# highlight-start -spawn: - keep-spawn-loaded: false -# highlight-end -``` - -Nothing but `_version` is set in `paper-world.yml` configuration files by default. In order to -override the default for an option, you must manually add it by copying from -`paper-world-defaults.yml`. - -### Inheritance - -All configuration not explicitly defined for a world is inherited from `paper-world-defaults.yml`. -This means that there is no need to repeat yourself between the `paper-world-defaults.yml` and each -individual `paper-world.yml`. You **do not need to and should not** copy the entire -`paper-world-default.yml` file into each `paper-world.yml` file you want to modify. Only copy the -exact value you want to change. - -For a more complex real-world example: setting both different `spawn-limits` and `keep-spawn-loaded` -in two worlds. - -```yaml title="paper-world-defaults.yml" -entities: - spawning: - spawn-limits: - ambient: 70 - axolotls: 10 - creature: 15 - monster: 5 - underground_water_creature: 5 - water_ambient: 5 - water_creature: 20 -spawn: - keep-spawn-loaded: true -``` - -```yaml title="world_nether/paper-world.yml" -entities: - spawning: - spawn-limits: - monster: 90 -``` - -```yaml title="resource_world/paper-world.yml" -entities: - spawning: - spawn-limits: - axolotls: 8 - creature: 15 - monster: 2 -spawn: - keep-spawn-loaded: false -``` - -This example demonstrates the concept of inheritance. For each world, this is the effective -configuration which will be applied: - -| Configuration Key | world | world_nether | world_the_end | resource_world | -| ----------------------------------------------------------- | ------ | ------------ | ------------- | -------------- | -| `entities.spawning.spawn-limits.ambient` | `15` | `15` | `15` | `15` | -| `entities.spawning.spawn-limits.axolotls` | `5` | `5` | `5` | `8` | -| `entities.spawning.spawn-limits.creature` | `10` | `10` | `10` | `15` | -| `entities.spawning.spawn-limits.monster` | `70` | `90` | `70` | `2` | -| `entities.spawning.spawn-limits.underground_water_creature` | `5` | `5` | `5` | `5` | -| `entities.spawning.spawn-limits.water_ambient` | `20` | `20` | `20` | `20` | -| `entities.spawning.spawn-limits.water_creature` | `5` | `5` | `5` | `5` | -| `spawn.keep-spawn-loaded` | `true` | `true` | `true` | `false` | - -Notice that `world_the_end/paper-world.yml` was never modified. Because of this, it inherits all the -configuration options from `config/paper-world-defaults.yml`. Additionally, `keep-spawn-loaded` was -only disabled in `resource_world/paper-world.yml` because in `config/paper-world-defaults.yml`, -`keep-spawn-loaded` is set to `true`. - - - - - - diff --git a/docs/versioned/paper/content/1.19/admin/how-to/update.md b/docs/versioned/paper/content/1.19/admin/how-to/update.md deleted file mode 100644 index 4c2e121fd..000000000 --- a/docs/versioned/paper/content/1.19/admin/how-to/update.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -slug: /updating ---- - -# Updating Paper - -Updating Paper is an important part of running every server. With new features and fixes coming -every day, we recommend updating at least once per week to keep your server patched for the latest -bugs. Installing updates is very simple, but it's important to know how to do it correctly. - -:::caution[Don't replace any JAR in a running server] - -Unless you know exactly what and why you're doing what you're doing, it's never a good idea to -replace any JAR in a running server, be that plugins, or Paper itself. - -::: - -## Step 1. Backup - -This is the most important step, and yet the most frequently skipped. While it is unlikely that -updating Paper itself will cause any issues requiring you to restore from a backup, plugin -malfunctions or other accidents might! Updating is a great time to work in a backup. Having -functioning backups is essential to every server, big or small. - -## Step 2. Update Plugins - -Just like it's important to update Paper, it's equally important to keep plugins up to date. You -never know what plugin authors may be working on, be it bugfixes or new features. - -A little known feature of Paper servers is the `update` folder. Here's how you use it. - -1. Create a folder called `update` within the `plugins` folder. -2. One by one, download plugins you would like to update and put them in the `update` folder. -3. Restart your server, do not remove or modify any plugins outside the `update` folder. - -By doing this, you are able to update all of your plugins at the same time without having the server -off, or replacing plugin JARs while the server is running. You do not need to restart your server -before updating Paper itself. This feature allows you to update both Paper and plugins all at the -same time, without needing any additional downtime. - -## Step 3. Update Paper - -:::tip - -If you are using a shared host, your host may provide a built-in way to update! Consult their -documentation before continuing. - -::: - -Updating Paper itself is very simple. - -1. Download a new JAR from [our downloads page](https://papermc.io/downloads) -2. Stop your server. It is not recommended and may cause issues to replace your Paper JAR while the - server is running. -3. Replace your old Paper JAR file with the new one. -4. Start your server. Watch the startup log to ensure everything goes to plan. If there are any - plugin conflicts or issues, you will see them here. - -To minimize downtime caused by updates, some server owners will, rather than replacing their server -JAR, upload a new one and set their start script to use the new one on the next restart. Both of -these are valid update strategies. - -:::caution[Automatic Updates] - -While it may be convenient to install updates automatically (and Paper's [downloads api](https://api.papermc.io/docs) allows you -to with ease), doing so is not recommended by Paper due to the possibility of plugin conflicts or -other issues that you may not know about. Always be present during updates, and keep a careful watch -on your server's log after the fact. - -If you do choose to automatically install updates, ensure you have a functioning backup strategy in -place! - -::: diff --git a/docs/versioned/paper/content/1.19/admin/reference/assets/cyclic-loading.png b/docs/versioned/paper/content/1.19/admin/reference/assets/cyclic-loading.png deleted file mode 100644 index 7bd09eee0..000000000 Binary files a/docs/versioned/paper/content/1.19/admin/reference/assets/cyclic-loading.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.19/admin/reference/assets/plugin-list.png b/docs/versioned/paper/content/1.19/admin/reference/assets/plugin-list.png deleted file mode 100644 index d5bac8498..000000000 Binary files a/docs/versioned/paper/content/1.19/admin/reference/assets/plugin-list.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.19/admin/reference/global-configuration.md b/docs/versioned/paper/content/1.19/admin/reference/global-configuration.md deleted file mode 100644 index 93cc97d5a..000000000 --- a/docs/versioned/paper/content/1.19/admin/reference/global-configuration.md +++ /dev/null @@ -1,525 +0,0 @@ ---- -slug: /reference/global-configuration -keywords: - - paper-global.yml - - paper.yml - - paper.yml settings ---- - -# Paper Global Config - -Global configuration options exposed by Paper will affect all worlds on a server, or the server -function itself. For per-world configuration, see the -[Per World Configuration Reference](world-configuration.md) - -## chunk-loading - -### 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 not affect - server-side chunk loading or ticking. - -### 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 and not generally recommended for use. - -### global-max-chunk-load-rate - -- **default**: `-1.0` -- **description**: The maximum number of chunks loaded per second for the whole server. Takes - priority over `player-max-chunk-load-rate`. - -### global-max-chunk-send-rate - -- **default**: `-1.0` -- **description**: The maximum number of chunks sent per second for the entire server. This may help - with server-side peak bandwidth usage. - -### global-max-concurrent-loads - -- **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. - -### 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, it is unlikely to help users with a poor internet connection. - -### min-load-radius - -- **default**: `2` -- **description**: The radius of chunks around a player that are not throttled for chunk loading. - The number of chunks affected is actually the configured value plus one, as this config controls - the number of chunks the client will actually be able to render. - -### player-max-chunk-load-rate - -- **default**: `-1.0` -- **description**: The maximum number of chunks loaded per second per player. - -### player-max-concurrent-loads - -- **default**: `20.0` -- **description**: The maximum number of chunk loads processed per player at one time. - -### target-player-chunk-send-rate - -- **default**: `100.0` -- **description**: The maximum number of chunks sent to an individual player within one second. - -## chunk-system - -### gen-parallelism - -- **default**: `default` -- **description**: Sets whether the server should use parallel chunk generation. The `default` value - will be used as `true`. Possible options are `true`, `on` and `enable` to make the server use the - system and `false`, `off` or `disabled` to disable. - -### io-threads - -- **default**: `-1` -- **description**: Sets the number of threads to be used for read and write operations with chunks. - If any value below zero is set, only one thread will be used. - -### worker-threads - -- **default**: `-1` -- **description**: Sets the number of threads to be used for parallel chunk generation. If any value below - zero is set, the server will determine the best number depending on the number of available CPU cores. - This is capped at a quarter of available processors and can be less for systems with very few processors. - _(Note: Hyper-Threaded threads **do not** count)_. - -## collisions - -### enable-player-collisions - -- **default**: `true` -- **description**: Sets whether the server should allow players to collide with one another. This - option can be broken by plugins interacting with the scoreboard. If you are having trouble with - this option, try without plugins installed. - -### 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. - -## commands - -### fix-target-selector-tag-completion - -- **default**: `true` -- **description**: Workaround for a client bug preventing entity type tag suggestions from - functioning in target selectors. Resolves [MC-235045](https://bugs.mojang.com/browse/MC-235045). - -### suggest-player-names-when-null-tab-completions - -- **default**: `true` -- **description**: Instructs the server to return a list of players when tab-completing when there - are no other completions available. - -### time-command-affects-all-worlds - -- **default**: `false` -- **description**: Whether the `/time` command should act on all worlds or just the sender's current - world. - -## console - -### enable-brigadier-completions - -- **default**: `true` -- **description**: Enables Mojang's Brigadier (advanced) command completions in the server console. - -### enable-brigadier-highlighting - -- **default**: `true` -- **description**: Enables Mojang's Brigadier highlighting in the server console. - -### has-all-permissions - -- **default**: `false` -- **description**: Whether the console command sender has all permissions. - -## item-validation - -### display-name - -- **default**: `8192` -- **description**: The maximum length of an item's display name in characters. - -### lore-line - -- **default**: `8192` -- **description**: The maximum length of a lore line in characters. - -### resolve-selectors-in-books - -- **default**: `false` -- **description** Whether to resolve selectors in books. With this enabled, players given creative - mode will be able to crash the server in yet another way. - -### book - -#### author - -- **default**: `8192` -- **description**: The maximum length of a book's author in characters. - -#### page - -- **default**: `16384` -- **description**: The maximum length of a book's page in characters. - -#### title - -- **default**: `8192` -- **description**: The maximum length of a book's title in characters. - -### 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 its contribution to - the allowed byte total for a book (with the first page being having a multiplier of `1.0`). - -## logging - -### deobfuscate-stacktraces - -- **default**: `true` -- **description**: Whether to remap Spigot mapped stacktraces to Mojang mappings in logging. Has no - impact on Mojang mapped servers. - -### log-player-ip-addresses - -- **default**: `true` -- **description**: Whether player IP addresses should be logged by the server. This does not impact - the ability of plugins to log the IP addresses of players. - -### use-rgb-for-named-text-colors - -- **default**: `true` -- **description**: Whether named ANSI colors should be logged with RGB codes. - -## messages - -### no-permission - -- **default**: - `I'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**: Default message sent to players when they have insufficient permissions for an - action. Plugins may override this for their commands. - -### use-display-name-in-quit-message - -- **default**: `false` -- **description**: Whether the server should use the player's display name (set by plugins) or - actual name in quit messages. - -### kick - -#### authentication-servers-down - -- **default**: `` -- **description**: Message sent to players when Mojang's authentication servers are unreachable. - -#### connection-throttle - -- **default**: `Connection throttled! Please wait before reconnecting.` -- **default**: Message sent to players when they are unable to join due to having their connection - throttled. Throttle configurable in `bukkit.yml`. - -#### flying-player - -- **default**: `` -- **description**: Message sent to players who are detected flying. - -#### flying-vehicle - -- **default**: `` -- **description**: Message sent to players who are detected riding a flying vehicle. - -## misc - -### fix-entity-position-desync - -- **default**: `true` -- **description**: Causes the server to lose the same precision that the client does for entities - preventing desync. Fixes [MC-4](https://bugs.mojang.com/browse/MC-4). - -### 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. - -### load-permissions-yml-before-plugins - -- **default**: `true` -- **description**: Loads bukkit's permission.yml file before plugins, allowing them to check - information set there immediately on enable. - -### 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 but not kicked. This is not - related to connection throttling found in `bukkit.yml`. - -### region-file-cache-size - -- **default**: `256` -- **description**: The maximum size of the region file cache. - -### use-alternative-luck-formula - -- **default**: `false` -- **description**: Use an - [alternative luck formula](https://gist.github.com/aikar/40281f6c73ec9b6fef7588e6461e1ba9) - allowing luck to be applied to items that have no quality defined. Makes major changes to fishing - formulas. - -### use-dimension-type-for-custom-spawners - -- **default**: `false` -- **description**: Whether phantoms, wandering traders, etc. should be able to spawn in custom - overworlds. Defaults to false in order to match vanilla behavior. - -## packet-limiter - -### all-packets - -#### action - -- **default**: `KICK` -- **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. - -#### 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 packets allowed per player within the interval. - -### kick-message - -- **default**: `` -- **description**: The message players are kicked with for sending too many packets. - -### overrides - -- **default**: `ServerboundPlaceRecipePacket`, `DROP`, `4.0`, `5.0` -- **description**: Override the global configuration for any individual named packet. You can find -the names of every packet as they are displayed on timings. For more experienced users, packets -named here use Mojang mappings regardless of the server. - - -## player-auto-save - -### max-per-tick - -- **default**: `-1` -- **description**: How many players should be saved at most in a single tick. A value of `-1` will - set a recommended value based on `player-auto-save.rate` of either `10` or `20`. - -### rate - -- **default**: `-1` -- **description**: How often player data should be saved in ticks. A value of `-1` will use - `ticks-per.autosave` in `bukkit.yml`. - -## proxies - -### proxy-protocol - -- **default**: `false` -- **description**: Whether the server should process - [PROXY Protocol](https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt) messages. This is - completely unrelated to Velocity or BungeeCord. Only enable this if you are using HAProxy or - similar. - -### bungee-cord - -#### online-mode - -- **default**: `true` -- **descriptions**: Instructs the server how to handle player UUIDs and data when behind BungeeCord. - Always set to match your proxy's online-mode setting. - -### velocity - -#### enabled - -- **default**: `false` -- **description**: Whether the server should accept Velocity Modern Forwarding. - -#### online-mode - -- **default**: `false` -- **description**: Instructs the server how to handle player UUIDs and data when behind Velocity. - Always set to match your proxy's online-mode setting. - -#### secret - -- **default**: ` ` -- **description**: The secret string that is shared by your Velocity proxy and this server. This - needs to match your proxy's secret as defined in the `forwarding.secret` file. - -## scoreboards - -### 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. - -### track-plugin-scoreboards - -- **default**: `false` -- **description**: Whether the server should track plugin scoreboards with only dummy objectives. - This is a breaking change; however, it provides a much more sensible default value. Enabling this - with plugins using many scoreboards will incur a performance degradation. - -## spam-limiter - -### incoming-packet-threshold - -- **default**: `300` -- **description**: Sets the threshold at which the server will consider incoming packets spam and - ignore them. - -### 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` -- **description**: The number that the recipe spam counter can reach until the server kicks the - player for spam. - -### 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. - -## timings - -### enabled - -- **default**: `true` -- **description**: Controls the global enable state of Timings. - -### hidden-config-entries - -- **default**: - `[database, settings.bungeecord-address, settings.velocity-support.secret, proxies.velocity.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. This value is validated - server-side. Large reports will be rejected. - -### server-name - -- **default**: `Unknown Server` -- **description**: Instructs Timings on what to put in for the server name. - -### server-name-privacy - -- **default**: `false` -- **description**: Instructs Timings to hide server name information in reports. - -### url - -- **default**: `https://timings.aikar.co` -- **description**: Specifies the URL of the [Timings Viewer](https://github.com/aikar/timings) - server where Timings reports are sent. - -### verbose - -- **default**: `true` -- **description**: Instructs Timings to provide more specific information in its reports. For - example, specific entity types causing lag rather than just "entities". - -## unsupported-settings - -### allow-headless-pistons - -- **default**: `false` -- **description**: Whether the server should allow the creation of headless pistons. These are often - used to break permanent blocks. - -### allow-permanent-block-break-exploits - -- **default**: `false` -- **description**: 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**: Whether to allow duplication of TNT, carpets, and rails. This does not control - sand duplication. - -### perform-username-validation - -- **default**: `true` -- **default**: Whether the server should validate usernames. While this may allow users with special - characters in their name to join, it can also cause issues with commands and plugins. - -## watchdog - -### early-warning-delay - -- **default**: `10000` -- **description**: The number of milliseconds before the watchdog thread starts printing thread - dumps after the server starts hanging. - -### early-warning-every - -- **default**: `5000` -- **description**: The interval in milliseconds between printed thread dumps while the server is - hanging. diff --git a/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md b/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md deleted file mode 100644 index 90d3a02e3..000000000 --- a/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -slug: /reference/paper-plugins ---- - -# Paper Plugins - -This documentation page serves to explain all the new semantics and possible confusions that Paper plugins may introduce. - -*As a developer, you can get more information [here](../../dev/getting-started/paper-plugins.md)* - -## What are they? - -Paper plugins are plugins which are loaded by Paper's new plugin loading framework. Paper plugins are used by developers to -take advantage of modern systems Mojang provides, for example, datapacks. - -![Plugin List](assets/plugin-list.png) - -## What is the difference? - -When enabled, Paper plugins are **identical** to Bukkit plugins. This allows plugins to still fully communicate and support each other, meaning that even if a -plugin is a Bukkit or Paper plugin, they are both able to depend on each other just fine. - -Paper plugins only support being loaded by Paper's Plugin Loader and may use new API unavailable to Bukkit plugins. - -### How do I add Paper plugins? - -Paper plugins are added the same as Bukkit plugins, therefore, you can follow [this guide](../../admin/getting-started/adding-plugins.md) - -### Cyclic Plugin Loading - -With the introduction of Paper plugins, Paper introduces a new plugin loader that fixes some odd issues. -However, as a result, this now causes [cyclic loading](#cyclic-plugin-loading) between plugins to no longer be supported. - -![Cyclic Loading](assets/cyclic-loading.png) - -Cyclic loading describes the phenomena when a plugin loading causes a loop which eventually will cycle back to the original plugin. - -If Paper detects a loop, your server will be shut down with an error similar to this: -``` -Circular plugin loading detected! -Circular load order: - MyPlugin -> MyOtherPlugin -> MyWorldPlugin -> MyPlugin -Please report this to the plugin authors of the first plugin of each loop or join the PaperMC Discord server for further help. -If you would like to still load these plugins, acknowledging that there may be unexpected plugin loading issues, run the server with -Dpaper.useLegacyPluginLoading=true -Failed to start the minecraft server -``` - -It is up to plugin developers to resolve these circular loading issues, however, you are able to use the legacy plugin loader if you -absolutely are unable to resolve this loading loop. - - -:::danger[Legacy] - -If your server **requires** this circular loading, you can enable this by adding the **-Dpaper.useLegacyPluginLoading=true** startup flag. -Please note that this may not be supported in the future. -::: diff --git a/docs/versioned/paper/content/1.19/admin/reference/system-properties.md b/docs/versioned/paper/content/1.19/admin/reference/system-properties.md deleted file mode 100644 index 35c60ef38..000000000 --- a/docs/versioned/paper/content/1.19/admin/reference/system-properties.md +++ /dev/null @@ -1,191 +0,0 @@ ---- -slug: /reference/system-properties ---- - -# Paper System Properties - -These system properties can be set when you start your server allowing for the configuration of various settings. - -:::danger[Danger Ahead] - -Setting flags for the JVM can alter how it operates and the same goes for the Paper server. -If you are unsure about what a flag does, it is recommended that you **do not use it**. - -::: - -## How they work - -System properties are set when you start your server. For example, if you are using a `.bat` or a `.sh` file to start your server, you can add the system properties to the file. For example: - -```bash -java -Dpaper.log-level=FINE -jar paper.jar -``` - -:::info - -Some of the paper system properties contain a `.` character in their name. When using Windows Powershell, these will require wrapping in quotes. -i.e. `"-Dpaper.log-level=FINE"` - -::: - -Where a `-D` is used to set a system property, and the system property is `paper.log-level` with a value of `FINE`. Otherwise, just add them to the start command - -:::note - -Where a system property is stated as `unset`, setting it as `true` will work to enable it. - -::: - -## List of System Properties - -#### paper.playerconnection.keepalive: - -- **default**: `30` -- **description**: Controls how long the player connection will wait before closing when not receiving any keepalives, in seconds. - -#### timings.bypassMax: - -- **default**: `unset` -- **description**: Allows for bypassing the max amount of data to send to the Aikar's Timings API. Setting this will not permit bypassing the limit unless the API is configured to allow it. - -#### LetMeReload: - -- **default**: `unset` -- **description**: This disables the reload confirmation message when using the `/reload` command. - -#### paper.disableChannelLimit: - -- **default**: `unset` -- **description**: Disables the plugin channel limit for the server. This will disable the limit of 128 plugin channels per player. - -#### net.kyori.adventure.text.warnWhenLegacyFormattingDetected: - -- **default**: `false` -- **description**: Enables or disables the warning when legacy formatting is detected in a chat component. - -#### Paper.DisableClassPrioritization: - -- **default**: `unset` -- **description**: Disables the class prioritization system - mostly an issue when failing to relocate or shade properly. - -#### Paper.disableFlushConsolidate: - -- **default**: `unset` -- **description**: Disables the netty flush consolidation system. - -#### Paper.debugDynamicMissingKeys: - -- **default**: `unset` -- **description**: Enables debug logging for missing keys in NBT objects. - -#### disable.watchdog: - -- **default**: `unset` -- **description**: Disables the watchdog warning system. - -#### paper.explicit-flush: - -- **default**: `unset` -- **description**: Enables explicit flushing of the network channel. - -#### Paper.enable-sync-chunk-writes: - -- **default**: `unset` -- **description**: Syncs writes on each write call. This has a performance impact, particularly on hard drives. - -#### paper.debug-sync-loads: - -- **default**: `unset` -- **description**: Enables debug logging for sync chunk loads. - -#### Paper.ignoreWorldDataVersion: - -- **default**: `unset` -- **description**: Ignores the world data version when loading a world. This is not recommended and will likely cause issues. - -#### debug.entities: - -- **default**: `unset` -- **description**: Enables debug log messages for entity information. - -#### Paper.bypassHostCheck: - -- **default**: `unset` -- **description**: Bypasses the host pattern matching attempt for the client when connecting to the server. - -#### paper.ticklist-warn-on-excessive-delay: - -- **default**: `unset` -- **description**: Enables the warning when a tick list is scheduled with an excessive delay. - -#### debug.rewriteForIde: - -- **default**: `unset` -- **description**: Removes the NMS revision from the stack trace to allow for easier debugging in IDEs. -It also remaps plugin CB calls to remove the version information. - -#### convertLegacySigns: - -- **default**: `unset` -- **description**: Converts legacy signs to the new format. - -#### paper.maxCustomChannelName: - -- **default**: `64` -- **description**: Sets the largest size that a plugin channel name can take. - -#### Paper.maxSignLength: - -- **default**: `80` -- **description**: Sets the maximum line length for signs. - -#### Paper.FilterThreshhold: - -- **default**: `8192` -- **min**: `8192` -- **description**: Sets the maximum size of a packet to be filtered. - -#### Paper.minPrecachedDatafixVersion: - -- **default**: `Minecraft world version + 1` -- **description**: If you are expecting to convert a large number of chunks you might consider setting this to only convert from a point onwards. - -#### Paper.WorkerThreadCount: - -- **default**: `8` or `number of cpus - 2`. Whichever is lower -- **description**: Sets the number of worker threads to use for chunk loading. - -#### Paper.excessiveTELimit: - -- **default**: `750` -- **description**: Splits tile entities into multiple packets if there are more than this many. - -#### io.papermc.paper.suppress.sout.nags: - -- **default**: `unset` -- **description**: Suppresses the nag message about using System.out/System.err in a plugin. - -#### paper.strict-thread-checks: - -- **default**: `unset` -- **description**: This sets the status of the AsyncCatcher so that it will always log an error if code is not run on the main thread. - -#### Paper.skipServerPropertiesComments: - -- **default**: `unset` -- **description**: Skips the comments in the server.properties file. - -#### Paper.debugInvalidSkullProfiles: - -- **default**: `unset` -- **description**: Enables debug logging for invalid skull profiles. This logs any invalid skulls in the world with the appropriate location information. - -#### paper.alwaysPrintWarningState: - -- **default**: `unset` -- **description**: Always prints the warning state for the particular level. - -#### Paper.parseYamlCommentsByDefault: - -- **default**: `true` -- **description**: Sets whether to parse comments in YAML files by default. diff --git a/docs/versioned/paper/content/1.19/admin/reference/world-configuration.md b/docs/versioned/paper/content/1.19/admin/reference/world-configuration.md deleted file mode 100644 index d3523c605..000000000 --- a/docs/versioned/paper/content/1.19/admin/reference/world-configuration.md +++ /dev/null @@ -1,1018 +0,0 @@ ---- -slug: /reference/world-configuration -keywords: - - paper-world-defaults.yml - - paper-world.yml - - world/paper-world.yml - - paper.yml - - paper.yml world-settings ---- - -# Paper Per World Configuration - -Configuration options in `paper-world-defaults.yml` are configurable on a per-world basis. For more -information, see the [Configuration Guide](../how-to/configuration.md) For global configuration, see -the [Paper Global Configuration Reference](global-configuration.md) - -## anticheat - -### anti-xray - -:::tip - -Recommended configuration for both `engine-mode` `1` and `2` can be found in the -[Configuring Anti-Xray](../how-to/anti-xray.mdx) guide. - -::: - -#### 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. `1` replaces specified blocks (`hidden-blocks`) - with other "fake" blocks, `stone` (`deepslate` at y < 0), `netherrack`, or `end_stone` based on - the dimension. In contrast, `2` will replace both `hidden-blocks` and `replacement-blocks` with - randomly generated `hidden-blocks`. - -#### max-block-height - -- **default**: `64` -- **description**: Sets the maximum height (`y` coordinate, starting from the bottom of the world) - to which anti-xray will operate. Only integer multiples of 16 are accepted. All other values will - be rounded down. The [Minecraft Wiki page about Ore](https://minecraft.wiki/w/Ore) may be - helpful in determining the best value for you. - -#### update-radius - -- **default**: `2` -- **description**: Radius for block updates which will be sent containing real block data when the - client interacts with a block. Only values `0`, `1`, and `2` are accepted. Values smaller than `0` - will be rounded up to `0`, while values larger than `2` will be rounded down to `2`. `0` is only - designed for testing purposes. Do not use it in production. - -#### lava-obscures - -- **default**: `false` -- **description**: Whether to obfuscate blocks touching lava. Does not work well with non-stone-like - ore textures. This is because lava, while being mostly opaque, does not cover blocks fully at the - surface. - -#### use-permission - -- **default**: `false` -- **description**: Whether 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 - -- **default**: - `[copper_ore, deepslate_copper_ore, gold_ore, deepslate_gold_ore, iron_ore, deepslate_iron_ore, coal_ore, deepslate_coal_ore, lapis_ore, deepslate_lapis_ore, mossy_cobblestone, obsidian, chest, diamond_ore, deepslate_diamond_ore, redstone_ore, deepslate_redstone_ore, clay, emerald_ore, deepslate_emerald_ore, ender_chest]` -- **description**: With `engine-mode: 1`, these blocks will be replaced by `stone` (`deepslate` at y < 0), `netherrack`, or `end_stone`, based on the dimension. All types of air are ignored on this list. - - With `engine-mode: 2`, these blocks will be randomly placed in the world, replacing both - `hidden-blocks` and `replacement-blocks`. Tile entities, such as chests or spawners, are not - allowed on this list. Individual blocks may be added multiple times, increasing their chance of - being placed. The default block states are placed. - -#### replacement-blocks: - -- **default**: [stone, oak_planks, deepslate] -- **description**: With `engine-mode: 1`, replacement blocks are not used. Changing this list will - have no effect. - - With `engine-mode: 2`, both `replacement-blocks` and `hidden-blocks` are randomly replaced by - `hidden-blocks.` While tile entities are ignored in the `hidden-blocks` list, they may be added to - the `replacement-blocks` list. All types of air blocks are ignored here. - -### obfuscation - -#### items - -##### hide-durability - -- **default**: `false` -- **description**: Controls whether durability information is sent to other players' clients. This - may break resource packs that rely on durability values when observing other players. - -##### hide-itemmeta - -- **default**: `false` -- **description**: Controls whether unnecessary item information (such as enchantments, items in a - shulker box/bundle, etc.) that can give cheat clients an advantage should be sent to other - players' clients. This may break resource packs that rely on information such as enchantments, - lore or item names when observing other players. - -##### hide-itemmeta-with-visual-effects - -- **default**: `false` -- **description**: Controls whether item information that affects how an item is displayed - (such as lodestone compass positions) should be sent to other players' clients. This information - could be used by cheat clients to give another advantage to the cheating player. However, this - will affect how certain items look when held by another player. - -## chunks - -### auto-save-interval - -- **default**: `-1` -- **description**: Configures the world saving interval in ticks. Overrides `ticks-per.autosave` in - `bukkit.yml` for this world. A value of `-1` will use the global `ticks-per.autosave` in - `bukkit.yml`. - -### delay-chunk-unloads-by - -- **default**: `10s` -- **description**: Delays chunk unloads by the specified time. - -### entity-per-chunk-save-limit - -- **default**: `{experience_orb: -1...}` -- **description**: Limits the number of any type of entity that will be saved/loaded per chunk. A - value of `-1` disables the limit for a specific entity. Any entity may be added to the list, - beyond the enumerated defaults. - -### fixed-chunk-inhabited-time - -- **default**: `-1` -- **description**: If `0` or greater, set the chunk inhabited time to a fixed number. Fixed in this - instance means static or unchanging. This is **not** fixing a bug. The timer is increased when - chunks are kept loaded because of player activity. - -### max-auto-save-chunks-per-tick - -- **default**: `24` -- **description**: The maximum number of chunks the auto-save system will save in a single tick. - -### prevent-moving-into-unloaded-chunks - -- **default**: `false` -- **description**: Sets whether the server will prevent players from moving into unloaded chunks or - not. - -## collisions - -### allow-player-cramming-damage - -- **default**: `false` -- **description**: Allows players to take damage from cramming when colliding with more entities - than set in the `maxEntityCramming` game rule. - -### allow-vehicle-collisions - -- **default**: `false` -- **description**: Whether vehicles should also be able to collide while `only-players-collide` is - enabled. - -### fix-climbing-bypassing-cramming-rule - -- **default**: `false` -- **description**: Sets whether climbing should bypass the entity cramming limit(`maxEntityCramming` game rule). If set to `true`, climbing entities will also be counted towards the entity cramming limit so that they can take suffocation damage. - -### max-entity-collisions - -- **default**: `8` -- **description**: Instructs the server to stop processing collisions after this value is reached. - -### only-players-collide - -- **default**: `false` -- **description**: Only calculate collisions if a player is one of the two entities colliding. - -## entities - -### armor-stands - -#### do-collision-entity-lookups - -- **default**: `true` -- **description**: Instructs armor stand entities to do entity collision checks. - -#### tick - -- **default**: `true` -- **description**: Disable to prevent armor stands from ticking. Can improve performance with many - armor stands. - -### markers - -#### tick - -- **default**: `true` -- **description**: Disable to prevent markers from ticking. This may affect how they behave as passengers - of other entities. - -### behavior - -#### 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 base speed, and `-0.4` would be 40% slower. - -#### disable-chest-cat-detection - -- **default**: `false` -- **description**: Allows you to open chests even if they have a cat sitting on top of them. - -#### disable-creeper-lingering-effect - -- **default**: `false` -- **description**: Disables creepers randomly leaving behind a lingering area effect cloud. - -#### disable-player-crits - -- **default**: `false` -- **description**: Instructs the server to disable critical hits in PvP, treating them as normal - hits instead. - -#### allow-spider-world-border-climbing - -- **default**: `true` -- **description:** Whether spiders should be able to climb on the world border, as if it were - a regular wall. - -#### door-breaking-difficulty - -- **default**: `[HARD, NORMAL, EASY, PEACEFUL]` -- **description**: Takes a list of difficulties at which each entity will attempt to break doors. - -#### ender-dragons-death-always-places-dragon-egg - -- **default**: `false` -- **description**: Controls whether ender dragons should always drop dragon eggs on death. - -#### experience-merge-max-value - -- **default**: `-1` -- **description**: Instructs the server to put a maximum value on experience orbs, preventing them - all from merging down into 1 single orb. A value of `-1` 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. - -#### mobs-can-always-pick-up-loot - -- **default**: `false` -- **description**: Controls whether zombies or skeletons (each configurable individually) will - always be able to pick up loot. If set to false, the probability that a zombie picks up items - depends on the world's difficulty (vanilla behavior). - -#### nerf-pigmen-from-nether-portals - -- **default**: `false` -- **description**: Removes AI from pigmen spawned via nether portals - -#### 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. - -#### 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 - -#### piglins-guard-chests - -- **default**: `true` -- **description**: If piglins should attempt to guard chests when angered. - -#### pillager-patrols - -##### disable - -- **default**: `false` -- **description**: Disables Pillager patrols and associated AI. - -##### 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. - -#### should-remove-dragon - -- **default**: `false` -- **description**: Sets whether to remove the dragon if it exists without a portal. - -#### spawner-nerfed-mobs-should-jump - -- **default**: `false` -- **description**: Determines if spawner nerfed mobs should attempt to float (jump) in water. - -#### zombie-villager-infection-chance - -- **default**: `-1.0` -- **description**: Sets the chance 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. - -#### zombies-target-turtle-eggs - -- **default**: `true` -- **description**: Sets whether zombies and zombified piglins should target turtle eggs. Setting - this to false may help with performance, as they won't search for nearby eggs. - -### entities-target-with-follow-range - -- **default**: `false` -- **description**: Sets whether the server should use follow range when targeting entities - -### mob-effects - -#### immune-to-wither-effect - -- **default**: `true` -- **description**: If the specified entity should be immune to the wither effect. - -#### spiders-immune-to-poison-effect - -- **default**: `true` -- **description**: If spiders should be immune to poison. - -#### undead-immune-to-certain-effects - -- **default**: `true` -- **description**: If undead mobs should be immune to regeneration and poison. - -### spawning - -#### 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. This may actually decrease your chances of running into a Slime as they now - have a much larger potential spawn area. - -#### alt-item-despawn-rate - -##### enabled - -- **default**: `false` -- **description**: Determines if items will have different despawn rates. - -##### items - -- **default**: `{ cobblestone: 300 }` (a list of item to ticks mappings) -- **description**: Determines how long each respective item despawns in ticks. The item ids are the - same as those used in the /give command. They can be viewed by enabling advanced item tooltips - in-game by pressing **F3 + H**; the item id will appear at the bottom of the tooltip that appears - when you hover over an item. - -#### count-all-mobs-for-spawning - -- **default**: `false` -- **description**: Determines whether spawner mobs and other misc mobs are counted towards the - global mob limit. - -#### creative-arrow-despawn-rate - -- **default**: `-1` -- **description**: The rate, in ticks, at which arrows shot from players in creative mode are - despawned. - -#### despawn-ranges - -##### soft - -- **default**: `32` -- **description**: The number of blocks away from a player in which each entity type (set - individually) will be randomly selected to be despawned. Takes effect both horizontally and - vertically. - -##### hard - -- **default**: `128` -- **description**: The number of blocks away from a player in which each entity type (set - individually) will be forcibly despawned. Takes effect both horizontally and vertically. - -#### disable-mob-spawner-spawn-egg-transformation - -- **default**: `false` -- **description**: Whether to block players from changing the type of mob spawners with a spawn egg. - -#### duplicate-uuid - -##### mode - -- **default**: `saferegen` - -- **description**: Specifies the method the server uses to resolve entities with duplicate UUIDs. - This can be one of 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. - -##### safe-regen-delete-range - -- **default**: `32` -- **description**: If multiple entities with duplicate UUIDs are within this many blocks, saferegen - will delete all but 1 of them. - -#### filter-bad-tile-entity-nbt-from-falling-blocks - -- **default**: `true` -- **description**: Instructs the server to remove certain NBT data from falling blocks. -- **note**: Some adventure maps may require this to be turned off to function correctly, but we do - not recommend turning it off on a public server. - -#### filtered-entity-tag-nbt-paths - -- **default**: `[Pos, Motion, SleepingX, SleepingY, SleepingZ]` -- **description**: A list of nbt tags that will be removed from the `EntityTag` tag on items which spawn entities. - The format of these strings follows the same format used to select nbt tags in vanilla commands. If the spawning was - directly caused by a player and the player has the `minecraft.nbt.place` permission, the filter list will be ignored. - The defaults are set to prevent entities from spawning or moving to a place other than the location they were placed. - For example, if `Pos` wasn't included, a spawn egg could place an entity at any location. -- **note**: Some adventure maps may require this to be an empty list to function correctly, but we do - not recommend turning it off on a public server. - -#### 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 - -#### monster-spawn-max-light-level - -- **default**: `-1` -- **description**: When set to `-1`, the Vanilla default will be used (=0). Set to `15` or greater - to revert to pre-1.18 behavior. - -#### non-player-arrow-despawn-rate - -- **default**: `default` -- **description**: The rate, in ticks, at which arrows shot from non-player entities are despawned. - The default value instructs the server to use the same default arrow despawn rate from spigot.yml - that is used for all arrows. - -#### 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. - -#### scan-for-legacy-ender-dragon - -- **default**: `true` -- **description**: Determines if the server attempts to start the ender dragon fight. Setting this - to `false` will make the ender dragon not spawn in the end, even with a new world. - -#### skeleton-horse-thunder-spawn-chance - -- **default**: `0.01` -- **description**: Sets the chance that a "Skeleton Trap" (4 skeleton horsemen) will spawn in a - thunderstorm. - -#### slime-spawn-height - -##### slime-chunk - -###### maximum - -- **default**: `40` -- **description**: Sets the maximum Y position for natural Slime spawn in Slime Chunks. - -##### surface-biome - -###### maximum - -- **default**: `70` -- **description**: Sets the maximum Y position for natural Slime spawn in Surface Biomes. - -###### minimum - -- **default**: `50` -- **description**: Sets the minimum Y position for natural Slime spawn in Surface Biomes. - -#### spawn-limits - -- **default**: `-1` -- **description**: The constant used to determine how many of each entity type (set individually) - will be naturally spawned 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. - -#### wandering-trader - -##### spawn-chance-failure-increment - -- **default**: `25` -- **description**: How much the spawn chance will be increased on every failed wandering trader - spawn. - -##### spawn-chance-max - -- **default**: `75` -- **description**: The maximum chance that a wandering trader will be spawned. - -##### spawn-chance-min - -- **default**: `25` -- **description**: The minimum chance that a wandering trader will be spawned. - -##### spawn-day-length - -- **default**: `24000` -- **description**: Time between wandering trader spawn attempts in ticks. - -##### spawn-minute-length - -- **default**: `1200` -- **description**: The length of the wandering trader spawn minute in ticks. - -#### wateranimal-spawn-height - -##### maximum - -- **default**: `default` -- **description**: The maximum height at which water animals 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). - -##### minimum - -- **default**: `default` -- **description**: The minimum height at which water animals 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). - -## environment - -### disable-explosion-knockback - -- **default**: `false` -- **description**: Instructs the server to completely block any knockback that occurs as a result of - an explosion. - -### disable-ice-and-snow - -- **default**: `false` -- **description**: Disables ice and snow formation. This also causes cauldrons to no longer be - filled by rain or snow. - -### 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. - -### disable-thunder - -- **default**: `false` -- **description**: Disables thunderstorms. - -### frosted-ice - -#### delay - -##### max - -- **default**: `40` -- **description**: Maximum RNG value to apply frosted-ice effects at. - -##### min - -- **default**: `20` -- **description**: Minimum RNG value to apply frosted-ice effects at. - -#### enabled - -- **default**: `true` -- **description**: Instructs the server to enable (and tick) frosted ice blocks. - -### generate-flat-bedrock - -- **default**: `false` -- **description**: Instructs the server to generate bedrock as a single flat layer. - -### nether-ceiling-void-damage-height - -- **default**: `disabled` -- **description**: Sets the level above which players in the nether will take void damage. This is a - vanilla-friendly way to restrict players from using the nether ceiling as a buildable area. - Setting to `disabled` disables this feature. - -### 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. - -### 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-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-search-vanilla-dimension-scaling - -- **default**: `true` -- **description**: Whether to apply vanilla dimension scaling to `portal-search-radius`. - -### treasure-maps - -#### enabled - -- **default**: `true` -- **description**: If villagers should trade treasure maps and treasure maps from chests should lead - to a feature. - -#### find-already-discovered - -- **description**: Vanilla mechanics normally find the first undiscovered location, which may lead - to structures that were not fully looted, and can also fail with a world border set. The options - below allow configuring the default behavior of maps obtained in different ways. - -##### loot-tables - -- **default**: `default` -- **description**: Overrides the loot table-configured check for undiscovered structures. `default` - allows loot tables to individually determine if the map should allow discovered locations in its - search. All vanilla loot tables default to skipping discovered locations so changing this to - `false` would override that behavior and force them to search discovered locations. - -##### villager-trade - -- **default**: `false` -- **description**: Instructs the server to target the first treasure location found for maps - obtained via trading with villagers. - -### water-over-lava-flow-speed - -- **default**: `5` -- **description**: Sets the speed at which water flows while over lava. - -## feature-seeds - -### generate-random-seeds-for-all - -- **default**: `false` -- **description**: Enables autofilling random seeds for all available features you haven't already - set a seed to. Using this in a controlled environment is also a good way of receiving a full list - of features you can set seeds for. - -### `` - -- **description**: Sets the population seed for the specified feature. If set to `-1`, the Vanilla - population seed stays unchanged and will not be overridden by the autofill option. - -## fishing-time-range - -### maximum - -- **default**: `600` -- **description**: The maximum number of RNG ticks before catching a fish. - -### minimum - -- **default**: `100` -- **description**: The minimum number of RNG ticks needed to catch a fish. - -## fixes - -### disable-unloaded-chunk-enderpearl-exploit - -- **default**: `true` -- **description**: Prevent enderpearls from storing the thrower when in an unloaded chunk. - -### falling-block-height-nerf - -- **default**: `disabled` -- **description**: The height at which falling blocks will be removed from the server. A value of `disabled` will disable this feature. - -### fix-curing-zombie-villager-discount-exploit - -- **default**: true -- **description**: Fixes the [exploit](https://bugs.mojang.com/browse/MC-181190) used to gain - massive discounts by infecting and curing a zombie villager. - -### fix-items-merging-through-walls - -- **default**: `false` -- **description**: Whether items should be prevented from merging through walls. Enabling this will - incur a performance 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. - -### split-overstacked-loot - -- **default**: `true` -- **description**: When set to false, loot tables will not attempt to split items with a stack size - higher than the maximum into items of smaller stack sizes. This will prevent overstacked items - from being lost or causing a chunk to become uninhabitable (due to players getting constantly - kicked because of oversized packets) when a shulker box is broken in survival. - -### tnt-entity-height-nerf - -- **default**: `disabled` -- **description**: The height at which Primed TNT entities will be removed from the server. A value of `disabled` will disable this feature. - -## hopper - -### cooldown-when-full - -- **default**: `true` -- **description**: Instructs the server to apply a short cooldown when the hopper is full, instead - of constantly 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. - -### ignore-occluding-blocks - -- **default**: `false` -- **description**: Determines if hoppers will ignore containers inside occluding blocks, like a - hopper minecart inside a sand block. Enabling this will improve performance for hoppers checking - where to insert items. - -## lootables - -### auto-replenish - -- **default**: `false` -- **description**: Instructs the server to automatically replenish lootable containers. This feature - is useful for long-term worlds in which players are not expected to constantly explore to generate - new chunks. - -### 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 refill an infinite number of times. - -### refresh-max - -- **default**: `2d` -- **description**: The maximum amount of time that can pass before a lootable is refilled. - -### refresh-min - -- **default**: `12h` -- **description**: The minimum amount of time that must pass before a lootable will be eligible to - be refilled. - -### 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. - -### restrict-player-reloot - -- **default**: `true` -- **description**: Prevents the same players from coming back and re-looting the same containers - over and over. - -## maps - -### 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. - -### 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. - -## max-growth-height - -### bamboo - -#### max - -- **default**: `16` -- **description**: Maximum height bamboo will naturally grow to. - -#### min - -- **default**: `11` -- **description**: Minimum height bamboo will naturally grow to. - -### 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. - -## misc - -### 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-sprint-interruption-on-attack - -- **default**: `false` -- **description**: Determines if the server will interrupt a sprinting player if they are attacked. - -### 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. - -### max-leash-distance - -- **default**: `10.0` -- **description**: Configure the maximum distance of a leash. If the distance to the leashed entity - is greater, the leash will break. - -### redstone-implementation - -:::caution - -Alternative implementations are ultimately experimental, and as such, could be removed between -updates or even permanently if issues are found. - -::: - -- **default**: `vanilla` -- **description**: Specifies the redstone implementation that the server uses. Alternative - implementations can greatly reduce the lag caused by redstone dust by optimizing power - calculations and reducing the number of block and shape updates emitted. The following - implementations are available: - - **vanilla**: The Vanilla redstone implementation. - - **eigencraft**: The Eigencraft redstone implementation by theosib. - - **alternate-current**: The Alternate Current redstone implementation by Space Walker. -- **note:** Both the Eigencraft and Alternate Current implementations change the behavior of - redstone dust. You can read about how behavior is changed in each implementation's respective - documention: - - Eigencraft: No official documentation available. However, - [theosib's comments](https://bugs.mojang.com/browse/MC-81098?focusedCommentId=420777#comment-420777) - on the Mojira bug tracker give an overview of the Eigencraft implementation. - - [Alternate Current](https://github.com/SpaceWalkerRS/alternate-current/blob/main/README.md) - -### shield-blocking-delay - -- **default**: `5` -- **description**: The number of ticks between a player activating their shield and it actually - blocking damage. - -### show-sign-click-command-failure-msgs-to-player - -- **default**: `false` -- **description**: Whether commands executed by sign click should show failure messages to players. - -### update-pathfinding-on-block-update - -- **default**: `true` -- **description**: Controls whether the pathfinding of mobs is updated when a block is updated in - the world. Disabling this option can improve the server performance significantly, while there is - almost no noticeable effect on the game mechanics. This is recommended when there are lots of - entities loaded, and you have automated farms or redstone clocks. - -## scoreboards - -### allow-non-player-entities-on-scoreboards - -- **default**: `true` -- **description**: Instructs the server to always treat non-player entities as if they are never on a - team. Disabling this may slightly decrease the amount of time the server - spends calculating entity collisions. - -### use-vanilla-world-scoreboard-name-coloring - -- **default**: `false` -- **description**: Instructs the server to use the vanilla scoreboard for player nickname coloring. - Useful when playing on adventure maps made for the vanilla server and client. - -## spawn - -### allow-using-signs-inside-spawn-protection - -- **default**: `false` -- **description**: Allows players to use signs while inside spawn protection. - -### keep-spawn-loaded - -- **default**: `true` -- **description**: Instructs the server to keep the spawn chunks loaded at all times. - -### keep-spawn-loaded-range - -- **default**: `10` -- **description**: The range in chunks around spawn to keep loaded. - -## tick-rates - -### behavior - -#### villager - -##### validatenearbypoi - -- **default**: `-1` -- **description**: Sets the tick rate of the `validatenearbypoi` behavior. of Villager entities - -#### `` - -##### `` - -- **description**: Sets the behavior tick rate of an entity. `-1` uses Vanilla. See timings for the - names. Might change between updates! - -### container-update - -- **default**: `1` -- **description**: The rate, in ticks, at which the server updates containers and inventories. - -### grass-spread - -- **default**: `1` -- **description**: Sets the delay, in ticks, at which the server attempts to spread grass. Higher - values will result in a slower spread. - -### mob-spawner - -- **default**: 1 -- **description**: How often mob spawners should tick to calculate available spawn areas and spawn - new entities into the world. A value of -1 will disable all spawners. - -### sensor - -#### villager - -##### secondarypoisensor - -- **default**: `40` -- **description**: Sets the tick rate of the `secondarypoisensor` sensor of Villager entities - -#### `` - -##### `` - -- **description**: Sets the sensor tick rate of an entity. `-1` uses Vanilla. See timings for - the names. Might change between updates! - -## 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](https://bugs.mojang.com/browse/MC-108513). diff --git a/docs/versioned/paper/content/1.19/dev/README.mdx b/docs/versioned/paper/content/1.19/dev/README.mdx deleted file mode 100644 index fdafd5fef..000000000 --- a/docs/versioned/paper/content/1.19/dev/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Development Guide - -Welcome to the Paper Development Guide! This guide includes information and tutorials for developers -on how to create and expand on Paper plugins. - ---- - - diff --git a/docs/versioned/paper/content/1.19/dev/api/README.mdx b/docs/versioned/paper/content/1.19/dev/api/README.mdx deleted file mode 100644 index 44a142c3b..000000000 --- a/docs/versioned/paper/content/1.19/dev/api/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Paper API - -Welcome to the Paper API Guide! -This guide includes information for developers about how to use specific parts of the Paper API - ---- - - diff --git a/docs/versioned/paper/content/1.19/dev/api/custom-inventory-holder.md b/docs/versioned/paper/content/1.19/dev/api/custom-inventory-holder.md deleted file mode 100644 index 70292d0a3..000000000 --- a/docs/versioned/paper/content/1.19/dev/api/custom-inventory-holder.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -slug: /dev/custom-inventory-holder ---- - -# Custom InventoryHolder - -Custom InventoryHolders can be used to identify your plugin's inventories in events. - -## Why use an InventoryHolder? - -Custom InventoryHolders simplify the steps you need to do to make sure an inventory was created by your plugin. - -:::info - -Using inventory names for identification is unreliable as other plugins can create inventories with names exactly as yours -and with components you need to make sure the name is exactly the same or serialize it to other formats. - -Custom InventoryHolders have no such downsides and by using them you're guaranteed to have methods available to handle your inventory. - -::: - -## Creating a custom InventoryHolder - -InventoryHolder is an interface that we must implement. -We can do this the following way: create a new class that will create our `Inventory` in the constructor. - -:::info - -The constructor takes your main plugin class as an argument in order to create the `Inventory`. -If you wish, you can use the static method `Bukkit.createInventory(InventoryHolder, int)` instead and remove the argument. - -::: - -```java -public class MyInventory implements InventoryHolder { - - private final Inventory inventory; - - public MyInventory(MyPlugin plugin) { - // Create an Inventory with 9 slots, `this` here is our InventoryHolder. - this.inventory = plugin.getServer().createInventory(this, 9); - } - - @Override - public Inventory getInventory() { - return this.inventory; - } - -} -``` - -## Opening the inventory - -To open the inventory, first we have to instantiate our `MyInventory` class and then open the inventory for the player. -You can do that wherever you need. - -:::note - -We pass an instance of our plugin's main class as it's required by the constructor. If you've used the static method and removed the constructor -argument you don't have to pass it here. - -::: - -```java -Player player; // Assume we have a Player instance. - // This can be a command, another event or anywhere else you have a Player. - -MyInventory myInventory = new MyInventory(myPlugin); -player.openInventory(myInventory.getInventory()); -``` - -## Listening to an event - -Once we have the inventory open, we can listen to any inventory events we like and check if the `Inventory#getHolder()` -returns an instance of our `MyInventory`. - -```java -@EventHandler -public void onInventoryClick(InventoryClickEvent event) { - Inventory inventory = event.getInventory(); - // Check if the holder is our MyInventory, - // if yes, use instanceof pattern matching to store it in a variable immediately. - if (!(inventory.getHolder() instanceof MyInventory myInventory)) { - // It's not our inventory, ignore it. - return; - } - - // Do what we need in the event. -} -``` - -## Storing data on the custom InventoryHolder - -You can store extra data for your inventories on the custom InventoryHolder by adding fields and methods to your class. - -Let's make an inventory that counts the amount of times we clicked a stone inside it. -First let's modify our `MyInventory` class a little: - -```java -public class MyInventory implements InventoryHolder { - - private final Inventory inventory; - - private int clicks = 0; // Store the amount of clicks. - - public MyInventory(MyPlugin plugin) { - this.inventory = plugin.getServer().createInventory(this, 9); - - // Set the stone that we're going to be clicking. - this.inventory.setItem(0, new ItemStack(Material.STONE)); - } - - // A method we will call in the listener whenever the player clicks the stone. - public void addClick() { - this.clicks++; - this.updateCounter(); - } - - // A method that will update the counter item. - private void updateCounter() { - this.inventory.setItem(8, new ItemStack(Material.BEDROCK, this.clicks)); - } - - @Override - public Inventory getInventory() { - return this.inventory; - } - -} -``` - -Now, we can modify our listener to check if the player clicked the stone, and if so, add a click. - -```java -@EventHandler -public void onInventoryClick(InventoryClickEvent event) { - // We're getting the clicked inventory to avoid situations where the player - // already has a stone in their inventory and clicks that one. - Inventory inventory = event.getClickedInventory(); - // Add a null check in case the player clicked outside the window. - if (inventory == null || !(inventory.getHolder() instanceof MyInventory myInventory)) { - return; - } - - event.setCancelled(true); - - ItemStack clicked = event.getCurrentItem(); - // Check if the player clicked the stone. - if (clicked != null && clicked.getType() == Material.STONE) { - // Use the method we have on MyInventory to increment the field - // and update the counter. - myInventory.addClick(); - } -} -``` - -:::info - -You can store the created `MyInventory` instance, e.g. on a `Map` for per-player use, or as a field to share the inventory between -all players, and use it to persist the counter even when opening the inventory for the next time. - -::: diff --git a/docs/versioned/paper/content/1.19/dev/api/event-api/custom-events.md b/docs/versioned/paper/content/1.19/dev/api/event-api/custom-events.md deleted file mode 100644 index 83a229f03..000000000 --- a/docs/versioned/paper/content/1.19/dev/api/event-api/custom-events.md +++ /dev/null @@ -1,150 +0,0 @@ ---- -slug: /dev/custom-events ---- - -# Custom Events - -Creating custom events is a great way to add functionality to your plugin. -This will allow other plugins to listen to your custom events and add functionality to your plugin. - -## Creating a custom event - -To create a custom event, you need to create a class that extends `Event`. Each event requires a `HandlerList` that will contain all the listeners that are listening to that event. The only exception to this requirement is when you have an event class that cannot be fired, but serves as a parent for other events instead. -An example of this is the BlockPistonEvent, which cannot be listened to directly. - -This list is used to call the listeners when the event is called. - -:::info[`getHandlerList`] - -Although it is not inherited from `Event`, you need to add a static `getHandlerList()` method and return the `HandlerList` for your event. -Both methods are required for your event to work. - -::: - -```java title="PaperIsCoolEvent.java" -public class PaperIsCoolEvent extends Event { - - private static final HandlerList HANDLER_LIST = new HandlerList(); - - public static HandlerList getHandlerList() { - return HANDLER_LIST; - } - - @Override - public HandlerList getHandlers() { - return HANDLER_LIST; - } -} -``` - -Now that we have created our event, we can add some functionality to it. -Perhaps this will contain a message that will be broadcast to the server when the event is called. - -```java title="PaperIsCoolEvent.java" -public class PaperIsCoolEvent extends Event { - - private static final HandlerList HANDLER_LIST = new HandlerList(); - private Component message; - - public PaperIsCoolEvent(Component message) { - this.message = message; - } - - public static HandlerList getHandlerList() { - return HANDLER_LIST; - } - - @Override - public HandlerList getHandlers() { - return HANDLER_LIST; - } - - public Component getMessage() { - return this.message; - } - - public void setMessage(Component message) { - this.message = message; - } -} -``` - -## Calling the event - -Now that we have created our event, we can call it. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - // ... - - public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); - coolEvent.callEvent(); - // Plugins could have changed the message from inside their listeners here. So we need to get the message again. - // This event structure allows for other plugins to change the message to their taste. - // Like, for example, a plugin that adds a prefix to all messages. - Bukkit.broadcast(coolEvent.getMessage()); - } -} -``` - -## Implementing cancellation - -If you want to allow your event to be cancelled, you can implement the `Cancellable` interface. - -```java title="PaperIsCoolEvent.java" -public class PaperIsCoolEvent extends Event implements Cancellable { - - private static final HandlerList HANDLER_LIST = new HandlerList(); - private Component message; - private boolean cancelled; - - // ... - - @Override - public boolean isCancelled() { - return this.cancelled; - } - - @Override - public void setCancelled(boolean cancelled) { - this.cancelled = cancelled; - } -} -``` - -Now, when the event is called, you can check if it is cancelled and act accordingly. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - // ... - - public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); - coolEvent.callEvent(); - if (!coolEvent.isCancelled()) { - Bukkit.broadcast(coolEvent.getMessage()); - } - } -} -``` - -When an event is cancellable, `Event#callEvent` will return false if the event was cancelled. This allows you to directly use `callEvent` -in your if statement, instead of having to check `Cancellable#isCancelled` manually. - - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - // ... - - public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); - if (coolEvent.callEvent()) { // Directly get the output from callEvent - Bukkit.broadcast(coolEvent.getMessage()); - } - } -} -``` diff --git a/docs/versioned/paper/content/1.19/dev/api/event-api/event-listeners.md b/docs/versioned/paper/content/1.19/dev/api/event-api/event-listeners.md deleted file mode 100644 index 42fe83a23..000000000 --- a/docs/versioned/paper/content/1.19/dev/api/event-api/event-listeners.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -slug: /dev/event-listeners ---- - -# Event Listeners - -Events are an efficient way to listen for specific actions that happen in the game. They can be called by the server, or by plugins. -These are called by the server or plugins when something happens, such as a player joining the server, or a block being broken. -Plugins are able to call custom events, such as a player completing a quest, for other plugins to listen for. - -## Your listener class - -To listen for events, you need to create a class that implements `Listener`. -This class can be called anything you want, but it is recommended to name it something related to the events you are listening for. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - // ... -} -``` - -## `@EventHandler` - -To listen for an event, you need to create a method that is annotated with `@EventHandler`. -This method can be named anything you want, but it is recommended to name it something meaningful related to the event it is listening for. - -## The listener method - -The method body does not need to return any data, for this reason, use void as the return type. -Listeners take in a single parameter, which is the event that is being listened to. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - // ... - } -} -``` - -:::note[Events] - -There is no list of events that can be listened to, however take a look -[here](https://jd.papermc.io/paper/1.19/org/bukkit/event/Event.html) to see all events that extend `Event`. - -An event can only be listened to if it has a static `getHandlerList` method. - -::: - -## Registering the listener - -To register the listener, you need to call `Bukkit.getPluginManager().registerEvents()` -and pass in your listener class instance and an instance of your plugin. - -This will register your listener class and allow it to listen for events. -This is commonly done in the `onEnable()` method of your plugin so that it is registered when the server starts ticking. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - @Override - public void onEnable() { - getServer().getPluginManager().registerEvents(new ExampleListener(), this); - } -} -``` - -## Event priority - -You can also specify the priority of the event. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler(priority = EventPriority.HIGH) - public void onPlayerJoin(PlayerJoinEvent event) { - // ... - } -} -``` -There are six different priorities that you can use: -- `EventPriority.LOWEST` -- `EventPriority.LOW` -- `EventPriority.NORMAL` -- `EventPriority.HIGH` -- `EventPriority.HIGHEST` -- `EventPriority.MONITOR` - -The order of the priorities is somewhat counter-intuitive. The **higher** the priority, the **later** the event is called. -For example, If it is important that your plugin has the last say in a certain event - to avoid it being changed - you -should use `EventPriority.HIGHEST`. - -:::note - -The `MONITOR` priority is used to monitor the event, but not change it. It is called after all other priorities have been called. -This means you can get the result of any plugin interaction such as cancellation or modification. - -::: - -## Event cancellation - -Some events can be cancelled, preventing the given action from being completed. These events implement `Cancellable`. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - event.setCancelled(true); - } -} -``` - -:::warning - -It is important to consider that another plugin could have cancelled or changed the event before your plugin is called. -Always check the event before doing anything with it. - -::: - -The above example will cancel the event, meaning that the player will not be able to join the server. -Once an event is cancelled, it will continue to call any other listeners for that event unless they add -`ignoreCancelled = true` to the `@EventHandler` annotation to ignore cancelled events. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler(ignoreCancelled = true) - public void onPlayerJoin(PlayerJoinEvent event) { - // ... - } -} -``` diff --git a/docs/versioned/paper/content/1.19/dev/api/event-api/handler-lists.md b/docs/versioned/paper/content/1.19/dev/api/event-api/handler-lists.md deleted file mode 100644 index 1f9bd0ba4..000000000 --- a/docs/versioned/paper/content/1.19/dev/api/event-api/handler-lists.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -slug: /dev/handler-lists ---- - -# Handler Lists - -Every `Event` that can be listened to has a `HandlerList` containing all the listeners that are listening to that event. -This list is used to call the listeners when the event is called. - -## Getting the handler list for an event - -To get the handler list for an event, you can call `getHandlerList()` on the specific event class. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - HandlerList handlerList = event.getHandlerList(); - // ... - } - - // Or: - - public ExampleListener() { - // Access the handler list through the static getter - HandlerList handlerList = PlayerJoinEvent.getHandlerList(); - // ... - } -} -``` - -## Unregistering a listener - -To unregister a listener, you can call `unregister()` on the `HandlerList` that the listener is registered to. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - HandlerList handlerList = event.getHandlerList(); - handlerList.unregister(this); - // ... - } - - // Or: - - public ExampleListener() { - // Access the handler list through the static getter - HandlerList handlerList = PlayerJoinEvent.getHandlerList(); - handlerList.unregister(this); - // Granted this is a pretty stupid example... - } -} -``` - -You can unregister based on `Listener` or `Plugin` for more convenience. -Likewise, you can also unregister all listeners for a specific event by calling `unregisterAll()` on the `HandlerList`. diff --git a/docs/versioned/paper/content/1.19/dev/api/pdc.md b/docs/versioned/paper/content/1.19/dev/api/pdc.md deleted file mode 100644 index 46ce4f15e..000000000 --- a/docs/versioned/paper/content/1.19/dev/api/pdc.md +++ /dev/null @@ -1,156 +0,0 @@ ---- -slug: /dev/pdc ---- - -# Persistent Data Container (PDC) - -The Persistent Data Container (PDC) is a way to store custom data on a whole range of objects; such as items, entities, and blocks. -The Full list of classes that support the PDC are: - -- [Chunk](#chunk) -- [World](#world) -- [Entity](#entity) -- [TileState](#tilestate) -- [ItemMeta](#itemmeta) -- [Structure](#structure) - -## What is it used for? -In the past, developers resorted to a variety of methods to store custom data on objects: - -- NBT tags: Requires reflection to access internals and was generally unreliable in the long term. -- Lore and display names: Prone to collisions as well as slow to access. - -The benefit of the PDC is that it allows for a more reliable and performant way to store arbitrary data on objects. -It also doesn't rely on accessing server internals, so it's less likely to break on future versions. It also removes the need to -manually track the data lifecycle, as, for example with an entity, the PDC will be saved when the entity unloads. - -## Adding Data -To store data in the PDC, there are a few things you need first. The first is a `NamespacedKey` which is used to identify the data. -The second is a `PersistentDataContainer` which is the object you want to store the data on. The third is the data itself. - -```java -// Create a NamespacedKey -NamespacedKey key = new NamespacedKey(pluginInstance, "example-key"); - -ItemStack item = new ItemStack(Material.DIAMOND); -// ItemMeta implements PersistentDataHolder so we can get the PDC from it -ItemMeta meta = item.getItemMeta(); -meta.getPersistentDataContainer().set(key, PersistentDataType.STRING, "I love Tacos!"); -item.setItemMeta(meta); -``` - -:::info - -It is considered good practice to reuse the `NamespacedKey` objects. They can be constructed with either: -- A `Plugin` instance and a `String` identifier -- A `String` namespace and a `String` identifier - -The first option is often preferred as it will automatically use the plugin's namespace, however the second option can be used if you -want to use a different namespace / access the data from another plugin. - -::: - -## Getting Data -To get data from the PDC, you need to know the `NamespacedKey` and the `PersistentDataType` of the data. - -```java -// Create a NamespacedKey -NamespacedKey key = new NamespacedKey(pluginInstance, "example-key"); - -ItemStack item = ...; // Retrieve the item from before -// Get the data from the PDC -PersistentDataContainer container = item.getItemMeta().getPersistentDataContainer(); -if (container.has(key, PersistentDataType.STRING)) { - String value = container.get(key, PersistentDataType.STRING); - // Do something with the value - player.sendMessage(Component.text(value)); -} -``` - -## Data Types - -The PDC supports a wide range of data types, such as: -- `Byte`, `Byte Array` -- `Double` -- `Float` -- `Integer`, `Integer Array` -- `Long`, `Long Array` -- `Short` -- `String` -- There are also `Tag Containers`. Tag Containers are a way of nesting PDC's within each other. To create a new PersistentDataContainer, you can use: - ```java - // Get the existing container - PersistentDataContainer container = ...; - // Create a new container - PersistentDataContainer newContainer = container.getAdapterContext().newPersistentDataContainer(); - ``` - -### Custom Data Types - -You can store a wide range of data in the PDC with the native adapters, however, if you need a more complex data type you can -implement your own `PersistentDataType` and use that instead. -The `PersistentDataType`'s job is to "deconstruct" a complex data type into something that is natively supported (see above) and then vice-versa. - -Here is an example of how to do that for a UUID: - -```java -public class UUIDDataType implements PersistentDataType { - @Override - public Class getPrimitiveType() { - return byte[].class; - } - - @Override - public Class getComplexType() { - return UUID.class; - } - - @Override - public byte[] toPrimitive(UUID complex, PersistentDataAdapterContext context) { - ByteBuffer bb = ByteBuffer.wrap(new byte[16]); - bb.putLong(complex.getMostSignificantBits()); - bb.putLong(complex.getLeastSignificantBits()); - return bb.array(); - } - - @Override - public UUID fromPrimitive(byte[] primitive, PersistentDataAdapterContext context) { - ByteBuffer bb = ByteBuffer.wrap(primitive); - long firstLong = bb.getLong(); - long secondLong = bb.getLong(); - return new UUID(firstLong, secondLong); - } - } -``` - -:::note - -In order to use your own `PersistentDataType`, you must pass an instance of it to the set/get/has methods. -```java -container.set(key, new UUIDDataType(), uuid); -``` - -::: - -## Storing on different objects - -- ##### Chunk - - `Chunk#getPersistentDataContainer()` -- ##### World - - `World#getPersistentDataContainer()` -- ##### Entity - - `Entity#getPersistentDataContainer()` -- ##### TileState - - This is slightly more complicated, as you need to cast the block to something that extends `TileState`. - This does not work for all blocks, only those that have a tile entity. F.E: - ```java - Block block = ...; - if (block.getState() instanceof Chest chest) { - chest.getPersistentDataContainer().set(key, PersistentDataType.STRING, "I love Tacos!"); - chest.update(); - } - ``` -- ##### Structure - - `Structure#getPersistentDataContainer()` -- ##### ItemMeta - - `ItemMeta#getPersistentDataContainer()` diff --git a/docs/versioned/paper/content/1.19/dev/getting-started/README.mdx b/docs/versioned/paper/content/1.19/dev/getting-started/README.mdx deleted file mode 100644 index 7e0a195c8..000000000 --- a/docs/versioned/paper/content/1.19/dev/getting-started/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Development Guide - -Welcome to the Paper Development Guide! This guide includes information and tutorials on -how to start developing plugins for Paper. - ---- - - diff --git a/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md b/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md deleted file mode 100644 index 944017289..000000000 --- a/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md +++ /dev/null @@ -1,167 +0,0 @@ ---- -slug: /dev/getting-started/paper-plugins ---- - -# Paper Plugins - -Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to -expand the field of what the Paper API is able to introduce. - -:::info[Experimental] - -This is experimental and may be subject to change. - -::: - -- [Bootstrapper](#bootstrapper) -- [Loader](#loaders) -- [Differences](#differences) - -## How do I use them? -Similarly to Bukkit plugins, you have to introduce a ``paper-plugin.yml`` file into your jar resources folder. -This can act as a drop in replacement for ``plugin.yml``, allowing you to specifically target the Paper platform. - -It should be noted you still have the ability to include both ``paper-plugin.yml``and ``plugin.yml`` in the same jar. - -Here is an example configuration. -```yml -name: Paper-Test-Plugin -version: '1.0' -main: io.papermc.testplugin.TestPlugin -description: Paper Test Plugin -api-version: '1.19' -bootstrapper: io.papermc.testplugin.TestPluginBootstrap -loader: io.papermc.testplugin.TestPluginLoader -``` - -### Dependency Declaration - -Dependency declaration is specified a bit differently than Bukkit plugins, as you are -able to define if a dependency is required during bootstrapping. This means that any bootstrapping -logic for your dependencies will be run before yours is run. -```yml -dependencies: - - name: DependencyName - required: true - bootstrap: true -``` - -If a dependency is ``required`` it must be installed on the server or your plugin will fail to load. If marked otherwise, it will -ignore if the dependency isn't found. -Otherwise, your plugin will be loaded fine, in the same fashion as a plugin that is a ``soft-depend`` in a Bukkit plugin.yml - -If a dependency is marked as ``bootstrap``, this indicates that this dependency is required during bootstrapping, which currently does not serve a purpose. - -:::note[Plugin Loading Order] - -Note that [unlike Bukkit plugins](#load-order-logic-split), dependencies are independent of the plugin load order. -This means that although declaring a dependency will give you access to its classes, if you require it to be initialised before your plugin is loaded, see how to [declare load order](#load-order-declaration). -::: - -### Load Order Declaration - -To declare the order in which plugins are loaded before/after your plugin, you are able to define two sections in your ``paper-plugin.yml``. - -It should be noted that the load order for bootstrapping is independent, meaning that if you want to define the load order for bootstrappers -you must set the ``bootstrap`` field to ``true``. - -:::note[Cyclic Loading] - -Note that in certain cases plugins may be able to introduce cyclic loading loops, which will prevent the server from starting. -Please read the [cyclic loading guide](docs/paper/admin/reference/paper-plugins.md#cyclic-plugin-loading) for more information. -::: - -#### load-before -You are able to define a list of plugins that your plugin should load before. -```yml -load-before: - - name: PluginName - bootstrap: false -``` -This means that your plugin will load **before** ``PluginName`` is loaded. - -#### load-after -You are then able to define a list of plugins that your plugin should load after. -```yml -load-after: - - name: PluginName - bootstrap: false -``` -This means that your plugin will load **after** ``PluginName`` is loaded. - -## What is it used for? -Paper plugins lay down the framework for some future API. -Our goals are to open more modern API that better aligns with Vanilla. -Paper plugins allow us to do just that by making a new way to load plugin resources -before the server has started by using [Bootstrappers](#bootstrapper). - - -## Bootstrapper -Paper plugins are able to identify their own bootstrapper by implementing ``io.papermc.paper.plugin.bootstrap.PluginBootstrap`` and adding -the class of your implementation to the bootstrapper field in the ``paper-plugin.yml``. -```java -public class TestPluginBootstrap implements PluginBootstrap { - - @Override - public void bootstrap(@NotNull PluginProviderContext context) { - - } - - @Override - public @NotNull JavaPlugin createPlugin(@NotNull PluginProviderContext context) { - return new TestPlugin("My custom parameter"); - } - -} -``` -A Bootstrapper allows you to also override how your plugin is initiated, allowing you to pass values into your plugin constructor. -Currently, bootstrappers do not offer much new API, and are highly experimental. This may be subject to change once more API is introduced. - -## Loaders -Paper plugins are able to identify their own plugin loader by implementing ``io.papermc.paper.plugin.loader.PluginLoader`` and adding -the class of your implementation to the loader field in the ``paper-plugin.yml``. - -The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into. -This, as of right now, only applies to creating the expected classpath for the plugin, e.g. supplying external libraries to the plugin. -```java -public class TestPluginLoader implements PluginLoader { - - @Override - public void classloader(@NotNull PluginClasspathBuilder classpathBuilder) { - classpathBuilder.addLibrary(new JarLibrary(Path.of("dependency.jar"))); - - MavenLibraryResolver resolver = new MavenLibraryResolver(); - resolver.addDependency(new Dependency(new DefaultArtifact("com.example:example:version"), null)); - resolver.addRepository(new RemoteRepository.Builder("paper", "default", "https://repo.papermc.io/repository/maven-public/").build()); - - classpathBuilder.addLibrary(resolver); - } -} - -``` -Currently, you are able to add two different library types, ``JarLibrary``, and ``MavenLibraryResolver``. - - -## Differences - -### Bukkit Serialization System -Paper plugins do not support the serialization system (``org.bukkit.configuration.serialization``) that Bukkit uses. Your classes will not be able to be -serialized, vise versa. It is highly recommended to not use this system with Paper plugins. - -### Classloading Isolation -Paper plugins have isolated classloaders, meaning that relocating dependencies will not be necessary. Paper plugins are not able to access each other unless given explicit access -by depending on another plugin, etc. This prevents plugins from accidentally accessing your dependencies, and in general helps ensure that plugins are only able to access your plugin -if they explicitly say that they're depending on it. - -Paper plugins have the ability to bypass this, being able to access OTHER plugins classloaders by adding -```yml -has-open-classloader: true -``` -to your ``paper-plugin.yml``. Note, other plugins will still be unable to access your classloader. - - -### Load Order Logic Split -In order to better take advantage of classloading isolation, Paper plugins do **not** use the ``dependencies`` field to determine load order. -This was done for a variety of reasons, mostly to allow better control and allow plugins to properly share classloaders. - -See information on [declaring load order](#load-order-declaration) for more information on how to declare the load order of your plugin. diff --git a/docs/versioned/paper/content/1.19/dev/getting-started/plugin-yml.md b/docs/versioned/paper/content/1.19/dev/getting-started/plugin-yml.md deleted file mode 100644 index bbac6e41b..000000000 --- a/docs/versioned/paper/content/1.19/dev/getting-started/plugin-yml.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -slug: /dev/plugin-yml ---- - -# Bukkit Plugin YML - -The plugin.yml file is the main configuration file for your plugin. -It contains information about your plugin, such as its name, version, and description. -It also contains information about the plugin's dependencies, permissions, and commands. - -The plugin.yml file is located in the `resources` directory of your project. -``` -example-plugin -├── build.gradle.kts -├── settings.gradle.kts -└── src - └── main - ├── java - └── resources - └── plugin.yml -``` - -## Example - -Here is an example of a plugin.yml file: - -```yaml -name: ExamplePlugin -version: 1.0.0 -main: io.papermc.testplugin.ExamplePlugin -description: An example plugin -author: PaperMC -website: https://papermc.io -api-version: '1.19' -``` - -## Fields - -:::note - -The fields in this section are not in any particular order. -If they have an asterisk (\*) next to them, that means they are required. - -::: - -### name* - -The name of your plugin. This is what will be displayed in the plugin list and log messages. -This will be overridden in the logs if the prefix is set. -- `name: ExamplePlugin` - -### version* - -The current version of the plugin. This is shown in plugin info messages and server logs. -- `version: 1.0.0` - -### main* - -The main class of your plugin. This is the class that extends `JavaPlugin` and is the entry point to your plugin. -- `main: io.papermc.testplugin.ExamplePlugin` - -This is the package path and class name of your main class. - -### description - -A short description of your plugin and what it does. This will be shown in the plugin info commands. -- `description: An example plugin` - -### author / authors - -The author(s) of the plugin. This can be a single author or a list of authors. -- `author: PaperMC` -- `authors: [PaperMC, SpigotMC, Bukkit]` -These will be shown in the plugin info commands. - -### contributors - -The contributors to the plugin that aren't the managing author(s). -- `contributors: [PaperMC, SpigotMC, Bukkit]` -These will be shown in the plugin info commands. - -### website - -The website of the plugin. This is useful for linking to a GitHub repository or a plugin page. -- `website: https://papermc.io` -This will be shown in the plugin info commands. - -### api-version - -The version of the Paper API that your plugin is using. This doesn't include the minor version. -Servers with a version lower than the version specified here will refuse to load the plugin. -The valid versions are 1.13 - 1.19. -- `api-version: '1.19'` - -:::info - -If this is not specified, the plugin will be loaded as a legacy plugin and a warning will be printed to the console. - -::: - -### load - -This tells the server when to load the plugin. This can be `STARTUP` or `POSTWORLD`. Will default to `POSTWORLD` if not specified. -- `load: STARTUP` - -### prefix - -The prefix of the plugin. This is what will be displayed in the log instead of the plugin name. -- `prefix: EpicPaperMCHypePlugin` - -### libraries - -:::warning - -The use of this feature is *currently* against maven central's TOS. However, this feature is very likely to stay. - -::: - -This is a list of libraries that your plugin depends on. These libraries will be downloaded from the Maven central repository and added to the classpath. -This removes the need to shade and relocate the libraries. - -```yaml -libraries: - - com.google.guava:guava:30.1.1-jre - - com.google.code.gson:gson:2.8.6 -``` - -### permissions - -This is a list of permissions that your plugin uses. This is useful for plugins that use permissions to restrict access to certain features. -```yaml -permissions : - permission.node: - description: "This is a permission node" - default: op - children: - permission.node.child: true - another.permission.node: - description: "This is another permission node" - default: not op -``` - -The description is the description of the permission node. This is what will be displayed in the permissions list. -The default is the default value of the permission node. This can be `op`/`not op`, or `true`/`false`. This defaults to the value of `default-permission` if not specified. (Which defaults to `op` if not specified) -Each permission node can have children. When set to `true` it will inherit the parent permission. - -### default-permission - -The default value that permissions that don't have a `default` specified will have. This can be `op`/`not op`, or `true`/`false`. -- `default-permission: true` - -## Commands - -This is a list of commands that your plugin uses. This is useful for plugins that use commands to provide features. -```yaml -commands: - command: - description: "This is a command" - usage: "/command " - aliases: [cmd, command] - permission: permission.node - permission-message: "You do not have permission to use this command" -``` - -- The __description__ is the description of the command. This gives a brief description of what the command does. -- The __usage__ is the usage of the command. This is what will be displayed when the player uses `/help `. -- The __aliases__ are a list of aliases that the command can be used with. This is useful for shortening the command. -- __permission__ is the permission node that the player needs to use the command. Note: Players will only see commands they have permission to use. -- __permission-message__ is the message that will be displayed when the player does not have permission to use the command. - -## Dependencies: - -:::warning[Dependency Loops] - -If a plugin is specified as a dependency, it will be loaded before your plugin. -Be careful as these can cause plugin load issues if cyclical dependencies appear. A Cyclical dependency can be illustrated as follows: - -PluginA -> PluginB -> PluginA -> PluginB... etc. - -Where PluginA and PluginB are plugins that depend on each other. - -::: - -### depend - -A list of plugins that your plugin depends on to __load__. They are specified by their plugin name. - -:::info - -If the plugin is not found, your plugin will not load. - -::: - -- `depend: [Vault, WorldEdit]` - -### softdepend - -A list of plugins that your plugin depends on to have __full functionality__. They are specified by their plugin name. - -- `softdepend: [Vault, WorldEdit]` - -### loadbefore - -A list of plugins that your plugin should be loaded __before__. They are specified by their plugin name. -This is useful if you want to load your plugin before another plugin for the other plugin to use your plugin's API. - -- `loadbefore: [Vault, FactionsUUID]` - -### provides - -This can be used to tell the server that this plugin will provide the functionality of some library or other plugin (like an alias system). -Plugins that (soft)depend on the other plugin will treat your plugin as if the other plugin exists when resolving dependencies or using `PluginManager#getPlugin(String)`. -- `provides: [SomeOtherPlugin]` diff --git a/docs/versioned/paper/content/1.19/dev/getting-started/project-setup.md b/docs/versioned/paper/content/1.19/dev/getting-started/project-setup.md deleted file mode 100644 index ea35cc25a..000000000 --- a/docs/versioned/paper/content/1.19/dev/getting-started/project-setup.md +++ /dev/null @@ -1,153 +0,0 @@ ---- -slug: /dev/project-setup ---- - -# Paper Project Setup - -As the Paper team primarily uses [IntelliJ IDEA](https://www.jetbrains.com/idea/), this guide will be focused on that IDE. -However, the steps below should apply to other IDEs as well, with some minor changes. - -The Paper team uses [Gradle](https://gradle.org/) as its build system, and its tools are implemented for Gradle. -Most of the code below can be altered to work with other build systems, such as Maven, but this guide will only cover Gradle. - -Follow the guide [here](https://docs.gradle.org/current/userguide/migrating_from_maven.html) to learn how to migrate from Maven to Gradle. - -### Creating a new project - -Open your IDE and select the option to create a new project. -In Intellij, you will get the option to select the type of project you want to create - select `New Project`. -Select `Gradle - Kotlin DSL` and click `Create`. - -You will land into the `build.gradle.kts` file where you can add your dependencies. - -### Adding Paper as a dependency - -To add Paper as a dependency, you will need to add the Paper repository to your `build.gradle.kts` file as well as the dependency itself. - -```kotlin title=build.gradle.kts -repositories { - mavenCentral() - maven("https://repo.papermc.io/repository/maven-public/") -} - -dependencies { - compileOnly("io.papermc.paper:paper-api:1.19.4-R0.1-SNAPSHOT") -} - -java { - toolchain.languageVersion.set(JavaLanguageVersion.of(17)) -} -``` - -### Setting up the `src` directory - -:::note - -If your IDE creates a `src` directory automatically, you can skip this step. - -::: - -To set up the `src` directory, you will need to create a new directory called `src` and then create a new directory called `main` inside of it. -Inside of `main`, create two new directories called `java` and `resources`. - -It should look like this: - -``` -... -example-plugin -├── build.gradle.kts -├── settings.gradle.kts -└── src - └── main - ├── java - └── resources -... -``` - -### Setting up the `java` directory - -You will place your Java source files in the `java` directory. You first need to create some packages to organize your code. -For this example, we will create three packages called `io.papermc.testplugin` and then create a class called `ExamplePlugin` inside of it. - -``` -... -example-plugin -├── build.gradle.kts -├── settings.gradle.kts -└── src - └── main - ├── java - │ └── io - │ └── papermc - │ └── testplugin - │ └── ExamplePlugin.java - └── resources -... -``` - -### Packages - -You can see here that the `ExamplePlugin` class is inside the `io.papermc.testplugin` package. -A package is a way to organize your code - essentially, it's a folder. Java packages are used to group related classes. -Oracle has a guide on [packages](https://docs.oracle.com/javase/tutorial/java/package/packages.html) if you want to learn more. - -When [naming](https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html) your packages, you should use your domain name in reverse order. For example, if your domain name is `papermc.io`, -your package name should be `io.papermc`. If you do not have a domain name, you could use something like your GitHub username. -If you were Linus Torvalds, your package would be `io.github.torvalds`. - -This is then followed by the name of your project. -For example, if your project was called `ExamplePlugin`, your package would be `io.github.torvalds.exampleplugin`. -This allows for a unique package name for every plugin. - -### The _main_ class - -The main class is the entry point to your plugin and will be the only class that extends `JavaPlugin` in your plugin. -This is an example of what your `ExamplePlugin` class could look like: - -```java -package io.papermc.testplugin; - -import net.kyori.adventure.text.Component; -import org.bukkit.Bukkit; -import org.bukkit.event.EventHandler; -import org.bukkit.event.Listener; -import org.bukkit.event.player.PlayerJoinEvent; -import org.bukkit.plugin.java.JavaPlugin; - -public class ExamplePlugin extends JavaPlugin implements Listener { - - @Override - public void onEnable() { - Bukkit.getPluginManager().registerEvents(this, this); - } - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - event.getPlayer().sendMessage(Component.text("Hello, " + event.getPlayer().getName() + "!")); - } - -} -``` - -### Setting up the `resources` - -The `resources` directory is where you will place your plugin's `plugin.yml` file. See the [Plugin YML](plugin-yml) page for more information. - -### Conclusion - -You should now have a project set up with Paper as a dependency. -All you have left to do now is to compile your plugin and run it on a Paper server. - -:::note - -If you want to streamline the process of testing a plugin, you can use the [Run-Paper](https://github.com/jpenilla/run-paper) Gradle task. -It will automatically download a Paper server and run it for you. - -::: - -:::info - -If you are using IntelliJ, you can use the Gradle GUI `Build` menu to compile your plugin - found on the top right of your IDE. -The output jar of your plugin will be in the `build/libs` directory. - -::: diff --git a/docs/versioned/paper/content/1.20/README.mdx b/docs/versioned/paper/content/1.20/README.mdx deleted file mode 100644 index c3bf58a9f..000000000 --- a/docs/versioned/paper/content/1.20/README.mdx +++ /dev/null @@ -1,30 +0,0 @@ -import DocCardList from "@theme/DocCardList"; - -# Welcome to the Paper Docs - -Paper is a high performance fork of Spigot that aims to fix gameplay and -mechanic inconsistencies as well as to improve performance. Paper contains numerous features, bug -fixes, exploit preventions and major performance improvements not found in Spigot. - ---- - - diff --git a/docs/versioned/paper/content/1.20/admin/README.mdx b/docs/versioned/paper/content/1.20/admin/README.mdx deleted file mode 100644 index 0538b45d1..000000000 --- a/docs/versioned/paper/content/1.20/admin/README.mdx +++ /dev/null @@ -1,15 +0,0 @@ ---- -slug: /admin ---- - -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Paper Administration Guide - -Welcome to the Paper administration guide! This guide includes information and tutorials -regarding the administration of a Paper server. - ---- - - diff --git a/docs/versioned/paper/content/1.20/admin/getting-started/adding-plugins.md b/docs/versioned/paper/content/1.20/admin/getting-started/adding-plugins.md deleted file mode 100644 index 2bc4f0a87..000000000 --- a/docs/versioned/paper/content/1.20/admin/getting-started/adding-plugins.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -toc_max_heading_level: 4 -slug: /adding-plugins -description: Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files. ---- - -# Adding Plugins - -Plugins are the most powerful way to extend the functionality of Paper beyond the configuration -files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow, -to adding entirely new and original game modes or items. - -:::danger[Malicious Plugins] - -Ensure you fully trust the source of any plugin before installing it. Plugins are given **full and -unrestricted** access to not only your server but also the machine that it runs on. Because of this, -it is imperative that plugins only be installed from trusted sources. Be careful! - -::: - -## Finding plugins - -Before installing a plugin, you'll need to find what you want to install. The best place to find plugins is [Hangar](https://hangar.papermc.io), Paper's plugin repository, but you can also find many plugins -on [SpigotMC](https://www.spigotmc.org/resources/), -[BukkitDev](https://dev.bukkit.org/bukkit-plugins), or the -[PaperMC Forums](https://forums.papermc.io/forums/paper-plugin-releases/), while other plugins may -release on [GitHub](https://github.com). One of the best ways to find plugins isn't to browse any of -these sites directly but to search for plugins using a search engine. Searching for the function you -desire followed by `Minecraft plugin` will often yield good results. - -:::tip[Spigot and Bukkit Plugins] - -Paper is compatible with both Spigot and Bukkit plugins. It's okay if a plugin does not explicitly -mention Paper compatibility. It'll still work. - -::: - -## Installing plugins - -1. Once you've found the plugin you'd like to install, download it. Ensure the file you have - downloaded ends in `.jar`. Some plugins also distribute as `.zip` files, in which case you will - need to extract the file and locate the `.jar` for your platform, often labelled `bukkit` or - `paper`. -2. Once you have the plugin downloaded locally, locate the `plugins` folder from the root directory - of your Paper server. -3. Drag and drop the plugin file (`.jar`) into the `plugins` folder. If you are using a shared - hosting service, you may need to use their web panel or SFTP to upload the plugin; however, the - procedure will be the same. -4. Restart your server. The plugin should load. -5. Check your work. Once the server has finished loading, run the `/plugins` command in-game or type - `plugins` into the console. You should see your freshly installed plugin listed in green. If it - is not listed or is colored red, continue to [troubleshooting](#troubleshooting). A plugin listed - in red means that it is not currently enabled. For a freshly installed plugin, this often means - that the plugin failed to load. - -## Troubleshooting - -### Check your logs - -The first step to troubleshooting installing plugins is to check the log of your server. Your -server's most recent logs will be stored to the `logs/latest.log` file. You may need to scroll near -the beginning of this file to see when plugins were loaded. - -#### Missing dependencies - -If you see something like this: - -```log -[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' -[00:00:00] [Server thread/WARN] org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. -``` - -This means that the plugin you tried to install is missing a dependency. A dependency, in this case, -is another plugin that you must install for the first to function. While you will get a big scary -error, the important line to look at is: - -```log -[00:00:00] [Server thread/WARN] Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'. -``` - -This is telling you that in order to load `MyAwesomePlugin`, you must first install `Vault`. - -#### Invalid `plugin.yml` - -If you see something closer to this: - -```log -[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins' -[00:00:00] [Server thread/WARN] org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml -``` - -This means that what you have downloaded isn't a valid Paper plugin. This is generally caused by one -of the following: - -1. The plugin you downloaded isn't a plugin at all, but instead a mod for Forge, Fabric, or similar. - These will not run on Paper. -2. The plugin failed to download completely. Especially when using tools such as `curl` or `wget`, - you can easily download error pages rather than the plugin you intended. This may also be caused - by a network issue. Attempt to download the plugin again. If you are using FTP (not SFTP or a web - panel) to upload your plugin to a shared hosting service, ensure your FTP client is in `binary` - and not `ASCII` mode. Consult the documentation for your FTP client for details. - -#### Ambiguous plugin name - -If you see something like this: - -```log -[00:00:00] [Server thread/WARN] Ambiguous plugin name `Essentials' for files `plugins/EssentialsX-2.19.4.jar' and `plugins/Essentialsx-2.20.0-dev.jar' in `plugins' -``` - -This means you have two plugins with the same name, which is not supported. In this case, two -versions of EssentialsX are installed. Both the release `2.19.4`, and a development build of -`2.20.0`. Ensure you only have one version of each plugin installed at one time. Delete the older -version of the duplicate plugin, and restart your server. - -To prevent accidentally installing two versions of one plugin while updating, you can use -the `update` folder as described in the [Update Guide](/paper/updating#step-2-update-plugins). - -#### Something else - -If you see an error, but it isn't similar to one of the above, attempt to read it yourself. While -the full error may be large and scary, you likely only have to read the first one or two lines to -understand what is going on. If you're not sure, do not hesitate to reach out for support on our -[Discord](https://discord.gg/papermc) in the `#paper-help` channel. - -### If nothing is logged - -If nothing is logged, your server is likely not attempting to load any plugins. The conditions -needed for the server to load a plugin are as follows: - -1. The file is at the root of the `plugins` folder, relative to its working directory. This is - usually the same folder as the server JAR file. **Subdirectories of the `plugins` folder will not - be checked.** All plugins must be in the root folder. -2. The file ends in `.jar`. If your plugin does not end in `.jar`, what you have downloaded may not - be a plugin. Note that some plugins distribute multiple JARs as `.zip` files. If this is the - case, you have to extract them before installing the plugin. - -If both of these are true, and you still see no logs, please reach out for support on our -[Discord](https://discord.gg/papermc) server in the `#paper-help` channel. We will be happy to -assist you. diff --git a/docs/versioned/paper/content/1.20/admin/getting-started/assets/hangar.png b/docs/versioned/paper/content/1.20/admin/getting-started/assets/hangar.png deleted file mode 100644 index 1bdead750..000000000 Binary files a/docs/versioned/paper/content/1.20/admin/getting-started/assets/hangar.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/admin/getting-started/getting-started.mdx b/docs/versioned/paper/content/1.20/admin/getting-started/getting-started.mdx deleted file mode 100644 index 75e382a71..000000000 --- a/docs/versioned/paper/content/1.20/admin/getting-started/getting-started.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -slug: /getting-started -description: How to get started with downloading and setting up a Paper server. ---- - -# Getting Started - -## Requirements - -:::tip - -Paper requires at least **Java ** to run, which [is easy to download and install](/misc/java-install). - -::: - -| Paper Version | Recommended Java Version | -|----------------|-----------------------------------------| -| 1.8 to 1.11 | Java 8 | -| 1.12 to 1.16.4 | Java 11 | -| 1.16.5 | Java 16 | -| 1.17.1-1.18.1+ | Java | - -## Downloading Paper - -Paper provides runnable server JARs directly from our -[website's downloads page](https://papermc.io/downloads). - -Click on the build number to download a file. - -## Running the server - -To run the server you will need to either create a startup script -or run a command in your terminal. - -You can generate a startup script using our [Startup Script Generator](/misc/tools/start-script-gen). -You can also obtain the optimized terminal command to run the server there. - -If you're just looking for a short command: -```bash -java -Xms4G -Xmx4G -jar paper.jar --nogui -``` -Ensure you navigated your terminal to the directory of your server -and that you have replaced `paper.jar` with the name of the JAR you have downloaded. - -The amount of RAM can be set by changing the numbers in the `Xmx` and `Xms` arguments. -`--nogui` disables Vanilla's GUI, so you don't get double interfaces when using the command line. - -To configure your server, see the [Global Configuration](../reference/configuration/global-configuration.mdx) and -[Per World Configuration](../reference/configuration/world-configuration.mdx) pages. - -## Updating the server - -Updating Paper is simple! See our [Update Tutorial](../how-to/update.md) for more information. - -## Migrating to Paper - -### 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. No additional consideration is required. - -### From CraftBukkit or Spigot - -Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes. - -## Next steps - -Take a look at our [Next Steps](/paper/next-steps) guide to get your server up and running with the best performance and -features. diff --git a/docs/versioned/paper/content/1.20/admin/getting-started/migration.md b/docs/versioned/paper/content/1.20/admin/getting-started/migration.md deleted file mode 100644 index be41c82bd..000000000 --- a/docs/versioned/paper/content/1.20/admin/getting-started/migration.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -slug: /migration -title: Migrating to or from Paper -description: It's simple to migrate your server to or from Paper. This page will help you get started. ---- - -It's simple to migrate your server to or from Paper. The steps below will help you get started. - -:::caution[Backup your data before you start!] - -Before you begin, please ensure you have a full backup of your server. - -See our [Backup Guide](/paper/updating#step-1-backup) for more information. - -::: - -## Migrating to Paper - -### From CraftBukkit or Spigot - -It's easy to migrate from CraftBukkit or Spigot to Paper. Follow the steps below. - -1. Stop your server if it is running, and create a full backup. -2. Download Paper from [our downloads page](https://papermc.io/downloads). -3. Rename the downloaded file to match the name specified in the [start command](getting-started.mdx#running-the-server). -4. Replace your existing JAR file with your freshly downloaded Paper JAR. -5. Start your new server. - -Paper retains full compatibility with all Spigot plugins, allowing a seamless transition. - -:::info - -Your new Paper server will still use [`bukkit.yml`](../reference/configuration/bukkit-configuration.mdx) -and [`spigot.yml`](../reference/configuration/spigot-configuration.mdx). -New configuration options can be found in [`config/paper-global.yml`](../reference/configuration/global-configuration.mdx) -and [`config/paper-world-defaults.yml`](../reference/configuration/world-configuration.mdx). - -::: - -If you have any issues migrating from CraftBukkit or Spigot, do not hesitate to reach out for -support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel). - -### From Vanilla - -When migrating to Paper from Vanilla, the way worlds are stored will automatically be changed. -Should you ever want to go back to Vanilla, follow the [Vanilla Migration Guide](#to-vanilla) -closely, as manual changes will be required. - -1. Stop your Vanilla server if it is running, and create a full backup. -2. Download Paper from [our downloads page](https://papermc.io/downloads) and replace your Vanilla - server JAR with your freshly downloaded Paper JAR. -3. Rename the downloaded file to match the name specified in the [start command](getting-started.mdx#running-the-server). -4. Start your new Paper server. - -You have now successfully migrated to Paper. If you encounter any issues, do not hesitate to reach -out for support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel). - -### From Fabric/Forge - -Because both Fabric and Forge use the Vanilla world directory structure, the same steps as the -[Vanilla Migration Guide](#from-vanilla) may be used, with one caveat. If your Fabric or Forge -server used mods that added new blocks, items, or other data to the game, Paper will be unable to -load these features. - -Additionally, note that Paper does not support Fabric or Forge mods. You will need to find plugin -replacements. Any hybrids that attempt to support both mods and plugins are fundamentally flawed and -not recommended for use. - -## Migrating from Paper - -### To Vanilla - -Because Paper stores worlds slightly differently than Vanilla, manual work is required to migrate. -If these steps are not taken, your nether and end will look like they have been reset. Don't worry! -Even if this has happened, you haven't lost any data. The Vanilla server just doesn't know where to -find it. - -Here is a chart to show the difference between how Vanilla and Paper store worlds. - -| Server Software | Overworld | Nether | End | -| --------------- | --------- | --------------------- | --------------------- | -| Vanilla | `/world` | `/world/DIM-1` | `/world/DIM1` | -| Paper | `/world` | `/world_nether/DIM-1` | `/world_the_end/DIM1` | - -Follow these steps to migrate from Paper to Vanilla: - -:::note - -These steps assume a `level-name` (as set in `server.properties`) of `world`. If this is not the -case for you, replace `world` with your `level-name` for all steps below. - -::: - -1. Stop your Paper server, if it is running. -2. If you have already started your server with Vanilla, enter the `world` folder and delete both - the `DIM-1` and `DIM1` folders. This step is only necessary should you have started your server - with Vanilla. -3. Copy the `/world_nether/DIM-1` folder into the `/world` folder. -4. Copy the `/world_the_end/DIM1` folder into the `/world` folder. -5. Delete both the `/world_nether` and `/world_the_end` folders. -6. Replace your Paper JAR with a Vanilla server JAR. -7. Start your Vanilla server. - -### To CraftBukkit or Spigot - -Paper does **not** support migration to either CraftBukkit or Spigot! While you may find success -(both CraftBukkit and Spigot use the same directory structure as Paper), **do not** reach out for -support with issues you encounter and note that data loss is possible. - -### To Fabric/Forge - -Because both Fabric and Forge use the same directory structure for world storage as Vanilla, follow -the [Vanilla Migration Guide](#to-vanilla) for this process. Note that neither Fabric nor Forge will -support Paper plugins! You will be required to find replacement mods. diff --git a/docs/versioned/paper/content/1.20/admin/getting-started/setup-next-steps.md b/docs/versioned/paper/content/1.20/admin/getting-started/setup-next-steps.md deleted file mode 100644 index ce52d6e0e..000000000 --- a/docs/versioned/paper/content/1.20/admin/getting-started/setup-next-steps.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -slug: /next-steps -description: How to proceed after starting your server. ---- - -# Next Steps - -Now that you have your server up and running, there are a few things you should do to ensure that your server is running smoothly. - -## Configuration - -One of the first things you should do is ensure your server is configured to your specifications. -Paper is highly configurable, and you can change many settings to suit your needs. We outline where -you can find these settings in the [Configuration](/paper/reference/configuration) guide. - -## Plugins - -One of the main reasons to use Paper is to take advantage of the many plugins which make use of our -expansive API. We have our own plugin repository, [Hangar](https://hangar.papermc.io/), where you can -find many plugins to use on your server. We also have a guide on how to install plugins -[here](/paper/adding-plugins). - -![Hangar](./assets/hangar.png) - -## Security - -### Whitelisting - -If you want to restrict who can join your server, you can use the whitelist feature. This allows you to -specify who can join your server, and stops anyone else from joining. You can use the whitelist from -the server console, or by editing the `whitelist.json` file in your server directory. - -### Permissions - -Permissions are a way to control what players can and cannot do on your server. You can use permissions -to restrict who can use certain commands, or who can access certain areas of your server. It is -common for plugins to use permissions to control who can use their features. You can use permission -plugins such as [LuckPerms](https://luckperms.net/) to manage the permissions which players will be granted. - -## Backups - -It's important to keep backups of your server. If something goes wrong, you can restore your server to a -previous state. We cover how to do this in the [Updating](/paper/updating) guide. - -## Optimization - -Out of the box, Paper is optimized for performance. However, there are many things you can do to further -optimize your server. One of the most common things to do is to make sure that you are running the -correct startup flags for your server. We have a tool that allows you to automatically generate a -startup script with the correct flags for your server. You can find this tool -[here](/misc/tools/start-script-gen). Beyond this, a guide such as [this one](https://paper-chan.moe/paper-optimization/) -will help you to further optimize your server. - -## Making your server public - -If you want to make your server public, you will need to port forward your server. This allows people -from outside your network to connect to your server. There is a guide made by -[NordVPN](https://nordvpn.com/blog/open-ports-on-router/) which explains what port forwarding is and how -to do it for your Paper server. - -## Troubleshooting - -If you encounter any issues with your server, you can follow our [Troubleshooting](/paper/basic-troubleshooting) -guide to help you diagnose and fix the issue. If you are unable to fix the issue, you can come and -ask for help in our [Discord](https://discord.gg/papermc) server! diff --git a/docs/versioned/paper/content/1.20/admin/how-to/aikars-flags.md b/docs/versioned/paper/content/1.20/admin/how-to/aikars-flags.md deleted file mode 100644 index 1904e0afc..000000000 --- a/docs/versioned/paper/content/1.20/admin/how-to/aikars-flags.md +++ /dev/null @@ -1,176 +0,0 @@ ---- -slug: /aikars-flags -description: Aikar's flags are a set of JVM flags designed to improve the performance of your Paper server. ---- - -# Aikar's Flags - -## Recommended JVM startup flags - -:::warning[Script Generator] - -**This page only serves as an explanation page.** If you want to generate a start script, please visit -our **[Script Generator](/misc/tools/start-script-gen)**. - -::: - -```bash -java -Xms10G -Xmx10G -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:MaxGCPauseMillis=200 -XX:+UnlockExperimentalVMOptions -XX:+DisableExplicitGC -XX:+AlwaysPreTouch -XX:G1NewSizePercent=30 -XX:G1MaxNewSizePercent=40 -XX:G1HeapRegionSize=8M -XX:G1ReservePercent=20 -XX:G1HeapWastePercent=5 -XX:G1MixedGCCountTarget=4 -XX:InitiatingHeapOccupancyPercent=15 -XX:G1MixedGCLiveThresholdPercent=90 -XX:G1RSetUpdatingPauseTimePercent=5 -XX:SurvivorRatio=32 -XX:+PerfDisableSharedMem -XX:MaxTenuringThreshold=1 -Dusing.aikars.flags=https://mcflags.emc.gs -Daikars.new.flags=true -jar paper.jar --nogui -``` - -:::danger[Do not allocate all of your available memory on a shared host!] - -When setting the `Xms` and `Xmx` values, if your host says you have 8GB of memory, **do not use 8GB**! - -Minecraft (and Java) needs additional memory on top of that `Xmx` parameter. It is recommended to -**reduce your `Xmx` and `Xms` by about 1000-1500MB** to avoid running out of memory or `OOMKiller` killing -your server. This also leaves room for the operating system to use memory too. - -Do you have 8GB of memory? Use 6500MB for safety. -_But you may also ask your host if they will cover this overhead for you and -give you 9500M instead. Some hosts will! Just ask._ - -::: - -## Recommended memory - -**We recommend using at least 6-10GB**, no matter how few players! If you can't afford 10GB of -memory, give as much as you can, but ensure you leave the operating system some memory too. G1GC -operates better with more memory. - -However, more memory does not mean better performance above a certain point. Eventually you will hit -a point of diminishing returns. Going out and getting 32GB of RAM for a server will only waste your -money with minimal returns. - -## Java GC logging - -Are you having old gen issues with these flags? Add the following flags based on your Java version -to enable GC logging: - -**Java 8-10** - -```bash --Xloggc:gc.log -verbose:gc -XX:+PrintGCDetails -XX:+PrintGCDateStamps -XX:+PrintGCTimeStamps --XX:+UseGCLogFileRotation -XX:NumberOfGCLogFiles=5 -XX:GCLogFileSize=1M -``` - -**Java 11+** - -```bash --Xlog:gc*:logs/gc.log:time,uptime:filecount=5,filesize=1M -``` - -GC logging does not hurt your performance and can be left on at all times. The files will not take -up much space (5MB) - -## Technical explanation of the flags - -1. **-Xms matching -Xmx - why:** You should never run your server with the case that `Xmx` can run - the system completely out of memory. Your server should always be expected to use the entire - `Xmx`! You should then ensure the OS has extra memory on top of that `Xmx` for non-Minecraft/OS level - things. Therefore, you should never run Minecraft with `Xmx` settings you can't support if Java uses it - all. Now, that means **if `Xms` is lower than `Xmx` you have unused memory**! Unused memory is - wasted memory. G1 operates better with the more memory it's given. G1 adaptively chooses how - much memory to give to each region to optimize pause time. If you have more memory than it needs - to reach an optimal pause time, G1 will simply push that extra into the old generation, and it - will not hurt you. The fundamental idea of improving GC behavior is to ensure short-lived objects - die young and never get promoted. With the more memory G1 has, the better assurance you will get - that objects are not getting prematurely promoted to the old generation. G1 operates differently - than previous collectors and is able to handle larger heaps more efficiently. - - If it does not need the memory given to it, it will not use it. The entire engine operates - differently and does not suffer from too large of heaps, and this is industry-wide accepted - information that under G1 to keep Xms and Xmx the same! - -2. **UnlockExperimentalVMOptions:** needed for some the below options - -3. **G1NewSizePercent:** These are the important ones. You now can specify percentages of an - overall desired range for the new generation. With these settings, we tell G1 to not use its - default 5% for new gen, and instead give it 40%! **Minecraft has an extremely high memory - allocation rate**, ranging to at least 800MB/second on a 30 player server! And this is - mostly short-lived objects (Block Position). - - Now, this means Minecraft **really** needs more focus on new gen to be able to even support this - allocation rate. If your new gen is too small, you will be running new gen collections 1-2+ - times per second, which is awful. You will have so many pauses that TPS has risk of suffering, - and the server will not be able to keep up with the cost of GCs. Then combine the fact that - objects will now promote faster, resulting in your old gen growing faster. Given more new gen, - we are able to slow down the intervals of young gen collections, resulting in more time for - short-lived objects to die young and overall more efficient GC behavior. - -4. **G1MixedGCLiveThresholdPercent:** Controls when to include regions in mixed GCs in the young - GC collection, keeping old gen tidy without doing a normal old gen GC collection. When your - memory is less than this percent, old gen won't even be included in 'mixed' collections. Mixed - are not as heavy as a full old collection, so having small incremental cleanups of old keeps - memory usage light. - - Default is 65 to 85 depending on the Java version, we are setting that to 90 to ensure we reclaim garbage - in old gen as fast as possible to retain as much free regions as we can. - -5. **G1ReservePercent=20:** Minecraft memory allocation rate in up-to-date versions is really insane. We - run the risk of a dreaded "to-space exhaustion" not having enough memory free to move data - around. This ensures more memory is waiting to be used for this operation. Default is 10, so we - are giving another 10 to it. - -6. **MaxTenuringThreshold=1:** Minecraft has a really high allocation rate of memory. Of that - memory, most is reclaimed in the eden generation. However, transient data will overflow into - survivor. Initially played with completely removing survivor and had decent results, but does - result in transient data making its way to old which is not good. Max Tenuring 1 ensures that we - do not promote transient data to old generation, but anything that survives 2 passes of GC is - just going to be assumed as longer-lived. - - Doing this greatly reduces pause times in young collections as copying data up to 15 times in - survivor space for a tenured object really takes a lot of time for actually old memory. Ideally - the GC engine would track average age for objects instead and tenure out data faster, but that - is not how it works. - - Considering average GC rate is 10s to the upwards of minutes per young collection, this does not - result in any 'garbage' being promoted, and just delays longer lived memory to be collected in - mixed GCs. - -7. **SurvivorRatio=32:** Because we drastically reduced MaxTenuringThreshold, we will be reducing - use of survivor space drastically. This frees up more regions to be used by eden instead. - -8. **AlwaysPreTouch:** AlwaysPreTouch gets the memory setup and reserved at process start ensuring - it is contiguous, improving the efficiency of it more. This improves the operating systems - memory access speed. Mandatory to use Transparent Huge Pages - -9. **+DisableExplicitGC:** Many plugins think they know how to control memory, and try to invoke - garbage collection. Plugins that do this trigger a full garbage collection, triggering a massive - lag spike. This flag disables plugins from trying to do this, protecting you from their bad - code. - -10. **MaxGCPauseMillis=200:** This setting controls how much memory is used in between the minimum - and maximum ranges specified for your new generation. This is a "goal" for how long you want - your server to pause for collections. 200 is aiming for at most loss of 4 ticks. This will - result in a short TPS drop, however the server can make up for this drop instantly, meaning it - will have no meaningful impact on your TPS. 200ms is lower than players can recognize. In - testing, having this value constrained to an even lower number results in G1 not recollecting - memory fast enough and potentially running out of old gen triggering a full collection. Just - because this number is 200 does not mean every collection will be 200. It means it can use up to - 200 if it really needs it, and we need to let it do its job when there is memory to collect. - -11. **+ParallelRefProcEnabled:** Optimizes the GC process to use multiple threads for weak reference - checking. Not sure why this isn't default... - -12. **G1RSetUpdatingPauseTimePercent=5:** Default is 10% of time spent during pause updating RSets, - reduce this to 5% to make more of it concurrent to reduce pause durations. - -13. **G1MixedGCCountTarget=4:** Default is 8. Because we are aiming to collect slower, with less old - gen usage, try to reclaim old gen memory faster to avoid running out of old. - -14. **G1HeapRegionSize=8M+:** Default is auto calculated. Super important for Minecraft, especially - 1.15, as with low memory situations, the default calculation will in most times be too low. Any - memory allocation half of this size (4MB) will be treated as "Humongous" and promote straight to - old generation and is harder to free. If you allow Java to use the default, you will be - destroyed with a significant chunk of your memory getting treated as Humongous. - -15. **+PerfDisableSharedMem:** Causes GC to write to file system which can cause major latency if - disk IO is high - see https://www.evanjones.ca/jvm-mmap-pause.html - -### Transparent huge pages - -Controversial feature but may be usable if you can not configure your host for real HugeTLBFS. Try -adding `-XX:+UseTransparentHugePages` but it's extremely important you also have `AlwaysPreTouch` set. -Otherwise, THP will likely hurt you. We have not measured how THP works for Minecraft or its impact with -`AlwaysPreTouch`, so this section is for the advanced users who want to experiment. diff --git a/docs/versioned/paper/content/1.20/admin/how-to/anti-xray.mdx b/docs/versioned/paper/content/1.20/admin/how-to/anti-xray.mdx deleted file mode 100644 index ba3e34957..000000000 --- a/docs/versioned/paper/content/1.20/admin/how-to/anti-xray.mdx +++ /dev/null @@ -1,470 +0,0 @@ ---- -slug: /anti-xray -description: Paper ships an obfuscation-based Anti-Xray system by default. Learn how to configure it here. ---- - -# Configuring Anti-Xray - -> Originally written and maintained by [stonar96](https://github.com/stonar96). - -Paper includes an obfuscation-based Anti-Xray with three modes, configurable on a per world basis. - -:::info[Per World Configuration] - -If you aren't already familiar with per world configuration, please take a moment to familiarize -yourself with the [Configuration Guide](./reference/configuration). - -::: - -This guide is a step-by-step walk-through for configuring Anti-Xray. For reference documentation, -refer to the Anti-Xray section of the -[Per-World Configuration Reference](../reference/configuration/world-configuration.mdx#anticheat_anti_xray). - -Anti-Xray has three different modes. `engine-mode: 1` replaces specified blocks (`hidden-blocks`) with -other "fake" blocks, `stone` (`deepslate` at y < 0), `netherrack`, or `end_stone` based on the -dimension. In contrast, `engine-mode: 2` will replace both `hidden-blocks` and `replacement-blocks` -with randomly generated `hidden-blocks`. `engine-mode: 3` works similarly to `engine-mode: 2`, but instead of -randomizing every block, it randomizes the block for each layer of a chunk. - -The following images[^1] show how each mode will look for a player using Xray with the recommended -configuration in both the overworld and nether. - -[^1]: - Image design by `Oberfail`, initially posted in the - [PaperMC Discord](https://discord.gg/papermc). - -{/* - -Seed: -7943468717341609647 - -# Overworld: -/tp @p -581.976 67.85076 -4924.106 47 36 - -# Nether: -/tp @p 789.437 117.38012 -319.064 -137.4 28 -*/} - -![Overworld Anti-Xray Comparison](assets/anti-xray-overworld.png) -![Nether Anti-Xray Comparison](assets/anti-xray-nether.png) - -Especially on the client side, `engine-mode: 1` is much less computationally intensive, while -`engine-mode: 2` may better prevent Xray. With `engine-mode: 1`, only ores that are entirely covered -by solid blocks will be hidden. Ores exposed to air in caves or water from a lake will not be -hidden. With `engine-mode: 2`, fake ores obstruct the view of real blocks. If `air` is added to -`hidden-blocks`, `engine-mode: 2` will effectively hide all ores, even those exposed to air. `engine-mode: 3` can reduce network load when joining by a factor of ~2 and helps with chunk packet compression. - -:::caution[Anti-Xray Bypasses] - -**Range Extension**: While Anti-Xray alone will prevent the majority of users from Xraying on your -server, it is not by any means infallible. Because of how Anti-Xray is (and has to be) implemented, -it is possible to, on a default server, extend the range of real ores you can see by a not -insignificant amount. This can be mitigated by any competent anti-cheat plugin; however, this is not -included out of the box. - -**Seed Reversing**: Another attack vector is the deterministic nature of Minecraft's world -generation. If the client is able to obtain the world seed, it is able to know the real location of -every generated ore, completely bypassing Anti-Xray. This can be partially worked around by making -it harder for the client to reverse the world seed with the -[`feature-seeds` configuration](../reference/configuration/world-configuration.mdx#feature_seeds), in conjunction -with the structure seed options in `spigot.yml`. Note that this is not a complete solution, and it -may still be possible for a client to obtain the server's world seed. Using a different seed for -each world may also be beneficial. - -**Ores Exposed to Air**: In `engine-mode: 1`, `engine-mode: 2` and `engine-mode: 3`, it is possible for a client -to view ores that are exposed to air. This can be mitigated in `engine-mode: 2` and `engine-mode: 3` by adding `air` to -the `hidden-blocks` list. However, doing this may cause client performance issues (FPS drops) for -some players. - -::: - -## Recommended configuration - -The recommended configuration for `engine-mode: 1`, `engine-mode: 2` and `engine-mode: 3` is as follows: - -:::tip[Spacing] - -YAML cares about whitespace! The example configuration below is already formatted correctly. Ensure -formatting and indentation remains unchanged by using the "copy" button in the top right of each -example. Especially ensure that no tabulators are accidentally inserted. Check your editor's options -for using spaces instead of tabulators for indentation. If your configuration file already contains -other important changes, it is recommended to make a backup before editing it. - -::: - -### `engine-mode: 1` - -
- Default World Configuration - -Replace the existing `anticheat.anti-xray` block in `paper-world-defaults.yml` with the following: - -```yaml title="paper-world-defaults.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 1 - hidden-blocks: - # There's no chance to hide dungeon chests as they are entirely surrounded by air, but buried treasures will be hidden. - - chest - - coal_ore - - deepslate_coal_ore - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - emerald_ore - - deepslate_emerald_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - lava-obscures: false - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - # The replacement-blocks list is not used in engine-mode: 1. Changing this will have no effect. - replacement-blocks: [] - update-radius: 2 - use-permission: false -``` - -
- -
- Nether Configuration - -Copy and paste into your `paper-world.yml` within your nether world folder. See the -[Configuration Guide](./reference/configuration) for more information. - -```yml title="world_nether/paper-world.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 1 - hidden-blocks: - - ancient_debris - - nether_gold_ore - - nether_quartz_ore - lava-obscures: false - max-block-height: 128 - # The replacement-blocks list is not used in engine-mode: 1. Changing this will have no effect. - replacement-blocks: [] - update-radius: 2 - use-permission: false -``` - -
- -
- End Configuration - -Copy and paste into your `paper-world.yml` within your end world folder. See the -[Configuration Guide](./reference/configuration) for more information. - -```yml title="world_the_end/paper-world.yml" -anticheat: - anti-xray: - enabled: false -``` - -
- -### `engine-mode: 2` - -
- Default World Configuration - -Replace the existing `anticheat.anti-xray` block in `paper-world-defaults.yml` with the following: - -```yaml title="paper-world-defaults.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 2 - hidden-blocks: - # You can add air here such that many holes are generated. - # This works well against cave finders but may cause client FPS drops for all players. - - air - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - lava-obscures: false - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - replacement-blocks: - # Chest is a tile entity and can't be added to hidden-blocks in engine-mode: 2. - # But adding chest here will hide buried treasures, if max-block-height is increased. - - chest - - amethyst_block - - andesite - - budding_amethyst - - calcite - - coal_ore - - deepslate_coal_ore - - deepslate - - diorite - - dirt - - emerald_ore - - deepslate_emerald_ore - - granite - - gravel - - oak_planks - - smooth_basalt - - stone - - tuff - update-radius: 2 - use-permission: false -``` - -
- -
- Nether Configuration - -Copy and paste into your `paper-world.yml` within your nether world folder. See the -[Configuration Guide](./reference/configuration) for more information. - -```yml title="world_nether/paper-world.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 2 - hidden-blocks: - # See note about air and possible client performance issues above. - - air - - ancient_debris - - bone_block - - glowstone - - magma_block - - nether_bricks - - nether_gold_ore - - nether_quartz_ore - - polished_blackstone_bricks - lava-obscures: false - max-block-height: 128 - replacement-blocks: - - basalt - - blackstone - - gravel - - netherrack - - soul_sand - - soul_soil - update-radius: 2 - use-permission: false - -``` - -
- -
- End Configuration - -Copy and paste into your `paper-world.yml` within your end world folder. See the -[Configuration Guide](./reference/configuration) for more information. - -```yml title="world_the_end/paper-world.yml" -anticheat: - anti-xray: - enabled: false -``` -
- - -### `engine-mode: 3` - -
- Default World Configuration - -Replace the existing `anticheat.anti-xray` block in `paper-world-defaults.yml` with the following: - -```yaml title="paper-world-defaults.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 3 - hidden-blocks: - # You can add air here such that many holes are generated. - # This works well against cave finders but may cause client FPS drops for all players. - - air - - copper_ore - - deepslate_copper_ore - - raw_copper_block - - diamond_ore - - deepslate_diamond_ore - - gold_ore - - deepslate_gold_ore - - iron_ore - - deepslate_iron_ore - - raw_iron_block - - lapis_ore - - deepslate_lapis_ore - - redstone_ore - - deepslate_redstone_ore - lava-obscures: false - # As of 1.18 some ores are generated much higher. - # Please adjust the max-block-height setting at your own discretion. - # https://minecraft.wiki/w/Ore might be helpful. - max-block-height: 64 - replacement-blocks: - # Chest is a tile entity and can't be added to hidden-blocks in engine-mode: 2. - # But adding chest here will hide buried treasures, if max-block-height is increased. - - chest - - amethyst_block - - andesite - - budding_amethyst - - calcite - - coal_ore - - deepslate_coal_ore - - deepslate - - diorite - - dirt - - emerald_ore - - deepslate_emerald_ore - - granite - - gravel - - oak_planks - - smooth_basalt - - stone - - tuff - update-radius: 2 - use-permission: false -``` - -
- -
- Nether Configuration - -Copy and paste into your `paper-world.yml` within your nether world folder. See the -[Configuration Guide](./reference/configuration) for more information. - -```yml title="world_nether/paper-world.yml" -anticheat: - anti-xray: - enabled: true - engine-mode: 3 - hidden-blocks: - # See note about air and possible client performance issues above. - - air - - ancient_debris - - bone_block - - glowstone - - magma_block - - nether_bricks - - nether_gold_ore - - nether_quartz_ore - - polished_blackstone_bricks - lava-obscures: false - max-block-height: 128 - replacement-blocks: - - basalt - - blackstone - - gravel - - netherrack - - soul_sand - - soul_soil - update-radius: 2 - use-permission: false -``` - -
- -
- End Configuration - -Copy and paste into your `paper-world.yml` within your end world folder. See the -[Configuration Guide](./reference/configuration) for more information. - -```yml title="world_the_end/paper-world.yml" -anticheat: - anti-xray: - enabled: false -``` - -
- -## FAQ, common pitfalls and support - -
- I can still see (some) ores / use X-ray - -As described above, there are several reasons why you might still see (some) ores even though you -have enabled Anti-Xray: - -* The ores are above the configured `max-block-height` value. -* Anti-Xray cannot hide ores exposed to air or other transparent blocks (in caves for example). In - principle this is also the case for `engine-mode: 2` and `engine-mode: 3`, however, usually the fake ores obstruct the - view of real blocks. Hiding those exposed ores too requires additional plugins. -* The `use-permission` option is enabled and you have the Anti-Xray bypass permission or you have - operator status. -* The block type is missing in the configured block lists. This can be the result of using an - outdated configuration file. - -
- -
- I have added fake blocks but X-ray doesn't show them - -If you use `engine-mode: 2` or `engine-mode: 3` and you have added fake blocks to the `hidden-blocks` list but you can't -see them in-game using X-ray, this can have the following reasons: - -* The added block types are tile entities. Anti-Xray can hide (replace) tile entities (such as - chests), provided that they are not exposed to air or other transparent blocks. However, Anti-Xray - can't place tile entities as fake blocks into the chunk. -* The block is disabled in your client's X-ray mod or not shown by your X-ray resource pack. - -
- -
- It doesn't work below y = 0 or in certain other places. - -* Your configuration file is probably outdated and missing important blocks in the - `replacement-blocks` list, such as `deepslate` or biome-specific blocks, such as `basalt`. You - might also want to check if the `hidden-blocks` list includes all important ores and their - `deepslate` variants. -* If it doesn't work above a certain y-level, check your `max-block-height` setting. - -
- -
- It still doesn't work, further troubleshooting - -* Make sure to always restart your server after making changes to the Anti-Xray configuration. - Changes won't be applied automatically. -* Do not use the `/reload` command. To apply Anti-Xray configuration changes a restart is required. -* After restarting the server, verify that the configuration is applied correctly by inspecting the - config sections with timings or spark. - -
- -
- How and where do I ask for support if it still doesn't work? - -If the above bullet points don't solve your problem or if you have further questions about -Anti-Xray, please don't hesitate to ask us on the [PaperMC Discord](https://discord.gg/papermc) -using the #paper-help channel. Please try to provide as much detail as possible about your problem. -"It doesn't work" isn't very helpful when asking for support. Describe what you want to achieve, -what you have tried, what you expect and what you observe. Ideally include a timings or spark link -and a picture what you observe in-game. - -
diff --git a/docs/versioned/paper/content/1.20/admin/how-to/assets/anti-xray-nether.png b/docs/versioned/paper/content/1.20/admin/how-to/assets/anti-xray-nether.png deleted file mode 100644 index 67beedf1d..000000000 Binary files a/docs/versioned/paper/content/1.20/admin/how-to/assets/anti-xray-nether.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/admin/how-to/assets/anti-xray-overworld.png b/docs/versioned/paper/content/1.20/admin/how-to/assets/anti-xray-overworld.png deleted file mode 100644 index f6eab58ef..000000000 Binary files a/docs/versioned/paper/content/1.20/admin/how-to/assets/anti-xray-overworld.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/admin/how-to/basic-troubleshooting.md b/docs/versioned/paper/content/1.20/admin/how-to/basic-troubleshooting.md deleted file mode 100644 index a8b83950c..000000000 --- a/docs/versioned/paper/content/1.20/admin/how-to/basic-troubleshooting.md +++ /dev/null @@ -1,144 +0,0 @@ ---- -slug: /basic-troubleshooting -description: This guide will help you diagnose your server's problem before reporting it to PaperMC or the plugin's author. ---- - -# Basic Troubleshooting - -This guide will help you diagnose your server's problem before reporting it to PaperMC or the plugin's author. - -:::caution[Stop Your Server And Take A Backup] - -Before following this guide, stop your server first. Modifying server files while it is still running will corrupt them. -Only a full server shutdown can prevent this. - -Also, if you don't follow this guide carefully or make a mistake while following this guide, you might corrupt your server. It is highly advised to back up your server before following this guide. -It would be ideal to create a test server by copying your production server's file, but that's not always possible. - -::: - -## Read the error message - -If your server encounters a problem, it will either print an error message on the server console, create a crash report and close itself, or do both. - -If your server crashes, the crash report will be saved in the `crash-report` directory. -If your server didn't crash, those error messages will be stored in the `log` directory along with other messages. - -Note that the logs older than the latest will be compressed and not stored as plain text files. - -The first thing you have to do is diagnose those messages. - -### Case 01: Paper watchdog thread dump - -If your error message looks like this, **do not blindly report it to PaperMC** as it says: - -``` -[00:00:00] [Paper Watchdog Thread/ERROR]: --- DO NOT REPORT THIS TO PAPER - THIS IS NOT A BUG OR A CRASH - git-Paper-366 (MC: 1.19.3) --- -[00:00:00] [Paper Watchdog Thread/ERROR]: The server has not responded for 10 seconds! Creating thread dump -[00:00:00] [Paper Watchdog Thread/ERROR]: ------------------------------ -``` - -This can be caused by various things. Maybe your server's hardware is not capable of running Minecraft server. Maybe one of the plugins you use is causing lag on your server. - -The thread dump from Paper Watchdog can be found below that line. If you find any plugin's name in there, talk to the plugin's author about that, not PaperMC. - -### Case 02: Stack trace - -Almost every problem you encounter will print error message lines, which are called "stack trace", on the server console. Examining the stack trace will help you find out what is causing problems on your server. - -The stack trace starts with the error message, exception type, and exception message. - -Both error messages and exception messages were put there by the developer of either your plugin or Paper. These messages tell you what problem your server experienced. -An exception type like `java.lang.RuntimeException` tells you the type of the exception. This will help the developer (and you) understand the type of problem. - -Many lines beginning with `at` may appear beneath the exception message. These are the body of the stack trace. These lines tell you where the problem starts. The top line of the body of the stack trace will tell you exactly where the problem occurred and, if possible, display where it came from. - -If you find any plugin's name in the stack trace, head to [Check Plugin Updates](#check-plugin-updates) and read from there. In most cases, the plugin, whose name is found on the stack trace, is causing the problem. If not, continue reading. - -Here are some examples of stack traces. - -
- Example 01: Server attempted to load chunk saved with newer version of minecraft! - -``` -[00:00:00 WARN]: java.lang.RuntimeException: Server attempted to load chunk saved with newer version of minecraft! 3218 > 3120 -``` - -You tried to load the world generated with a higher version of Minecraft. You cannot do this. -If you don't have any backup of your world before the chunk version update, you must use your updated world with a higher version of Minecraft. - -
- -## Finding the culprit - -If you can't find the name of any plugin in the thread dump or stack trace, try these steps. - -### Disable all plugins - -To determine if it is a plugin or Paper itself that is causing problems, disable all of your plugins first. - -You can disable all of your plugins by renaming the `plugins` directory to something else, such as `plugins-disabled`, or by archiving the `plugins` directory and deleting it. - -After that, try to run your server. - -If the problem is resolved after removing the plugins, you know that it was a plugin that caused the issue. -If you still experience problems, head to [Paper Documentation](#paper-documentation). Maybe your server is misconfigured, and that is creating issues. - -### Binary search - -To efficiently search for the plugin that is causing the issue, you can do the following: - -1. **Split your plugins into two groups** - The size of the two groups can be different, but it is ideal if the difference is minimal. Make sure that plugins that depend on each other are grouped together. -2. **Disable one of the two groups of plugins** - You can disable them by changing their extension from `.jar` to something else, such as `.jar-disabled`, or move them outside the `plugins` directory and into a temporary directory. -3. **Run your server and check if the problem still exists** - If the problem is resolved, the plugin that caused the issue is one of the disabled plugins. - If the problem is not resolved, the plugin that is causing the issue is one of the active plugins. -4. **Repeat from the start with the suspect plugin group** - Repeat the steps above with groups that have the plugin that is causing the issue. - -:::danger - -Some plugins that you install are not a typical plugin, but a library. These are installed like plugins, -however tend to offer few user-facing features and are relied upon by other plugins for their -functionality. If you disable a library, plugins that depend on it will not work properly. Common -examples of these libraries are ProtocolLib, Vault providers, permission plugins, etc. - -::: - -## Check plugin updates - -There is a chance that your problem is already fixed in the latest release or latest build of the plugin. - -Head to your plugin's official download page and check if you are using the latest build or the latest release of the plugin. If not, update it to the latest version and try to run your server again to see if the problem is resolved. - -### Update library plugins - -Many plugins use library plugins like ProtocolLib, and you have to download them and put them in `plugins` directory. - -If you don't update them to the latest version or latest build, you might experience problems related to plugins that use the library plugin. - -Some library plugins tell their users to use their latest development build for support of the latest Minecraft version. You should look carefully at the requirements of your plugin. - -## Check documentation - -If you misconfigured your plugin or your server, it can also cause problems on your server. - -### Plugin documentation - -Many plugins provide their own documentation about how to set them up properly. Read those documents carefully and check if there is something wrong with the plugin's configuration. - -### Paper documentation - -Paper can also be configured in a variety of ways. Check these documents for detailed explanations about each configuration. - -* [Paper Global Config](../reference/configuration/global-configuration.mdx) -* [Paper Per World Configuration](../reference/configuration/world-configuration.mdx) - -## Consult with a developer - -If your problem is related to a plugin you use, and you still don't know how to solve it, you can try to reach out to the plugin's author. -Many plugins have a way to contact their author, like a GitHub issue tracker, Discord support guild, Gitter, IRC, etc. - -If your problem isn't related to any plugin, you can come to PaperMC's Discord server and ask for help, or create a new issue on our GitHub issue tracker. diff --git a/docs/versioned/paper/content/1.20/admin/how-to/update.md b/docs/versioned/paper/content/1.20/admin/how-to/update.md deleted file mode 100644 index a6a77157b..000000000 --- a/docs/versioned/paper/content/1.20/admin/how-to/update.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -slug: /updating -description: Paper has new features and fixes coming every day, this guide explains the updating process. ---- - -# Updating Paper - -Updating Paper is an important part of running every server. With new features and fixes coming -every day, we recommend updating at least once per week to keep your server patched for the latest -bugs. Installing updates is very simple, but it's important to know how to do it correctly. - -:::caution[Don't replace any JAR in a running server] - -Unless you know exactly what and why you're doing what you're doing, it's never a good idea to -replace any JAR in a running server, be that plugins, or Paper itself. - -::: - -## Step 1. Backup - -:::tip - -If you are using a shared host, your host may provide a built-in way to back up. Consult their -documentation before continuing. - -::: - -This is the most important step, and yet the most frequently skipped. While it is unlikely that -updating Paper itself will cause any issues requiring you to restore from a backup, plugin -malfunctions or other accidents might! Updating is a great time to work in a backup. Having -functioning backups is essential to every server, big or small. The main things to back up are: - -- The world folders -- Server Configuration Files -- Plugin Configuration Files & Plugin JARs - -You should aim to have backups from multiple times, and keep them in a safe place. A common approach -is to keep rolling backups, so you always have a certain number of backups from a set amount of time. - -## Step 2. Update plugins - -Just like it's important to update Paper, it's equally important to keep plugins up to date. You -never know what plugin authors may be working on, be it bugfixes or new features. - -A little known feature of Paper servers is the `update` folder. Here's how you use it. - -1. Create a folder called `update` within the `plugins` folder. -2. One by one, download plugins you would like to update and put them in the `update` folder. -3. Restart your server, do not remove or modify any plugins outside the `update` folder. - -By doing this, you are able to update all of your plugins at the same time without having the server -off, or replacing plugin JARs while the server is running. You do not need to restart your server -before updating Paper itself. This feature allows you to update both Paper and plugins all at the -same time, without needing any additional downtime. - -## Step 3. Update Paper - -:::tip - -If you are using a shared host, your host may provide a built-in way to update! Consult their -documentation before continuing. - -::: - -Updating Paper itself is very simple. - -1. Download a new JAR from [our downloads page](https://papermc.io/downloads). -2. Stop your server. It is not recommended and may cause issues to replace your Paper JAR while the server is running. -3. Rename the downloaded file to match the name specified in the [start command](../getting-started/getting-started.mdx#running-the-server). -4. Replace your old Paper JAR file with the new renamed one. -5. Start your server. Watch the startup log to ensure everything goes to plan. If there are any - plugin conflicts or issues, you will see them here. - -To minimize downtime caused by updates, some server owners will, rather than replacing their server -JAR, upload a new one and set their start script to use the new one on the next restart. Both of -these are valid update strategies. - -:::caution[Automatic Updates] - -While it may be convenient to install updates automatically (and Paper's [downloads API](/misc/downloads-api) allows you -to with ease), doing so is not recommended by Paper due to the possibility of plugin conflicts or -other issues that you may not know about. Always be present during updates, and keep a careful watch -on your server's log after the fact. - -If you do choose to automatically install updates, ensure you have a functioning backup strategy in -place! - -::: diff --git a/docs/versioned/paper/content/1.20/admin/misc/faq.md b/docs/versioned/paper/content/1.20/admin/misc/faq.md deleted file mode 100644 index edafad1c2..000000000 --- a/docs/versioned/paper/content/1.20/admin/misc/faq.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -slug: /faq -description: Questions frequently asked by our community, answered by us! ---- - -# Frequently Asked Questions - -## Unsupported Java detected, what do I do?! - -Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken. -As such, we cannot provide support for servers running such versions. -You should install a supported version of Java as explained [here](/misc/java-install). - -If you still wish to continue, knowing that you are on your own and will receive NO support, you can disable the check with a system property, as explained [here](/paper/reference/system-properties#paperignorejavaversion). diff --git a/docs/versioned/paper/content/1.20/admin/misc/paper-bug-fixes.md b/docs/versioned/paper/content/1.20/admin/misc/paper-bug-fixes.md deleted file mode 100644 index 38b28b827..000000000 --- a/docs/versioned/paper/content/1.20/admin/misc/paper-bug-fixes.md +++ /dev/null @@ -1,69 +0,0 @@ ---- -slug: /misc/paper-bug-fixes -description: An explanation of which Vanilla bugs we fix in Paper. ---- - -# Paper Bug Fixes - -Paper fixes many gameplay and technical issues within Minecraft. The most prevalent fixes are to TNT duplication and bedrock breaking. - -## Vanilla bug fixes - -Paper fixes many Vanilla bugs that were not intended by Mojang. These bugs are patched to fix behavior or prevent abuse and -instability on the server. Some of our fixes are configurable, as we understand that some servers may want to keep the -Vanilla behavior. You will find these configuration options in the [global configuration](/docs/paper/admin/reference/configuration/global-configuration.mdx) -and the [world configuration](/docs/paper/admin/reference/configuration/world-configuration.mdx). - -### What is intended behavior vs a bug? - -When an issue is reported to us, we check Mojang's issue tracker. If the problem has been reported there, then we -check to see if it: - -1) Has been confirmed as a bug -2) Has an assigned priority to it - -If it meets these two criteria then we will accept changes to fix the bug, as it can take a long time for Mojang to fix -them (sometimes years). If an issue gets declined by Mojang, we normally do not "fix" it as it is intended behavior. - -## Duplication bugs - -Because TNT duping is considered a form of automated mining and not a resource dupe, we have provided an option to -restore it. This, undesirably, also re-enables carpet and rail duping, which normally we would not provide a config for, -but it's the same bug for those, so we have no choice. However, the config option is as follows: - -```yaml -unsupported-settings: - allow-piston-duplication: true -``` - -We also allow you to restore the ability to duplicate gravity blocks, such as sand, using end portals. This is not -recommended, as it can cause issues with the server, but we do provide a config option to restore this functionality: -```yaml -unsupported-settings: - allow-unsafe-end-portal-teleportation: true -``` - -Similarly, we also allow you to enable string-based duplication bugs with the following config option: -```yaml -unsupported-settings: - allow-tripwire-disarming-exploits: true -``` -This is a [long term bug](https://bugs.mojang.com/browse/MC-129055) that has not yet been fixed by Mojang. We have -fixed it in Paper, but we provide a config option to restore Vanilla behavior. - -## Block breaking - -We also fix the ability to break Bedrock and End Portal frames. We do also provide a config option to restore this -functionality, but it is not recommended: -```yaml -unsupported-settings: - allow-permanent-block-break-exploits: true -``` - -## Afterword - -We will not support you if you have issues whilst these settings are enabled, as they can cause unintended side effects. -These settings are also not guaranteed to be supported in the future and may have their behavior changed, or removed, at any time. - -For legacy reasoning behind not having configuration options for many duplication bugs, see: -[#3724](https://github.com/PaperMC/Paper/issues/3724) diff --git a/docs/versioned/paper/content/1.20/admin/reference/assets/plugin-list.png b/docs/versioned/paper/content/1.20/admin/reference/assets/plugin-list.png deleted file mode 100644 index 4843252c3..000000000 Binary files a/docs/versioned/paper/content/1.20/admin/reference/assets/plugin-list.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/README.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/README.mdx deleted file mode 100644 index 8e363aa5e..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/README.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -slug: /reference/configuration ---- - -# Paper Configuration - -import ConfigurationStructureDiagram from "@site/src/components/config/ConfigurationStructureDiagram"; - ---- - -## Paper configuration files - -:::info - -Many of our files have been comprehensively documented. If this is the case, they will offer a link to their page. -If this is not the case, they offer a brief explanation to what they are. - -::: - - - -## Per-world configuration - -One of the most powerful yet least understood features of the Paper configuration is setting -configuration options per world. While you can not override every config option per world, -everything stored within `paper-world-defaults.yml` can be. - -### Default values - -Paper sets no per-world overrides out of the box, storing all default values in -`config/paper-world-defaults.yml`. Everything in this file can be overridden per world but isn't by -default. Changing something in `paper-world-defaults.yml` will change the value for all worlds where -you have not manually overridden it. - -### Per-world values - -To set a value for a specific world, edit `paper-world.yml` within the world folder. For example, if -you wanted to disable `spawn.keep-spawn-loaded` for a world named `resource`, you would edit -`paper-world.yml` within the `resource` folder like so: - -```yaml title=resource/paper-world.yml -_version: 28 - -# highlight-start -spawn: - keep-spawn-loaded: false -# highlight-end -``` - -Nothing but `_version` is set in `paper-world.yml` configuration files by default. In order to -override the default for an option, you must manually add it by copying from -`paper-world-defaults.yml`. - -### Inheritance - -All configuration not explicitly defined for a world is inherited from `paper-world-defaults.yml`. -This means that there is no need to repeat yourself between the `paper-world-defaults.yml` and each -individual `paper-world.yml`. You **do not need to and should not** copy the entire -`paper-world-default.yml` file into each `paper-world.yml` file you want to modify. Only copy the -exact value you want to change. - -For a more complex real-world example: setting both different `spawn-limits` and `keep-spawn-loaded` -in two worlds. - -```yaml title="paper-world-defaults.yml" -entities: - spawning: - spawn-limits: - ambient: 70 - axolotls: 10 - creature: 15 - monster: 5 - underground_water_creature: 5 - water_ambient: 5 - water_creature: 20 -spawn: - keep-spawn-loaded: true -``` - -```yaml title="world_nether/paper-world.yml" -entities: - spawning: - spawn-limits: - monster: 90 -``` - -```yaml title="resource_world/paper-world.yml" -entities: - spawning: - spawn-limits: - axolotls: 8 - creature: 15 - monster: 2 -spawn: - keep-spawn-loaded: false -``` - -This example demonstrates the concept of inheritance. For each world, this is the effective -configuration which will be applied: - -| Configuration Key | world | world_nether | world_the_end | resource_world | -|-------------------------------------------------------------|--------|--------------|---------------|----------------| -| `entities.spawning.spawn-limits.ambient` | `15` | `15` | `15` | `15` | -| `entities.spawning.spawn-limits.axolotls` | `5` | `5` | `5` | `8` | -| `entities.spawning.spawn-limits.creature` | `10` | `10` | `10` | `15` | -| `entities.spawning.spawn-limits.monster` | `70` | `90` | `70` | `2` | -| `entities.spawning.spawn-limits.underground_water_creature` | `5` | `5` | `5` | `5` | -| `entities.spawning.spawn-limits.water_ambient` | `20` | `20` | `20` | `20` | -| `entities.spawning.spawn-limits.water_creature` | `5` | `5` | `5` | `5` | -| `spawn.keep-spawn-loaded` | `true` | `true` | `true` | `false` | - -Notice that `world_the_end/paper-world.yml` was never modified. Because of this, it inherits all the -configuration options from `config/paper-world-defaults.yml`. Additionally, `keep-spawn-loaded` was -only disabled in `resource_world/paper-world.yml` because in `config/paper-world-defaults.yml`, -`keep-spawn-loaded` is set to `true`. diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/bukkit-commands-configuration.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/bukkit-commands-configuration.mdx deleted file mode 100644 index 450dc73c7..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/bukkit-commands-configuration.mdx +++ /dev/null @@ -1,27 +0,0 @@ ---- -slug: /reference/bukkit-commands-configuration ---- - -# Bukkit Commands Configuration - -import React from 'react'; -import ConfigDocBlock from '@site/src/components/config/ConfigDocBlock'; -import BukkitCommandsSpec from '!!raw-loader!@site/config-specs/paper/commands.yml'; - -:::info - -The below YAML shows you the structure and default values for the legacy `commands.yml`. - -Click on a leaf node to view the description for that setting. - -::: - -:::warning - -The aliases defined in this legacy file do not support modern features, such as: -- Tab completion -- Permissions - -::: - - diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/bukkit-configuration.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/bukkit-configuration.mdx deleted file mode 100644 index 1116f171c..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/bukkit-configuration.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: /reference/bukkit-configuration -description: An explanation of Bukkit's configuration file. ---- - -# Bukkit Configuration - -import React from 'react'; -import ConfigDocBlock from '@site/src/components/config/ConfigDocBlock'; -import BukkitConfigSpec from '!!raw-loader!@site/config-specs/paper/bukkit.yml'; - -:::info - -The below YAML shows you the structure and default values for `bukkit.yml`. - -Click on a leaf node to view the description for that setting. - -::: - - diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/global-configuration.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/global-configuration.mdx deleted file mode 100644 index 60ae08b4d..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/global-configuration.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: /reference/global-configuration -description: An explanation of Paper's global configuration file. ---- - -# Global Configuration - -import React from 'react'; -import ConfigDocBlock from '@site/src/components/config/ConfigDocBlock'; -import GlobalConfigSpec from '!!raw-loader!@site/config-specs/paper/paper-global.yml'; - -:::info - -The below YAML shows you the structure and default values for the global configuration (`config/paper-global.yml`). - -Click on a leaf node to view the description for that setting. - -::: - - diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/server-properties.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/server-properties.mdx deleted file mode 100644 index 82382e4c4..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/server-properties.mdx +++ /dev/null @@ -1,21 +0,0 @@ ---- -slug: /reference/server-properties -description: An explanation of Minecraft's server.properties file. ---- - -# Server Properties - -import React from 'react'; -import ConfigDocBlock from '@site/src/components/config/ConfigDocBlock'; -import ServerPropertiesSpec from '!!raw-loader!@site/config-specs/paper/server-properties.yml'; - -:::info - -The below page shows the settings and default values for the `server.properties` file. - -Click on a property to learn more about it. - -::: - - - diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/spigot-configuration.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/spigot-configuration.mdx deleted file mode 100644 index 54c59c621..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/spigot-configuration.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -slug: /reference/spigot-configuration -description: An explanation of Spigot's configuration file. ---- - -# Spigot Configuration - -import React from 'react'; -import ConfigDocBlock from '@site/src/components/config/ConfigDocBlock'; -import SpigotConfigSpec from '!!raw-loader!@site/config-specs/paper/spigot.yml'; - -:::info - -The below YAML shows you the structure and default values for `spigot.yml` - -Click on a leaf node to view the description for that setting. - -::: - -:::note - -To override a per-world option, create a new key under `world-settings` with the level-name (name of the folder). - -::: - - diff --git a/docs/versioned/paper/content/1.20/admin/reference/configuration/world-configuration.mdx b/docs/versioned/paper/content/1.20/admin/reference/configuration/world-configuration.mdx deleted file mode 100644 index 750fe4096..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/configuration/world-configuration.mdx +++ /dev/null @@ -1,20 +0,0 @@ ---- -slug: /reference/world-configuration -description: An explanation of Paper's world configuration file. ---- - -# World Configuration - -import React from 'react'; -import ConfigDocBlock from '@site/src/components/config/ConfigDocBlock'; -import WorldConfigSpec from '!!raw-loader!@site/config-specs/paper/paper-world-defaults.yml'; - -:::info - -The below YAML shows you the structure and default values for the world configuration (`config/paper-world-defaults.yml` and `/paper-world.yml`). - -Click on a leaf node to view the description for that setting. - -::: - - diff --git a/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md b/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md deleted file mode 100644 index 52d527c09..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -slug: /reference/paper-plugins -description: A guide to the ins and outs of Paper plugins. ---- - -# Paper Plugins - -This documentation page serves to explain all the new semantics and possible confusions that Paper plugins may introduce. - -:::info - -Developers can get more information on Paper plugins [here](docs/paper/dev/getting-started/paper-plugins.mdx). - -::: - -## What are they? - -Paper plugins are plugins which are loaded by Paper's new plugin loading framework. Paper plugins are used by developers to -take advantage of modern systems Mojang provides, for example, datapacks. - -![Plugin List](assets/plugin-list.png) - -## What is the difference? - -When enabled, Paper plugins are **identical** to Bukkit plugins. This allows plugins to still fully communicate and support each other, meaning that even if a -plugin is a Bukkit or Paper plugin, they are both able to depend on each other just fine. - -Paper plugins only support being loaded by Paper's Plugin Loader and may use new API unavailable to Bukkit plugins. - -### How do I add Paper plugins? - -Paper plugins are added the same as Bukkit plugins, therefore, you can follow [this guide](docs/paper/admin/getting-started/adding-plugins.md). - -### Cyclic plugin loading - -With the introduction of Paper plugins, Paper introduces a new plugin loader that fixes some odd issues. -However, as a result, this now causes [cyclic loading](docs/paper/dev/getting-started/paper-plugins.mdx#cyclic-plugin-loading) between plugins to no longer be supported. - -If Paper detects a loop, your server will be shut down with an error. - -:::danger[Legacy] - -If your server **requires** this circular loading, you can enable this by adding the [`-Dpaper.useLegacyPluginLoading=true`](system-properties.md#paperuselegacypluginloading) startup flag. -Please note that this may not be supported in the future. - -::: diff --git a/docs/versioned/paper/content/1.20/admin/reference/system-properties.md b/docs/versioned/paper/content/1.20/admin/reference/system-properties.md deleted file mode 100644 index e479fa97b..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/system-properties.md +++ /dev/null @@ -1,217 +0,0 @@ ---- -slug: /reference/system-properties -description: Documentation for the system properties Paper may check. ---- - -# Paper System Properties - -These system properties can be set when you start your server allowing for the configuration of various settings. - -:::danger[Danger Ahead] - -Setting flags for the JVM can alter how it operates and the same goes for the Paper server. -If you are unsure about what a flag does, it is recommended that you **do not use it**. - -::: - -## How they work - -System properties are set when you start your server. For example, if you are using a `.bat` or a `.sh` file to start your server, you can add the system properties to the file. For example: - -```bash -java -Dpaper.log-level=FINE -jar paper.jar -``` - -:::info - -Some of Paper's system properties contain a `.` character in their name. When using PowerShell, these will require wrapping in quotes. -i.e. `"-Dpaper.log-level=FINE"` - -::: - -Where a `-D` is used to set a system property, and the system property is `paper.log-level` with a value of `FINE`. Otherwise, just add them to the start command - -:::note - -Where a system property is stated as `unset`, setting it as `true` will work to enable it. - -::: - -## List of system properties - -#### paper.playerconnection.keepalive: - -- **default**: `30` -- **description**: Controls how long the player connection will wait before closing when not receiving any keepalives, in seconds. - -#### timings.bypassMax: - -- **default**: `unset` -- **description**: Allows for bypassing the max amount of data to send to the Aikar's Timings API. Setting this will not permit bypassing the limit unless the API is configured to allow it. - -#### LetMeReload: - -- **default**: `unset` -- **description**: This disables the reload confirmation message when using the `/reload` command. - -#### paper.disableChannelLimit: - -- **default**: `unset` -- **description**: Disables the plugin channel limit for the server. This will disable the limit of 128 plugin channels per player. - -#### net.kyori.adventure.text.warnWhenLegacyFormattingDetected: - -- **default**: `false` -- **description**: Enables or disables the warning when legacy formatting is detected in a chat component. - -#### Paper.DisableClassPrioritization: - -- **default**: `unset` -- **description**: Disables the class prioritization system - mostly an issue when failing to relocate or shade properly. - -#### Paper.disableFlushConsolidate: - -- **default**: `unset` -- **description**: Disables the netty flush consolidation system. - -#### Paper.debugDynamicMissingKeys: - -- **default**: `unset` -- **description**: Enables debug logging for missing keys in NBT objects. - -#### disable.watchdog: - -- **default**: `unset` -- **description**: Disables the watchdog warning system. - -#### paper.explicit-flush: - -- **default**: `unset` -- **description**: Enables explicit flushing of the network channel. - -#### Paper.enable-sync-chunk-writes: - -- **default**: `unset` -- **description**: Syncs writes on each write call. This has a performance impact, particularly on hard drives. - -#### paper.debug-sync-loads: - -- **default**: `unset` -- **description**: Enables debug logging for sync chunk loads. - -#### Paper.ignoreWorldDataVersion: - -- **default**: `unset` -- **description**: Ignores the world data version when loading a world. This is not recommended and will likely cause issues. - -#### debug.entities: - -- **default**: `unset` -- **description**: Enables debug log messages for entity information. - -#### Paper.bypassHostCheck: - -- **default**: `unset` -- **description**: Bypasses the host pattern matching attempt for the client when connecting to the server. - -#### paper.ticklist-warn-on-excessive-delay: - -- **default**: `unset` -- **description**: Enables the warning when a tick list is scheduled with an excessive delay. - -#### debug.rewriteForIde: - -- **default**: `unset` -- **description**: Removes the NMS revision from the stack trace to allow for easier debugging in IDEs. -It also remaps plugin CB calls to remove the version information. - -#### convertLegacySigns: - -- **default**: `unset` -- **description**: Converts legacy signs to the new format. - -#### paper.maxCustomChannelName: - -- **default**: `64` -- **description**: Sets the largest size that a plugin channel name can take. - -#### Paper.maxSignLength: - -- **default**: `80` -- **description**: Sets the maximum line length for signs. - -#### Paper.FilterThreshhold: - -- **default**: `8192` -- **min**: `8192` -- **description**: Sets the maximum size of a packet to be filtered. - -#### Paper.minPrecachedDatafixVersion: - -- **default**: `Minecraft world version + 1` -- **description**: If you are expecting to convert a large number of chunks you might consider setting this to only convert from a point onwards. - -#### Paper.WorkerThreadCount: - -- **default**: `8` or `number of cpus - 2`. Whichever is lower -- **description**: Sets the number of worker threads to use for chunk loading. - -#### Paper.excessiveTELimit: - -- **default**: `750` -- **description**: Splits tile entities into multiple packets if there are more than this many. - -#### io.papermc.paper.suppress.sout.nags: - -- **default**: `unset` -- **description**: Suppresses the nag message about using `System.out`/`System.err` in a plugin. - -#### paper.strict-thread-checks: - -- **default**: `unset` -- **description**: This sets the status of the AsyncCatcher so that it will always log an error if code is not run on the main thread. - -#### Paper.skipServerPropertiesComments: - -- **default**: `unset` -- **description**: Skips the comments in the `server.properties` file. - -#### Paper.debugInvalidSkullProfiles: - -- **default**: `unset` -- **description**: Enables debug logging for invalid skull profiles. This logs any invalid skulls in the world with the appropriate location information. - -#### paper.alwaysPrintWarningState: - -- **default**: `unset` -- **description**: Always prints the warning state for the particular level. - -#### Paper.parseYamlCommentsByDefault: - -- **default**: `true` -- **description**: Sets whether to parse comments in YAML files by default. - -#### paperclip.patchonly: - -- **default**: `false` -- **description**: If the server is started via the Paperclip patch utility (the default distribution on the downloads page) then this sets whether it should only patch the Vanilla server and download libraries without starting the server. - -#### Paper.IgnoreJavaVersion: - -- **default**: `false` -- **description**: Allows you to bypass the Java version check. See [here](/paper/faq#unsupported-java-detected-what-do-i-do) for more info. - -#### paper.useLegacyPluginLoading: - -- **default**: `false` -- **description**: Allows cyclic plugin loading. See [here](paper-plugins.md#cyclic-plugin-loading) for more info. - -#### Paper.DisableCommandConverter: - -- **default**: `false` -- **description**: Disables Paper's automatic upgrading of commands, including items with custom data defined in command blocks and other places that may contain commands, to the new component format introduced in version 1.20.5. - -#### paper.disable-plugin-rewriting - -- **default**: `false` -- **description**: Disables plugin remapping introduced in 1.20.5 and everything involving automatic plugin conversion by commodore. For more information see the [userdev](../../dev/getting-started/userdev.mdx#1205-and-beyond) documentation and the official [announcement](https://discord.com/channels/289587909051416579/976631292747735080/1232740079097876570). diff --git a/docs/versioned/paper/content/1.20/admin/reference/vanilla-command-permissions.mdx b/docs/versioned/paper/content/1.20/admin/reference/vanilla-command-permissions.mdx deleted file mode 100644 index 5b1dadea8..000000000 --- a/docs/versioned/paper/content/1.20/admin/reference/vanilla-command-permissions.mdx +++ /dev/null @@ -1,44 +0,0 @@ ---- -slug: /reference/permissions -description: All permissions available in the default Paper server. ---- - -# Permissions - -import React from "react"; -import { CommandsPermissionsTable, PermissionsTable } from "@site/src/components/permission/Permissions"; -import {vanillaCommands, bukkitCommands, paperCommands, vanillaPermissions, bukkitPermissions, paperPermissions} from "@site/src/components/permission/PermissionSpec"; - -This page lists all permissions that are included in the default Paper server. - -## Vanilla command permissions - -The following is a list of permissions for Vanilla commands. - - - -## Bukkit command permissions - -The following is a list of permissions for Bukkit commands. - - -## Paper command permissions - -The following is a list of permissions for Paper commands. - - -## Vanilla permissions - -The following is a list of all additional Vanilla Permissions. - - -## Bukkit permissions - -The following is a list of all additional Bukkit Permissions. - - -## Paper permissions - -The following is a list of all additional Paper Permissions. - - diff --git a/docs/versioned/paper/content/1.20/contributing/README.mdx b/docs/versioned/paper/content/1.20/contributing/README.mdx deleted file mode 100644 index 300bb16b7..000000000 --- a/docs/versioned/paper/content/1.20/contributing/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Contributing Guide - -Welcome to the Paper contributing guide! This guide includes information and tutorials for developers -wishing to contribute to the Paper project. - ---- - - diff --git a/docs/versioned/paper/content/1.20/contributing/events.mdx b/docs/versioned/paper/content/1.20/contributing/events.mdx deleted file mode 100644 index 57a2c9de7..000000000 --- a/docs/versioned/paper/content/1.20/contributing/events.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -slug: /contributing/events -description: A guide on how to add new events to Paper. ---- - -# Events -There are several requirements for events in the Paper API. - -:::note - -Note that while not all existing events may follow these -guidelines, all new and modified events should adhere to them. - -::: - -All new events should go in the package (sub-package of) `io.papermc.paper.event`. - -### Constructors - -All new constructors added should be annotated with -[`@ApiStatus.Internal`](https://javadoc.io/doc/org.jetbrains/annotations/latest/org/jetbrains/annotations/ApiStatus.Internal.html) -to signify that they are not considered API and can change at any time without warning. - -Constructors that are being replaced, if they aren't being removed, should be marked with -`@Deprecated` and -`@DoNotUse`. - -### Mutability -Certain API types are "mutable" which can lead to unexpected behavior within events. Mutable types like -`Location` and `Vector` -should therefore be cloned when returned from a "getter" in an event. - -### `HandlerList` -For an event class or any subclass of it to be listened to, a `HandlerList` -field must be present with an instance and static method to retrieve it. -See the docs for `Event` for specifics. -This field should be static and final and named `HANDLER_LIST`. - -Also consider not putting a `HandlerList` on every event, just a "common parent" event so that a plugin can listen to the -parent event and capture any child events but also listen to the child event separately. - -### Miscellaneous - -* New parameters or method returns of type `ItemStack` -should be [`@NotNull`](https://javadoc.io/doc/org.jetbrains/annotations/latest/org/jetbrains/annotations/NotNull.html). diff --git a/docs/versioned/paper/content/1.20/dev/README.mdx b/docs/versioned/paper/content/1.20/dev/README.mdx deleted file mode 100644 index 47307b5b1..000000000 --- a/docs/versioned/paper/content/1.20/dev/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Development Guide - -Welcome to the Paper development guide! This guide includes information and tutorials for developers -on how to create and expand on Paper plugins. - ---- - - diff --git a/docs/versioned/paper/content/1.20/dev/api/README.mdx b/docs/versioned/paper/content/1.20/dev/api/README.mdx deleted file mode 100644 index b5048c957..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Paper API - -Welcome to the Paper API guide! -This guide includes information for developers about how to use specific parts of the Paper API. - ---- - - diff --git a/docs/versioned/paper/content/1.20/dev/api/commands.mdx b/docs/versioned/paper/content/1.20/dev/api/commands.mdx deleted file mode 100644 index 842da0c73..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/commands.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -slug: /dev/commands -description: A guide to Paper's Brigadier command API. ---- - -# Command API - -Paper's command system is built on top of Minecraft's Brigadier command system. This system is a -powerful and flexible way to define commands and arguments. - -:::danger[Experimental] - -Paper's command system is still experimental and may change in the future. - -::: - -## Defining commands - -:::note - -This uses the LifecycleEventManager -to register the command. See the [Lifecycle Events](./lifecycle.mdx) page for more information. - -::: - -### JavaPlugin - -Commands can be registered inside the onEnable -method of the plugin. Commands registered here will not be available to datapack functions because -functions are loaded by the server before plugins are loaded. To make commands available to -datapacks, register them via the [PluginBootstrap](#pluginbootstrap). - -```java -public class YourPluginClass extends JavaPlugin { - - @Override - public void onEnable() { - LifecycleEventManager manager = this.getLifecycleManager(); - manager.registerEventHandler(LifecycleEvents.COMMANDS, event -> { - final Commands commands = event.registrar(); - commands.register( - Commands.literal("new-command") - .executes(ctx -> { - ctx.getSource().getSender().sendPlainMessage("some message"); - return Command.SINGLE_SUCCESS; - }) - .build(), - "some bukkit help description string", - List.of("an-alias") - ); - }); - } -} -``` - -### PluginBootstrap - -:::note - -If any plugin on the server registers a handler for the `LifecycleEvents.COMMANDS` event, the -server will disable Bukkit's plugin reload functionality. This is a limitation with how -the plugin reload system works in conjunction with the plugin bootstrapper system. The `/reload` -command should never be used regardless. - -::: - -Commands are registered in the same way in a plugin's -bootstrapper. -The benefit of registering commands here is that they will be available to datapack functions -because the command registration happens early enough. - -```java -public class YourPluginBootstrap implements PluginBootstrap { - - @Override - public void bootstrap(BootstrapContext context) { - LifecycleEventManager manager = context.getLifecycleManager(); - // Same as for JavaPlugin - } -} -``` - -### BasicCommand - -Paper provides a simple BasicCommand -interface which can be used to define a command in a similar way to Bukkit's `CommandExecutor`. -There are methods on the Commands interface -to register such commands. - -Example registration and implementation of a BasicCommand: - -```java -LifecycleEventManager manager = context.getLifecycleManager(); -manager.registerEventHandler(LifecycleEvents.COMMANDS, event -> { - final Commands commands = event.registrar(); - commands.register("fun", "some help description string", new FunCommand()); -}); -``` - -```java -class FunCommand implements BasicCommand { - - @Override - public void execute(@NotNull CommandSourceStack stack, @NotNull String[] args) { - if (args.length == 1 && args[0].equalsIgnoreCase("start")) { - stack.getSender().sendRichMessage("Fun activated!"); - } - } -} -``` - -## Arguments - -### Built-in arguments - -Vanilla has lots of built-in arguments that the client also supports. These can provide better -syntax and error-checking before even executing the commands. ArgumentTypes -has all the argument types available to the API. - -For now, you can find specific examples of arguments, among other things, on the [Fabric Wiki](https://fabricmc.net/wiki/tutorial:commands). - -### Custom arguments - -Custom arguments can be created by implementing the CustomArgumentType -interface. See the Javadocs for more information on how they work. - -## Lifecycle - -Commands are not just registered once at the start, but anytime a reload happens. This can be -either via Bukkit's reload command (which should never be used and may not always be available) or -Minecraft's `/reload` command (which can be used), the commands are re-registered by having the -event handlers called again. diff --git a/docs/versioned/paper/content/1.20/dev/api/component-api/audiences.mdx b/docs/versioned/paper/content/1.20/dev/api/component-api/audiences.mdx deleted file mode 100644 index d562eb522..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/component-api/audiences.mdx +++ /dev/null @@ -1,53 +0,0 @@ ---- -slug: /dev/component-api/audiences -description: How to use Adventure's Audiences. -title: Audiences ---- - -Audiences wrap a collection of recipients that can receive messages. They can be used to send messages to individual -players, groups of players, or even the entire server (including the console). - -## Who is an `Audience`? - -All `CommandSender`s are single audiences. This includes players, the console, and command blocks. `Server`, `Team` and -`World` are all forwarding audiences. This means that they are made up of multiple audiences. For example, the server is -made up of all online players and the console. - -This means that all the [`Audience`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/Audience.html) -methods are available on `CommandSender`, -`Server`, `Team` -and `World`. - -## `ForwardingAudience` - -The [`ForwardingAudience`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/ForwardingAudience.html) -wraps a collection of [`Audience`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/Audience.html) -instances and forwards messages to all of them. This is useful for sending messages to multiple audiences (players) at once. - -```java -// Server is a ForwardingAudience which includes all online players and the console -ForwardingAudience audience = Bukkit.getServer(); - -// To construct an audience from a collection of players, use: -Audience audience = Audience.audience(Audience...); -// If you pass in a single Audience, it will be returned as-is. If you pass in a collection of Audiences, they will be -// wrapped in a ForwardingAudience. -``` - -## What do `Audience`s do? - -Audiences are used for interacting with players. They can be used to send messages, play sounds, show bossbars, and more. -They are mostly used for sending other parts of the API to players. For example, you can send a [`Component`](https://jd.advntr.dev/api/latest/net/kyori/adventure/text/Component.html) -to a player using [`Audience#sendMessage(Component)`](https://jd.advntr.dev/api/latest/net/kyori/adventure/audience/Audience.html#sendMessage(net.kyori.adventure.text.Component)). - -## Pointers - -Audiences can also provide arbitrary information, such as display name or UUID. This is done using the pointer system. - -```java -// Get the uuid from an audience member, returning an Optional -Optional uuid = audience.get(Identity.UUID); - -// Get the display name, returning a default -Component name = audience.getOrDefault(Identity.DISPLAY_NAME, Component.text("no display name!")); -``` diff --git a/docs/versioned/paper/content/1.20/dev/api/component-api/i18n.mdx b/docs/versioned/paper/content/1.20/dev/api/component-api/i18n.mdx deleted file mode 100644 index 0be99e29d..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/component-api/i18n.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -slug: /dev/component-api/i18n -description: How to use Adventure's internationalization. -title: Internationalization ---- - -Generally it's a good idea to support translations in your plugin, especially if you want to -appeal to the largest user base. Adventure makes this simple by adding a server-side -translation layer to almost all text that ends up being displayed to clients. - -:::info[Javadocs] - -Adventure's Javadocs for all-things translations can be found [here](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/package-summary.html). - -::: - -## GlobalTranslator - -All translation is done through [`GlobalTranslator`](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/GlobalTranslator.html). -You can render translations yourself and add new sources for translations. - -You can add sources to the `GlobalTranslator` by creating instances of [`TranslationRegistry`](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/TranslationRegistry.html) -or implementing the [`Translator`](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/Translator.html) interface yourself. - -## Where translations work - -Vanilla Minecraft handles translations on the client by using the language files bundled with the client or provided via resource packs. If you don't want to send custom language files -in a resource pack, server-side translations are the only alternative. They work anywhere the component API exists, except for `ItemStack` -display text like the display name or lore. So chat, entity display names, scoreboards, tab lists, etc., all support translations. - -:::caution - -The player's language as declared in the settings packet sent by the client arrives **after** the player has joined the server, so there are no guarantees that -translations will work for a client that is joining during the `PlayerJoinEvent` or any earlier event. -You can listen for the first `PlayerClientOptionsChangeEvent` -after joining to know with 100% certainty what language the client that joined is using. - -::: - -## Examples - -### `ResourceBundle` -```properties title="src/main/resources/your/plugin/Bundle_en_US.properties" -some.translation.key=Translated Message: {0} -``` - -```java -TranslationRegistry registry = TranslationRegistry.create(Key.key("namespace:value")); - -ResourceBundle bundle = ResourceBundle.getBundle("your.plugin.Bundle", Locale.US, UTF8ResourceBundleControl.get()); -registry.registerAll(Locale.US, bundle, true); -GlobalTranslator.translator().addSource(registry); -``` - -This creates a new `TranslationRegistry` under a specified namespace. Then, a `ResourceBundle` -is created from a bundle located on the classpath with the specified `Locale`. -Finally, that `ResourceBundle` is added to the registry. That registry is then added as a source to the `GlobalTranslator`. -This makes all the translations available server-side. - -Now you can use translation keys in translatable components. - -```java -final Component message = Component.translatable("some.translation.key", Component.text("The Argument")) -``` - -This will show to clients using the US English language: `Translated Message: The Argument`. diff --git a/docs/versioned/paper/content/1.20/dev/api/component-api/intro.mdx b/docs/versioned/paper/content/1.20/dev/api/component-api/intro.mdx deleted file mode 100644 index af54ba871..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/component-api/intro.mdx +++ /dev/null @@ -1,197 +0,0 @@ ---- -slug: /dev/component-api/introduction -description: An introduction to how components work. -title: Introduction ---- - -:::note - -This documentation page applies to both the Paper and Velocity projects. - -::: - -Since Minecraft 1.7, the game has utilized components to represent text to be displayed -by clients. Components offer a number of benefits over plain text strings which are enumerated below. -Paper and Velocity natively implements the Adventure API to add component support wherever possible. - -## Why you should use Components - -Previously, text was a linear structure with the only formatting options being -confusing symbols like `§c` and `§k` to control basic colors and styles of text. -Components are a tree-like structure which inherit style and colors from their parents. - -Components have several types which do different things than just display raw text, like -translating text to the client's language based on a key, or showing a client-specific keybind -to a player. - -All these component types support more style options like any RGB color, interaction events -(click and hover). The other component types and these style options have poor or missing -representations in the legacy string format. - -## Usage - -Representing text as components is now the supported way of representing text for Paper and Velocity. They are used -for almost all aspects of text being displayed to clients. Text like item names, lore, bossbars, team prefixes and -suffixes, custom names, and much more all support components in respective APIs. -[Mojang has stated](https://bugs.mojang.com/browse/MC-190605?focusedId=993040&page=com.atlassian.jira.plugin.system.issuetabpanels%3Acomment-tabpanel#comment-993040) -that client support for the legacy format with `§` will be removed in the future. - - -:::tip - -In the Paper API, there are lots of deprecated methods and types that deal with this legacy format. This is to -signal that a better alternative in components is available and should be migrated to going forward. - -::: - -## Creating components - -Components can be interacted with as objects. There are different interfaces for each type along with -builders for all the types. These objects are immutable so when constructing more complex components, it's -recommended to use builders to avoid creating new Component instances with every change. - -```java -// This is a sub-optimal construction of the -// component as each change creates a new component -final Component component = Component.text("Hello") - .color(TextColor.color(0x13f832)) - .append(Component.text(" world!", NamedTextColor.GREEN)); - -/* This is an optimal use of the builder to create - the same component. Also note that Adventure - Components are designed for use with static method imports - to make code less verbose */ -final Component component = text() - .content("Hello").color(color(0x13f832)) - .append(text(" world!", GREEN)) - .build(); -``` - -:::info[In-Depth Documentation] - -For complete documentation on the Adventure Component API Paper and Velocity use, please look at the -[Adventure documentation](https://docs.advntr.dev). - -::: - -## MiniMessage - -Paper and Velocity include the MiniMessage library, which is a string representation of components. If you prefer working with -strings rather than objects, MiniMessage is vastly superior to the legacy string format. It can utilize the tree -structure for style inheritance and can represent the more complex component types while legacy cannot. - -```java -final Component component = MiniMessage.miniMessage().deserialize( - "<#438df2>This is the parent component; its style is " + - "applied to all children.\nThis is the first child, " + - "which is rendered after the parent" -); -``` - -We recommend using this format for user-facing input such as commands or configuration values. - -:::info[In-Depth Documentation] - -MiniMessage is a part of Adventure, and you can find its documentation on [Adventure's documentation](https://docs.advntr.dev/minimessage/index.html). - -::: - -:::tip - -MiniMessage has a [web viewer](https://webui.advntr.dev/), which is useful for constructing more complicated components and seeing the results in real time. - -::: - -## JSON format - -Components can be serialized and deserialized from a standard JSON format. This format is used -in Vanilla in various commands which accept component arguments like `/tellraw`. Below is a simple example -of this format. - -```json -{ - "text": "This is the parent component; its style is applied to all children.\n", - "color": "#438df2", - "bold": true, - "extra": [ - { - "text": "This is this first child, which is rendered after the parent", - "underlined": true, - // This overrides the parent's "bold" value just for this component - "bold": false - }, - { - // This is a keybind component which will display the client's keybind for that action - "keybind": "key.inventory" - } - ] -} -``` - -:::info[In-Depth Documentation] - -The JSON format is fully documented on the [Minecraft Wiki](https://minecraft.wiki/w/Raw_JSON_text_format). - -::: - -:::tip - -There are online tools to make generating this format much easier like [JSON Text Generator](https://minecraft.tools/en/json_text.php). - -::: - -## Serializers - -Paper and Velocity come bundled with different serializers for converting between -[`Component`](https://jd.advntr.dev/api/latest/net/kyori/adventure/text/Component.html)s and other forms of serialized text. - -### [`GsonComponentSerializer`](https://jd.advntr.dev/text-serializer-gson/latest) - -Converts between `Component` -and JSON-formatted strings with convenience methods to directly deal with Gson's -[`JsonElement`](https://javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/JsonElement.html). -This conversion is lossless and is the preferred form of serialization for components that do not have to be edited by users regularly. - -### [`MiniMessage`](https://jd.advntr.dev/text-minimessage/latest) - -Converts between `Component` -and a MiniMessage-formatted string. This conversion is lossless and is the preferred form of -serialization for components that have to be edited by users. There is also extensive customization you can add to the -serializer, which is [documented here](https://docs.advntr.dev/minimessage/api.html#getting-started). - -### [`PlainTextComponentSerializer`](https://jd.advntr.dev/text-serializer-plain/latest) - -Serializes a `Component` into a plain text string. This is very lossy as all style information as well as most other -types of components will lose information. There may be special handling for -[`TranslatableComponent`](https://jd.advntr.dev/api/latest/net/kyori/adventure/text/TranslatableComponent.html)s to be serialized -into a default language, but generally this shouldn't be used except in certain circumstances, like logging to a text file. - -### [`LegacyComponentSerializer`](https://jd.advntr.dev/text-serializer-legacy/latest) - -:::caution - -This is not recommended for use as the legacy format may be removed in the future. - -::: - -Converts between `Component` and the legacy string format. -This conversion is very lossy as component types and events do not have a legacy string representation. - -A more useful use case is converting legacy text to MiniMessage format in a migration process. -```java -final String legacyString = ChatColor.RED + "This is a legacy " + ChatColor.GOLD + "string"; - -// runs the legacy string through two serializers to convert legacy -> MiniMessage -final String miniMessageString = MiniMessage.miniMessage().serialize( - LegacyComponentSerializer.legacySection().deserialize(legacyString) -); -``` - -:::note - -There are 2 built-in legacy serializers, one dealing with `§` symbols and the other for -`&` symbols. They have their own instances available through -[`LegacyComponentSerializer#legacySection()`](https://jd.advntr.dev/text-serializer-legacy/latest/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.html#legacySection()) -and [`LegacyComponentSerializer#legacyAmpersand()`](https://jd.advntr.dev/text-serializer-legacy/latest/net/kyori/adventure/text/serializer/legacy/LegacyComponentSerializer.html#legacyAmpersand()). - -::: diff --git a/docs/versioned/paper/content/1.20/dev/api/custom-inventory-holder.mdx b/docs/versioned/paper/content/1.20/dev/api/custom-inventory-holder.mdx deleted file mode 100644 index 7c78956f5..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/custom-inventory-holder.mdx +++ /dev/null @@ -1,159 +0,0 @@ ---- -slug: /dev/custom-inventory-holder -description: How to use a custom InventoryHolder to identify custom inventories. ---- - -# Custom `InventoryHolder` - -`InventoryHolder`s are a way to identify your plugin's inventories in events. - -## Why use an `InventoryHolder`? - -`InventoryHolder`s simplify the steps you need to do to make sure an inventory was created by your plugin. - -Using inventory names for identification is unreliable, as other plugins, or even players, can create inventories with names the exact same as yours. -With components, you also need to make sure the name is exactly the same or serialize it to other formats. - -Custom `InventoryHolder`s have no such downsides and by using them you're guaranteed to have methods available to handle your inventory. - -## Creating a custom holder - -The first step is to implement the `InventoryHolder` interface. -We can do this the following way: create a new class that will create our `Inventory` in the constructor. - -:::info - -The constructor takes your main plugin class as an argument in order to create the `Inventory`. -If you wish, you can use the static method `Bukkit#createInventory(InventoryHolder, int)` instead and remove the argument. - -::: - -```java -public class MyInventory implements InventoryHolder { - - private final Inventory inventory; - - public MyInventory(MyPlugin plugin) { - // Create an Inventory with 9 slots, `this` here is our InventoryHolder. - this.inventory = plugin.getServer().createInventory(this, 9); - } - - @Override - public Inventory getInventory() { - return this.inventory; - } - -} -``` - -## Opening the inventory - -To open the inventory, first we have to instantiate our `MyInventory` class and then open the inventory for the player. -You can do that wherever you need. - -:::note - -We pass an instance of our plugin's main class as it's required by the constructor. If you've used the static method and removed the constructor -argument you don't have to pass it here. - -::: - -```java -Player player; // Assume we have a Player instance. - // This can be a command, another event or anywhere else you have a Player. - -MyInventory myInventory = new MyInventory(myPlugin); -player.openInventory(myInventory.getInventory()); -``` - -## Listening to an event - -Once we have the inventory open, we can listen to any inventory events we like and check if -`Inventory#getHolder()` returns an instance of our `MyInventory`. - -```java -@EventHandler -public void onInventoryClick(InventoryClickEvent event) { - Inventory inventory = event.getInventory(); - // Check if the holder is our MyInventory, - // if yes, use instanceof pattern matching to store it in a variable immediately. - if (!(inventory.getHolder(false) instanceof MyInventory myInventory)) { - // It's not our inventory, ignore it. - return; - } - - // Do what we need in the event. -} -``` - -## Storing data on the holder - -You can store extra data for your inventories on the `InventoryHolder` by adding fields and methods to your class. - -Let's make an inventory that counts the amount of times we clicked a stone inside it. -First, let's modify our `MyInventory` class a little: - -```java -public class MyInventory implements InventoryHolder { - - private final Inventory inventory; - - private int clicks = 0; // Store the amount of clicks. - - public MyInventory(MyPlugin plugin) { - this.inventory = plugin.getServer().createInventory(this, 9); - - // Set the stone that we're going to be clicking. - this.inventory.setItem(0, new ItemStack(Material.STONE)); - } - - // A method we will call in the listener whenever the player clicks the stone. - public void addClick() { - this.clicks++; - this.updateCounter(); - } - - // A method that will update the counter item. - private void updateCounter() { - this.inventory.setItem(8, new ItemStack(Material.BEDROCK, this.clicks)); - } - - @Override - public Inventory getInventory() { - return this.inventory; - } - -} -``` - -Now, we can modify our listener to check if the player clicked the stone, and if so, add a click. - -```java -@EventHandler -public void onInventoryClick(InventoryClickEvent event) { - // We're getting the clicked inventory to avoid situations where the player - // already has a stone in their inventory and clicks that one. - Inventory inventory = event.getClickedInventory(); - // Add a null check in case the player clicked outside the window. - if (inventory == null || !(inventory.getHolder(false) instanceof MyInventory myInventory)) { - return; - } - - event.setCancelled(true); - - ItemStack clicked = event.getCurrentItem(); - // Check if the player clicked the stone. - if (clicked != null && clicked.getType() == Material.STONE) { - // Use the method we have on MyInventory to increment the field - // and update the counter. - myInventory.addClick(); - } -} -``` - -:::info - -You can store the created `MyInventory` instance, e.g. on a `Map` for per-player use, or as a field to share the inventory between -all players, and use it to persist the counter even when opening the inventory for the next time. - -::: diff --git a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-interp.gif b/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-interp.gif deleted file mode 100644 index b2c1ef87e..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-interp.gif and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-rotation.png b/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-rotation.png deleted file mode 100644 index 02edf6fff..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-rotation.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-scale.png b/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-scale.png deleted file mode 100644 index 77398ea6b..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-scale.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-trans.png b/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-trans.png deleted file mode 100644 index 4d5b70d5c..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/api/entity-api/assets/display-trans.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/api/entity-api/display-entities.mdx b/docs/versioned/paper/content/1.20/dev/api/entity-api/display-entities.mdx deleted file mode 100644 index 6a0e6a454..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/entity-api/display-entities.mdx +++ /dev/null @@ -1,242 +0,0 @@ ---- -slug: /dev/display-entities -description: The display entity API and how to use it. ---- - -# Display Entities - -Added in 1.19.4, [display entities](https://minecraft.wiki/w/Display) are a powerful way to display -various things in the world, like blocks, items and text. - -By default, these entities have no hitbox, don't move, make sounds or take damage, -making them the perfect for all kinds of applications, like holograms. - -## Types - -### Text - -Text can be displayed via a `TextDisplay` -entity. - -```java -TextDisplay display = world.spawn(location, TextDisplay.class, entity -> { - // customize the entity! - entity.text(Component.text("Some awesome content", NamedTextColor.BLACK)); - entity.setBillboard(Display.Billboard.VERTICAL); // pivot only around the vertical axis - entity.setBackgroundColor(Color.RED); // make the background red - - // see the Display and TextDisplay Javadoc, there are many more options -}); -``` - -### Blocks - -Blocks can be displayed via a `BlockDisplay` -entity. - -```java -BlockDisplay display = world.spawn(location, BlockDisplay.class, entity -> { - // customize the entity! - entity.setBlock(Material.GRASS_BLOCK.createBlockData()); -}); -``` - -### Items - -Items can be displayed via an `ItemDisplay` -entity. - -Despite its name, an _item_ display can also display _blocks_, with the difference being the -position in the model - an item display has its position in the center, whereas a block display has -its position in the corner of the block (this can be seen with the hitbox debug mode - F3+B). - -```java -ItemDisplay display = world.spawn(location, ItemDisplay.class, entity -> { - // customize the entity! - entity.setItemStack(new ItemStack(Material.SKELETON_SKULL)); -}); -``` - -## Transformation - -Displays can have an arbitrary affine transformation applied to them, allowing you to position and -warp them as you choose in 3D space. - -Transformations are applied to the display in this order: - -```mermaid -flowchart LR; - translation[Translation]-->left_rotation[Left rotation]; - left_rotation-->scale[Scale]; - scale-->right_rotation[Right rotation]; -``` - -:::tip[Visualizing transformations] - -Use the [Transformation Visualizer](https://misode.github.io/transformation/) website to visualize -a transformation for quick prototyping! - -::: - -### Scale - -The most basic transformation is scaling, let's take a grass block and scale it up: - -```java -world.spawn(location, BlockDisplay.class, entity -> { - entity.setBlock(Material.GRASS_BLOCK.createBlockData()); - entity.setTransformation( - new Transformation( - new Vector3f(), // no translation - new AxisAngle4f(), // no left rotation - new Vector3f(2, 2, 2), // scale up by a factor of 2 on all axes - new AxisAngle4f() // no right rotation - ) - ); - // or set a raw transformation matrix from JOML - // entity.setTransformationMatrix( - // new Matrix4f() - // .scale(2) // scale up by a factor of 2 on all axes - // ); -}); -``` - -![Scaling example](./assets/display-scale.png) - -### Rotation - -You can also rotate it, let's tip it on its corner: - -```java -world.spawn(location, BlockDisplay.class, entity -> { - entity.setBlock(Material.GRASS_BLOCK.createBlockData()); - entity.setTransformation( - new Transformation( - new Vector3f(), // no translation - // highlight-next-line - new AxisAngle4f((float) -Math.toRadians(45), 1, 0, 0), // rotate -45 degrees on the X axis - new Vector3f(2, 2, 2), // scale up by a factor of 2 on all axes - // highlight-next-line - new AxisAngle4f((float) Math.toRadians(45), 0, 0, 1) // rotate +45 degrees on the Z axis - ) - ); - // or set a raw transformation matrix from JOML - // entity.setTransformationMatrix( - // new Matrix4f() - // .scale(2) // scale up by a factor of 2 on all axes - // highlight-start - // .rotateXYZ( - // (float) Math.toRadians(360 - 45), // rotate -45 degrees on the X axis - // 0, - // (float) Math.toRadians(45) // rotate +45 degrees on the Z axis - // ) - // highlight-end - // ); -}); -``` - -![Rotation example](./assets/display-rotation.png) - -### Translation - -Finally, we can also apply a translation transformation (position offset) to the display, for example: - -```java -world.spawn(location, BlockDisplay.class, entity -> { - entity.setBlock(Material.GRASS_BLOCK.createBlockData()); - entity.setTransformation( - new Transformation( - // highlight-next-line - new Vector3f(0.5F, 0.5F, 0.5F), // offset by half a block on all axes - new AxisAngle4f((float) -Math.toRadians(45), 1, 0, 0), // rotate -45 degrees on the X axis - new Vector3f(2, 2, 2), // scale up by a factor of 2 on all axes - new AxisAngle4f((float) Math.toRadians(45), 0, 0, 1) // rotate +45 degrees on the Z axis - ) - ); - // or set a raw transformation matrix from JOML - // entity.setTransformationMatrix( - // new Matrix4f() - // highlight-next-line - // .translate(0.5F, 0.5F, 0.5F) // offset by half a block on all axes - // .scale(2) // scale up by a factor of 2 on all axes - // .rotateXYZ( - // (float) Math.toRadians(360 - 45), // rotate -45 degrees on the X axis - // 0, - // (float) Math.toRadians(45) // rotate +45 degrees on the Z axis - // ) - // ); -}); -``` - -![Translation example](./assets/display-trans.png) - -## Interpolation - -A transformation can be linearly interpolated by the client to create a smooth animation, -switching from one transformation to the next. - -An example of this would be smoothly rotating a block/item/text in-place. In conjunction with the -[Scheduler API](../scheduler.mdx), the animation can be restarted after it's done, -making the display spin indefinitely: - -```java -ItemDisplay display = location.getWorld().spawn(location, ItemDisplay.class, entity -> { - entity.setItemStack(new ItemStack(Material.GOLDEN_SWORD)); -}); - -int duration = 5 * 20; // duration of half a revolution (5 * 20 ticks = 5 seconds) - -Matrix4f mat = new Matrix4f().scale(0.5F); // scale to 0.5x - smaller item -Bukkit.getScheduler().runTaskTimer(plugin, task -> { - if (!display.isValid()) { // display was removed from the world, abort task - task.cancel(); - return; - } - - display.setTransformationMatrix(mat.rotateY(((float) Math.toRadians(180)) + 0.1F /* prevent the client from interpolating in reverse */)); - display.setInterpolationDelay(0); // no delay to the interpolation - display.setInterpolationDuration(duration); // set the duration of the interpolated rotation -}, 1 /* delay the initial transformation by one tick from display creation */, duration); -``` - -![Interpolation example](./assets/display-interp.gif) - -## Use cases - -Displays have many different use cases, ranging from stationary decoration to complex animation. - -A popular, simple use case is to make a decoration that's visible to only specific players, -which can be achieved using standard entity API - `Entity#setVisibleByDefault()` -and `Player#showEntity()`/ -`Player#hideEntity()`. - -:::warning - -If the display is only used temporarily, its persistence can be disabled with -`Entity#setPersistent()`, -meaning it will disappear when the chunk unloads. - -_However, if the display is located in a chunk that never unloads, i.e. a spawn chunk, it will never -be removed, creating a resource leak. Make sure to remove the display afterward with -`Entity#remove()`._ - -::: - -They can also be added as passengers to entities with the -`Entity#addPassenger()`/ -`Entity#removePassenger()` -methods, useful for making styled name tags! - -```java -TextDisplay display = world.spawn(location, TextDisplay.class, entity -> { - // ... - - entity.setVisibleByDefault(false); // hide it for everyone - entity.setPersistent(false); // don't save the display, it's temporary -}); - -entity.addPassenger(display); // mount it on top of an entity's head -player.showEntity(plugin, display); // show it to a player -// ... -display.remove(); // done with the display -``` diff --git a/docs/versioned/paper/content/1.20/dev/api/entity-api/entity-teleport.mdx b/docs/versioned/paper/content/1.20/dev/api/entity-api/entity-teleport.mdx deleted file mode 100644 index 3214b796e..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/entity-api/entity-teleport.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -slug: /dev/entity-teleport -description: The entity teleportation API and how to use it. ---- - -# Teleportation - -Entities can be instantaneously teleported to specific positions, synchronously and asynchronously with the -`teleport` and -`teleportAsync` API. - -:::tip[Performance] - -If you expect to teleport into unloaded chunks, it is recommended to use the `teleportAsync` API, -as it avoids doing synchronous chunk loads, which put a lot of stress on the server's main thread - -hurting overall performance. - -::: - -```java -entity.teleport(location); // loads chunks synchronously and teleports the entity - -entity.teleportAsync(location).thenAccept(success -> { // loads chunks asynchronously and teleports the entity - // this code is ran when the teleport completes - // the Future is completed on the main thread, so it is safe to use the API here - - if (success) { - // the entity was teleported successfully! - } -}); -``` - -:::danger - -You should **NEVER** call `.get()`/`.join()` on the `teleportAsync` `Future` on the main thread, -as it **WILL** deadlock your server, if the chunk you're teleporting into is not loaded. - -::: - -## Look at - -The `lookAt` -API allows you to make a player look at a certain position or entity. - -```java -player.lookAt( - position, - LookAnchor.EYES // the player's eyes will be facing the position -); - -player.lookAt( - entity, - LookAnchor.EYES // the player's eyes will be facing the entity - LookAnchor.FEET // the player will be facing the entity's feet -); -``` - -## Teleport flags - -Teleport flags offer a way to teleport entities whilst being able to customize behavior. -This allows you to do things like teleport players using relative flags and being able to retain passengers. - -All available teleport flags can be found in the `TeleportFlag` class. - -### Relative teleportation - -Teleport a player relatively, preventing velocity from being reset in the X, Y and Z axes. - -```java -player.teleport( - location, - TeleportFlag.Relative.X, - TeleportFlag.Relative.Y, - TeleportFlag.Relative.Z -); -``` - -### Retaining passengers - -Teleport an entity with the `RETAIN_PASSENGERS` flag, -allowing its passengers to be transferred with the entity. - -```java -entity.teleport(location, TeleportFlag.EntityState.RETAIN_PASSENGERS); -``` diff --git a/docs/versioned/paper/content/1.20/dev/api/event-api/assets/plain-message-rendering.png b/docs/versioned/paper/content/1.20/dev/api/event-api/assets/plain-message-rendering.png deleted file mode 100644 index fa40385d7..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/api/event-api/assets/plain-message-rendering.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/api/event-api/assets/prefix-rendering.png b/docs/versioned/paper/content/1.20/dev/api/event-api/assets/prefix-rendering.png deleted file mode 100644 index 664cfb4f8..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/api/event-api/assets/prefix-rendering.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/api/event-api/chat-event.mdx b/docs/versioned/paper/content/1.20/dev/api/event-api/chat-event.mdx deleted file mode 100644 index e8685dc2b..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/event-api/chat-event.mdx +++ /dev/null @@ -1,144 +0,0 @@ ---- -slug: /dev/chat-events -description: An outline on AsyncChatEvent and how to handle it. ---- - -# Chat Events - -The chat event has evolved a few times over the years. -This guide will explain how to properly use the new `AsyncChatEvent` -and its `ChatRenderer`. -The `AsyncChatEvent` -is an improved version of the old `AsyncPlayerChatEvent` -that allows you to render chat messages individually for each player. - -:::note[`AsyncChatEvent` vs `ChatEvent`] - -The key difference between `AsyncChatEvent` -and `ChatEvent` is that -`AsyncChatEvent` is fired asynchronously. - -This means that it does not block the main thread and sends the chat message when the listener has completed. -Be aware that using the Bukkit API in an asynchronous context (i.e. the event handler) is unsafe and exceptions may be thrown. -If you need to use the Bukkit API, you can use `ChatEvent`. -However, we recommend using [`BukkitScheduler`](../scheduler.mdx). - -::: - -## Understanding the renderer - -Before we can start using the new chat event, we need to understand how the new renderer works. -The renderer is Paper's way of allowing plugins to modify the chat message before it is sent to the player. -This is done by using the `ChatRenderer` interface with its -`render` -method. Previously, this was done by using the `AsyncPlayerChatEvent` -with its `setFormat` method. - -```java title="ChatRenderer#render" -public @NotNull Component render(@NotNull Player source, @NotNull Component sourceDisplayName, @NotNull Component message, @NotNull Audience viewer) { - // ... -} -``` - -- The `render` method is called when a chat message is sent to the player. -- The `source` parameter is the player that sent the message. -- The `sourceDisplayName` parameter is the display name of the player that sent the message. -- The `message` parameter is the message that was sent. -- The `viewer` parameter is the player that is receiving the message. - -:::tip[`ChatRenderer.ViewerUnaware`] - -If your renderer does not need to know about the viewer, you can use the -`ChatRenderer.ViewerUnaware` -interface instead of the `ChatRenderer` interface. -This will benefit performance as the message will only be rendered once instead of each individual player. - -::: - -## Using the renderer - -There are two ways to use the renderer. -1. Implementing the `ChatRenderer` interface in a class. -2. Using a lambda expression. - -Depending on the complexity of your renderer, you may want to use one or the other. - -### Implementing the `ChatRenderer` interface - -The first way of using the renderer is by implementing the `ChatRenderer` -interface in a class. In this example, we will be using our `ChatListener` class. - -Next, we need to tell the event to use the renderer by using the -`renderer` method. - -```java title="ChatListener.java" -public class ChatListener implements Listener, ChatRenderer { // Implement the ChatRenderer and Listener interface - - // Listen for the AsyncChatEvent - @EventHandler - public void onChat(AsyncChatEvent event) { - event.renderer(this); // Tell the event to use our renderer - } - - // Override the render method - @Override - public @NotNull Component render(@NotNull Player source, @NotNull Component sourceDisplayName, @NotNull Component message, @NotNull Audience viewer) { - // ... - } -} -``` - -:::note - -If you decide to create a separate class for your renderer, it is important to know that you don't need to instantiate the class every time the event is called. -In this case, you can use [the singleton pattern](https://en.wikipedia.org/wiki/Singleton_pattern) to create a single instance of the class. - -::: - -### Using a lambda expression - -Another way of using the renderer is by using a lambda expression. - -```java title="ChatListener.java" -public class ChatListener implements Listener { - - @EventHandler - public void onChat(AsyncChatEvent event) { - event.renderer((source, sourceDisplayName, message, viewer) -> { - // ... - }); - } -} -``` - -## Rendering the message - -Now that we have our renderer, we can start rendering the message. - -Let's say we want to render our chat to look like this: - -![](./assets/plain-message-rendering.png) - -To do this, we need to return a new [`Component`](https://jd.advntr.dev/api/latest/net/kyori/adventure/text/Component.html) that contains the message we want to send. - -```java title="ChatListener.java" -public class ChatListener implements Listener, ChatRenderer { - - // Listener logic - - @Override - public @NotNull Component render(@NotNull Player source, @NotNull Component sourceDisplayName, @NotNull Component message, @NotNull Audience viewer) { - return sourceDisplayName - .append(Component.text(": ")) - .append(message); - } -} -``` - -Now you can see that the message is rendered as we wanted it to be. - -## Conclusion - -That is all you need to know about the new chat event and its renderer. -Of course there are many more things you can do with components in general. -If you want to learn more about components, you can read the [Component Documentation](https://docs.advntr.dev/text.html). diff --git a/docs/versioned/paper/content/1.20/dev/api/event-api/custom-events.mdx b/docs/versioned/paper/content/1.20/dev/api/event-api/custom-events.mdx deleted file mode 100644 index f27ffe73e..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/event-api/custom-events.mdx +++ /dev/null @@ -1,153 +0,0 @@ ---- -slug: /dev/custom-events -description: A guide to show you how to add custom events to your plugin. ---- - -# Custom Events - -Creating custom events is a great way to add functionality to your plugin. -This will allow other plugins to listen to your custom events and add functionality to your plugin. - -## Creating a custom event - -To create a custom event, you need to create a class that extends `Event`. -Each event requires a `HandlerList` that will contain all the listeners that are listening to that event. -The only exception to this requirement is when you have an event class that cannot be fired, but serves as a parent for other events instead. -An example of this is `BlockPistonEvent`, which cannot be listened to directly. - -This list is used to call the listeners when the event is called. - -:::info - -Although `getHandlerList` is not inherited from `Event`, you need to add a static `getHandlerList()` method and return the `HandlerList` for your event. -Both methods are required for your event to work. - -::: - -```java title="PaperIsCoolEvent.java" -public class PaperIsCoolEvent extends Event { - - private static final HandlerList HANDLER_LIST = new HandlerList(); - - public static HandlerList getHandlerList() { - return HANDLER_LIST; - } - - @Override - public HandlerList getHandlers() { - return HANDLER_LIST; - } -} -``` - -Now that we have created our event, we can add some functionality to it. -Perhaps this will contain a message that will be broadcast to the server when the event is called. - -```java title="PaperIsCoolEvent.java" -public class PaperIsCoolEvent extends Event { - - private static final HandlerList HANDLER_LIST = new HandlerList(); - private Component message; - - public PaperIsCoolEvent(Component message) { - this.message = message; - } - - public static HandlerList getHandlerList() { - return HANDLER_LIST; - } - - @Override - public HandlerList getHandlers() { - return HANDLER_LIST; - } - - public Component getMessage() { - return this.message; - } - - public void setMessage(Component message) { - this.message = message; - } -} -``` - -## Calling the event - -Now that we have created our event, we can call it. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - // ... - - public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); - coolEvent.callEvent(); - // Plugins could have changed the message from inside their listeners here. So we need to get the message again. - // This event structure allows for other plugins to change the message to their taste. - // Like, for example, a plugin that adds a prefix to all messages. - Bukkit.broadcast(coolEvent.getMessage()); - } -} -``` - -## Implementing cancellation - -If you want to allow your event to be cancelled, you can implement the `Cancellable` interface. - -```java title="PaperIsCoolEvent.java" -public class PaperIsCoolEvent extends Event implements Cancellable { - - private static final HandlerList HANDLER_LIST = new HandlerList(); - private Component message; - private boolean cancelled; - - // ... - - @Override - public boolean isCancelled() { - return this.cancelled; - } - - @Override - public void setCancelled(boolean cancelled) { - this.cancelled = cancelled; - } -} -``` - -Now, when the event is called, you can check if it is cancelled and act accordingly. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - // ... - - public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); - coolEvent.callEvent(); - if (!coolEvent.isCancelled()) { - Bukkit.broadcast(coolEvent.getMessage()); - } - } -} -``` - -When an event is cancellable, `Event#callEvent()` -will return false if the event was cancelled. This allows you to directly use `callEvent` in your `if` statement, -instead of having to check `Cancellable#isCancelled()` manually. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - // ... - - public void callCoolPaperEvent() { - PaperIsCoolEvent coolEvent = new PaperIsCoolEvent(Component.text("Paper is cool!")); - if (coolEvent.callEvent()) { // Directly get the output from callEvent - Bukkit.broadcast(coolEvent.getMessage()); - } - } -} -``` diff --git a/docs/versioned/paper/content/1.20/dev/api/event-api/event-listeners.mdx b/docs/versioned/paper/content/1.20/dev/api/event-api/event-listeners.mdx deleted file mode 100644 index 522d2f606..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/event-api/event-listeners.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -slug: /dev/event-listeners -description: Developer guide for how to listen to the broadcasted events. ---- - -# Event Listeners - -Events are an efficient way to listen for specific actions that happen in the game. They can be called by the server, or by plugins. -These are called by the server or plugins when something happens, such as a player joining the server, or a block being broken. -Plugins are able to call custom events, such as a player completing a quest, for other plugins to listen for. - -## Your listener class - -To listen for events, you need to create a class that implements `Listener`. -This class can be called anything you want, but it is recommended to name it something related to the events you are listening for. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - // ... -} -``` - -## `@EventHandler` - -To listen for an event, you need to create a method that is annotated with `@EventHandler`. -This method can be named anything you want, but it is recommended to name it something meaningful related to the event it is listening for. - -## The listener method - -The method body does not need to return any data, for this reason, use void as the return type. -Listeners take in a single parameter, which is the event that is being listened to. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerMove(PlayerMoveEvent event) { - // ... - } -} -``` - -:::note[Events] - -There is no list of events that can be listened to, however take a -look here -to see all classes that extend `Event`. - -An event can only be listened to if it has a static `getHandlerList` method. - -::: - -## Registering the listener - -To register the listener, you need to call `Bukkit.getPluginManager().registerEvents()` -and pass in your listener class instance and an instance of your plugin. - -This will register your listener class and allow it to listen for events. -This is commonly done in the `onEnable()` method of your plugin so that it is registered when the server starts ticking. - -```java title="ExamplePlugin.java" -public class ExamplePlugin extends JavaPlugin { - - @Override - public void onEnable() { - getServer().getPluginManager().registerEvents(new ExampleListener(), this); - } -} -``` - -## Event priority - -You can also specify the priority of the event. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler(priority = EventPriority.HIGH) - public void onPlayerMove(PlayerMoveEvent event) { - // ... - } -} -``` -There are six different priorities that you can use: -- `EventPriority.LOWEST` -- `EventPriority.LOW` -- `EventPriority.NORMAL` -- `EventPriority.HIGH` -- `EventPriority.HIGHEST` -- `EventPriority.MONITOR` - -The order of the priorities is somewhat counter-intuitive. The **higher** the priority, the **later** the event is called. -For example, if it is important that your plugin has the last say in a certain event - to avoid it being changed - you -should use `EventPriority.HIGHEST`. - -:::note - -The `MONITOR` priority is used to monitor the event, but not change it. It is called after all other priorities have been called. -This means you can get the result of any plugin interaction such as cancellation or modification. - -::: - -## Event cancellation - -Some events can be cancelled, preventing the given action from being completed. -These events implement `Cancellable`. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerMove(PlayerMoveEvent event) { - event.setCancelled(true); - } -} -``` - -:::warning - -It is important to consider that another plugin could have cancelled or changed the event before your plugin is called. -Always check the event before doing anything with it. - -::: - -The above example will cancel the event, meaning that the player will not be able to move. -Once an event is cancelled, it will continue to call any other listeners for that event unless they add -`ignoreCancelled = true` to the `@EventHandler` annotation to ignore cancelled events. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler(ignoreCancelled = true) - public void onPlayerMove(PlayerMoveEvent event) { - // ... - } -} -``` diff --git a/docs/versioned/paper/content/1.20/dev/api/event-api/handler-lists.mdx b/docs/versioned/paper/content/1.20/dev/api/event-api/handler-lists.mdx deleted file mode 100644 index 511bb2c77..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/event-api/handler-lists.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -slug: /dev/handler-lists -description: An explanation to what an event's HandlerList is. ---- - -# Handler Lists - -Every `Event` that can be listened to has a -`HandlerList` containing all the listeners that are listening to that event. -This list is used to call the listeners when the event is called. - -## Getting the handler list for an event - -To get the handler list for an event, you can call `getHandlerList()` on the specific event class. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - HandlerList handlerList = event.getHandlerList(); - // ... - } - - // Or: - - public ExampleListener() { - // Access the handler list through the static getter - HandlerList handlerList = PlayerJoinEvent.getHandlerList(); - // ... - } -} -``` - -## Unregistering a listener - -To unregister a listener, you can call `unregister()` on the `HandlerList` that the listener is registered to. - -```java title="ExampleListener.java" -public class ExampleListener implements Listener { - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - HandlerList handlerList = event.getHandlerList(); - handlerList.unregister(this); - // ... - } - - // Or: - - public ExampleListener() { - // Access the handler list through the static getter - HandlerList handlerList = PlayerJoinEvent.getHandlerList(); - handlerList.unregister(this); - // Granted this is a pretty stupid example... - } -} -``` - -You can unregister based on `Listener` -or `Plugin` for more convenience. -Likewise, you can also unregister all listeners for a specific event by calling -`unregisterAll()` on the `HandlerList`. diff --git a/docs/versioned/paper/content/1.20/dev/api/folia-support.mdx b/docs/versioned/paper/content/1.20/dev/api/folia-support.mdx deleted file mode 100644 index d105db95f..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/folia-support.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -slug: /dev/folia-support -description: How to support both Folia and Paper within your plugin. ---- - -# Supporting Paper and Folia - -![](/img/folia.png) - -[Folia](https://github.com/PaperMC/Folia) is a fork of Paper, which is currently maintained by the PaperMC team. -It adds the ability to split the world into regions as outlined [here](/folia/reference/overview) in more depth. - -# Checking for Folia - -Depending on what platform your plugin is running on, you may need to implement features differently. For this, you can -use this utility method to check if the current server is running Folia: - -```java -private static boolean isFolia() { - try { - Class.forName("io.papermc.paper.threadedregions.RegionizedServer"); - return true; - } catch (ClassNotFoundException e) { - return false; - } -} -``` - -## Schedulers - -In order to support Paper and Folia, you must use the correct scheduler. Folia has different types of schedulers -that can be used for different things. They are: - -- [Global](#global-scheduler) -- [Region](#region-scheduler) -- [Async](#async-scheduler) -- [Entity](#entity-scheduler) - -If you use these schedulers when running Paper, they will be internally handled to provide the same functionality as if you were -running Folia. - -### Global scheduler -The tasks that you run on the global scheduler will be executed on the global region, see [here](/folia/reference/overview#global-region) for -more information. You should use this scheduler for any tasks that do not belong to any particular region. These can be fetched with: -```java -GlobalRegionScheduler globalScheduler = server.getGlobalRegionScheduler(); -``` - -### Region scheduler -The region scheduler will be in charge of running tasks for the region that owns a certain location. Do not use this scheduler for -operations on entities, as this scheduler is tied to the region. Each entity has its [own scheduler](#entity-scheduler) -which will follow it across regions. As an example, let's say I want to set a block to a beehive: -```java -Location locationToChange = ...; -RegionScheduler scheduler = server.getRegionScheduler(); - -scheduler.execute(plugin, locationToChange, () -> { - locationToChange.getBlock().setType(Material.BEEHIVE); -}); -``` - -We pass the location as a parameter to the `RegionScheduler` -as it needs to work out which region to execute on. - -### Async scheduler -The async scheduler can be used for running tasks independent of the server tick process. This can be fetched with: -```java -AsyncScheduler asyncScheduler = server.getAsyncScheduler(); -``` - -### Entity scheduler -Entity schedulers are used for executing tasks on an entity. These will follow the entity wherever it goes, so you must use -these instead of the region schedulers. -```java -EntityScheduler scheduler = entity.getScheduler(); -``` diff --git a/docs/versioned/paper/content/1.20/dev/api/lifecycle.mdx b/docs/versioned/paper/content/1.20/dev/api/lifecycle.mdx deleted file mode 100644 index 8350b9da7..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/lifecycle.mdx +++ /dev/null @@ -1,159 +0,0 @@ ---- -slug: /dev/lifecycle -description: A guide to Paper's Lifecycle API ---- - -# Lifecycle API - -The lifecycle API can be used for lifecycle-related registration. It is currently used by the -Brigadier command API. It is planned to be used for the Registry Modification API as well. -Generally, systems that are initialized very early in the startup process can take advantage of this -event system. - -:::danger[Experimental] - -The Lifecycle API and anything that uses it is currently experimental and may change in the future. - -::: - -## LifecycleEventManager - -The LifecycleEventManager is tied -to either a Plugin instance or a -BootstrapContext depending on where you access it from. For example in your plugin's main class: - -```java title="TestPlugin.java" -@Override -public void onEnable() { - final LifecycleEventManager lifecycleManager = this.getLifecycleManager(); -} -``` - -Or, with a bootstrapper: - -```java title="TestPluginBootstrap.java" -@Override -public void bootstrap(@NotNull BootstrapContext context) { - final LifecycleEventManager lifecycleManager = context.getLifecycleManager(); -} -``` - -## LifecycleEvents - -After obtaining the correct `LifecycleEventManager`, create a event handler by selecting an -event type from LifecycleEvents: -```java title="TestPlugin.java" -@Override -public void onEnable() { - final LifecycleEventManager lifecycleManager = this.getLifecycleManager(); - PrioritizedLifecycleEventHandlerConfiguration config = LifecycleEvents.SOME_EVENT.newHandler((event) -> { - // Handler for the event - }); -} -``` - -### Configuration - -Each handler created can be configured in several ways. The available configuration options -depend on the event type itself and will vary from event type to event type. - -#### Priority - -Setting the priority of a handler can determine where it runs relative to other handlers -on the same event type. The lower the number, the earlier it will be run. The default priority -is 0. - -#### Monitor - -Marking the handler as a monitor will cause it to be called after all other non-monitor handlers -have been called. Only use this to inspect some state in the event. Do not modify any state in -the handler. - -The priority and monitor state are exclusive options, setting one will reset the other. - -```java title="TestPlugin.java" -@Override -public void onEnable() { - final LifecycleEventManager lifecycleManager = this.getLifecycleManager(); - PrioritizedLifecycleEventHandlerConfiguration config = LifecycleEvents.SOME_EVENT.newHandler((event) -> { - // Handler for the event - }); - config.priority(10); // sets a priority of 10 - // or - config.monitor(); // marks the handler as a monitor -} -``` - -### Registering - -Once the handler has been configured, it can be registered with the lifecycle manager: - -```java title="TestPlugin.java" -@Override -public void onEnable() { - final LifecycleEventManager lifecycleManager = this.getLifecycleManager(); - PrioritizedLifecycleEventHandlerConfiguration config = LifecycleEvents.SOME_EVENT.newHandler((event) -> { - // Handler for the event - }).priority(10); - lifecycleManager.registerEventHandler(config); -} -``` -There is also a shorthand way to register just the handler without doing any configuration: - -```java title="TestPlugin.java" -@Override -public void onEnable() { - final LifecycleEventManager lifecycleManager = this.getLifecycleManager(); - lifecycleManager.registerEventHandler(LifecycleEvents.COMMANDS, (event) -> { - // Handler for the event - }); -} -``` - -:::note - -Some event types have special behaviors that restrict certain mechanics. The reloading plugins -functionality (via `/bukkit:reload` or `Server#reload()`) is disabled if plugins register handlers -in certain situations. This is due to the plugin reloads having to fully unload the plugin and its -classes which is an issue if an event has to run while the plugin is unloaded. - -::: - -## Why does this exist? - -We already have an event system, why do we need another one? This is a fair question. The answer is -that some of these events fire well before `JavaPlugin` instances are created, before the -`MinecraftServer` instance is created, right at the very start of server startup. These can be -before all the registries have been initialized which is one of the first things to happen on a Vanilla -server. The existing Bukkit event system is not designed to exist at this time, and modifying it to -support this environment is more trouble than just having a separate system for specific events that -can fire during this early initialization. - -:::info[Technical Explanation] - -Here is an ever-expanding list of specific reasons why we can't just modify the existing event -system to support this new need for events: - -- You cannot have generics on Bukkit events because there is 0 compile time checking since they are - registered reflectively. This is a problem because the events are mostly going to follow a very - similar pattern, specifically the registry modification events. If we can’t use generics, there’s - going to be many useless classes. - -- Another reason is that the existing system has priorities, but always has them. With the lifecycle - events, there may be some events for which we do not want to support priorities (it would - be based purely on plugin load order then). - -- Exists too late. `HandlerList` and event registration all use the `Plugin` instance which does not exist, - and cannot exist, during the bootstrapper. Changing this would require a substantial rewrite of the - existing system and probably confuse API users who expect all `RegisteredListeners` to have a - Plugin attached. - -- A new system lets us use interfaces and server implementations for events which dramatically - simplifies them. With the Bukkit system you could kind of do this with a server impl event - extending the API event, but interfaces are more flexible. - -- A new system lets us enforce, at compile time, which events you can register where based on the - context of the registration. So you can’t even register a handler for an event in the wrong spot, - that will be a compiler error thanks to our implementation using Generics. - -::: diff --git a/docs/versioned/paper/content/1.20/dev/api/pdc.mdx b/docs/versioned/paper/content/1.20/dev/api/pdc.mdx deleted file mode 100644 index 013346b16..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/pdc.mdx +++ /dev/null @@ -1,189 +0,0 @@ ---- -slug: /dev/pdc -description: A guide to the PDC API for storing data. ---- - -# Persistent Data Container (PDC) - -The Persistent Data Container (PDC) is a way to store custom data on a whole range of objects; such as items, entities, and blocks. -The full list of classes that support the PDC are: - -- [`Chunk`](#chunk) -- [`World`](#world) -- [`Entity`](#entity) -- [`TileState`](#tilestate) -- [`ItemMeta`](#itemmeta) -- [`Structure`](#structure) - -## What is it used for? -In the past, developers resorted to a variety of methods to store custom data on objects: - -- NBT tags: Requires reflection to access internals and was generally unreliable in the long term. -- Lore and display names: Prone to collisions as well as slow to access. - -The benefit of the PDC is that it allows for a more reliable and performant way to store arbitrary data on objects. -It also doesn't rely on accessing server internals, so it's less likely to break on future versions. It also removes the need to -manually track the data lifecycle, as, for example with an entity, the PDC will be saved when the entity unloads. - -## Adding data -To store data in the PDC, there are a few things you need first. The first is a `NamespacedKey`, -which is used to identify the data. The second is a `PersistentDataContainer`, -which is the object you want to store the data on. The third is the data itself. - -```java -// Create a NamespacedKey -NamespacedKey key = new NamespacedKey(pluginInstance, "example-key"); - -ItemStack item = new ItemStack(Material.DIAMOND); -// ItemMeta implements PersistentDataHolder, so we can get the PDC from it -ItemMeta meta = item.getItemMeta(); -meta.getPersistentDataContainer().set(key, PersistentDataType.STRING, "I love Tacos!"); -item.setItemMeta(meta); -``` - -:::info - -It is considered good practice to reuse `NamespacedKey` objects. They can be constructed with either: -- A `Plugin` instance and a `String` identifier -- A `String` namespace and a `String` identifier - -The first option is often preferred as it will automatically use the plugin's namespace; however, the second option can be used if you -want to use a different namespace or access the data from another plugin. - -::: - -## Getting data -To get data from the PDC, you need to know the `NamespacedKey` and the `PersistentDataType` of the data. - -```java -// Create a NamespacedKey -NamespacedKey key = new NamespacedKey(pluginInstance, "example-key"); - -ItemStack item = ...; // Retrieve the item from before -// Get the data from the PDC -PersistentDataContainer container = item.getItemMeta().getPersistentDataContainer(); -if (container.has(key, PersistentDataType.STRING)) { - String value = container.get(key, PersistentDataType.STRING); - // Do something with the value - player.sendMessage(Component.text(value)); -} -``` - -## Data types - -The PDC supports a wide range of data types, such as: -- `Byte`, `Byte Array` -- `Double` -- `Float` -- `Integer`, `Integer Array` -- `Long`, `Long Array` -- `Short` -- `String` -- `Boolean` -- `Tag Containers` - a way to nest PDCs within each other. To create a new `PersistentDataContainer`, you can use: - ```java - // Get the existing container - PersistentDataContainer container = ...; - // Create a new container - PersistentDataContainer newContainer = container.getAdapterContext().newPersistentDataContainer(); - ``` -- `Lists` - a way to represent lists of data that can be stored via another persistent data type. You may create them via: - ```java - // Storing a list of strings in a container by verbosely creating - // a list data type wrapping the string data type. - container.set( - key, - PersistentDataType.LIST.listTypeFrom(PersistentDataType.STRING), - List.of("a", "list", "of", "strings") - ); - - // Storing a list of strings in a container by using the api - // provided pre-definitions of commonly used list types. - container.set(key, PersistentDataType.LIST.strings(), List.of("a", "list", "of", "strings")); - - // Retrieving a list of strings from the container. - List strings = container.get(key, PersistentDataType.LIST.strings()); - ``` - -:::info[Boolean `PersistentDataType`] - -The `Boolean` PDC type exists for convenience -- you cannot make more complex types distill to a `Boolean`. - -::: - -### Custom data types - -You can store a wide range of data in the PDC with the native adapters; however, if you need a more complex data type, you can -implement your own `PersistentDataType` and use that instead. -The `PersistentDataType`'s job is to "deconstruct" a complex data type into something that is natively supported (see above) and then vice-versa. - -Here is an example of how to do that for a UUID: - -```java -public class UUIDDataType implements PersistentDataType { - @Override - public Class getPrimitiveType() { - return byte[].class; - } - - @Override - public Class getComplexType() { - return UUID.class; - } - - @Override - public byte[] toPrimitive(UUID complex, PersistentDataAdapterContext context) { - ByteBuffer bb = ByteBuffer.wrap(new byte[16]); - bb.putLong(complex.getMostSignificantBits()); - bb.putLong(complex.getLeastSignificantBits()); - return bb.array(); - } - - @Override - public UUID fromPrimitive(byte[] primitive, PersistentDataAdapterContext context) { - ByteBuffer bb = ByteBuffer.wrap(primitive); - long firstLong = bb.getLong(); - long secondLong = bb.getLong(); - return new UUID(firstLong, secondLong); - } - } -``` - -:::note - -In order to use your own `PersistentDataType`, you must pass an instance of it to the -`get`/ -`set`/ -`has` methods. -```java -container.set(key, new UUIDDataType(), uuid); -``` - -::: - -## Storing on different objects - -Objects that can have a PDC implement the `PersistentDataHolder` interface -and their PDC can be fetched with `PersistentDataHolder#getPersistentDataContainer()`. - -- ##### `Chunk` - - `Chunk#getPersistentDataContainer()` -- ##### `World` - - `World#getPersistentDataContainer()` -- ##### `Entity` - - `Entity#getPersistentDataContainer()` -- ##### `TileState` - - This is slightly more complicated, as you need to cast the block to something that extends `TileState`. - This does not work for all blocks, only those that have a tile entity. - ```java - Block block = ...; - if (block.getState() instanceof Chest chest) { - chest.getPersistentDataContainer().set(key, PersistentDataType.STRING, "I love Tacos!"); - chest.update(); - } - ``` -- ##### `Structure` - - `Structure#getPersistentDataContainer()` -- ##### `ItemMeta` - - `ItemMeta#getPersistentDataContainer()` diff --git a/docs/versioned/paper/content/1.20/dev/api/plugin-configs.mdx b/docs/versioned/paper/content/1.20/dev/api/plugin-configs.mdx deleted file mode 100644 index 4fa782d71..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/plugin-configs.mdx +++ /dev/null @@ -1,169 +0,0 @@ ---- -slug: /dev/plugin-configurations -description: How to create configuration files for your plugins to customize behavior. ---- - -# Plugin Configurations - -Configuration files allow users to change certain behavior and functionality of plugins. This guide will outline how to use them. - -## Format - -By default, plugins use a YAML configuration format (`.yml` file). Other formats, such as JSON or TOML, can be used; -however, these are not natively supported by Paper, so they will not be covered in this guide. - -YAML works by having a tree-like `key: value` pair structure, as you would have seen in your [`plugin.yml`](../getting-started/plugin-yml.mdx). -An example would look like this: - -```yaml -root: - one-key: 10 - another-key: David -``` - -When accessing indented values, you separate the levels with dots (`.`). For example, the key for the `David` string would be `root.another-key`. - -## Creating a `config.yml` - -By placing a `config.yml` file inside your plugin, you can specify the default values for certain settings. -This will be located in the `resources` directory: -``` -example-plugin -└── src - └── main - ├── java - └── resources - ├── config.yml - └── plugin.yml -``` - -When your plugin is initialized, you must save this resource into the plugin's data directory, so that a user can edit the values. -Here is an example of how you would do this in your plugin's `onEnable`: - -```java -public class TestPlugin extends JavaPlugin { - - @Override - public void onEnable() { - saveResource("config.yml", /* replace */ false); - - // You can also use this for configuration files: - saveDefaultConfig(); - // Where the default config.yml will be saved if it does not already exist - - // getConfig()... - } - -} -``` - -:::info - -The boolean `replace` parameter specifies whether it should replace an existing file if one exists. -If set to true, the configuration will be overwritten on every call. - -::: - -## Getting and setting data - -The `FileConfiguration` of the plugin can be fetched with -`JavaPlugin#getConfig()` once it has been saved. -This will allow data to be fetched and set with the respective `#get...(key)` and -`#set(key, value)`. -By default, most basic data types are supported by YAML. These can be fetched simply with -`#getString(key)` or -`#getBoolean(key)`. - -However, some more complex Bukkit data types are also supported. A few of these include -`ItemStack`, -`Location` and `Vector`s. -Here is an example of loading a value from the config for teleporting a player: - -:::info[Saving Configs] - -Whenever setting data in configurations, you must call -`FileConfiguration#save(File/String)` -for the changes to be persisted to disk. - -::: - -```java -public class TestPlugin extends JavaPlugin { - public void teleportPlayer(Player player) { - Location to = getConfig().getLocation("target_location"); - player.teleport(to); - } -} -``` - -This is possible as they implement `ConfigurationSerializable`. -You can use this yourself, by implementing and registering a custom class. - -```java -public class TeleportOptions implements ConfigurationSerializable { - private int chunkX; - private int chunkZ; - private String name; - - public TeleportOptions(int chunkX, int chunkZ, String name) { - // Set the values - } - - public Map serialize() { - Map data = new HashMap<>(); - - data.put("chunk-x", this.chunkX); - data.put("chunk-z", this.chunkZ); - data.put("name", this.name); - - return data; - } - - public static TeleportOptions deserialize(Map args) { - return new TeleportOptions( - (int) args.get("chunk-x"), - (int) args.get("chunk-z"), - (String) args.get("name") - ); - } -} -``` - -Here we can see that we have an instance-based `serialize` method, which returns a map, and then a static `deserialize` -method that takes a `Map` as a parameter and returns an instance -of the `TeleportOptions` class. Finally, for this to work, we must call: -`ConfigurationSerialization.registerClass(TeleportOptions.class)` - -:::warning - -If you do not call `ConfigurationSerialization#registerClass(Class)` -with Paper plugins, you will not be able to load nor save your custom classes. - -::: - -## Custom configuration files - -It is highly likely that you will have many different things to configure in your plugin. If you choose to split these -across multiple different files, you can still use the Bukkit `FileConfiguration` API to read the data from these. -It is as simple as: - -```java -File file = new File(plugin.getDataFolder(), "items.yml"); -YamlConfiguration config = YamlConfiguration.loadConfiguration(file); -// Work with config here -config.save(file); -``` - -This example reads the `items.yml` file from your plugin's data directory. This file must exist, else an error will be thrown. - -:::danger[Blocking I/O] - -Loading and saving files on the main thread will slow your server. `load` and `save` operations should be executed asynchronously. - -::: - -## Configurate - -Configurate is a third-party library for working with configurations, maintained by the Sponge project. This project is -used internally by Paper for its configuration and offers many features that the `FileConfiguration` API doesn't have. See their project -[here](https://github.com/SpongePowered/Configurate) for more information. diff --git a/docs/versioned/paper/content/1.20/dev/api/plugin-messaging.mdx b/docs/versioned/paper/content/1.20/dev/api/plugin-messaging.mdx deleted file mode 100644 index 817820917..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/plugin-messaging.mdx +++ /dev/null @@ -1,226 +0,0 @@ ---- -slug: /dev/plugin-messaging -description: How to communicate with clients or proxies. ---- - -# Plugin Messaging - -First introduced in [2012](https://web.archive.org/web/20220711204310/https://dinnerbone.com/blog/2012/01/13/minecraft-plugin-channels-messaging/), -Plugin messaging is a way for plugins to communicate with clients. When your servers are behind a proxy, -it will allow your plugins to communicate with the proxy server. - -## BungeeCord channel - -The BungeeCord channel is used for communication between your Paper server and a BungeeCord (or a BungeeCord-compatible) proxy. - -Originally, the channel supported by the BungeeCord proxy was called `BungeeCord`. In versions 1.13 and above, -the channel was renamed to `bungeecord:main` to create a key structure for plugin messaging channels. - -Paper handles this change internally and automatically changes any messages sent on the `BungeeCord` channel -to the `bungeecord:main` channel. This means that your plugins should continue to use the `BungeeCord` channel. - -## Sending plugin messages - -First, we're going to take a look at your Paper server. Your plugin will need to register that it -will be sending on any given plugin channel. You should to do this alongside your other event listener registrations. - -```java -public final class PluginMessagingSample extends JavaPlugin { - - @Override - public void onEnable() { - getServer().getMessenger().registerOutgoingPluginChannel(this, "BungeeCord"); - // Blah blah blah... - } - -} -``` - -Now that we're registered, we can send messages on the `BungeeCord` channel. - -Plugin messages are formatted as byte arrays and can be sent using the `sendPluginMessage` -method on a `Player` object. -Let's take a look at an example of sending a plugin message to the `BungeeCord` channel to send our player to another server. - -```java -public final class PluginMessagingSample extends JavaPlugin implements Listener { - - @Override - public void onEnable() { - getServer().getPluginManager().registerEvents(this, this); - getServer().getMessenger().registerOutgoingPluginChannel(this, "BungeeCord"); - } - - @EventHandler - public void onPlayerJump(PlayerJumpEvent event) { - Player player = event.getPlayer(); - - ByteArrayDataOutput out = ByteStreams.newDataOutput(); - out.writeUTF("Connect"); - out.writeUTF("hub2"); - player.sendPluginMessage(this, "BungeeCord", out.toByteArray()); - } - -} -``` - -:::tip - -These channels rely on the Minecraft protocol, and are sent as a special type of packet called a -[Plugin Message](https://minecraft.wiki/w/Minecraft_Wiki:Projects/wiki.vg_merge/Plugin_channels). They piggyback on player connections, so if there is no -player connected to the server, it will not be able to send or receive plugin messages. - -::: - -### What did we just do? - -We sent a plugin message on the `BungeeCord` channel! The message we sent was a byte array that contained two strings converted to bytes: `Connect` and `hub2`. - -Our proxy server received the message through the player who triggered the `PlayerJumpEvent` on our Java server. -Then, it recognized the channel as its own and, in alignment with BungeeCord's protocol, sent our player to the `hub2` server. - -For BungeeCord, we can think of this message as a case-sensitive command with arguments. -Here, our command is `Connect` and our only argument is `hub2`, but some "commands" may have multiple arguments. -For other channels introduced by client side mods, refer to their documentation to best understand how to format your messages. - -### Plugin message types - -Although we sent a `Connect` message to the proxy, there are a few other cases that BungeeCord-compatible proxies will act on. -These are the following: - -| Message Type | Description | Arguments | Response | -|:------------------|:-------------------------------------------------------|:-----------------------------------------------------------------|:--------------------------------------------------| -| `Connect` | Connects the player to the specified server. | `server name` | N/A | -| `ConnectOther` | Connects another player to the specified server. | `player name`, `server name` | N/A | -| `IP` | Returns the IP of the specified player. | `player name` | `IP`, `port` | -| `PlayerCount` | Returns the number of players on the specified server. | `server name` | `server name`, `player count` | -| `PlayerList` | Returns a list of players on the specified server. | `server name` | `server name`, `CSV player names` | -| `GetServers` | Returns a list of all servers. | N/A | `CSV server names` | -| `Message` | Sends a message to the specified player. | `player name`, `message` | N/A | -| `MessageRaw` | Sends a raw chat component to the specified player. | `player name`, `JSON chat component` | N/A | -| `GetServer` | Returns the server the player is connected to. | N/A | `server name` | -| `UUID` | Returns the UUID of player. | N/A | `UUID` | -| `UUIDOther` | Returns the UUID of the specified player. | `player name` | `player name`, `UUID` | -| `ServerIp` | Returns the IP of the specified server. | `server name` | `server name`, `IP`, `port` | -| `KickPlayer` | Kicks the specified player. | `player name`, `reason` | N/A | -| `Forward` | Forwards a plugin message to another server. | `server`, `subchannel`, `size of plugin message`, `message` | `subchannel`, `size of plugin message`, `message` | -| `ForwardToPlayer` | Forwards a plugin message to another player. | `player name`, `subchannel`, `size of plugin message`, `message` | `subchannel`, `size of plugin message`, `message` | - -#### `PlayerCount` - -```java -public class MyPlugin extends JavaPlugin implements PluginMessageListener { - - @Override - public void onEnable() { - this.getServer().getMessenger().registerOutgoingPluginChannel(this, "BungeeCord"); - this.getServer().getMessenger().registerIncomingPluginChannel(this, "BungeeCord", this); - - Player player = ...; - ByteArrayDataOutput out = ByteStreams.newDataOutput(); - out.writeUTF("PlayerCount"); - out.writeUTF("lobby"); - player.sendPluginMessage(this, "BungeeCord", out.toByteArray()); - // The response will be handled in onPluginMessageReceived - } - - @Override - public void onPluginMessageReceived(String channel, Player player, byte[] message) { - if (!channel.equals("BungeeCord")) { - return; - } - ByteArrayDataInput in = ByteStreams.newDataInput(message); - String subchannel = in.readUTF(); - if (subchannel.equals("PlayerCount")) { - // This is our response to the PlayerCount request - String server = in.readUTF(); - int playerCount = in.readInt(); - } - } -} -``` - -#### `Forward` - -```java -public class MyPlugin extends JavaPlugin implements PluginMessageListener { - - @Override - public void onEnable() { - this.getServer().getMessenger().registerOutgoingPluginChannel(this, "BungeeCord"); - this.getServer().getMessenger().registerIncomingPluginChannel(this, "BungeeCord", this); - - Player player = ...; - ByteArrayDataOutput out = ByteStreams.newDataOutput(); - out.writeUTF("Forward"); - out.writeUTF("ALL"); // This is the target server. "ALL" will message all servers apart from the one sending the message - out.writeUTF("SecretInternalChannel"); // This is the channel. - - ByteArrayOutputStream msgbytes = new ByteArrayOutputStream(); - DataOutputStream msgout = new DataOutputStream(msgbytes); - msgout.writeUTF("Paper is the meaning of life"); // You can do anything you want with msgout - msgout.writeShort(42); // Writing a random short - - out.writeShort(msgbytes.toByteArray().length); // This is the length. - out.write(msgbytes.toByteArray()); // This is the message. - - player.sendPluginMessage(this, "BungeeCord", out.toByteArray()); - // The response will be handled in onPluginMessageReceived - } - - @Override - public void onPluginMessageReceived(String channel, Player player, byte[] message) { - if (!channel.equals("BungeeCord")) { - return; - } - ByteArrayDataInput in = ByteStreams.newDataInput(message); - String subchannel = in.readUTF(); - if (subchannel.equals("SecretInternalChannel")) { - short len = in.readShort(); - byte[] msgbytes = new byte[len]; - in.readFully(msgbytes); - - DataInputStream msgIn = new DataInputStream(new ByteArrayInputStream(msgbytes)); - String secretMessage = msgIn.readUTF(); // Read the data in the same way you wrote it - short meaningofLife = msgIn.readShort(); - } - } -} -``` - -This message is used to forward a plugin message to another server. This is useful for server-to-server communication within a proxy network. -For example, if a certain player is banned on one server, you can forward a message to all other servers to ban them there too. - -:::caution[Example of banning a player on all servers] - -This is not a recommended way to ban players, due to the fact that there may not be anyone online on the target servers, -but it is an example of how this can be used. - -::: - -#### `MessageRaw` - -The `MessageRaw` message type is used to send a raw chat component to a player. The target player is specified -by the second parameter - Player name or "ALL" for all players. This is also useful for sending messages to -players who are on a different server within the proxied network. - -```java -public class MyPlugin extends JavaPlugin { - - @Override - public void onEnable() { - this.getServer().getMessenger().registerOutgoingPluginChannel(this, "BungeeCord"); - - Player player = ...; - ByteArrayDataOutput out = ByteStreams.newDataOutput(); - out.writeUTF("MessageRaw"); - out.writeUTF("ALL"); - out.writeUTF(GsonComponentSerializer.gson().serialize( - Component.text("Click Me!").clickEvent(ClickEvent.openUrl("https://papermc.io")) - )); - player.sendPluginMessage(this, "BungeeCord", out.toByteArray()); - } -} -``` - -This will send the player a clickable message saying "Click Me!" that opens `https://papermc.io` upon clicking. diff --git a/docs/versioned/paper/content/1.20/dev/api/recipes.mdx b/docs/versioned/paper/content/1.20/dev/api/recipes.mdx deleted file mode 100644 index dde1a6644..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/recipes.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -slug: /dev/recipes -description: How to create and manage recipes. ---- - -# Recipe API - -Recipes are a way to define a way to craft a particular item. They are defined by a plugin or -datapack, however we are only going to cover the plugin side of things here. - -## `ShapedRecipe` - -A shaped recipe is a recipe that requires a specific pattern of items in the crafting grid to craft an item. -These are created using a pattern string and a map of characters to items. The pattern strings are 3, -3-character strings that represent the rows of the crafting grid. They can be created as follows: - -```java -public class TestPlugin extends JavaPlugin { - @Override - public void onEnable() { - NamespacedKey key = new NamespacedKey(this, "WarriorSword"); - ItemStack item = new ItemStack(Material.DIAMOND_SWORD); - - ShapedRecipe recipe = new ShapedRecipe(key, item); - recipe.shape(" A ", "AAA", " B "); - recipe.setIngredient('A', Material.DIAMOND); - recipe.setIngredient('B', Material.STICK); - - getServer().addRecipe(recipe); - } -} -``` - -This recipe would require a diamond sword to be crafted with a diamond in the top row, a stick in -the middle row, and a diamond in the bottom row. The diamond sword would be in the middle column of -the bottom row. The result would look like this in the crafting grid: - -``` - A -AAA - B -``` - -:::info - -You do not need to register the recipe within your plugin's `onEnable` method, You can register it -at any time. However, if you do not register it after the plugin has been enabled and there are -players online, you will need to either resend all the recipes to the players or use the boolean -parameter in the `addRecipe` -method to update all players with the new recipe. - -::: - -:::warning - -You cannot use Air as a material in a shaped recipe, this will cause an error. - -::: - - -## `ShapelessRecipe` - -A shapeless recipe is a recipe that requires a specific number of items in the crafting grid to craft an item. -These are created using a list of items. They can be created as follows: - -```java -public class TestPlugin extends JavaPlugin { - @Override - public void onEnable() { - NamespacedKey key = new NamespacedKey(this, "WarriorSword"); - ItemStack item = new ItemStack(Material.DIAMOND_SWORD); - - ShapelessRecipe recipe = new ShapelessRecipe(key, item); - recipe.addIngredient(3, Material.DIAMOND); - recipe.addIngredient(2, Material.STICK); - - getServer().addRecipe(recipe); - } -} -``` - -This recipe declares that you simply need 3 diamonds and 2 sticks to craft the item, without any specific -orientation of the cross pattern in the crafting grid. This could be crafted in any of the following ways: -``` - DSS | SDS | S D - D | D | D - D | D | D S -``` -And, any other composition of the 5 items. diff --git a/docs/versioned/paper/content/1.20/dev/api/roadmap.mdx b/docs/versioned/paper/content/1.20/dev/api/roadmap.mdx deleted file mode 100644 index d6d0003fb..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/roadmap.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -slug: /dev/roadmap -description: Outlines the future intents and plans of the Paper project. ---- - -# Roadmap - -Paper offers a rich API with a wide range of features that can help you unlock the full potential of your server. -However, in order to make room for new features and improvements, some of the older APIs will be phased out. This page -is intended to document any future API changes that are planned or possible deprecations that may be coming up. - -## Future plans - -### Interface `ItemStack`s - -When you create `ItemStack`s, you create an API representation of an `ItemStack`. -However, there are also places where you can obtain an `ItemStack` that is backed by a NMS object instead. -This can lead to inconsistencies and unnecessary upkeep, since we need to maintain our own `ItemStack` implementation and also -support the NMS-backed object using ugly methods due to it not being a plain interface. - -In the future, `ItemStack` will be converted to an interface that allows developers to use an underlying -`ItemStack` directly, instead of going through the API implementation. - -#### Precautions - -- Avoid directly extending the `ItemStack` class. - - Custom implementations of this class are not supported. - -### `ServerPlayer` reuse -*Note: Only applies to NMS usage, will not apply to API.* - -Avoid directly storing player (`ServerPlayer`) entity instances. Currently, the player instance is reused when switching -worlds, however, in the future, this behavior will be reverted to match Vanilla behavior. API entities (wrappers) will -continue to function and will have their underlying instance replaced automatically. - -This is done to help reduce possible inconsistencies between world switching between Vanilla and Paper. - -## Deprecation policy - -:::warning - -It is highly recommended that you avoid using any APIs that are marked as deprecated. - -::: - -If you continue to use deprecated APIs, your server may become unstable and may not function as expected. -You may also experience performance issues and other problems. To ensure the best possible experience and longevity -of your plugins, it is important to stay up-to-date with the latest API changes and avoid using any APIs -that are marked for deprecation. - -API marked with `@Deprecated` should not be used in your code base, -as alternative API may be able to be used instead. While certain API may continue to function despite being deprecated, -it **cannot** be promised that this API won't be marked as deprecated for removal in the future. -```java -@Deprecated -public void exampleMethod(); // Example deprecated method -``` - -### Deprecated for removal - -In addition to being marked as `@Deprecated`, API may be marked as `forRemoval` with a given -[`@ApiStatus.ScheduledForRemoval`](https://javadoc.io/doc/org.jetbrains/annotations/latest/org/jetbrains/annotations/ApiStatus.ScheduledForRemoval.html) version. -API scheduled for removal should only occur within major release versions of Minecraft. -It is highly recommended you migrate away from API scheduled for removal. - -It should be noted, that API scheduled for removal will be given adequate time to allow plugin developers to migrate -away from said API. -```java -@ApiStatus.ScheduledForRemoval(inVersion = "1.20") -@Deprecated(forRemoval = true) -public void exampleMethod(); // Example method marked for removal in 1.20 -``` - -## Deprecation reasons - -There are many possible reasons why an API might be deprecated. -Some of the common reasons why API can be deprecated is: - -### Old API - -As the game evolves, the API may represent concepts that no longer exist in the core game. - -Old API is most likely not functional and/or may behave unexpectedly in newer versions of the game, -therefore it may be scheduled for removal. - -### Duplicate API - -As Paper continues to upstream Spigot, it can occasionally include APIs that clash with what Paper already has. -Typically, Paper will deprecate Spigot’s API in favor of their own API. - -However, in cases where upstream offers a more powerful API, Paper’s may be deprecated instead. -While Paper is still upstreaming Spigot, any API introduced by Spigot will continue to function, and will -not be removed. - -### Obsolete API -Paper strives to improve on APIs that may already be included. There may be some cases where we have built new -APIs to offer as a replacement to another. - -Obsolete API is expected for function for the far future and may not be scheduled for removal -for a fair amount of time. diff --git a/docs/versioned/paper/content/1.20/dev/api/scheduler.mdx b/docs/versioned/paper/content/1.20/dev/api/scheduler.mdx deleted file mode 100644 index 35d99b82a..000000000 --- a/docs/versioned/paper/content/1.20/dev/api/scheduler.mdx +++ /dev/null @@ -1,222 +0,0 @@ ---- -slug: /dev/scheduler -description: A guide on how to use BukkitScheduler to run code at specific times. ---- - -# Using the Scheduler - -The `BukkitScheduler` can be used to schedule your code to be run later or repeatedly. - -:::info[Folia] - -This guide is designed for non-Folia Bukkit servers. If you are using Folia, you should use its respective schedulers. - -::: - -## What is a tick? - -Every game runs something called a game loop ,which essentially executes all the logic of the game over and over. -A single execution of that loop in Minecraft is called a 'tick'. - -In Minecraft, there are 20 ticks per second or in other words, one tick every 50 milliseconds. This means that the game loop is executed -20 times per second. A tick taking more than 50ms to execute is the moment when your server starts to fall behind on -its work and lag. - -A task that should run after 100 ticks will run after 5 seconds (100 ticks / 20 ticks per second = 5 seconds). However, -if the server is only running at 10 ticks per second, a task that is scheduled to run after 100 ticks will take 10 -seconds. - -### Converting between human units and Minecraft ticks - -Every method of the scheduler that takes a delay or period uses ticks as a unit of time. - -Converting from human units to ticks and back is as simple as: -- `ticks = seconds * 20` -- `seconds = ticks / 20` - -You can make your code more readable by using the -`TimeUnit` -enum, e.g. to convert 5 minutes to ticks and back: -- `TimeUnit.MINUTES.toSeconds(5) * 20` -- `TimeUnit.SECONDS.toMinutes(ticks / 20)` - -You can also use the `Tick` class from Paper to convert between human units and ticks, e.g. to convert 5 minutes to ticks: -`Tick.tick().fromDuration(Duration.ofMinutes(5))` will yield `6000` ticks. - -## Obtaining the scheduler - -To obtain a scheduler, you can use the `getScheduler` method -on the `Server` class, e.g. in your `onEnable` method: - -```java -@Override -public void onEnable() { - BukkitScheduler scheduler = this.getServer().getScheduler(); -} -``` - -## Scheduling tasks - -Scheduling a task requires you to pass: - -- Your plugin's instance -- The code to run, either with a `Runnable` -or `Consumer``<``BukkitTask``>` -- The delay in ticks before the task should run for the first time -- The period in ticks between each execution of the task, if you're scheduling a repeating task - -### Difference between synchronous and asynchronous tasks - -#### Synchronous tasks (on the main thread) - -Synchronous tasks are tasks that are executed on the main server thread. This is the same -thread that handles all game logic. - -All tasks scheduled on the main thread will affect the server's performance. If your task -is making web requests, accessing files, databases or otherwise time-consuming operations, you should consider using -an asynchronous task. - -#### Asynchronous tasks (off the main thread) - -Asynchronous tasks are tasks that are executed on separate threads, therefore will not directly affect -your server's performance. - -:::warning - -**Large portions of the Bukkit API are not safe to use from within asynchronous tasks**. If a method changes or -accesses the world state, it is not safe to be used from an asynchronous task. - -::: - -:::info - -While the tasks are executed on separate threads, they are still started from the main thread -and will be affected if the server is lagging, an example would be 20 ticks not being exactly 1 second. - -If you need a scheduler that runs independently of the server, consider using your own -`ScheduledExecutorService`. -You can follow [this guide](https://www.baeldung.com/java-executor-service-tutorial#ScheduledExecutorService) to learn how to use it. - -::: - -### Different ways to schedule tasks - -#### Using `Runnable` - -The `Runnable` interface is used for the simplest tasks -that don't require a `BukkitTask` instance. - -You can either implement it in a separate class, e.g.: - -```java -public class MyRunnableTask implements Runnable { - - private final MyPlugin plugin; - - public MyRunnableTask(MyPlugin plugin) { - this.plugin = plugin; - } - - @Override - public void run() { - this.plugin.getServer().broadcast(Component.text("Hello, World!")); - } - -} -``` -```java -scheduler.runTaskLater(plugin, new MyRunnableTask(plugin), 20); -``` - -Or use a lambda expression, which is great for simple and short tasks: - -```java -scheduler.runTaskLater(plugin, /* Lambda: */ () -> { - this.plugin.getServer().broadcast(Component.text("Hello, World!")); -}, /* End of the lambda */ 20); -``` - -#### Using `Consumer` - -The `Consumer` interface is used for tasks -that require a `BukkitTask` instance (usually in repeated tasks), -e.g. when you want to cancel the task from inside it. - -You can either implement it in a separate class similarly to the `Runnable`, e.g.: - -```java -public class MyConsumerTask implements Consumer { - - private final UUID entityId; - - public MyConsumerTask(UUID uuid) { - this.entityId = uuid; - } - - @Override - public void accept(BukkitTask task) { - Entity entity = Bukkit.getServer().getEntity(this.entityId); - - if (entity instanceof LivingEntity livingEntity) { - livingEntity.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, 20, 1)); - return; - } - - task.cancel(); // The entity is no longer valid, there's no point in continuing to run this task - } -} -``` -```java -scheduler.runTaskTimer(plugin, new MyConsumerTask(someEntityId), 0, 20); -``` - -Or use a lambda expression, which again is much cleaner for short and simple tasks: - -```java -scheduler.runTaskTimer(plugin, /* Lambda: */ task -> { - Entity entity = Bukkit.getServer().getEntity(entityId); - - if (entity instanceof LivingEntity livingEntity) { - livingEntity.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, 20, 1)); - return; - } - - task.cancel(); // The entity is no longer valid, there's no point in continuing to run this task -} /* End of the lambda */, 0, 20); -``` - -##### Using `BukkitRunnable` - -`BukkitRunnable` is a class that implements `Runnable` -and holds a `BukkitTask` instance. This means that you do not need to access the task from inside the `run()` method, -you can simply use the `this.cancel()` method: - -```java -public class CustomRunnable extends BukkitRunnable { - - private final UUID entityId; - - public CustomRunnable(UUID uuid) { - this.entityId = uuid; - } - - @Override - public void run() { - Entity entity = Bukkit.getServer().getEntity(this.entityId); - - if (entity instanceof LivingEntity livingEntity) { - livingEntity.addPotionEffect(new PotionEffect(PotionEffectType.SPEED, 20, 1)); - return; - } - - task.cancel(); // The entity is no longer valid, there's no point in continuing to run this task - } -} -``` - -This simply adds a potion effect until the entity dies. - -#### Using a delay of 0 ticks - -A delay of 0 ticks is treated as you wanting to run the task on the next tick. If you schedule a task with a delay of 0 ticks -while the server is starting, or before it is enabled, it will be executed before the server is enabled. diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/README.mdx b/docs/versioned/paper/content/1.20/dev/getting-started/README.mdx deleted file mode 100644 index 1f89bab23..000000000 --- a/docs/versioned/paper/content/1.20/dev/getting-started/README.mdx +++ /dev/null @@ -1,11 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Development Guide - -Welcome to the Paper development guide! This guide includes information and tutorials on -how to start developing plugins for Paper. - ---- - - diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/assets/installing-plugin.png b/docs/versioned/paper/content/1.20/dev/getting-started/assets/installing-plugin.png deleted file mode 100644 index f4ebb6716..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/getting-started/assets/installing-plugin.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/assets/new-project-paper.png b/docs/versioned/paper/content/1.20/dev/getting-started/assets/new-project-paper.png deleted file mode 100644 index 99f7b7c03..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/getting-started/assets/new-project-paper.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/assets/paper-plugin-overview.png b/docs/versioned/paper/content/1.20/dev/getting-started/assets/paper-plugin-overview.png deleted file mode 100644 index 8b42e5b27..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/getting-started/assets/paper-plugin-overview.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/assets/restart-ide.png b/docs/versioned/paper/content/1.20/dev/getting-started/assets/restart-ide.png deleted file mode 100644 index 78dc17107..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/getting-started/assets/restart-ide.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/how-do-plugins-work.mdx b/docs/versioned/paper/content/1.20/dev/getting-started/how-do-plugins-work.mdx deleted file mode 100644 index be0419d78..000000000 --- a/docs/versioned/paper/content/1.20/dev/getting-started/how-do-plugins-work.mdx +++ /dev/null @@ -1,128 +0,0 @@ ---- -slug: /dev/how-do-plugins-work -description: How plugins work in Paper. ---- - -# How Plugins Work - -## Introduction - -Plugins are a way to extend the functionality of a Minecraft server. They are written in JVM-based languages such as -Java, Kotlin, Groovy or Scala. Plugins are loaded from the `plugins` folder in the server directory. Plugins will be -loaded from a `.jar` file. Each plugin has a main class that is specified in the plugin's `plugin.yml` file. This -class must extend JavaPlugin, and is the entry point for the plugin and is where the plugin's lifecycle methods are -defined. - -:::warning - -We do not recommend writing code inside your main class's constructor as there are no guarantees about what -API is available at that point. Instead, you should use the `onLoad` method to initialize your plugin. Also, -do not call your plugin's constructor directly. This will cause issues with your plugin. - -::: - -## Plugin lifecycle - -Plugins are loaded and unloaded at runtime. When a plugin is loaded, it is initialized and enabled. When a plugin is -unloaded, it is disabled and finalized. - -### Initialization - -When a plugin is loaded, it is initialized. This means that the plugin is loaded into memory and its `onLoad` -method is called. This method is used to initialize the plugin and set up any resources that it needs. Most of the -Bukkit API is not available at this point, so it is not safe to interact with it. - -### Enabling - -When a plugin is enabled, its `onEnable` method is called. This method is used to set up any resources that the plugin -needs to run. This method is called when the plugin is initialized but before the server has started ticking, so it is -safe to register event listeners and other resources that the plugin needs to run, however often not safe to interact -with a lot of APIs. - -This is when you can also open database connections, start threads, and other things that are not safe to do in the -`onLoad` method. - -### Disabling - -When a plugin is disabled, its `onDisable` method is called. This method is used to clean up any resources that the -plugin has allocated. This method is called before all plugins are unloaded, and is meant for any cleanup that needs to -be done before the plugin is unloaded. This may include saving data to disk or closing connections to databases. - -## Event listeners - -Events are a way for plugins to listen to things that happen in the server and run code when they are fired. For -example, `PlayerJoinEvent` is fired when a player -joins the server. This is a more performant way to run code when something happens, as opposed to constantly checking. -See our [event listener page](/paper/dev/event-listeners) for more. - -Some events are cancellable. This means that when the event is fired, it can be cancelled which negates or stops the -effect of the event. For example, `PlayerMoveEvent` -is cancellable. This means that when it is cancelled, the player will not move. This is useful for things like anti-cheat, -where you want to cancel the event if the player is moving too fast. - -It is important to think about how "hot" an event is when writing event listeners. A "hot" event is an event that is fired -very often. For example, `PlayerMoveEvent` is fired every time a player moves. This means that if you have a lot of -expensive code in your event listener, it will be run every time a player moves. This can cause a lot of lag. It is -important to keep event listeners as lightweight as possible. One possible way is to quickly check if the event should -be handled, and if not, return. For example, if you only want to handle the event if the player is moving from one block -to another, you can check if the player's location has changed blocks. If it hasn't, you can return from the listener. - -## Commands - -Commands are a way for players, the console, RCON and command blocks to run code on the server. Commands are registered -by plugins and can be run by command senders. For example, the `/help` command is registered by the server and can be -run by players. Commands can be run by players by typing them in the chat or by running them from a command block. - -Commands can have arguments. For example, the `/give` command takes an argument for the player to give the item to and -an argument for the item to give. Arguments are separated by spaces. For example, the command `/give Notch diamond` will -give the player named Notch a diamond. Note here that the arguments are `["Notch", "diamond"]`. - -### Permissions - -Permissions are a way to control who can run commands and who can listen to events. Permissions -are registered by plugins and can be checked by other plugins. Permissions can be granted to players and groups. -Permissions can have a hierarchical nature, if defined so by the plugin in their `plugin.yml`. For example, a -plugin can define `example.command.help` as a sub-permission of `example.command`. This means that if a player -has the `example.command` permission, they will also have the `example.command.help` permission. - -:::note - -Permission plugins can allow the usage of wildcard permissions using the `*` character to grant any permission -or sub-permission available, allowing hierarchical permissions even if not set by the plugin itself. For example, -granting `example.command.*` through a permission plugin with wildcard support will grant access to all permissions -starting with `example.command.` itself. - -It is **not** recommended to use wildcard permissions, especially `*` (All permissions), as it can be a huge -security risk, as well as potentially causing unwanted side effects to a player. Use with caution. - -::: - -## Configuration - -Plugins can have configuration files. These files are used to store data that the plugin needs to run. For example, a -plugin that adds a new block to the game might have a configuration file that stores the block's ID. Configuration files -should be stored in the plugin's data folder, within the `plugins` folder. The server offers a YAML configuration API -that can be used to read and write configuration files. See [here](/paper/dev/plugin-configurations) for more information. - -## Scheduling tasks - -Plugins can schedule tasks to run at a later time. This is useful for things like running code after a certain amount -of time has passed. For example, a plugin might want to run code after 5 seconds. This can be done by scheduling a task -to run after 100 ticks - one second is 20 ticks during normal operation. It is important to note that tasks might be -delayed if the server is lagging. For example, if the server is only running at 10 ticks per second, a task that is -scheduled to run after 100 ticks will take 10 seconds. - -In Java, typically you could use `Thread#sleep()` to delay -the execution of code. However, if the code is running on the main thread, this will cause the server to pause for the -delay. Instead, you should use the `Scheduler` API to schedule tasks to run later. -Learn more about the `Scheduler` API [here](/paper/dev/scheduler). - -## Components - -Since Minecraft 1.7 and the introduction of "components", plugins can now send messages to players that contain -rich text. This means that plugins can send messages that contain things like colors, bold text, and clickable links. -Colors were always possible, but only through the use of legacy color codes. - -Paper implements a library called `Adventure` that makes it easy to create and send messages to players. Learn more -about the `Adventure` API [here](https://docs.advntr.dev/) from their docs or our docs -[here](/paper/dev/component-api/introduction). diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/paper-plugins.mdx b/docs/versioned/paper/content/1.20/dev/getting-started/paper-plugins.mdx deleted file mode 100644 index 08a561b68..000000000 --- a/docs/versioned/paper/content/1.20/dev/getting-started/paper-plugins.mdx +++ /dev/null @@ -1,216 +0,0 @@ ---- -slug: /dev/getting-started/paper-plugins -description: A development guide for how to write Paper-specific plugins. ---- - -# Paper Plugins (Experimental) - -Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to -expand the field of what the Paper API is able to introduce. - -:::danger[Experimental] - -This is experimental and may be subject to change. - -::: - -- [Bootstrapper](#bootstrapper) -- [Loader](#loaders) -- [Differences](#differences) - -## How do I use them? -Similarly to Bukkit plugins, you have to introduce a `paper-plugin.yml` file into your JAR resources folder. -This will not act as a drop-in replacement for `plugin.yml`, as some things, as outlined in this guide, need to be declared differently. - -It should be noted that you still have the ability to include both `paper-plugin.yml` and `plugin.yml` in the same JAR. - -Here is an example configuration: - -``` -name: Paper-Test-Plugin -version: '1.0' -main: io.papermc.testplugin.TestPlugin -description: Paper Test Plugin -api-version: '%%_MAJ_MIN_PAT_MC_%%' -bootstrapper: io.papermc.testplugin.TestPluginBootstrap -loader: io.papermc.testplugin.TestPluginLoader -``` - - -### Dependency declaration - -Paper plugins change how to declare dependencies in your `paper-plugin.yml`: - -```yml -dependencies: - bootstrap: - # Let's say that RegistryPlugin registers some data that your plugin needs to use - # We don't need this during runtime, so it's not required in the server section. - # However, can be added to both if needed - RegistryPlugin: - load: BEFORE - required: true - join-classpath: true # Defaults to true - server: - # Add a required "RequiredPlugin" dependency, which will load AFTER your plugin. - RequiredPlugin: - load: AFTER - required: true - # This means that your plugin will not have access to their classpath - join-classpath: false -``` - -With Paper plugins, dependencies are split into two sections: -- `bootstrap` - These are dependencies that you will be using in the [bootstrap](#bootstrapper). -- `server` - These are dependencies that are used for the core functionality of your plugin, whilst the server is running. - -Let's take a look at a dependency: -```yml -RegistryPlugin: - load: BEFORE # Defaults to OMIT - required: true # Defaults to true - join-classpath: true # Defaults to true -``` - -- `load` (`BEFORE`|`AFTER`|`OMIT`): Whether this plugin should load before or after **your** plugin. Note: `OMIT` has undefined ordering behavior. -- `required`: Whether this plugin is required for your plugin to load. -- `join-classpath`: Whether your plugin should have access to their classpath. This is used for plugins that need to access other plugins internals directly. - -:::note[Cyclic Loading] - -Note that in certain cases, plugins may be able to introduce cyclic loading loops, which will prevent the server from starting. -Please read the [cyclic loading guide](#cyclic-plugin-loading) for more information. - -::: - -Here are a couple of examples: -```yml -# Suppose we require ProtocolLib to be loaded for our plugin -ProtocolLib: - load: BEFORE - required: true - -# Now, we are going to register some details for a shop plugin -# So the shop plugin should load after our plugin -SuperShopsXUnlimited: - load: AFTER - required: false - -# Now, we are going to need to access a plugins classpath -# So that we can properly interact with it. -SuperDuperTacoParty: - required: true - join-classpath: true -``` - -## What is it used for? -Paper plugins lay down the framework for some future API. Our goals are to open more modern API that better aligns -with Vanilla. Paper plugins allow us to do just that by making a new way to load plugin resources before the server -has started by using [bootstrappers](#bootstrapper). - -## Bootstrapper -Paper plugins are able to identify their own bootstrapper by implementing -`PluginBootstrap` -and adding the class of your implementation to the bootstrapper field in the `paper-plugin.yml`. -```java -public class TestPluginBootstrap implements PluginBootstrap { - - @Override - public void bootstrap(@NotNull BootstrapContext context) { - - } - - @Override - public @NotNull JavaPlugin createPlugin(@NotNull PluginProviderContext context) { - return new TestPlugin("My custom parameter"); - } - -} -``` -A bootstrapper also allows you to change the way your plugin is initialized, allowing you to pass values into your plugin constructor. -Currently, bootstrappers do not offer much new API and are highly experimental. This may be subject to change once more API is introduced. - -## Loaders -Paper plugins are able to identify their own plugin loader by implementing -`PluginLoader` -and adding the class of your implementation to the loader field in the `paper-plugin.yml`. - -The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into. -This, as of right now, only applies to creating the expected classpath for the plugin, e.g. supplying external libraries to the plugin. -```java -public class TestPluginLoader implements PluginLoader { - - @Override - public void classloader(@NotNull PluginClasspathBuilder classpathBuilder) { - classpathBuilder.addLibrary(new JarLibrary(Path.of("dependency.jar"))); - - MavenLibraryResolver resolver = new MavenLibraryResolver(); - resolver.addDependency(new Dependency(new DefaultArtifact("com.example:example:version"), null)); - resolver.addRepository(new RemoteRepository.Builder("paper", "default", "https://repo.papermc.io/repository/maven-public/").build()); - - classpathBuilder.addLibrary(resolver); - } -} -``` -Currently, you are able to add two different library types: -`JarLibrary` and -`MavenLibraryResolver`. - -## Differences - -### Bukkit serialization system -Paper plugins still support the serialization system (`org.bukkit.configuration.serialization`) that Bukkit uses. However, custom classes will not be -automatically registered for serialization. In order to use `ConfigurationSection#getObject`, -you **must** call `ConfigurationSerialization#registerClass(Class)` -before you attempt to fetch objects from configurations. - -### Classloading isolation -Paper plugins are not able to access each other unless given explicit access by depending on another plugin, etc. This -helps prevent Paper plugins from accidentally accessing each other's dependencies, and in general helps ensure that -plugins are only able to access what they explicitly depend on. - -Paper plugins have the ability to bypass this, being able to access OTHER plugins' classloaders by adding a `join-classpath` option to their `paper-plugin.yml`. - -```yml -Plugin: - join-classpath: true # Means you have access to their classpath -``` - -Note, other Paper plugins will still be unable to access your classloader. - -### Load order logic split -In order to better take advantage of classloading isolation, Paper plugins do **not** use the `dependencies` field to determine load order. -This was done for a variety of reasons, mostly to allow better control and allow plugins to properly share classloaders. - -See [declaring dependencies](#dependency-declaration) for more information on how to declare the load order of your plugin. - -### Commands -Paper plugins do not use the `commands` field to register commands. This means that you do not need to include all -of your commands in the `paper-plugin.yml` file. Instead, you can register commands using the -[Brigadier Command API](../api/commands.mdx). - -### Cyclic plugin loading - -Cyclic loading describes the phenomenon when a plugin loading causes a loop that eventually cycles back to the original plugin. -Unlike Bukkit plugins, Paper plugins will not attempt to resolve cyclic loading issues. - -```mermaid -graph LR; - A-->B; - B-->C; - C-->D; - D-->A; -``` - -However, if Paper detects a loop that cannot be resolved, you will get an error that looks like this: -``` -[ERROR]: [LoadOrderTree] ================================= -[ERROR]: [LoadOrderTree] Circular plugin loading detected: -[ERROR]: [LoadOrderTree] 1) Paper-Test-Plugin1 -> Paper-Test-Plugin -> Paper-Test-Plugin1 -[ERROR]: [LoadOrderTree] Paper-Test-Plugin1 loadbefore: [Paper-Test-Plugin] -[ERROR]: [LoadOrderTree] Paper-Test-Plugin loadbefore: [Paper-Test-Plugin1] -[ERROR]: [LoadOrderTree] Please report this to the plugin authors of the first plugin of each loop or join the PaperMC Discord server for further help. -[ERROR]: [LoadOrderTree] ================================= -``` - -It is up to you to resolve these cyclical loading issues. diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/plugin-yml.mdx b/docs/versioned/paper/content/1.20/dev/getting-started/plugin-yml.mdx deleted file mode 100644 index 909a9a640..000000000 --- a/docs/versioned/paper/content/1.20/dev/getting-started/plugin-yml.mdx +++ /dev/null @@ -1,224 +0,0 @@ ---- -slug: /dev/plugin-yml -description: A guide to Bukkit's plugin.yml file. ---- - -# Bukkit Plugin YML - -The `plugin.yml` file is the main configuration file for your plugin. -It contains information about your plugin, such as its name, version, and description. -It also contains information about the plugin's dependencies, permissions, and commands. - -The `plugin.yml` file is located in the `resources` directory of your project. -``` -example-plugin -├── build.gradle.kts -├── settings.gradle.kts -└── src - └── main - ├── java - └── resources - └── plugin.yml -``` - -## Example - -Here is an example of a `plugin.yml` file: - - -``` -name: ExamplePlugin -version: 1.0.0 -main: io.papermc.testplugin.ExamplePlugin -description: An example plugin -author: PaperMC -website: https://papermc.io -api-version: '%%_MAJ_MIN_PAT_MC_%%' -``` - - -## Fields - -:::note - -The fields in this section are not in any particular order. -If they have an asterisk (\*) next to them, that means they are required. - -::: - -### name* - -The name of your plugin. This is what will be displayed in the plugin list and log messages. -This will be overridden in the logs if the prefix is set. -- `name: ExamplePlugin` - -### version* - -The current version of the plugin. This is shown in plugin info messages and server logs. -- `version: 1.0.0` - -### main* - -The main class of your plugin. This is the class that extends `JavaPlugin` and is the entry point to your plugin. -- `main: io.papermc.testplugin.ExamplePlugin` - -This is the package path and class name of your main class. - -### description - -A short description of your plugin and what it does. This will be shown in the plugin info commands. -- `description: An example plugin` - -### author / authors - -The author(s) of the plugin. This can be a single author or a list of authors. -- `author: PaperMC` -- `authors: [PaperMC, SpigotMC, Bukkit]` -These will be shown in the plugin info commands. - -### contributors - -The contributors to the plugin that aren't the managing author(s). -- `contributors: [PaperMC, SpigotMC, Bukkit]` -These will be shown in the plugin info commands. - -### website - -The website of the plugin. This is useful for linking to a GitHub repository or a plugin page. -- `website: https://papermc.io` -This will be shown in the plugin info commands. - -### api-version - -The version of the Paper API that your plugin is using. This doesn't include the minor version until 1.20.5. From 1.20.5 and onward, a minor version is supported. -Servers with a version lower than the version specified here will refuse to load the plugin. -The valid versions are 1.13 - . -- `api-version: '%%_MAJ_MIN_PAT_MC_%%'` - -:::info - -If this is not specified, the plugin will be loaded as a legacy plugin and a warning will be printed to the console. - -::: - -### load - -This tells the server when to load the plugin. This can be `STARTUP` or `POSTWORLD`. Will default to `POSTWORLD` if not specified. -- `load: STARTUP` - -### prefix - -The prefix of the plugin. This is what will be displayed in the log instead of the plugin name. -- `prefix: EpicPaperMCHypePlugin` - -### libraries - -:::warning - -The use of this feature is *currently* against Maven Central's TOS. However, this feature is very likely to stay. - -::: - -This is a list of libraries that your plugin depends on. These libraries will be downloaded from the Maven Central repository and added to the classpath. -This removes the need to shade and relocate the libraries. - -```yaml -libraries: - - com.google.guava:guava:30.1.1-jre - - com.google.code.gson:gson:2.8.6 -``` - -### permissions - -This is a list of permissions that your plugin uses. This is useful for plugins that use permissions to restrict access to certain features. -```yaml -permissions : - permission.node: - description: "This is a permission node" - default: op - children: - permission.node.child: true - another.permission.node: - description: "This is another permission node" - default: not op -``` - -The description is the description of the permission node. This is what will be displayed in the permissions list. -The default is the default value of the permission node. This can be `op`/`not op` or `true`/`false`. -This defaults to the value of `default-permission` if not specified, which in turn defaults to `op`. -Each permission node can have children. When set to `true`, it will inherit the parent permission. - -### default-permission - -The default value that permissions that don't have a `default` specified will have. This can be `op`/`not op` or `true`/`false`. -- `default-permission: true` - -## Commands - -This is a list of commands that your plugin uses. This is useful for plugins that use commands to provide features. -```yaml -commands: - command: - description: "This is a command" - usage: "/command " - aliases: [cmd, command] - permission: permission.node - permission-message: "You do not have permission to use this command" -``` - -- `description` is the description of the command. This gives a brief description of what the command does. -- `usage` is the usage of the command. This is what will be displayed when the player uses `/help `. -- `aliases` are a list of aliases that the command can be used with. This is useful for shortening the command. -- `permission` is the permission node that the player needs to use the command. Note: Players will only see commands they have permission to use. -- `permission-message` is the message that will be displayed when the player does not have permission to use the command. - -## Dependencies - -:::warning[Dependency Loops] - -If a plugin is specified as a dependency, it will be loaded before your plugin. -Be careful as these can cause plugin load issues if cyclical dependencies appear. A cyclical dependency can be illustrated as follows: - -```mermaid -graph LR; - PluginA-->PluginB; - PluginB-->PluginC; - PluginC-->PluginD; - PluginD-->PluginA; -``` - -Where `PluginA` and `PluginB` are plugins that depend on each other. - -::: - -### depend - -A list of plugins that your plugin depends on to __load__. They are specified by their plugin name. - -:::info - -If the plugin is not found, your plugin will not load. - -::: - -- `depend: [Vault, WorldEdit]` - -### softdepend - -A list of plugins that your plugin depends on to have __full functionality__. They are specified by their plugin name. - -- `softdepend: [Vault, WorldEdit]` - -### loadbefore - -A list of plugins that your plugin should be loaded __before__. They are specified by their plugin name. -This is useful if you want to load your plugin before another plugin for the other plugin to use your plugin's API. - -- `loadbefore: [Vault, FactionsUUID]` - -### provides - -This can be used to tell the server that this plugin will provide the functionality of some library or other plugin (like an alias system). -Plugins that (soft)depend on the other plugin will treat your plugin as if the other plugin exists when resolving dependencies or using -`PluginManager#getPlugin(String)`. -- `provides: [SomeOtherPlugin]` diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/project-setup.mdx b/docs/versioned/paper/content/1.20/dev/getting-started/project-setup.mdx deleted file mode 100644 index 2231cb660..000000000 --- a/docs/versioned/paper/content/1.20/dev/getting-started/project-setup.mdx +++ /dev/null @@ -1,306 +0,0 @@ ---- -slug: /dev/project-setup -description: Step-by-step instructions on how to set up a plugin development environment. ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - -# Paper Project Setup - -As the Paper team primarily uses [IntelliJ IDEA](https://www.jetbrains.com/idea/), this guide will be focused on that IDE. -However, the steps below should apply to other IDEs as well, with some minor changes. - -The Paper team uses [Gradle](https://gradle.org/) as its build system, and its tools are implemented for Gradle. -Most of the code below can be altered to work with other build systems, such as Maven, but this guide will only cover Gradle. - -Follow the guide [here](https://docs.gradle.org/current/userguide/migrating_from_maven.html) to learn how to migrate from Maven to Gradle. - -## Creating a new project - -Open your IDE and select the option to create a new project. -In IntelliJ, you will get the option to select the type of project you want to create - select `New Project`. -Select `Gradle - Kotlin DSL` and click `Create`. - -You will land into the `build.gradle.kts` file where you can add your dependencies. - -### Adding Paper as a dependency - -To add Paper as a dependency, you will need to add the Paper repository to your `build.gradle.kts` file as well as the dependency itself. - - -``` -repositories { - mavenCentral() - maven("https://repo.papermc.io/repository/maven-public/") -} - -dependencies { - compileOnly("io.papermc.paper:paper-api:%%_MAJ_MIN_PAT_MC_%%-R0.1-SNAPSHOT") -} - -java { - toolchain.languageVersion.set(JavaLanguageVersion.of(21)) -} -``` - - -### Setting up the `src` directory - -:::note - -If your IDE creates a `src` directory automatically, you can skip this step. - -::: - -To set up the `src` directory, you will need to create a new directory called `src` and then create a new directory called `main` inside of it. -Inside of `main`, create two new directories called `java` and `resources`. - -It should look like this: - -``` -... -example-plugin -├── build.gradle.kts -├── settings.gradle.kts -└── src - └── main - ├── java - └── resources -... -``` - -### Setting up the `java` directory - -You will place your Java source files in the `java` directory. You first need to create some packages to organize your code. -For this example, we will create three packages called `io.papermc.testplugin` and then create a class called `ExamplePlugin` inside of it. - -``` -... -example-plugin -├── build.gradle.kts -├── settings.gradle.kts -└── src - └── main - ├── java - │ └── io - │ └── papermc - │ └── testplugin - │ └── ExamplePlugin.java - └── resources -... -``` - -### Packages - -You can see here that the `ExamplePlugin` class is inside the `io.papermc.testplugin` package. -A package is a way to organize your code - essentially, it's a folder. Java packages are used to group related classes. -Oracle has a guide on [packages](https://docs.oracle.com/javase/tutorial/java/package/packages.html) if you want to learn more. - -When [naming](https://docs.oracle.com/javase/tutorial/java/package/namingpkgs.html) your packages, you should use your domain name in reverse order. For example, if your domain name is `papermc.io`, -your package name should be `io.papermc`. If you do not have a domain name, you could use something like your GitHub username. -If you were Linus Torvalds, your package would be `io.github.torvalds`. - -This is then followed by the name of your project. -For example, if your project was called `ExamplePlugin`, your package would be `io.github.torvalds.exampleplugin`. -This allows for a unique package name for every plugin. - -### The _main_ class - -The main class is the entry point to your plugin and will be the only class that extends -`JavaPlugin` in your plugin. -This is an example of what your `ExamplePlugin` class could look like: - -```java -package io.papermc.testplugin; - -import net.kyori.adventure.text.Component; -import org.bukkit.Bukkit; -import org.bukkit.event.EventHandler; -import org.bukkit.event.Listener; -import org.bukkit.event.player.PlayerJoinEvent; -import org.bukkit.plugin.java.JavaPlugin; - -public class ExamplePlugin extends JavaPlugin implements Listener { - - @Override - public void onEnable() { - Bukkit.getPluginManager().registerEvents(this, this); - } - - @EventHandler - public void onPlayerJoin(PlayerJoinEvent event) { - event.getPlayer().sendMessage(Component.text("Hello, " + event.getPlayer().getName() + "!")); - } - -} -``` - -### Setting up the `resources` - -The `resources` directory is where you will place your plugin's `plugin.yml` file. See the [Plugin YML](plugin-yml) page for more information. - -## Using the Minecraft Development IntelliJ plugin - -Alternatively, you can use the [Minecraft Development IntelliJ plugin](https://plugins.jetbrains.com/plugin/8327-minecraft-development) -to create a new project. - -:::info - -This tutorial only works with IntelliJ IDEA. If you are using another IDE, please follow the manual project setup guide described above. - -::: - -### Installing the Minecraft Development plugin -The first thing you need to do is install the [Minecraft Development](https://plugins.jetbrains.com/plugin/8327-minecraft-development) plugin. -You can do this by going to `File > Settings > Plugins` and searching for `Minecraft Development` under the `Marketplace` section. - -![](assets/installing-plugin.png) - -Once you have installed the plugin, you will need to restart IntelliJ. -To do that you can click the `Restart IDE` button that appears after installing the plugin. - -![](assets/restart-ide.png) - -### Creating a new project -Once you have installed the plugin, you can create a new project by going to `File > New > Project...` and selecting `Minecraft` from the list of options. - -![](assets/new-project-paper.png) - -You will be asked to provide some information about your project. - -| Field | Explanation | -|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Name** | The name of your project. | -| **Location** | The location of your project. This is where the project files will be stored. | -| **Platform Type** | The platform type you are developing for. This should be `Plugin`. | -| **Platform** | The platform you are developing for. This should be `Paper`. | -| **Minecraft Version** | The version of Minecraft you are developing for. | -| **Plugin Name** | The name of your plugin. | -| **Main Class** | The main class of your plugin. This should be the class that extends `JavaPlugin`. | -| **Optional Settings** | Here you can define things like authors, website, description, etc. These are optional and not required for the plugin to work. | -| **Build System** | The build system you want to use. Paper recommends using Gradle but you can use Maven if you prefer. | -| **Paper Manifest** | Whether you want to use the new Paper plugins or not. For now this is not recommended as it is still in development. | -| **Group ID** | The group ID of your project. This is used for Maven and Gradle. This is usually your domain name in reverse. If you don't know what you should put here, you can use something like `io.github.` or if you don't have GitHub you can use `me.`. | -| **Artifact ID** | The artifact ID of your project. This is used for Maven and Gradle. This is usually the name of your project. This is usually the same as the `Name` field. | -| **Version** | The version of your project. This is used for Maven and Gradle. This is usually `1.0-SNAPSHOT` and does not really matter for now. | -| **JDK** | The JDK you want to use. This can be anything from Java 17 and above. | - -Now you can click on the `Create` button and IntelliJ will create the project for you. -If everything went well, you should see something like this: - -![](assets/paper-plugin-overview.png) - -## Plugin remapping - -As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. -If you are using Spigot/Bukkit plugins, your plugin will be assumed to be Spigot-mapped. -This means that the server will have to deobfuscate and remap the plugin JAR when it's loaded for the first time. - -:::info - -`paperweight-userdev` already sets this attribute automatically. For more information see the [userdev](./userdev) documentation. - -::: - -### Mojang mappings - -To tell the server that your plugin is Mojang-mapped, you need to add the following code to your build script: - -:::note[Paper plugins] - -If you are using Paper plugins, this step is not needed as plugins will be assumed to be Mojang-mapped. - -::: - - - - ```kotlin - tasks.jar { - manifest { - attributes["paperweight-mappings-namespace"] = "mojang" - } - } - // if you have shadowJar configured - tasks.shadowJar { - manifest { - attributes["paperweight-mappings-namespace"] = "mojang" - } - } - ``` - - - ```xml - - org.apache.maven.plugins - maven-jar-plugin - 3.4.1 - - - - mojang - - - - - ``` - - - -### Spigot mappings - -If you explicitly want to tell the server that your plugin is Spigot-mapped, you need to add the following code to your build script: - - - - ```kotlin - tasks.jar { - manifest { - attributes["paperweight-mappings-namespace"] = "spigot" - } - } - // if you have shadowJar configured - tasks.shadowJar { - manifest { - attributes["paperweight-mappings-namespace"] = "spigot" - } - } - ``` - - - ```xml - - org.apache.maven.plugins - maven-jar-plugin - 3.4.1 - - - - spigot - - - - - ``` - - - -## Conclusion - -You should now have a project set up with Paper as a dependency. -All you have left to do now is to compile your plugin and run it on a Paper server. - -:::note - -If you want to streamline the process of testing a plugin, you can use the [Run-Task](https://github.com/jpenilla/run-task) Gradle plugin. -It will automatically download a Paper server and run it for you. - -::: - -:::info - -If you are using IntelliJ, you can use the Gradle GUI `Build` menu to compile your plugin - found on the top right of your IDE. -The output JAR of your plugin will be in the `build/libs` directory. - -::: diff --git a/docs/versioned/paper/content/1.20/dev/getting-started/userdev.mdx b/docs/versioned/paper/content/1.20/dev/getting-started/userdev.mdx deleted file mode 100644 index 9686b154e..000000000 --- a/docs/versioned/paper/content/1.20/dev/getting-started/userdev.mdx +++ /dev/null @@ -1,149 +0,0 @@ ---- -slug: /dev/userdev -sidebar_label: Paperweight Userdev -description: A guide on how to use the paperweight-userdev Gradle plugin to access internal code. ---- - -# paperweight-userdev - -**paperweight** is the name of Paper's custom build tooling. The **paperweight-userdev** Gradle plugin part of that -provides access to internal code (also known as NMS) during development. - -:::note - -This guide is written using the Gradle Kotlin DSL and assumes you have some basic knowledge of Gradle. -If you want to see a fully-functioning plugin that uses **paperweight-userdev**, -check out this [example plugin](https://github.com/PaperMC/paperweight-test-plugin). - -::: - -## Why this is useful -The Paper server JARs we provide on the downloads page through the API are **paperclip** JARs. These -use Spigot's mappings, which are essentially some type names, but fully obfuscated fields and methods. -This can make it hard to work with in a development environment. This plugin lets you use fully deobfuscated -types, names, and fields during development, and then remaps your plugin, so it can still be used with the obfuscated -server. - -:::caution[1.20.5] - -As of Minecraft version 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. -See [here](#1205-and-beyond) for more details. - -::: - -:::caution - -The re-obfuscation does not apply to reflection. Look at something like [this library](https://github.com/jpenilla/reflection-remapper) to be able to -use non-obfuscated names in reflection. - -::: - -## Adding the plugin -Add the plugin to your `build.gradle.kts` file. -```kotlin -plugins { - id("io.papermc.paperweight.userdev") version "1.7.1" // Check for new versions at https://plugins.gradle.org/plugin/io.papermc.paperweight.userdev -} -``` - -The latest version of `paperweight-userdev` supports dev bundles for Minecraft 1.17.1 and newer, so it's best practice to keep it up to date! -Only the latest version of `paperweight-userdev` is officially supported, and we will ask you to update first if you are having problems with old versions. - -:::info[Snapshots] - -**paperweight-userdev** releases are available through the [Gradle Plugin Portal](https://plugins.gradle.org/plugin/io.papermc.paperweight.userdev), but if you -want to use SNAPSHOT versions, you must add Paper's Maven repository to `settings.gradle.kts` with: -```kotlin -pluginManagement { - repositories { - gradlePluginPortal() - maven("https://repo.papermc.io/repository/maven-public/") - } -} -``` - -::: - -## Adding the dev bundle dependency -If you try to load your Gradle project now, you will receive an error saying you have to declare -a dev bundle dependency. You can do that by adding to your `dependencies` block in your `build.gradle.kts` -file. - - -``` -dependencies { - // Other Dependencies - paperweight.paperDevBundle("%%_MAJ_MIN_PAT_MC_%%-R0.1-SNAPSHOT") -} -``` - - -:::tip - -You should remove any dependency on the Paper API, as the dev bundle includes that. - -::: - -## Gradle tasks - -### `reobfJar` - -This task creates a plugin JAR that is re-obfuscated to Spigot's runtime mappings. -This means it will work on standard Paper servers. - -The output will be inside the `build/libs` folder. The JAR whose filename includes `-dev` -is Mojang-mapped (not re-obfuscated) and will not work on most servers. - -:::info[Shadow] - -If you have the shadow Gradle plugin applied in your build script, **paperweight-userdev** will -detect that and use the shaded JAR as the input for the `reobfJar` task. - -The `-dev-all.jar` file in `build/libs` is the shaded, but not re-obfuscated JAR. - -::: - -You can make the `reobfJar` task run on the default `build` task with: -```kotlin -tasks.assemble { - dependsOn(reobfJar) -} -``` - -## 1.20.5 and beyond - -As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. -Additionally, CraftBukkit classes will no longer be relocated into a versioned package. -This requires plugins to be deobfuscated before loading when necessary. - -Most of this process is done automatically by paperweight but there are some important things to know when using NMS from now on. - -### Default mappings assumption -* By default, all Spigot/Bukkit plugins will be assumed to be Spigot-mapped if they do not specify their mappings namespace in the manifest. Conversely, all Paper plugins will be assumed to be Mojang-mapped if they do not specify their mappings namespace in the manifest. -* Spigot-mapped plugins will need to be deobfuscated on first load, Mojang-mapped plugins will not. - -### Mojang mappings - -If you want to map your plugin with Mojang mappings, you need to add the following code to your build script: - -:::note - -You only have to change this setting if you are using Bukkit/Spigot plugins. Paper plugins are already assumed to be Mojang-mapped. - -::: - -```kotlin title="build.gradle.kts" -paperweight.reobfArtifactConfiguration = io.papermc.paperweight.userdev.ReobfArtifactConfiguration.MOJANG_PRODUCTION -``` - -Additionally, you need to remove all `dependsOn(reobfJar)` lines. - -### Spigot mappings - -If you are using Paper plugins but want to explicitly use Spigot mappings, you need to change the property to: - -```kotlin title="build.gradle.kts" -paperweight.reobfArtifactConfiguration = io.papermc.paperweight.userdev.ReobfArtifactConfiguration.REOBF_PRODUCTION -``` - - diff --git a/docs/versioned/paper/content/1.20/dev/misc/README.mdx b/docs/versioned/paper/content/1.20/dev/misc/README.mdx deleted file mode 100644 index 5cfd897a8..000000000 --- a/docs/versioned/paper/content/1.20/dev/misc/README.mdx +++ /dev/null @@ -1,10 +0,0 @@ -import DocCardList from "@theme/DocCardList"; -import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; - -# Miscellaneous Development Guides - -These guides are for helping developers with parts of the development process that don't fit into the other categories. - ---- - - diff --git a/docs/versioned/paper/content/1.20/dev/misc/assets/add_breakpoints.png b/docs/versioned/paper/content/1.20/dev/misc/assets/add_breakpoints.png deleted file mode 100644 index c4f4e6753..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/misc/assets/add_breakpoints.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/misc/assets/config_add.png b/docs/versioned/paper/content/1.20/dev/misc/assets/config_add.png deleted file mode 100644 index 8d8572203..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/misc/assets/config_add.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/misc/assets/config_dropdown.png b/docs/versioned/paper/content/1.20/dev/misc/assets/config_dropdown.png deleted file mode 100644 index 085bb357f..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/misc/assets/config_dropdown.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/misc/assets/debugger_connect.png b/docs/versioned/paper/content/1.20/dev/misc/assets/debugger_connect.png deleted file mode 100644 index f54920a1d..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/misc/assets/debugger_connect.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/misc/assets/debugger_use.png b/docs/versioned/paper/content/1.20/dev/misc/assets/debugger_use.png deleted file mode 100644 index baef37066..000000000 Binary files a/docs/versioned/paper/content/1.20/dev/misc/assets/debugger_use.png and /dev/null differ diff --git a/docs/versioned/paper/content/1.20/dev/misc/databases.mdx b/docs/versioned/paper/content/1.20/dev/misc/databases.mdx deleted file mode 100644 index 355fb23d5..000000000 --- a/docs/versioned/paper/content/1.20/dev/misc/databases.mdx +++ /dev/null @@ -1,195 +0,0 @@ ---- -slug: dev/using-databases -description: Databases are the recommended way to store a large amount of data. This guide outlines a few key details. ---- - -# Using Databases - -When you are storing larger amounts of data inside a plugin, we recommend using a database. This guide will walk you through the startup process. - -## What is a database? - -A database is a collection of information that is stored electronically on a computer system. There are many different types of databases, -and the main two categories are SQL and NoSQL. - -### NoSQL vs SQL - -A NoSQL (Not Only SQL) database is a type of database management system that differs from the traditional relational database model. -Unlike traditional SQL databases, which store data in structured tables with predefined schemas, NoSQL databases are schema-less -and offer flexible data models. - -They are designed to handle large volumes of unstructured or semi-structured data. -NoSQL databases use various data models, such as key-value, document, column-family, or graph, depending on -the specific requirements of the application. - -On the other hand, an SQL database is a type of database management system that follows the relational database model. -It organizes data into structured tables with predefined schemas, where each table represents an entity and columns -represent attributes of that entity. SQL (Structured Query Language) is used to interact with the database, -allowing users to perform various operations like querying, inserting, updating, and deleting data. - -## File-based vs standalone databases - -When working with databases, you have two options: file-based or standalone. File-based databases are stored in a file on the disk, -and are usually used for smaller databases. Standalone databases operate in a separate process, and are usually used for larger data models. - -### File-based databases - -File-based databases are all stored within a single file on the disk. They are usually used for smaller databases, as they are easier to set up and use. -They can be created and handled from within your plugin code, but offer lesser performance than standalone databases. -Some examples of file-based databases are `SQLite` and `H2`. - -
- Simple SQLite Setup - -#### SQLite - -To work with SQLite, you will need a driver to connect / initialize the database. - -:::note - -The JDBC Driver is bundled with Paper, so you do not need to shade/relocate it in your plugin. - -::: - -##### Usage - -You must invoke a `Class#forName(String)` -on the driver to allow it to initialize and then create the connection to the database: - -```java -public class DatabaseManager { - - public void connect() { - Class.forName("org.sqlite.JDBC"); - Connection connection = DriverManager.getConnection("jdbc:sqlite:plugins/TestPlugin/database.db"); - } -} -``` - -You then have access to a `Connection` object, -which you can use to create a `Statement` and execute SQL queries. -To learn more about the Java Database Connectivity API, see [here](https://www.baeldung.com/java-jdbc) - -
- -### Standalone databases - -As previously mentioned, standalone databases operate in a separate process. They are harder to set up and use, -but offer better performance than file-based databases. Some examples of standalone databases are `MySQL`, `MariaDB` and `PostgreSQL`. -There are many more, but these are some of the most popular ones. Each has their own advantages and disadvantages, -so it is up to you to decide which one to use. - -The connectors for these databases often have connection pooling. Database connection pooling is where it creates -a pool of pre-established and reusable database connections. Instead of opening a new connection every time a -database operation is required, the application can request a connection from the pool, use it for the required task, -and then return it back to the pool for future reuse. This significantly reduces the overhead of creating and tearing -down connections repeatedly, leading to improved application performance and better scalability. - -
- Simple MySQL Setup - -#### MySQL - -Working with MySQL requires a few more steps, however it can offer performance benefits for larger databases with -many tables and concurrent accesses. This is a short setup guide for using the [Hikari](https://github.com/brettwooldridge/HikariCP) library with MySQL. - -:::note - -This will require a running MySQL database to connect to. - -::: - -First, add the dependency to your project with the following dependency: - -##### Maven -```xml - - com.zaxxer - HikariCP - 4.0.3 - compile - -``` - -##### Gradle -```kotlin -dependencies { - implementation("com.zaxxer:HikariCP:4.0.3") -} -``` - -:::caution - -The Hikari library is not bundled with Paper, so you will need to shade/relocate it. In Gradle, you will need to use the [Shadow plugin](https://imperceptiblethoughts.com/shadow/). -Alternatively, you can use the library loader with your Paper plugin to load the library at runtime. See [here](../getting-started/paper-plugins.mdx#loaders) -for more information on how to use this. - -::: - -##### Usage - -Once you have the dependency added, we can work with the connector in our code: - -```java -public class DatabaseManager { - - public void connect() { - HikariConfig config = new HikariConfig(); - config.setJdbcUrl("jdbc://mysql://localhost:3306/mydatabase"); // Address of your running MySQL database - config.setUsername("username"); // Username - config.setPassword("password"); // Password - config.setMaximumPoolSize(10); // Pool size defaults to 10 - - config.addDataSourceProperty("", ""); // MISC settings to add - HikariDataSource dataSource = new HikariDataSource(config); - - try (Connection connection = dataSource.getConnection()) { - // Use a try-with-resources here to autoclose the connection. - PreparedStatement sql = connection.prepareStatement("SQL"); - // Execute statement - } catch (Exception e) { - // Handle any exceptions that arise from getting / handing the exception. - } - } -} -``` - -
- -## Security - -### SQL Injection - -SQL injection is a malicious technique where attackers exploit improper input validation to execute unauthorized SQL commands, -potentially causing data breaches or damage to the database. - -For example, consider the following code: - -```java -public void login(String username, String password) { - String sql = "SELECT * FROM users WHERE username = '" + username + "' AND password = '" + password + "'"; - // Execute SQL -} -``` - -If the user enters the following as their username: - -``` -' OR 1=1; -- -``` - -The SQL statement will become: - -```sql -SELECT * FROM users WHERE username = '' OR 1=1; -- AND password = 'password' -``` - -This will return all users in the database, regardless of the password they entered. This is a simple example, -but it can be used to do much more malicious things, such as deleting the entire database or stealing user data. - -### Prepared statements - -Using prepared statements in Java with `PreparedStatement`s -helps prevent SQL injection. They separate SQL code from user input by using placeholders, reducing the risk of executing unintended SQL commands. -**Always** use prepared statements to ensure the security and integrity of your data. Read more about SQL injection -[here](https://www.baeldung.com/sql-injection). diff --git a/docs/versioned/paper/content/1.20/dev/misc/debugging.mdx b/docs/versioned/paper/content/1.20/dev/misc/debugging.mdx deleted file mode 100644 index dba3b4379..000000000 --- a/docs/versioned/paper/content/1.20/dev/misc/debugging.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -slug: /dev/debugging -description: Debugging is common when writing code. This guide outlines the common ways to debug your plugin. ---- - -# Debugging Your Plugin - -Debugging your plugin is vital to being able to fix bugs and issues in your plugin. This page will cover some of the most common debugging techniques. - -### Printing to the console - -One of the most common debugging techniques is to print to the console. This is likely something you've done before, as it's very simple. -This has a few downsides, though. It can be hard to find the print statements in the console, and it can be hard to remove them all when you're done debugging. Most notably, you have to recompile your plugin and restart the server to add or remove debugging. - -When debugging, you can use `System.out.println("");` to print to the console. It is recommended to use your plugin's logger instead though, -as it will be easier to know which plugin the log has come from. This can be done simply with: - -```java -plugin.getComponentLogger().debug(Component.text("SuperDuperBad Thing has happened")); -``` - -:::note[Logger Levels] - -In some consoles, using the `warning` level will print the message in different colors. -This can be useful for finding your print statements in the console. - -::: - -### Using a remote debugger - -A debugger is a tool that allows you to pause your code at a certain point and inspect the values of variables. -This can be very useful for finding out why your code isn't working as expected and also for finding out where your code is going wrong. - -#### Setting up the debugger - -To use a debugger, you need to set up your IDE to use it. This is different for each IDE, but for the sake of this guide, we will be using IntelliJ IDEA. - -To set up a debugger in IntelliJ, you need to create a new run configuration. -You can do this by clicking the dropdown next to the run button and clicking `Edit Configurations...`: - -![](./assets/config_dropdown.png) - -Then, click the `+` button in the top left and select `Remote JVM Debug`. You can then name the configuration whatever you want, and click `Apply`: - -![](./assets/config_add.png) - -Finally, copy the command line arguments from the window, and paste these into your server's startup script. -These will go after the `java` command and before `-jar`. Once you have done this, you can click `OK`. For example: - - -``` -java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar paper-%%_MAJ_MIN_PAT_MC_%%.jar nogui -``` - - -Once your server is running, you can use the bug icon in the top right to connect your debugger to the server: - -![](./assets/debugger_connect.png) - -#### Using the debugger - -Let's say we have this code: - -```java -@EventHandler -public void onPlayerMove(PlayerMoveEvent event) { - Player player = event.getPlayer(); - Location location = player.getLocation(); - - if (location.getWorld() == null) - return; - - if (location.getWorld().getEnvironment() == World.Environment.NETHER) { - player.sendMessage("You are in the nether!"); - } -} -``` - -You can add a breakpoint to the line by clicking on the line number: - -![](./assets/add_breakpoints.png) - -This will pause the code when it reaches that line. You can then use the debugger to inspect the values of variables: - -![](./assets/debugger_use.png) - -You can inspect the values of each of the variables in the current scope. -You can also use the buttons in the top to step from one breakpoint to the next. -If needed, you can also use the text box at the top to evaluate expressions for debugging purposes. - -### Using direct debugging - -Direct debugging will allow you to run the server directly from your IDE, and will allow you to use breakpoints and step through your code. -We can achieve this by using [JPenilla's Gradle plugin](https://github.com/jpenilla/run-task) to run the server directly from the IDE. -See [here](https://github.com/jpenilla/run-task#basic-usage) for instructions on how to set up the plugin. diff --git a/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx b/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx deleted file mode 100644 index dd1fe591a..000000000 --- a/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -slug: /dev/internals -description: A brief overview of how to use internals in your plugin. ---- - -# Minecraft Internals - -The code that runs Minecraft is not open source. Bukkit is an API that allows plugins to interact with the server. This -is implemented by CraftBukkit and interacts with Minecraft's code. You will often hear the terms NMS and CraftBukkit -when talking about Minecraft internals. - -:::danger[Using Minecraft Internals] - -Using Minecraft internals is not recommended. This is because using internal code directly is not guaranteed to be -stable and it changes often. This means that your plugin may break when a new version of Minecraft is released. -Whenever possible, you should use API instead of internals. - -**PaperMC will offer no direct support for programming against Minecraft internals.** - -::: - -## What is NMS? - -NMS stands for `net.minecraft.server` and refers to a Java package that contains a lot of Mojang's code. This code is -proprietary and is not open source. This code is not guaranteed to be stable when invoked externally and may change at -any time. - -## Accessing Minecraft Internals - -In order to use Mojang and CraftBukkit code, you may either use the `paperweight-userdev` Gradle plugin or use reflection. -[`paperweight-userdev`](https://github.com/PaperMC/paperweight-test-plugin) is the recommended way to access internal code -as it is easier to use due to being able to have the remapped code in your IDE. You can find -out more about this in the [`paperweight-userdev`](/paper/dev/userdev) section. - -However, if you are unable to use `paperweight-userdev`, you can use reflection. - -### Reflection - -Reflection is a way to access code at runtime. This allows you to access code that may not be available at compile time. -Reflection is often used to access internal code across multiple versions. However, reflection does come -with performance impacts if used improperly. For example, if you are accessing a method or field more than once, -you should cache the `Field`/ -`Method` to prevent the performance -impact of looking up the field/method each time. - -The internal CraftBukkit code is relocated to `org.bukkit.craftbukkit.` unless you run a Mojang-mapped version -of Paper. This is unlikely to be the case in most production environments. This means that any attempts to reflect must -include the version. For example, `org.bukkit.craftbukkit.v1_20_R2.CraftServer` is the full class and package name -for the CraftServer class in version 1.20.2. You can access these classes easily with some reflection utilities. - -:::warning[Removal of relocation in 1.20.5] - -As of 1.20.5, the versioned relocation of the CraftBukkit package was removed and -CraftBukkit packages are now located in `org.bukkit.craftbukkit` and not in `org.bukkit.craftbukkit.`. - -::: - -```java -private static final String CRAFTBUKKIT_PACKAGE = Bukkit.getServer().getClass().getPackage().getName(); - -public static String cbClass(String clazz) { - return CRAFTBUKKIT_PACKAGE + "." + clazz; -} - -// You can then use this method to get the CraftBukkit class: -Class.forName(cbClass("entity.CraftBee")); -``` - -Minecraft's code is obfuscated. This means that the names of classes and methods are changed to make them harder to -understand. Paper deobfuscates these identifiers for development; however, to provide compatibility with legacy plugins, -Paper is re-obfuscated at runtime. You can use a library like [reflection-remapper](https://github.com/jpenilla/reflection-remapper) to automatically remap the -reflection references. This will allow you to use the de-obfuscated, Mojang-mapped, names in your code. This is recommended as -it makes the code easier to understand. - -### Mojang-Mapped Servers - -:::info[Mojang-mapped runtime as of 1.20.5] - -As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. -For more information, see the [plugin remapping](./project-setup#plugin-remapping) section and [userdev](./userdev#1205-and-beyond) documentation covering these changes. - -::: - -Running a Mojang-Mapped (moj-map) server is an excellent way to streamline your processes because you can develop using -the same mappings that will be present at runtime. This eliminates the need for remapping in your compilation. If you -are creating custom plugins for your server, we highly recommend running a moj-map server. It simplifies debugging and -allows you to hotswap plugins. - -In the future, the Paper server will no longer undergo remapping. By adopting Mojang mappings now, you can ensure that -your plugin won't require internal remapping when we make the switch. - -### Getting the current Minecraft version - -You can get the current Minecraft version to allow you to use the correct code for a specific version. This can be done -with one of the following methods: - - -``` -// Example value: %%_MAJ_MIN_PAT_MC_%% -String minecraftVersion = Bukkit.getServer().getMinecraftVersion(); - -// Example value: %%_MAJ_MIN_PAT_MC_%%-R0.1-SNAPSHOT -String bukkitVersion = Bukkit.getServer().getBukkitVersion(); - -// Example value for 1.20.1: 3465 -int dataVersion = Bukkit.getUnsafe().getDataVersion(); -``` - - -:::danger[Parsing the version] - -Parsing the version from the package name of classes is no longer possible as of 1.20.5 as Paper stopped relocating the CraftBukkit package. -See the [reflection](#reflection) section for more information. - -::: diff --git a/docs/versioned/paper/content/1.20/dev/misc/reading-stacktraces.mdx b/docs/versioned/paper/content/1.20/dev/misc/reading-stacktraces.mdx deleted file mode 100644 index c32dbe9b3..000000000 --- a/docs/versioned/paper/content/1.20/dev/misc/reading-stacktraces.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -slug: /dev/reading-stacktraces -description: Stacktraces are produced by the JVM when an exception occurs. This guide will discuss the basics of how to read them. ---- - -# Reading Stacktraces - -## What is a stacktrace? -In Java, a stacktrace shows the call stack of a thread. The call stack is the path of execution that led to the current point in the program. -Usually, the stacktrace will be printed to the console when an exception is not handled correctly. - -Stacktraces are a useful tool for debugging your code. They show you the exact line of code that caused an error, and the -line of code that called that line of code, and so on. This is useful because it allows you to see the exact path of execution that led to the error. - -### Example - -Here is an example of a stacktrace, which has been caused due to a `NullPointerException`: - -```javastacktrace -[15:20:42 ERROR]: Could not pass event PluginEnableEvent to TestPlugin v1.0 -java.lang.NullPointerException: Cannot invoke "Object.toString()" because "player" is null - at io.papermc.testplugin.TestPlugin.onPluginEnable(TestPlugin.java:23) ~[TestPlugin-1.0-SNAPSHOT.jar:?] - at com.destroystokyo.paper.event.executor.asm.generated.GeneratedEventExecutor1.execute(Unknown Source) ~[?:?] - at org.bukkit.plugin.EventExecutor$2.execute(EventExecutor.java:77) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?] - at co.aikar.timings.TimedEventExecutor.execute(TimedEventExecutor.java:81) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:git-Paper-49] - at org.bukkit.plugin.RegisteredListener.callEvent(RegisteredListener.java:70) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?] - at io.papermc.paper.plugin.manager.PaperEventManager.callEvent(PaperEventManager.java:54) ~[paper-1.20.2.jar:git-Paper-49] - at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.callEvent(PaperPluginManagerImpl.java:126) ~[paper-1.20.2.jar:git-Paper-49] - at org.bukkit.plugin.SimplePluginManager.callEvent(SimplePluginManager.java:615) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?] - at io.papermc.paper.plugin.manager.PaperPluginInstanceManager.enablePlugin(PaperPluginInstanceManager.java:200) ~[paper-1.20.2.jar:git-Paper-49] - at io.papermc.paper.plugin.manager.PaperPluginManagerImpl.enablePlugin(PaperPluginManagerImpl.java:104) ~[paper-1.20.2.jar:git-Paper-49] - at org.bukkit.plugin.SimplePluginManager.enablePlugin(SimplePluginManager.java:507) ~[paper-api-1.20.2-R0.1-SNAPSHOT.jar:?] - at org.bukkit.craftbukkit.v1_20_R2.CraftServer.enablePlugin(CraftServer.java:636) ~[paper-1.20.2.jar:git-Paper-49] - at org.bukkit.craftbukkit.v1_20_R2.CraftServer.enablePlugins(CraftServer.java:547) ~[paper-1.20.2.jar:git-Paper-49] - at net.minecraft.server.MinecraftServer.loadWorld0(MinecraftServer.java:636) ~[paper-1.20.2.jar:git-Paper-49] - at net.minecraft.server.MinecraftServer.loadLevel(MinecraftServer.java:435) ~[paper-1.20.2.jar:git-Paper-49] - at net.minecraft.server.dedicated.DedicatedServer.initServer(DedicatedServer.java:308) ~[paper-1.20.2.jar:git-Paper-49] - at net.minecraft.server.MinecraftServer.runServer(MinecraftServer.java:1101) ~[paper-1.20.2.jar:git-Paper-49] - at net.minecraft.server.MinecraftServer.lambda$spin$0(MinecraftServer.java:318) ~[paper-1.20.2.jar:git-Paper-49] - at java.lang.Thread.run(Thread.java:833) ~[?:?] -``` - -- Firstly, we can see that this certain error occurred when a `PluginEnableEvent` - was being handled by the `TestPlugin`. - -- Then we can see on the second line, the cause of the exception: - > `java.lang.NullPointerException: Cannot invoke "Object.toString()" because "player" is null` - - This tells us that the exception was caused by a `NullPointerException`, - and that the exception was caused because we tried to call the `toString()` method on a null "player" object. - -- From here, as we work down the stacktrace, we can see the exact path of execution that led to the error. In this case, - the next line of the stacktrace is: - > `at io.papermc.testplugin.TestPlugin.onPluginEnable(TestPlugin.java:23) ~[TestPlugin-1.0-SNAPSHOT.jar:?]` - - Which tells us that the error was thrown at line 23 of `TestPlugin.java`. - -- You can continue to work down the stacktrace, and see the exact path of execution that led to the error. In this case, - it is server internals, so we can generally ignore it. - -## Omitted stacktraces - -In JDK 5, the JVM started to omit stacktraces for certain exceptions. This was common when the JVM had optimized the code, -and you could get `NullPointerException`s without a stacktrace. In order to fix this, you can pass the `-XX:-OmitStackTraceInFastThrow` flag to the JVM: - -```bash -java -XX:-OmitStackTraceInFastThrow -jar paper.jar -``` diff --git a/docs/versioned/paper/sidebars/1.18.json b/docs/versioned/paper/sidebars/1.18.json deleted file mode 100644 index 86d9238d4..000000000 --- a/docs/versioned/paper/sidebars/1.18.json +++ /dev/null @@ -1,70 +0,0 @@ -{ - "primary": [ - "README", - { - "type": "category", - "label": "Administration", - "collapsed": true, - "link": { - "type": "doc", - "id": "admin/README" - }, - "items": [ - { - "type": "category", - "label": "Getting Started", - "link": { - "type": "generated-index", - "slug": "/cat/admin/getting-started" - }, - "items": [ - "admin/getting-started/getting-started", - "admin/getting-started/adding-plugins", - "admin/getting-started/migration" - ] - }, - { - "type": "category", - "label": "How-to Guides", - "link": { - "type": "generated-index", - "slug": "/cat/admin/how-to-guides" - }, - "items": [ - "admin/how-to/configuration", - "admin/how-to/update", - "admin/how-to/aikars-flags", - "admin/how-to/anti-xray" - ] - }, - { - "type": "category", - "label": "Reference", - "link": { - "type": "generated-index", - "slug": "/cat/admin/reference" - }, - "items": [ - "admin/reference/global-configuration", - "admin/reference/world-configuration" - ] - } - ] - }, - { - "type": "category", - "label": "Development", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/README" - }, - "items": [ - { - "type": "ref", - "id": "dev/README" - } - ] - } - ] -} diff --git a/docs/versioned/paper/sidebars/1.19.json b/docs/versioned/paper/sidebars/1.19.json deleted file mode 100644 index ff6bada53..000000000 --- a/docs/versioned/paper/sidebars/1.19.json +++ /dev/null @@ -1,106 +0,0 @@ -{ - "primary": [ - "README", - { - "type": "category", - "label": "Administration", - "collapsed": true, - "link": { - "type": "doc", - "id": "admin/README" - }, - "items": [ - { - "type": "category", - "label": "Getting Started", - "link": { - "type": "generated-index", - "slug": "/cat/admin/getting-started" - }, - "items": [ - "admin/getting-started/getting-started", - "admin/getting-started/adding-plugins", - "admin/getting-started/migration", - "admin/reference/paper-plugins" - ] - }, - { - "type": "category", - "label": "How-to Guides", - "link": { - "type": "generated-index", - "slug": "/cat/admin/how-to-guides" - }, - "items": [ - "admin/how-to/basic-troubleshooting", - "admin/how-to/configuration", - "admin/how-to/update", - "admin/how-to/aikars-flags", - "admin/how-to/anti-xray" - ] - }, - { - "type": "category", - "label": "Reference", - "link": { - "type": "generated-index", - "slug": "/cat/admin/reference" - }, - "items": [ - "admin/reference/global-configuration", - "admin/reference/world-configuration", - "admin/reference/system-properties" - ] - } - ] - }, - { - "type": "category", - "label": "Development", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/README" - }, - "items": [ - { - "type": "category", - "label": "Getting started", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/getting-started/README" - }, - "items": [ - "dev/getting-started/project-setup", - "dev/getting-started/plugin-yml", - "dev/getting-started/paper-plugins" - ] - }, - { - "type": "category", - "label": "API", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/api/README" - }, - "items": [ - { - "type": "category", - "label": "Event API", - "collapsed": true, - "items": [ - "dev/api/event-api/event-listeners", - "dev/api/event-api/custom-events", - "dev/api/event-api/handler-lists" - ] - }, - "dev/api/pdc", - "dev/api/custom-inventory-holder" - ] - } - ] - } - ] -} diff --git a/docs/versioned/paper/sidebars/1.20.json b/docs/versioned/paper/sidebars/1.20.json deleted file mode 100644 index c9e50d37f..000000000 --- a/docs/versioned/paper/sidebars/1.20.json +++ /dev/null @@ -1,190 +0,0 @@ -{ - "primary": [ - "README", - { - "type": "category", - "label": "Administration", - "collapsed": true, - "link": { - "type": "doc", - "id": "admin/README" - }, - "items": [ - { - "type": "category", - "label": "Getting Started", - "link": { - "type": "generated-index", - "slug": "/cat/admin/getting-started" - }, - "items": [ - "admin/getting-started/getting-started", - "admin/getting-started/setup-next-steps", - "admin/getting-started/adding-plugins", - "admin/getting-started/migration" - ] - }, - { - "type": "category", - "label": "How-to Guides", - "link": { - "type": "generated-index", - "slug": "/cat/admin/how-to-guides" - }, - "items": [ - "admin/how-to/basic-troubleshooting", - "admin/how-to/update", - "admin/how-to/aikars-flags", - "admin/how-to/anti-xray" - ] - }, - { - "type": "category", - "label": "Reference", - "link": { - "type": "generated-index", - "slug": "/cat/admin/reference" - }, - "items": [ - { - "type": "category", - "label": "Configuration", - "link": { - "type": "doc", - "id": "admin/reference/configuration/README" - }, - "items": [ - "admin/reference/configuration/global-configuration", - "admin/reference/configuration/world-configuration", - "admin/reference/configuration/server-properties", - "admin/reference/configuration/spigot-configuration", - "admin/reference/configuration/bukkit-configuration", - "admin/reference/configuration/bukkit-commands-configuration" - ] - }, - "admin/reference/system-properties", - "admin/reference/paper-plugins", - "admin/reference/vanilla-command-permissions" - ] - }, - { - "type": "category", - "label": "Miscellaneous", - "link": { - "type": "generated-index", - "slug": "/cat/admin/misc" - }, - "items": [ - "admin/misc/faq", - "admin/misc/paper-bug-fixes" - ] - } - ] - }, - { - "type": "category", - "label": "Development", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/README" - }, - "items": [ - { - "type": "category", - "label": "Getting started", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/getting-started/README" - }, - "items": [ - "dev/getting-started/project-setup", - "dev/getting-started/plugin-yml", - "dev/getting-started/how-do-plugins-work", - "dev/getting-started/paper-plugins", - "dev/getting-started/userdev" - ] - }, - { - "type": "category", - "label": "API", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/api/README" - }, - "items": [ - { - "type": "category", - "label": "Event API", - "collapsed": true, - "items": [ - "dev/api/event-api/event-listeners", - "dev/api/event-api/custom-events", - "dev/api/event-api/handler-lists", - "dev/api/event-api/chat-event" - ] - }, - { - "type": "category", - "label": "Entity API", - "collapsed": true, - "items": [ - "dev/api/entity-api/entity-teleport", - "dev/api/entity-api/display-entities" - ] - }, - { - "type": "category", - "label": "Component API (Adventure)", - "collapsed": true, - "items": [ - "dev/api/component-api/intro", - "dev/api/component-api/i18n", - "dev/api/component-api/audiences" - ] - }, - "dev/api/pdc", - "dev/api/custom-inventory-holder", - "dev/api/commands", - "dev/api/scheduler", - "dev/api/plugin-messaging", - "dev/api/plugin-configs", - "dev/api/lifecycle", - "dev/api/recipes", - "dev/api/folia-support", - "dev/api/roadmap" - ] - }, - { - "type": "category", - "label": "Miscellaneous", - "collapsed": true, - "link": { - "type": "doc", - "id": "dev/misc/README" - }, - "items": [ - "dev/misc/reading-stacktraces", - "dev/misc/debugging", - "dev/misc/databases", - "dev/misc/internal-code" - ] - } - ] - }, - { - "type": "category", - "label": "Contributing", - "collapsed": true, - "link": { - "type": "doc", - "id": "contributing/README" - }, - "items": [ - "contributing/events" - ] - } - ] -} diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 3e27b8603..ea0d7696b 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -135,13 +135,6 @@ const config: Config = { path: "docs/paper", routeBasePath: "paper", sidebarPath: require.resolve("./config/sidebar.paper"), - lastVersion: "current", - versions: { - current: { - label: "1.21", - path: "", - }, - }, }, ], [ @@ -152,13 +145,6 @@ const config: Config = { path: "docs/folia", routeBasePath: "folia", sidebarPath: require.resolve("./config/sidebar.folia"), - lastVersion: "current", - versions: { - current: { - label: "1.20", - path: "", - }, - }, }, ], [ diff --git a/src/theme/DocItem/Layout/index.tsx b/src/theme/DocItem/Layout/index.tsx new file mode 100644 index 000000000..bf3aeaa1a --- /dev/null +++ b/src/theme/DocItem/Layout/index.tsx @@ -0,0 +1,75 @@ +import React from 'react'; +import clsx from 'clsx'; +import {useWindowSize} from '@docusaurus/theme-common'; +import {useDoc} from '@docusaurus/plugin-content-docs/client'; +import DocItemPaginator from '@theme/DocItem/Paginator'; +import DocVersionBanner from '@theme/DocVersionBanner'; +import DocVersionBadge from '@theme/DocVersionBadge'; +import DocItemFooter from '@theme/DocItem/Footer'; +import DocItemTOCMobile from '@theme/DocItem/TOC/Mobile'; +import DocItemTOCDesktop from '@theme/DocItem/TOC/Desktop'; +import DocItemContent from '@theme/DocItem/Content'; +import DocBreadcrumbs from '@theme/DocBreadcrumbs'; +import ContentVisibility from '@theme/ContentVisibility'; +import type {Props} from '@theme/DocItem/Layout'; + +import styles from './styles.module.css'; + +/** + * Decide if the toc should be rendered, on mobile or desktop viewports + */ +function useDocTOC() { + const {frontMatter, toc} = useDoc(); + const windowSize = useWindowSize(); + + const hidden = frontMatter.hide_table_of_contents; + const canRender = !hidden && toc.length > 0; + + const mobile = canRender ? : undefined; + + const desktop = + canRender && (windowSize === 'desktop' || windowSize === 'ssr') ? ( + + ) : undefined; + + return { + hidden, + mobile, + desktop, + }; +} + +function DocVersionLabel({ version }: { version: string }): JSX.Element { + return ( +
+ Written for version: {version} +
+ ); +} + +export default function DocItemLayout({children}: Props): JSX.Element { + const docTOC = useDocTOC(); + const {metadata} = useDoc(); + const targetVersion: string = metadata.frontMatter?.targetVersion?.toString() ?? null; + + return ( +
+
+ + +
+
+ + + {docTOC.mobile} + {children} + + {targetVersion && } +
+ +
+
+ {docTOC.desktop &&
{docTOC.desktop}
} +
+ ); +} diff --git a/src/theme/DocItem/Layout/styles.module.css b/src/theme/DocItem/Layout/styles.module.css new file mode 100644 index 000000000..0a6ee4f1b --- /dev/null +++ b/src/theme/DocItem/Layout/styles.module.css @@ -0,0 +1,22 @@ +.docItemContainer header + *, +.docItemContainer article > *:first-child { + margin-top: 0; +} + +@media (min-width: 997px) { + .docItemCol { + max-width: 75% !important; + } +} + +.docVersionContainer { + background: var(--ifm-color-info-contrast-background); + border-radius: 12px; + padding: 15px 20px; + display: flex; + align-items: center; + font-size: 16px; + font-weight: bold; + margin-top: 10px; + justify-content: center; +}