From 416d78bc8dedfa4a8b2f71db8584523feb311b09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Matou=C5=A1=20Ku=C4=8Dera?= Date: Thu, 11 Apr 2024 14:33:12 +0200 Subject: [PATCH] chore: syntax cleanup and standardization (#343) chore: syntax housekeeping --------- Co-authored-by: Ollie <69084614+olijeffers0n@users.noreply.github.com> --- .typos.toml | 6 ++ CONTRIBUTING.md | 4 ++ config-specs/paper/bukkit.yml | 24 +++---- config-specs/paper/commands.yml | 8 +-- config-specs/paper/paper-global.yml | 6 +- config-specs/paper/paper-world-defaults.yml | 22 +++---- config-specs/paper/spigot.yml | 46 ++++++------- docs/folia/admin/README.mdx | 4 +- docs/folia/admin/reference/faq.md | 16 ++--- docs/folia/admin/reference/overview.md | 45 +++++++------ docs/folia/admin/reference/region-logic.md | 25 ++++--- docs/folia/dev/README.mdx | 2 +- docs/misc/assets.md | 4 +- docs/misc/downloads-api.mdx | 6 +- docs/misc/hangar-publishing.md | 14 ++-- docs/misc/tools/start-script-gen.mdx | 4 +- docs/paper/README.mdx | 2 +- docs/paper/admin/README.mdx | 4 +- .../admin/getting-started/adding-plugins.md | 20 +++--- .../admin/getting-started/getting-started.mdx | 12 ++-- docs/paper/admin/getting-started/migration.md | 12 ++-- docs/paper/admin/how-to/aikars-flags.md | 38 +++++------ docs/paper/admin/how-to/anti-xray.mdx | 21 +----- .../admin/how-to/basic-troubleshooting.md | 60 ++++++++--------- docs/paper/admin/how-to/update.md | 6 +- docs/paper/admin/misc/paper-bug-fixes.md | 14 ++-- .../admin/reference/configuration/README.mdx | 12 ++-- .../bukkit-commands-configuration.mdx | 2 +- .../configuration/bukkit-configuration.mdx | 2 +- .../configuration/spigot-configuration.mdx | 2 +- .../configuration/world-configuration.mdx | 2 +- docs/paper/admin/reference/paper-plugins.md | 6 +- .../admin/reference/system-properties.md | 15 +++-- docs/paper/contributing/README.mdx | 2 +- docs/paper/contributing/events.mdx | 8 +-- docs/paper/dev/README.mdx | 2 +- docs/paper/dev/api/README.mdx | 4 +- docs/paper/dev/api/component-api/audiences.md | 14 ++-- docs/paper/dev/api/component-api/i18n.md | 3 +- docs/paper/dev/api/component-api/intro.md | 39 +++++------ docs/paper/dev/api/custom-inventory-holder.md | 30 ++++----- docs/paper/dev/api/event-api/chat-event.mdx | 53 +++++++++------ docs/paper/dev/api/event-api/custom-events.md | 7 +- .../dev/api/event-api/event-listeners.mdx | 4 +- docs/paper/dev/api/folia-support.md | 22 +++---- docs/paper/dev/api/{pdc.md => pdc.mdx} | 62 ++++++++--------- docs/paper/dev/api/plugin-configs.md | 64 +++++++++--------- docs/paper/dev/api/plugin-messaging.md | 66 +++++++++---------- docs/paper/dev/api/roadmap.md | 65 +++++++++--------- docs/paper/dev/api/scheduler.md | 22 +++---- docs/paper/dev/getting-started/README.mdx | 2 +- .../getting-started/how-do-plugins-work.md | 6 +- .../dev/getting-started/paper-plugins.mdx | 53 +++++++-------- docs/paper/dev/getting-started/plugin-yml.mdx | 43 +++++++----- .../dev/getting-started/project-setup.mdx | 6 +- docs/paper/dev/getting-started/userdev.mdx | 16 ++--- docs/paper/dev/misc/databases.mdx | 30 ++++----- docs/paper/dev/misc/debugging.mdx | 2 +- docs/paper/dev/misc/reading-stacktraces.md | 6 +- docs/velocity/README.mdx | 2 +- docs/velocity/admin/README.mdx | 4 +- docs/velocity/admin/getting-started/faq.mdx | 17 +++-- .../admin/getting-started/forwarding.md | 5 +- .../admin/getting-started/why-velocity.md | 2 +- docs/velocity/admin/how-to/migration.md | 2 +- docs/velocity/admin/how-to/security.md | 16 ++--- docs/velocity/admin/how-to/tuning.md | 4 +- docs/velocity/admin/reference/commands.md | 7 +- docs/velocity/admin/reference/comparison.md | 4 +- .../velocity/admin/reference/configuration.md | 38 +++++------ docs/velocity/admin/reference/libraries.md | 2 +- .../admin/reference/server-compatibility.mdx | 18 ++--- docs/velocity/dev/README.mdx | 2 +- docs/velocity/dev/api/command.md | 6 +- .../dev/api/component-api/audiences.mdx | 2 +- docs/velocity/dev/api/component-api/i18n.mdx | 2 +- docs/velocity/dev/api/component-api/intro.mdx | 2 +- docs/velocity/dev/api/event.md | 8 +-- docs/velocity/dev/api/plugin-messaging.md | 20 +++--- docs/velocity/dev/api/scheduler.md | 2 +- .../dev/getting-started/api-basics.md | 8 +-- .../creating-your-first-plugin.mdx | 6 +- docs/velocity/dev/getting-started/pitfalls.md | 4 +- docs/velocity/dev/how-to/dependencies.md | 8 +-- .../dev/how-to/porting-from-velocity-1.mdx | 6 +- docs/waterfall/configuration.mdx | 2 +- docs/waterfall/getting-started.md | 12 ++-- .../config/ConfigurationStructureDiagram.tsx | 2 +- 88 files changed, 660 insertions(+), 650 deletions(-) rename docs/paper/dev/api/{pdc.md => pdc.mdx} (78%) diff --git a/.typos.toml b/.typos.toml index 00fa3790a..48f763082 100644 --- a/.typos.toml +++ b/.typos.toml @@ -18,6 +18,7 @@ armour = "armor" authorise = "authorize" authorised = "authorized" authorising = "authorizing" +behaviour = "behavior" catalogue = "catalog" centre = "center" civilisation = "civilization" @@ -25,11 +26,16 @@ civilised = "civilized" colour = "color" colours = "colors" defence = "defense" +generalise = "generalize" +generalised = "generalized" gramme = "gram" grammes = "grams" grey = "gray" honour = "honor" honours = "honors" +initialise = "initialize" +initialised = "initialized" +initialiser = "initializer" kerb = "curb" kerbs = "curbs" labour = "labor" diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 01f5c2f5a..c4a02c8df 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -79,6 +79,8 @@ To maintain consistency and readability across the documentation, please adhere 2. **Markdown Format**: Documentation should be written in Markdown format (.md or .mdx) for easy rendering on the website. 3. **Heading Structure**: Use `h1` (#) for the main title, `h2` (##) for section headings, and follow this pattern for subsequent subheadings. + Capitalize the first letter of each word in a h1, however, only capitalize the first letter of the first word in h2 and h3 unless~ + it is a proper noun. 4. **Code Blocks**: When including code snippets or terminal commands, use fenced code blocks with the appropriate syntax highlighting. @@ -95,6 +97,8 @@ To maintain consistency and readability across the documentation, please adhere 10. **Be Inclusive**: Be mindful of all readers and contributors. Use language that is inclusive and welcoming to everyone. +11. **Capitalise Vanilla**: When referring to the base game, use "Vanilla" with a capital "V". + ## Automatic Doc Versioning There are components and methods in order to embed the current Project Version into the documentation. This is done one diff --git a/config-specs/paper/bukkit.yml b/config-specs/paper/bukkit.yml index 82f39c275..8a44e13b7 100644 --- a/config-specs/paper/bukkit.yml +++ b/config-specs/paper/bukkit.yml @@ -51,7 +51,7 @@ settings: default: update description: >- Path to replace new plugin versions with. - [See Updating Plugins](/paper/updating#step-2-update-plugins) for more information. + See [Updating Plugins](/paper/updating#step-2-update-plugins) for more information. use-map-color-cache: default: "true" description: >- @@ -65,37 +65,37 @@ spawn-limits: default: "15" description: >- Set the spawn-limits for ambient mobs. This can be overridden by the - [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_ambient). + [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_ambient). animals: default: "10" description: >- Set the spawn-limits for animals. This can be overridden by the - [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_creature). + [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_creature). axolotls: default: "5" description: >- Set the spawn-limits for axolotls. This can be overridden by the - [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_axolotls). + [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_axolotls). monsters: default: "70" description: >- Set the spawn-limits for monsters. This can be overridden by the - [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_monster). + [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_monster). water-ambient: default: "20" description: >- Set the spawn-limits for water ambient mobs. This can be overridden by the - [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_water_ambient). + [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_water_ambient). water-animals: default: "5" description: >- Set the spawn-limits for water animals. This can be overridden by the - [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_water_creature). + [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_water_creature). water-underground-creature: default: "5" description: >- Set the spawn-limits for water underground creatures. This can be - overridden by the [paper-world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_underground_water_creature). + overridden by the [Paper world config](/paper/reference/world-configuration#entities_spawning_spawn_limits_underground_water_creature). ticks-per: ambient-spawns: default: "1" @@ -142,14 +142,14 @@ worlds: biome-provider: default: "N/A" description: >- - The biome provider to use for this world. Plugins must register a BiomeProvider + The biome provider to use for this world. Plugins must register a `BiomeProvider` to be used here. The format is *plugin-name:extra-parameters* or *plugin-name* if no extra parameters are needed. The plugin name is as defined in the - plugin.yml or paper-plugin.yml. + `plugin.yml` or `paper-plugin.yml`. generator: default: "N/A" description: >- - The generator to use for this world. Plugins must register a ChunkGenerator + The generator to use for this world. Plugins must register a `ChunkGenerator` to be used here. The format is *plugin-name:extra-parameters* or *plugin-name* if no extra parameters are needed. The plugin name is as defined - in the plugin.yml or paper-plugin.yml. + in the `plugin.yml` or `paper-plugin.yml`. diff --git a/config-specs/paper/commands.yml b/config-specs/paper/commands.yml index de63aaf8e..be5212c4f 100644 --- a/config-specs/paper/commands.yml +++ b/config-specs/paper/commands.yml @@ -1,16 +1,16 @@ command-block-overrides: default: "[]" description: > - Which vanilla commands should be prioritized over those provided by Bukkit - or plugins. Useful for compatibility with adventure maps built for vanilla + Which Vanilla commands should be prioritized over those provided by Bukkit + or plugins. Useful for compatibility with adventure maps built for Vanilla command blocks. - Use the literal ''*'' to always use the vanilla version in command blocks. + Use the literal ''*'' to always use the Vanilla version in command blocks. By default, no commands are overridden. ignore-vanilla-permissions: default: "false" - description: Whether to use vanilla permission levels when executing commands. + description: Whether to use Vanilla permission levels when executing commands. aliases: : default: "[]" diff --git a/config-specs/paper/paper-global.yml b/config-specs/paper/paper-global.yml index f08aa2265..ec50dcad0 100644 --- a/config-specs/paper/paper-global.yml +++ b/config-specs/paper/paper-global.yml @@ -81,7 +81,7 @@ collisions: default: "true" description: >- Collisions with boats and minecarts are often subject to client/server - disagreement, which may cause glitchy behaviour for players. This setting + 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 @@ -225,7 +225,7 @@ misc: 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 + custom overworlds. Defaults to false in order to match Vanilla behavior strict-advancement-dimension-check: default: "false" description: >- @@ -400,7 +400,7 @@ unsupported-settings: allow-permanent-block-break-exploits: default: "false" description: >- - Whether unbreakable blocks can be broken with vanilla exploits. This + 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" diff --git a/config-specs/paper/paper-world-defaults.yml b/config-specs/paper/paper-world-defaults.yml index ef6088d0e..25f38f14a 100644 --- a/config-specs/paper/paper-world-defaults.yml +++ b/config-specs/paper/paper-world-defaults.yml @@ -175,11 +175,11 @@ collisions: command-blocks: permissions-level: default: "2" - description: "Default vanilla permission level for command blocks." + description: "Default Vanilla permission level for command blocks." force-follow-perm-level: default: "true" description: "Require that command blocks meet both the Bukkit permission requirements - and the vanilla permission level. Otherwise, only 1 of those is required." + and the Vanilla permission level. Otherwise, only 1 of those is required." entities: armor-stands: do-collision-entity-lookups: @@ -240,13 +240,13 @@ entities: description: >- Instructs the server to allow zombies to pick up loot. If set to false, the probability that a zombie picks up items depends on the - world's difficulty (vanilla behavior) + world's difficulty (Vanilla behavior) skeleton: default: "false" description: >- Instructs the server to allow skeletons to pick up loot. If set to false, the probability that a skeleton picks up items depends on the - world's difficulty (vanilla behavior) + world's difficulty (Vanilla behavior) nerf-pigmen-from-nether-portals: default: "false" description: "Removes AI from pigmen spawned via nether portals " @@ -429,9 +429,9 @@ entities: 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 + 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 + 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 @@ -660,7 +660,7 @@ environment: 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 + 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" @@ -680,7 +680,7 @@ environment: 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 + description: Whether to apply Vanilla dimension scaling to portal-search-radius treasure-maps: enabled: default: "true" @@ -693,7 +693,7 @@ environment: 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 + 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 @@ -923,8 +923,8 @@ scoreboards: 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 + 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: diff --git a/config-specs/paper/spigot.yml b/config-specs/paper/spigot.yml index 90eca1611..ae6728592 100644 --- a/config-specs/paper/spigot.yml +++ b/config-specs/paper/spigot.yml @@ -394,7 +394,7 @@ world-settings: bamboo-modifier: default: "100" description: >- - The growth modifier percentage for bamboo, where vanilla speed is + The growth modifier percentage for bamboo, where Vanilla speed is 100%. This option is unable to disable growth at 0%, instead defaulting to 100% @@ -402,7 +402,7 @@ world-settings: beetroot-modifier: default: "100" description: >- - The growth modifier percentage for beetroot, where vanilla speed is + The growth modifier percentage for beetroot, where Vanilla speed is 100%. This option is unable to disable growth at 0%, instead defaulting to 100% @@ -410,7 +410,7 @@ world-settings: cactus-modifier: default: "100" description: >- - The growth modifier percentage for cactus, where vanilla speed is + The growth modifier percentage for cactus, where Vanilla speed is 100%. This option is unable to disable growth at 0, instead defaulting to 100% @@ -418,7 +418,7 @@ world-settings: cane-modifier: default: "100" description: >- - The growth modifier percentage for sugarcane, where vanilla speed is + The growth modifier percentage for sugarcane, where Vanilla speed is 100%. This option is unable to disable growth at 0%, instead defaulting to 100% @@ -426,7 +426,7 @@ world-settings: carrot-modifier: default: "100" description: >- - The growth modifier percentage for carrots, where vanilla speed is + The growth modifier percentage for carrots, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -434,7 +434,7 @@ world-settings: cavevines-modifier: default: "100" description: >- - The growth modifier percentage for cave-vines, where vanilla speed is + The growth modifier percentage for cave-vines, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -442,7 +442,7 @@ world-settings: cocoa-modifier: default: "100" description: >- - The growth modifier percentage for cocoa beans, where vanilla speed is + The growth modifier percentage for cocoa beans, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -450,7 +450,7 @@ world-settings: glowberry-modifier: default: "100" description: >- - The growth modifier percentage for glow-berries, where vanilla speed + The growth modifier percentage for glow-berries, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -458,14 +458,14 @@ world-settings: kelp-modifier: default: "100" description: >- - The growth modifier percentage for kelp, where vanilla speed is 100%. + The growth modifier percentage for kelp, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% The maximum effectiveness is roughly 715% melon-modifier: default: "100" description: >- - The growth modifier percentage for melons, where vanilla speed is + The growth modifier percentage for melons, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -473,7 +473,7 @@ world-settings: mushroom-modifier: default: "100" description: >- - The growth modifier percentage for mushrooms, where vanilla speed is + The growth modifier percentage for mushrooms, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -481,7 +481,7 @@ world-settings: netherwart-modifier: default: "100" description: >- - The growth modifier percentage for netherwart, where vanilla speed is + The growth modifier percentage for netherwart, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -489,7 +489,7 @@ world-settings: pitcherplant-modifier: default: "100" description: >- - The growth modifier percentage for pitcherplants, where vanilla speed + The growth modifier percentage for pitcherplants, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -497,7 +497,7 @@ world-settings: potato-modifier: default: "100" description: >- - The growth modifier percentage for potatoes, where vanilla speed is + The growth modifier percentage for potatoes, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -505,7 +505,7 @@ world-settings: pumpkin-modifier: default: "100" description: >- - The growth modifier percentage for pumpkins, where vanilla speed is + The growth modifier percentage for pumpkins, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -513,7 +513,7 @@ world-settings: sapling-modifier: default: "100" description: >- - The growth modifier percentage for saplings, where vanilla speed is + The growth modifier percentage for saplings, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -521,7 +521,7 @@ world-settings: sweetberry-modifier: default: "100" description: >- - The growth modifier percentage for sweet-berries, where vanilla speed + The growth modifier percentage for sweet-berries, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -529,7 +529,7 @@ world-settings: torchflower-modifier: default: "100" description: >- - The growth modifier percentage for torchflowers, where vanilla speed + The growth modifier percentage for torchflowers, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -537,7 +537,7 @@ world-settings: twistingvines-modifier: default: "100" description: >- - The growth modifier percentage for twisting-vines, where vanilla speed + The growth modifier percentage for twisting-vines, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -545,14 +545,14 @@ world-settings: vine-modifier: default: "100" description: >- - The growth modifier percentage for vines, where vanilla speed is 100%. + The growth modifier percentage for vines, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% The maximum effectiveness is 400% weepingvines-modifier: default: "100" description: >- - The growth modifier percentage for weeping-vines, where vanilla speed + The growth modifier percentage for weeping-vines, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% @@ -560,7 +560,7 @@ world-settings: wheat-modifier: default: "100" description: >- - The growth modifier percentage for wheat, where vanilla speed is 100%. + The growth modifier percentage for wheat, where Vanilla speed is 100%. This option is unable to disable growth, instead defaulting to 100% The maximum effectiveness is 5100% @@ -624,7 +624,7 @@ world-settings: default: "3.0" description: >- The range, in blocks, that exp orbs will combine at on initial spawn. - This behavior is not present in vanilla and doesn't impact the usual + This behavior is not present in Vanilla and doesn't impact the usual merge range once spawned. Set to 0 to disable. item: default: "2.5" diff --git a/docs/folia/admin/README.mdx b/docs/folia/admin/README.mdx index b3a5d4879..308b6ff71 100644 --- a/docs/folia/admin/README.mdx +++ b/docs/folia/admin/README.mdx @@ -5,9 +5,9 @@ slug: /admin import DocCardList from "@theme/DocCardList"; import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; -# Folia Server Administration +# Folia Administration Guide -Welcome to the Folia Server Administration Guide! This guide includes information and tutorials +Welcome to the Folia administration guide! This guide includes information and tutorials regarding the administration of a Folia server. --- diff --git a/docs/folia/admin/reference/faq.md b/docs/folia/admin/reference/faq.md index 81f8a7acd..0d358cc3c 100644 --- a/docs/folia/admin/reference/faq.md +++ b/docs/folia/admin/reference/faq.md @@ -7,7 +7,7 @@ description: Questions frequently asked by our community, answered by us! # FAQ ## What server types can benefit from Folia? -Server types that naturally spread players out, +Server types that naturally spread players out, like skyblock or SMP, will benefit the most from Folia. The server should have a sizeable player count, too. @@ -20,12 +20,12 @@ of chunk system worker threads required is reduced greatly. The following is a _very rough_ estimation based off of the testing done before Folia was released on the test server we ran that -had ~330 players peak. So, it is not exact and will require further tuning - +had ~330 players peak. So, it is not exact and will require further tuning - just take it as a starting point. -The total number of cores on the machine available should be -taken into account. Then, allocate threads for: -- netty IO :~4 per 200-300 players +The total number of cores on the machine available should be +taken into account. Then, allocate threads for: +- netty IO: ~4 per 200-300 players - chunk system io threads: ~3 per 200-300 players - chunk system workers if pre-generated, ~2 per 200-300 players - There is no best guess for chunk system workers if not pre-generated, as @@ -38,14 +38,14 @@ taken into account. Then, allocate threads for: After all of that allocation, the remaining cores on the system until 80% allocation (total threads allocated < 80% of cpus available) can be -allocated to tickthreads (under global config, threaded-regions.threads). +allocated to tickthreads (under global config, `threaded-regions.threads`). The reason you should not allocate more than 80% of the cores is due to the -fact that plugins or even the server may make use of additional threads +fact that plugins or even the server may make use of additional threads that you cannot configure or even predict. Additionally, the above is all a rough guess based on player count, but -it is very likely that the thread allocation will not be ideal, and you +it is very likely that the thread allocation will not be ideal, and you will need to tune it based on usage of the threads that you end up seeing. ## What commands does Folia disable? diff --git a/docs/folia/admin/reference/overview.md b/docs/folia/admin/reference/overview.md index 709154c30..2deb30ac0 100644 --- a/docs/folia/admin/reference/overview.md +++ b/docs/folia/admin/reference/overview.md @@ -1,7 +1,7 @@ --- slug: /reference/overview title: Overview -description: An overview to how Folia works. +description: An overview of how Folia works. --- # Project overview @@ -31,21 +31,21 @@ one independent area must be eventually split into independent regions when possible. Finally, to ensure that ticking regions may store and maintain data -about the current region (i.e tick count, entities within the region, chunks +about the current region (i.e. tick count, entities within the region, chunks within the region, block/fluid tick lists, and more), regions have their own data object that may only be accessed while ticking the region and by the thread ticking the region. Also, there are callbacks to merging or splitting regions so that the data object may be updated appropriately. -The implementation of these rules is described in [Region Logic](/folia/reference/region-logic). +The implementation of these rules is described in [Region Logic](region-logic.md). The end result of applying these rules is that a ticking region can ensure that only the current thread has write access to any data contained within the region, and that at any given time the number of independent regions is close to maximum. -## Intra region operations +## Intra-region operations -Intra region operations refer to any operations that only deal with data +Intra-region operations refer to any operations that only deal with data for a single region by the owning region, or to merge/split logic. ### Ticking for independent regions @@ -65,8 +65,8 @@ It is important to note that at no time was B's schedule affected by the fact th A fell behind its 20TPS target. To implement the described behavior, each region maintains a repeating -task on a scheduled executor (See SchedulerThreadPool) that schedules -tasks according to an earliest start time first scheduling algorithm. The +task on a scheduled executor (see `SchedulerThreadPool`) that schedules +tasks according to an earliest-start-time-first scheduling algorithm. The algorithm is similar to EDF, but schedules according to start time. However, given that the deadline for each tick is 50ms + the start time, it behaves identically to the EDF algorithm. @@ -140,7 +140,7 @@ in region y, so that the relative tick deadline is maintained. We can achieve this by applying an offset o to d1 so that d1 + o = d2, and the offset used is o = tick to - tick from. This offset must be calculated for redstone tick and current tick separately, since the logic to increase -redstone tick can be turned off by the Level#tickTime field. +redstone tick can be turned off by the `Level#tickTime` field. Finally, the split case is easy - when a split occurs, the independent regions from the split inherit the redstone/current tick @@ -152,34 +152,34 @@ remain unaffected when regions split or merge as the relative deadline is maintained by applying an offset in the merge case and by copying the tick number in the split case. -## Inter region operations +## Inter-region operations -Inter region refer to operations that work with other regions that are not +Inter-region operations refer to operations that work with other regions that are not the current ticking region that are in a completely unknown state. These regions may be transient, may be ticking, or may not even exist. ### Utilities to assist operations In order to assist in inter region operations, several utilities are provided. -In NMS, these utilities are the EntityScheduler, the RegionizedTaskQueue, +In NMS, these utilities are the `EntityScheduler`, the `RegionizedTaskQueue`, the global region task queue, and the region-local data provider -RegionizedData. The Folia API has similar analogues, but does not have +`RegionizedData`. The Folia API has similar analogues, but does not have a region-local data provider as the NMS data provider holds critical locks and is invoked in critical areas of code when performing any callback logic and is thus highly susceptible to fatal plugin errors involving lengthy I/O or world state modification. -#### EntityScheduler +#### `EntityScheduler` -The EntityScheduler allows tasks to be scheduled to be executed on the +The `EntityScheduler` allows tasks to be scheduled to be executed on the region that owns the entity. This is particularly useful when dealing with entity teleportation, as once an entity begins an asynchronous teleport the entity cannot tick until the teleport has completed, and the timing is undefined. -#### RegionizedTaskQueue +#### `RegionizedTaskQueue` -The RegionizedTaskQueue allows tasks to be scheduled to be executed on +The `RegionizedTaskQueue` allows tasks to be scheduled to be executed on the next tick of a region that owns a specific location, or creating such region if it does not exist. This is useful for tasks that may need to edit or retrieve world/block/chunk data outside the current region. @@ -190,15 +190,14 @@ The global region task queue is simply used to perform edits on data that the global region owns, such as game rules, day time, weather, or to execute commands using the console command sender. -#### RegionizedData +#### `RegionizedData` -The RegionizedData class allows regions to define region-local data, +The `RegionizedData` class allows regions to define region-local data, which allow regions to store data without having to consider concurrent data access from other regions. For example, current per region entity/chunk/block/fluid tick lists are maintained so that regions do not need to consider concurrent access to these data sets. -

The utilities allow various cross-region issues to be resolved in a simple fashion, such as editing block/entity/world state from any region by using tasks queues, or by avoiding concurrency issues by using @@ -206,12 +205,12 @@ RegionizedData. More advanced operations such as teleportation, player respawning, and portalling, all make use of these utilities to ensure the operation is thread-safe. -### Entity intra and inter dimension teleports +### Entity intra- and inter-dimension teleports Entities need special logic in order to teleport safely between other regions or other dimensions. In all cases however, the call to teleport/place an entity must be invoked on the region owning the entity. -The EntityScheduler can be used to easily schedule code to execute in such +The `EntityScheduler` can be used to easily schedule code to execute in such a context. #### Simple teleportation @@ -221,7 +220,7 @@ and the target location and dimension are known. This operation is split into two parts: transform and async place. In this case, the transform operation removes the entity from the current world, then adjusts the position. The async place operation schedules a task -to the target location using the RegionizedTaskQueue to add the entity to +to the target location using the `RegionizedTaskQueue` to add the entity to the target dimension at the target position. The various implementation details such as non-player entities being @@ -271,7 +270,7 @@ which then runs the shutdown logic: 8. Save all players 9. Shutting down the resource manager 10. Releasing the level lock -11. Halting remaining executors (Util executor, region I/O threads, etc) +11. Halting remaining executors (Util executor, region I/O threads, etc.) The important differences to Vanilla is that the player kick and diff --git a/docs/folia/admin/reference/region-logic.md b/docs/folia/admin/reference/region-logic.md index 4fe95464f..a60248714 100644 --- a/docs/folia/admin/reference/region-logic.md +++ b/docs/folia/admin/reference/region-logic.md @@ -17,7 +17,7 @@ the region z owns the chunk position y. ## Regionizer Each world has its own regionizer. The regionizer is a term used -to describe the logic that the class "ThreadedRegionizer" executes +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 @@ -62,7 +62,7 @@ when the ticking region finishes ticking. 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 +and then access chunk holders around it (i.e. sync loading) without the possibility that it steps on another region's toes. ### Fourth invariant @@ -81,7 +81,7 @@ with the regionizer's merge and split logic. ## Regionizer implementation The regionizer implementation is a description of how -the class "ThreadedRegionizer" adheres to the four invariants +the class `ThreadedRegionizer` adheres to the four invariants described previously. ### Splitting the world into sections @@ -158,19 +158,19 @@ region coordinate = chunk coordinate >> region section chunk shift. ### Operation -The regionizer is operated by invoking ThreadedRegionizer#addChunk(x, z) -or ThreadedRegionizer#removeChunk(x, z) when a chunk holder is created +The regionizer is operated by invoking `ThreadedRegionizer#addChunk(x, z)` +or `ThreadedRegionizer#removeChunk(x, z)` when a chunk holder is created or destroyed. -Additionally, ThreadedRegion#tryMarkTicking can be used by a caller +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 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 +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 a region as ticking must mark it as non-ticking by using -ThreadedRegion#markNotTicking. +`ThreadedRegion#markNotTicking`. The function ThreadedRegion#markNotTicking returns true if the region was migrated from "ticking" state to "ready" state, and false @@ -192,7 +192,7 @@ allows the recalculation logic of a region to be delayed until the region 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) +### Addition of chunks (`addChunk`) The addition of chunks to the regionizer boils down to two cases: @@ -262,19 +262,19 @@ 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) +### Removal of chunks (`removeChunk`) Removal of chunks from region sections simple updates the region sections state to "dead" or "alive", as well as the region sections in the empty creation radius. It will not update any region state, and nor will it purge region sections. -### Region tick start (tryMarkTicking) +### Region tick start (`tryMarkTicking`) The tick start simply migrates the state to ticking, so that invariants #2 and #3 can be met. -### Region tick end (markNotTicking) +### Region tick end (`markNotTicking`) At the end of a tick, the region's new state is not immediately known. @@ -289,4 +289,3 @@ 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 in the first place. - diff --git a/docs/folia/dev/README.mdx b/docs/folia/dev/README.mdx index bced8cf8d..f98cb1566 100644 --- a/docs/folia/dev/README.mdx +++ b/docs/folia/dev/README.mdx @@ -3,7 +3,7 @@ import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; # Development Guide -Welcome to the Folia Development Guide! This guide includes information and tutorials for developers +Welcome to the Folia development guide! This guide includes information and tutorials for developers on how to create and expand on Folia plugins. --- diff --git a/docs/misc/assets.md b/docs/misc/assets.md index f8db5c51d..5b8d06147 100644 --- a/docs/misc/assets.md +++ b/docs/misc/assets.md @@ -22,7 +22,7 @@ You may: attention to the project. - Use the PaperMC logomark to represent Paper-Server in downloads, server selectors, and similar places. -- Crop out extra transparent canvas space behind the PaperMC logomark so it fits better next to +- Crop out extra transparent canvas space behind the PaperMC logomark, so it fits better next to other content. You may not: @@ -33,7 +33,7 @@ You may not: - Add your own project images or branding to the PaperMC logomark. - Claim the logomark as your own work or use it as a representation of your own projects. - Sell the PaperMC logomark on its own or as part of other products without explicit permission. -- Alter the transparency of any of the elements in the PaperMC logomark. +- Alter the transparency of any elements within the PaperMC logomark. ![PaperMC logomark](papermc-logomark-512.png) diff --git a/docs/misc/downloads-api.mdx b/docs/misc/downloads-api.mdx index c6e3c2862..50e66afb3 100644 --- a/docs/misc/downloads-api.mdx +++ b/docs/misc/downloads-api.mdx @@ -20,7 +20,7 @@ We require `jq` to be installed for the examples below. You can install it with ::: -## Getting Latest Version +## Getting the latest version ```shell #!/bin/bash @@ -35,7 +35,7 @@ echo "Latest version is $LATEST_VERSION" This will get the latest available Minecraft version for the given project. -## Getting Latest Stable Build Number +## Getting the latest stable build number ``` @@ -53,7 +53,7 @@ echo "Latest build is $LATEST_BUILD" This will get the latest stable build for the given project and Minecraft version. -## Downloading Latest Stable Build +## Downloading the latest stable build ``` diff --git a/docs/misc/hangar-publishing.md b/docs/misc/hangar-publishing.md index dd032805e..784f4662c 100644 --- a/docs/misc/hangar-publishing.md +++ b/docs/misc/hangar-publishing.md @@ -4,7 +4,7 @@ description: How to automatically publish your plugin to Hangar on commits. --- If you want to automatically publish your plugin to [Hangar](https://hangar.papermc.io/) on commits, you can use -our [Hangar publish Gradle plugin](https://github.com/HangarMC/hangar-publish-plugin). +our [Gradle plugin](https://github.com/HangarMC/hangar-publish-plugin). After you have added the required `hangarPublish` configuration, you can manually publish it by running `./gradlew build publishPluginPublicationToHangar`, or have GitHub Actions automatically publish a version on @@ -28,14 +28,14 @@ are able to convert the example code. ::: -### Creating the Snapshot release channel +### Creating the `Snapshot` release channel The builds script below will publish non-release builds under a `Snapshot` channel. You need to create this channel in your Hangar project's channel page first. ![Create a Snapshot channel](https://i.imgur.com/p4UEIeJ.png) -### Adding the HANGAR_API_TOKEN repository secret +### Adding the `HANGAR_API_TOKEN` repository secret First, you need to create a Hangar API token. Go to your Hangar settings in the profile dropdown and click on "Api keys" on the left. Then, tick the `create_version` permission box, give the key a name and create it. **At the top**, you should be given your secret API @@ -47,13 +47,13 @@ secret `HANGAR_API_TOKEN` and paste the Hangar API token from the previous step ![Action secrets](https://i.imgur.com/l11Bnx5.png) -## Project Files +## Project files The files below are simple examples that require little manual changes for you to use, but you can still adapt them depending on your needs. Take a look at the comments and especially the TODOs to figure out what you still need to change. -### gradle.properties +### `gradle.properties` Create a `gradle.properties` file in your project root directory if it does not already exist. In there, you define the platform versions your plugin is compatible with. Simply remove the platforms you don't need and put in the correct @@ -70,7 +70,7 @@ velocityVersion=3.2 waterfallVersion=1.20 ``` -### build.gradle.kts +### `build.gradle.kts` In the plugins block of your `build.gradle.kts` build script, add the publish plugin: @@ -106,7 +106,7 @@ hangarPublish { register(Platforms.PAPER) { // TODO: If you're using ShadowJar, replace the jar lines with the appropriate task: // jar.set(tasks.shadowJar.flatMap { it.archiveFile }) - // Set the jar file to upload + // Set the JAR file to upload jar.set(tasks.jar.flatMap { it.archiveFile }) // Set platform versions from gradle.properties file diff --git a/docs/misc/tools/start-script-gen.mdx b/docs/misc/tools/start-script-gen.mdx index 3250fc672..d9e7e34f9 100644 --- a/docs/misc/tools/start-script-gen.mdx +++ b/docs/misc/tools/start-script-gen.mdx @@ -1,9 +1,9 @@ --- slug: /tools/start-script-gen -description: A Start Script Generator for PaperMC Projects +description: A start script generator for PaperMC projects. --- -import StartScriptGenerator from '@site/src/components/StartScriptGenerator'; +import StartScriptGenerator from "@site/src/components/StartScriptGenerator"; # Start Script Generator diff --git a/docs/paper/README.mdx b/docs/paper/README.mdx index c4fd38174..c3bf58a9f 100644 --- a/docs/paper/README.mdx +++ b/docs/paper/README.mdx @@ -2,7 +2,7 @@ import DocCardList from "@theme/DocCardList"; # Welcome to the Paper Docs -Paper is a high performance fork of the Spigot Minecraft Server that aims to fix gameplay and +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/paper/admin/README.mdx b/docs/paper/admin/README.mdx index c5d37505e..0538b45d1 100644 --- a/docs/paper/admin/README.mdx +++ b/docs/paper/admin/README.mdx @@ -5,9 +5,9 @@ slug: /admin import DocCardList from "@theme/DocCardList"; import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; -# Paper Server Administration +# Paper Administration Guide -Welcome to the Paper Server Administration Guide! This guide includes information and tutorials +Welcome to the Paper administration guide! This guide includes information and tutorials regarding the administration of a Paper server. --- diff --git a/docs/paper/admin/getting-started/adding-plugins.md b/docs/paper/admin/getting-started/adding-plugins.md index 631833b54..2bc4f0a87 100644 --- a/docs/paper/admin/getting-started/adding-plugins.md +++ b/docs/paper/admin/getting-started/adding-plugins.md @@ -18,7 +18,7 @@ it is imperative that plugins only be installed from trusted sources. Be careful ::: -## Finding Plugins +## 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/), @@ -35,7 +35,7 @@ mention Paper compatibility. It'll still work. ::: -## Installing Plugins +## 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 @@ -61,7 +61,7 @@ The first step to troubleshooting installing plugins is to check the log of 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 +#### Missing dependencies If you see something like this: @@ -72,7 +72,7 @@ If you see something like this: 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 +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'. @@ -80,7 +80,7 @@ error, the important line to look at is This is telling you that in order to load `MyAwesomePlugin`, you must first install `Vault`. -#### Invalid plugin.yml +#### Invalid `plugin.yml` If you see something closer to this: @@ -113,10 +113,10 @@ versions of EssentialsX are installed. Both the release `2.19.4`, and a developm `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)." +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 +#### 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 @@ -132,9 +132,9 @@ needed for the server to load a plugin are as follows: 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 + 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 +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/paper/admin/getting-started/getting-started.mdx b/docs/paper/admin/getting-started/getting-started.mdx index 2eda8b385..c2695c065 100644 --- a/docs/paper/admin/getting-started/getting-started.mdx +++ b/docs/paper/admin/getting-started/getting-started.mdx @@ -23,12 +23,12 @@ Paper requires at least **Java ** to run. We r ## Downloading Paper -Paper provides runnable server jars directly from our +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 +## Running the server To run the server you will need to either create a startup script or run a command in your terminal. @@ -37,11 +37,11 @@ You can generate a startup script using our [Startup Script Generator](/misc/too You can also obtain the optimized terminal command to run the server there. If you're just looking for a short command: -``` +```bash java -Xmx4G -Xms4G -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. +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. @@ -49,7 +49,7 @@ The amount of RAM can be set by changing the numbers in the `Xmx` and `Xms` argu 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 the server Updating Paper is simple! See our [Update Tutorial](../how-to/update.md) for more information. @@ -67,7 +67,7 @@ Paper will handle this conversion for you automatically. No additional considera Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes. -## Next Steps +## 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/paper/admin/getting-started/migration.md b/docs/paper/admin/getting-started/migration.md index 3635bc72c..be41c82bd 100644 --- a/docs/paper/admin/getting-started/migration.md +++ b/docs/paper/admin/getting-started/migration.md @@ -10,7 +10,7 @@ It's simple to migrate your server to or from Paper. The steps below will help y Before you begin, please ensure you have a full backup of your server. -[//]: # "See our [Backup Guide](/backup) for more information." +See our [Backup Guide](/paper/updating#step-1-backup) for more information. ::: @@ -23,7 +23,7 @@ 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. +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. @@ -31,7 +31,7 @@ Paper retains full compatibility with all Spigot plugins, allowing a seamless tr :::info Your new Paper server will still use [`bukkit.yml`](../reference/configuration/bukkit-configuration.mdx) -and [`spigot.yml`](../reference/configuration/spigot-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). @@ -48,7 +48,7 @@ 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. + 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. @@ -66,7 +66,7 @@ Additionally, note that Paper does not support Fabric or Forge mods. You will ne replacements. Any hybrids that attempt to support both mods and plugins are fundamentally flawed and not recommended for use. -## Migrating From Paper +## Migrating from Paper ### To Vanilla @@ -98,7 +98,7 @@ case for you, replace `world` with your `level-name` for all steps below. 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. +6. Replace your Paper JAR with a Vanilla server JAR. 7. Start your Vanilla server. ### To CraftBukkit or Spigot diff --git a/docs/paper/admin/how-to/aikars-flags.md b/docs/paper/admin/how-to/aikars-flags.md index 249329488..763573a5d 100644 --- a/docs/paper/admin/how-to/aikars-flags.md +++ b/docs/paper/admin/how-to/aikars-flags.md @@ -5,7 +5,7 @@ description: Aikar's flags are a set of JVM flags designed to improve the perfor # Aikar's Flags -## Recommended JVM Startup 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. @@ -14,13 +14,13 @@ For an automated script to generate these flags for you, see 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 +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 ``` @@ -32,13 +32,13 @@ Minecraft (and Java) needs additional memory on top of that `Xmx` parameter. It **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. +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 +## 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 @@ -48,10 +48,10 @@ However, more memory does not mean better performance above a certain point. Eve 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 +## 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: +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** @@ -69,7 +69,7 @@ to enable GC Logging: 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 +## 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 @@ -88,7 +88,7 @@ up much space (5MB) 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 +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 @@ -122,7 +122,7 @@ up much space (5MB) 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 + 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 @@ -174,9 +174,9 @@ up much space (5MB) 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 +### 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. +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. +`AlwaysPreTouch`, so this section is for the advanced users who want to experiment. diff --git a/docs/paper/admin/how-to/anti-xray.mdx b/docs/paper/admin/how-to/anti-xray.mdx index 22eae5770..ba3e34957 100644 --- a/docs/paper/admin/how-to/anti-xray.mdx +++ b/docs/paper/admin/how-to/anti-xray.mdx @@ -77,7 +77,7 @@ some players. ::: -## Recommended Configuration +## Recommended configuration The recommended configuration for `engine-mode: 1`, `engine-mode: 2` and `engine-mode: 3` is as follows: @@ -98,7 +98,6 @@ other important changes, it is recommended to make a backup before editing it. 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: @@ -134,7 +133,6 @@ anticheat: replacement-blocks: [] update-radius: 2 use-permission: false - ``` @@ -145,7 +143,6 @@ anticheat: Copy and paste into your `paper-world.yml` within your nether world folder. See the [Configuration Guide](./reference/configuration) for more information. -{/* prettier-ignore */} ```yml title="world_nether/paper-world.yml" anticheat: anti-xray: @@ -161,7 +158,6 @@ anticheat: replacement-blocks: [] update-radius: 2 use-permission: false - ``` @@ -172,12 +168,10 @@ anticheat: Copy and paste into your `paper-world.yml` within your end world folder. See the [Configuration Guide](./reference/configuration) for more information. -{/* prettier-ignore */} ```yml title="world_the_end/paper-world.yml" anticheat: anti-xray: enabled: false - ``` @@ -189,7 +183,6 @@ anticheat: 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: @@ -241,7 +234,6 @@ anticheat: - tuff update-radius: 2 use-permission: false - ``` @@ -252,7 +244,6 @@ anticheat: Copy and paste into your `paper-world.yml` within your nether world folder. See the [Configuration Guide](./reference/configuration) for more information. -{/* prettier-ignore */} ```yml title="world_nether/paper-world.yml" anticheat: anti-xray: @@ -291,12 +282,10 @@ anticheat: Copy and paste into your `paper-world.yml` within your end world folder. See the [Configuration Guide](./reference/configuration) for more information. -{/* prettier-ignore */} ```yml title="world_the_end/paper-world.yml" anticheat: anti-xray: enabled: false - ``` @@ -308,7 +297,6 @@ anticheat: 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: @@ -360,7 +348,6 @@ anticheat: - tuff update-radius: 2 use-permission: false - ``` @@ -371,7 +358,6 @@ anticheat: Copy and paste into your `paper-world.yml` within your nether world folder. See the [Configuration Guide](./reference/configuration) for more information. -{/* prettier-ignore */} ```yml title="world_nether/paper-world.yml" anticheat: anti-xray: @@ -399,7 +385,6 @@ anticheat: - soul_soil update-radius: 2 use-permission: false - ``` @@ -410,17 +395,15 @@ anticheat: Copy and paste into your `paper-world.yml` within your end world folder. See the [Configuration Guide](./reference/configuration) for more information. -{/* prettier-ignore */} ```yml title="world_the_end/paper-world.yml" anticheat: anti-xray: enabled: false - ``` -## FAQ, Common Pitfalls and Support +## FAQ, common pitfalls and support
I can still see (some) ores / use X-ray diff --git a/docs/paper/admin/how-to/basic-troubleshooting.md b/docs/paper/admin/how-to/basic-troubleshooting.md index 08df8c8f7..cf660efb2 100644 --- a/docs/paper/admin/how-to/basic-troubleshooting.md +++ b/docs/paper/admin/how-to/basic-troubleshooting.md @@ -9,30 +9,30 @@ This guide will help you diagnose your server's problem before reporting it to P :::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. +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. +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 +## 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 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 +### 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]: ------------------------------ @@ -42,69 +42,69 @@ This can be caused by various things. Maybe your server's hardware is not capabl 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 +### 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. +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 trace. +Here are some examples of stack traces.
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. +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 +## Find 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 +### Disable all plugins -To determine if it is a plugin or the paper itself that is causing problems, disable all of your plugins first. +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 paper server is misconfigured, and that is creating issues. +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 +### 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** +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** +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. +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** +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 +## 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 +### Update library plugins Many plugins use library plugins like ProtocolLib, and you have to download them and put them in `plugins` directory. @@ -112,24 +112,24 @@ If you don't update them to the latest version or latest build, you might experi 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 +## Check documentation If you misconfigured your plugin or your server, it can also cause problems on your server. -### Plugin Documentation +### 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 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 Developer +## 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 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/paper/admin/how-to/update.md b/docs/paper/admin/how-to/update.md index 21298b9f4..a6a77157b 100644 --- a/docs/paper/admin/how-to/update.md +++ b/docs/paper/admin/how-to/update.md @@ -20,7 +20,7 @@ replace any JAR in a running server, be that plugins, or Paper itself. :::tip -If you are using a shared host, your host may provide a built-in way to backup. Consult their +If you are using a shared host, your host may provide a built-in way to back up. Consult their documentation before continuing. ::: @@ -37,7 +37,7 @@ functioning backups is essential to every server, big or small. The main things 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 +## 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. @@ -77,7 +77,7 @@ 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 +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. diff --git a/docs/paper/admin/misc/paper-bug-fixes.md b/docs/paper/admin/misc/paper-bug-fixes.md index 42b10799e..38b28b827 100644 --- a/docs/paper/admin/misc/paper-bug-fixes.md +++ b/docs/paper/admin/misc/paper-bug-fixes.md @@ -7,11 +7,11 @@ description: An explanation of which Vanilla bugs we fix in Paper. Paper fixes many gameplay and technical issues within Minecraft. The most prevalent fixes are to TNT duplication and bedrock breaking. -## Vanilla Bug Fixes +## 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 +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) +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? @@ -23,9 +23,9 @@ check to see if it: 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 behaviour. +them (sometimes years). If an issue gets declined by Mojang, we normally do not "fix" it as it is intended behavior. -## Duplication Bugs +## 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, @@ -49,9 +49,9 @@ 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 behaviour. +fixed it in Paper, but we provide a config option to restore Vanilla behavior. -## Block Breaking +## 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: diff --git a/docs/paper/admin/reference/configuration/README.mdx b/docs/paper/admin/reference/configuration/README.mdx index dfc0817a9..8e363aa5e 100644 --- a/docs/paper/admin/reference/configuration/README.mdx +++ b/docs/paper/admin/reference/configuration/README.mdx @@ -4,11 +4,11 @@ slug: /reference/configuration # Paper Configuration -import ConfigurationStructureDiagram from '@site/src/components/config/ConfigurationStructureDiagram'; +import ConfigurationStructureDiagram from "@site/src/components/config/ConfigurationStructureDiagram"; --- -## Paper Configuration Files +## Paper configuration files :::info @@ -19,20 +19,20 @@ If this is not the case, they offer a brief explanation to what they are. -## Per World Configuration +## 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 +### 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 +### 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 @@ -99,7 +99,7 @@ This example demonstrates the concept of inheritance. For each world, this is th 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` | diff --git a/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx b/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx index 3d0a20b43..450dc73c7 100644 --- a/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx +++ b/docs/paper/admin/reference/configuration/bukkit-commands-configuration.mdx @@ -18,7 +18,7 @@ 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 +The aliases defined in this legacy file do not support modern features, such as: - Tab completion - Permissions diff --git a/docs/paper/admin/reference/configuration/bukkit-configuration.mdx b/docs/paper/admin/reference/configuration/bukkit-configuration.mdx index 4f5710e48..1116f171c 100644 --- a/docs/paper/admin/reference/configuration/bukkit-configuration.mdx +++ b/docs/paper/admin/reference/configuration/bukkit-configuration.mdx @@ -11,7 +11,7 @@ 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` +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/paper/admin/reference/configuration/spigot-configuration.mdx b/docs/paper/admin/reference/configuration/spigot-configuration.mdx index ca6123915..54c59c621 100644 --- a/docs/paper/admin/reference/configuration/spigot-configuration.mdx +++ b/docs/paper/admin/reference/configuration/spigot-configuration.mdx @@ -19,7 +19,7 @@ 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) +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/paper/admin/reference/configuration/world-configuration.mdx b/docs/paper/admin/reference/configuration/world-configuration.mdx index 5cda8b322..750fe4096 100644 --- a/docs/paper/admin/reference/configuration/world-configuration.mdx +++ b/docs/paper/admin/reference/configuration/world-configuration.mdx @@ -11,7 +11,7 @@ import WorldConfigSpec from '!!raw-loader!@site/config-specs/paper/paper-world-d :::info -The below YAML shows you the structure and default values for the world configuration. (`config/paper-world-defaults.yml` and `/paper-world.yml`) +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/paper/admin/reference/paper-plugins.md b/docs/paper/admin/reference/paper-plugins.md index cfb96a342..52d527c09 100644 --- a/docs/paper/admin/reference/paper-plugins.md +++ b/docs/paper/admin/reference/paper-plugins.md @@ -31,16 +31,16 @@ Paper plugins only support being loaded by Paper's Plugin Loader and may use new 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 +### 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. +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** startup flag. +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/paper/admin/reference/system-properties.md b/docs/paper/admin/reference/system-properties.md index 421a9bfe7..f5afc6119 100644 --- a/docs/paper/admin/reference/system-properties.md +++ b/docs/paper/admin/reference/system-properties.md @@ -24,7 +24,7 @@ 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. +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"` ::: @@ -37,7 +37,7 @@ Where a system property is stated as `unset`, setting it as `true` will work to ::: -## List of System Properties +## List of system properties #### paper.playerconnection.keepalive: @@ -122,7 +122,7 @@ Where a system property is stated as `unset`, setting it as `true` will work to #### debug.rewriteForIde: - **default**: `unset` -- **description**: Removes the NMS revision from the stack trace to allow for easier debugging in IDEs. +- **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: @@ -164,7 +164,7 @@ It also remaps plugin CB calls to remove the version information. #### io.papermc.paper.suppress.sout.nags: - **default**: `unset` -- **description**: Suppresses the nag message about using System.out/System.err in a plugin. +- **description**: Suppresses the nag message about using `System.out`/`System.err` in a plugin. #### paper.strict-thread-checks: @@ -174,7 +174,7 @@ It also remaps plugin CB calls to remove the version information. #### Paper.skipServerPropertiesComments: - **default**: `unset` -- **description**: Skips the comments in the server.properties file. +- **description**: Skips the comments in the `server.properties` file. #### Paper.debugInvalidSkullProfiles: @@ -200,3 +200,8 @@ It also remaps plugin CB calls to remove the version information. - **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. diff --git a/docs/paper/contributing/README.mdx b/docs/paper/contributing/README.mdx index e9c3357a0..300bb16b7 100644 --- a/docs/paper/contributing/README.mdx +++ b/docs/paper/contributing/README.mdx @@ -3,7 +3,7 @@ import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; # Contributing Guide -Welcome to the Paper Contributing Guide! This guide includes information and tutorials for developers +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/paper/contributing/events.mdx b/docs/paper/contributing/events.mdx index 632fd72d1..28e2109cd 100644 --- a/docs/paper/contributing/events.mdx +++ b/docs/paper/contributing/events.mdx @@ -17,21 +17,21 @@ 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` to signify that they are not considered +All new constructors added should be annotated with `@ApiStatus.Internal` 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`. +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 +### `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 +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 diff --git a/docs/paper/dev/README.mdx b/docs/paper/dev/README.mdx index fdafd5fef..47307b5b1 100644 --- a/docs/paper/dev/README.mdx +++ b/docs/paper/dev/README.mdx @@ -3,7 +3,7 @@ import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; # Development Guide -Welcome to the Paper Development Guide! This guide includes information and tutorials for developers +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/paper/dev/api/README.mdx b/docs/paper/dev/api/README.mdx index 44a142c3b..b5048c957 100644 --- a/docs/paper/dev/api/README.mdx +++ b/docs/paper/dev/api/README.mdx @@ -3,8 +3,8 @@ 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 +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/paper/dev/api/component-api/audiences.md b/docs/paper/dev/api/component-api/audiences.md index 753b8af3f..37598683c 100644 --- a/docs/paper/dev/api/component-api/audiences.md +++ b/docs/paper/dev/api/component-api/audiences.md @@ -4,18 +4,18 @@ 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 +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? +## Who is an `Audience`? -All `CommandSender`'s are single audiences. This includes players, the console, and command blocks. `Server`, `Team` and +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 methods are available on `CommandSender`'s, `Server`, `Team`, and `World`. +This means that all the Audience methods are available on `CommandSender`, `Server`, `Team` and `World`. -## ForwardingAudience +## `ForwardingAudience` The `ForwardingAudience` wraps a collection of `Audience` instances and forwards messages to all of them. This is useful for sending messages to multiple audiences (players) at once. @@ -30,9 +30,9 @@ Audience audience = Audience.audience(Audience...); // wrapped in a ForwardingAudience. ``` -## What do Audiences do? +## What do `Audience`s do? -Audiences are used for interacting with players. They can be used to send messages, play sounds, show boss bars, and more. +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` to a player using `Audience#sendMessage(Component)`. diff --git a/docs/paper/dev/api/component-api/i18n.md b/docs/paper/dev/api/component-api/i18n.md index ba342fddb..8b635e112 100644 --- a/docs/paper/dev/api/component-api/i18n.md +++ b/docs/paper/dev/api/component-api/i18n.md @@ -10,7 +10,7 @@ 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). +Adventure's Javadocs for all-things translations can be found [here](https://jd.advntr.dev/api/latest/net/kyori/adventure/translation/package-summary.html). ::: @@ -62,4 +62,3 @@ final Component message = Component.translatable("some.translation.key", Compone ``` This will show to clients using the US English language: `Translated Message: The Argument`. - diff --git a/docs/paper/dev/api/component-api/intro.md b/docs/paper/dev/api/component-api/intro.md index 7dfaed9a9..a5003c4cd 100644 --- a/docs/paper/dev/api/component-api/intro.md +++ b/docs/paper/dev/api/component-api/intro.md @@ -6,7 +6,7 @@ title: Introduction :::note -This documentation page applies to both the Paper and Velocity projects +This documentation page applies to both the Paper and Velocity projects. ::: @@ -30,9 +30,9 @@ 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, boss bars, team prefixes and -suffixes, custom names, and much more all support Components in respective APIs. +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. @@ -40,7 +40,7 @@ that client support for the legacy format with `§` will be removed in the futur :::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. +signal that a better alternative in components is available and should be migrated to going forward. ::: @@ -51,7 +51,7 @@ builders for all the types. These objects are immutable so when constructing mor recommended to use builders to avoid creating new Component instances with every change. ```java -// This is a sub-optimimal construction of the +// 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)) @@ -59,7 +59,7 @@ final Component component = Component.text("Hello") /* 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 + Components are designed for use with static method imports to make code less verbose */ final Component component = text() .content("Hello").color(color(0x13f832)) @@ -98,14 +98,14 @@ MiniMessage is a part of Adventure, and you can find its documentation on [Adven :::tip -MiniMessage has a [WebViewer](https://webui.advntr.dev/) which is useful for constructing more complicated components and seeing the results in real time +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 +in Vanilla in various commands which accept component arguments like `/tellraw`. Below is a simple example of this format. ```json @@ -130,7 +130,7 @@ of this format. :::info[In-Depth Documentation] -The JSON format is fully documented on the [Minecraft Wiki](https://minecraft.wiki/w/Raw_JSON_text_format). +The JSON format is fully documented on the [Minecraft Wiki](https://minecraft.wiki/w/Raw_JSON_text_format). ::: @@ -142,12 +142,12 @@ There are online tools to make generating this format much easier like [JSON Tex ## Serializers -Paper and Velocity come bundled with different serializers for converting between Components and other forms +Paper and Velocity come bundled with different serializers for converting between `Component`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 `JsonElement`. +Converts between `Component` and JSON-formatted strings with convenience methods to directly deal with Gson's `JsonElement`. This conversion is lossless and is the preferred form of serialization for components that do not have to be edited by users regularly. @@ -155,14 +155,13 @@ for components that do not have to be edited by users regularly. 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). +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`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. - +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) @@ -179,7 +178,7 @@ A more useful use case is converting legacy text to MiniMessage format in a migr ```java final String legacyString = ChatColor.RED + "This is a legacy " + ChatColor.GOLD + "string"; -// this just runs the legacy string through two serializers to +// runs the legacy string through two serializers to convert legacy -> MiniMessage final String miniMessageString = MiniMessage.miniMessage().serialize( LegacyComponentSerializer.legacySection().deserialize(legacyString) ); @@ -187,6 +186,8 @@ final String miniMessageString = MiniMessage.miniMessage().serialize( :::note -There are 2 built in legacy serializers, one dealing with `§` symbols and the other for -`&` symbols. They have their own instances available with `LegacyComponentSerializer#legacySection()` -and `LegacyComponentSerializer#legacyAmpersand()` +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()` +and `LegacyComponentSerializer#legacyAmpersand()`. + +::: diff --git a/docs/paper/dev/api/custom-inventory-holder.md b/docs/paper/dev/api/custom-inventory-holder.md index 7a575628b..cdbf0ca7b 100644 --- a/docs/paper/dev/api/custom-inventory-holder.md +++ b/docs/paper/dev/api/custom-inventory-holder.md @@ -3,32 +3,28 @@ slug: /dev/custom-inventory-holder description: How to use a custom InventoryHolder to identify custom inventories. --- -# Custom InventoryHolder +# Custom `InventoryHolder` -Custom InventoryHolders can be used to identify your plugin's inventories in events. +`InventoryHolder`s are a way to identify your plugin's inventories in events. -## Why use an InventoryHolder? +## Why use an `InventoryHolder`? -Custom InventoryHolders simplify the steps you need to do to make sure an inventory was created by your plugin. +`InventoryHolder`s 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. +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 InventoryHolders have no such downsides and by using them you're guaranteed to have methods available to handle your inventory. - -::: +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 InventoryHolder +## Creating a custom holder -InventoryHolder is an interface that we must implement. +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. +If you wish, you can use the static method `Bukkit#createInventory(InventoryHolder, int)` instead and remove the argument. ::: @@ -90,12 +86,12 @@ public void onInventoryClick(InventoryClickEvent event) { } ``` -## Storing data on the custom InventoryHolder +## Storing data on the holder -You can store extra data for your inventories on the custom InventoryHolder by adding fields and methods to your class. +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: +First, let's modify our `MyInventory` class a little: ```java public class MyInventory implements InventoryHolder { diff --git a/docs/paper/dev/api/event-api/chat-event.mdx b/docs/paper/dev/api/event-api/chat-event.mdx index 9abb3dae4..0ee5d680e 100644 --- a/docs/paper/dev/api/event-api/chat-event.mdx +++ b/docs/paper/dev/api/event-api/chat-event.mdx @@ -5,19 +5,23 @@ description: An outline on the 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. +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 +:::note[`AsyncChatEvent` vs `ChatEvent`] -#### AsyncChatEvent vs ChatEvent +The key difference between `AsyncChatEvent` +and `ChatEvent` is that +`AsyncChatEvent` is fired asynchronously. -The key difference between the `AsyncChatEvent` and the `ChatEvent` is that the `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 the event might cause errors. -If you need to use the Bukkit API, you can use the `ChatEvent`. -However, we recommend using the [`BukkitScheduler`](../scheduler.md). +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.md). ::: @@ -25,7 +29,10 @@ However, we recommend using the [`BukkitScheduler`](../scheduler.md). 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. +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) { @@ -33,15 +40,17 @@ public @NotNull Component render(@NotNull Player source, @NotNull Component sour } ``` -- The `render` method is called when a chat message is sent to the player. +- 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] +:::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. +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. ::: @@ -52,13 +61,15 @@ 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. +Depending on the complexity of your renderer, you may want to use one or the other. + +### Implementing the `ChatRenderer` interface -### 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. -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. +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 @@ -80,7 +91,7 @@ public class ChatListener implements Listener, ChatRenderer { // Implement the C :::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 to create a single instance of the class. +In this case, you can use [the singleton pattern](https://en.wikipedia.org/wiki/Singleton_pattern) to create a single instance of the class. ::: @@ -129,5 +140,5 @@ 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). +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/paper/dev/api/event-api/custom-events.md b/docs/paper/dev/api/event-api/custom-events.md index c398bf9e3..bcab15fdf 100644 --- a/docs/paper/dev/api/event-api/custom-events.md +++ b/docs/paper/dev/api/event-api/custom-events.md @@ -10,7 +10,9 @@ This will allow other plugins to listen to your custom events and add functional ## 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. +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. @@ -133,8 +135,7 @@ public class ExamplePlugin extends JavaPlugin { ``` 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. - +in your `if` statement, instead of having to check `Cancellable#isCancelled` manually. ```java title="ExamplePlugin.java" public class ExamplePlugin extends JavaPlugin { diff --git a/docs/paper/dev/api/event-api/event-listeners.mdx b/docs/paper/dev/api/event-api/event-listeners.mdx index e2f8139a6..2d85bc7af 100644 --- a/docs/paper/dev/api/event-api/event-listeners.mdx +++ b/docs/paper/dev/api/event-api/event-listeners.mdx @@ -43,7 +43,7 @@ public class ExampleListener implements Listener { :::note[Events] There is no list of events that can be listened to, however take a -look { here } +look here to see all classes that extend `Event`. An event can only be listened to if it has a static `getHandlerList` method. @@ -90,7 +90,7 @@ There are six different priorities that you can use: - `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 +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 diff --git a/docs/paper/dev/api/folia-support.md b/docs/paper/dev/api/folia-support.md index dc8904316..2e86ddf8d 100644 --- a/docs/paper/dev/api/folia-support.md +++ b/docs/paper/dev/api/folia-support.md @@ -10,7 +10,7 @@ description: How to support both Folia and Paper within your plugin. [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: +# 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: @@ -31,22 +31,22 @@ private static boolean isFolia() { 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 Scheduler](#global-scheduler) -- [Region Scheduler](#region-scheduler) -- [Async Scheduler](#async-scheduler) -- [Entity Scheduler](#entity-scheduler) +- [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 +### 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 +### 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: @@ -61,13 +61,13 @@ scheduler.execute(plugin, locationToChange, () -> { 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: +### 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 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 diff --git a/docs/paper/dev/api/pdc.md b/docs/paper/dev/api/pdc.mdx similarity index 78% rename from docs/paper/dev/api/pdc.md rename to docs/paper/dev/api/pdc.mdx index feb12fbf4..57468a5d4 100644 --- a/docs/paper/dev/api/pdc.md +++ b/docs/paper/dev/api/pdc.mdx @@ -6,14 +6,14 @@ 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: +The full list of classes that support the PDC are: -- [Chunk](#chunk) -- [World](#world) -- [Entity](#entity) -- [TileState](#tilestate) -- [ItemMeta](#itemmeta) -- [Structure](#structure) +- [`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: @@ -25,16 +25,16 @@ The benefit of the PDC is that it allows for a more reliable and performant way 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. +## 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 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); @@ -42,16 +42,16 @@ item.setItemMeta(meta); :::info -It is considered good practice to reuse the `NamespacedKey` objects. They can be constructed with either: +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 / access the data from another plugin. +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 +## Getting data To get data from the PDC, you need to know the `NamespacedKey` and the `PersistentDataType` of the data. ```java @@ -68,7 +68,7 @@ if (container.has(key, PersistentDataType.STRING)) { } ``` -## Data Types +## Data types The PDC supports a wide range of data types, such as: - `Byte`, `Byte Array` @@ -78,15 +78,15 @@ The PDC supports a wide range of data types, such as: - `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: +- `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(); ``` -- `Boolean` -- `Lists`. Represent lists of data that can be stored via another persistent data type. You may create them via: +- `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. @@ -104,15 +104,15 @@ The PDC supports a wide range of data types, such as: List strings = container.get(key, PersistentDataType.LIST.strings()); ``` -:::info[Boolean PersistentDataType] +:::info[Boolean `PersistentDataType`] -The Boolean PDC type exists for convenience - you cannot make more complex types distill to a Boolean +The `Boolean` PDC type exists for convenience - you cannot make more complex types distill to a `Boolean`. ::: -### Custom Data Types +### 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 +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. @@ -150,7 +150,7 @@ public class UUIDDataType implements PersistentDataType { :::note -In order to use your own `PersistentDataType`, you must pass an instance of it to the set/get/has methods. +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); ``` @@ -159,15 +159,15 @@ container.set(key, new UUIDDataType(), uuid); ## Storing on different objects -- ##### Chunk +- ##### `Chunk` - `Chunk#getPersistentDataContainer()` -- ##### World +- ##### `World` - `World#getPersistentDataContainer()` -- ##### Entity +- ##### `Entity` - `Entity#getPersistentDataContainer()` -- ##### TileState +- ##### `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: + This does not work for all blocks, only those that have a tile entity. ```java Block block = ...; if (block.getState() instanceof Chest chest) { @@ -175,7 +175,7 @@ container.set(key, new UUIDDataType(), uuid); chest.update(); } ``` -- ##### Structure +- ##### `Structure` - `Structure#getPersistentDataContainer()` -- ##### ItemMeta +- ##### `ItemMeta` - `ItemMeta#getPersistentDataContainer()` diff --git a/docs/paper/dev/api/plugin-configs.md b/docs/paper/dev/api/plugin-configs.md index b3b0783f8..59659813a 100644 --- a/docs/paper/dev/api/plugin-configs.md +++ b/docs/paper/dev/api/plugin-configs.md @@ -1,18 +1,18 @@ --- slug: /dev/plugin-configurations -description: How to create configuration files for your plugins to customize behaviour. +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. +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 will not be covered in this guide. +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). +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 @@ -21,11 +21,11 @@ root: another-key: David ``` -When accessing indented values, you separate the levels with `.`'s. For example, the key for the "David" string would be `root.another-key` +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 +## Creating a `config.yml` -By placing a `config.yml` file inside your plugin, you can specify the default values for certain settings. +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 @@ -37,12 +37,12 @@ example-plugin └── plugin.yml ``` -Then, when your plugin is initialised you must save this resource into the plugins data directory so that a user can edit the values. +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); @@ -53,13 +53,13 @@ public class TestPlugin extends JavaPlugin { // getConfig()... } - + } ``` :::info -The boolean `replace` parameter specifies whether it should replace an existing file if one exists. +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. ::: @@ -68,14 +68,14 @@ If set to true, the configuration will be overwritten on every call. 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` or `#getBoolean`. +by YAML. These can be fetched simply with `#getString` or `#getBoolean`. -However, some more complex Bukkit data types are also supported. A few of these include `ItemStack`, `Location` and `Vector`s. +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` for the changes to persist on disk +Whenever setting data in configurations, you must call `FileConfiguration#save` for the changes to be persisted to disk. ::: @@ -95,46 +95,46 @@ 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"), + (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 then returns an instance of the `TeleportOptions` Class. Finally, for this to work we must call: +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` with Paper Plugins, -you will not be able to load / save your custom classes. +If you do not call `ConfigurationSerialization.registerClass` with Paper plugins, +you will not be able to load nor save your custom classes. ::: -## Custom Configuration Files +## 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 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 @@ -144,16 +144,16 @@ YamlConfiguration config = YamlConfiguration.loadConfiguration(file); config.save(file); ``` -This example reads the `items.yml` file from your plugin data directory. This file must exist and an error will be thrown if it doesn't. +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 our configurations and offers many features that plain YAML files do not. See their project +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/paper/dev/api/plugin-messaging.md b/docs/paper/dev/api/plugin-messaging.md index 6808b3553..23bb6a8ed 100644 --- a/docs/paper/dev/api/plugin-messaging.md +++ b/docs/paper/dev/api/plugin-messaging.md @@ -1,27 +1,27 @@ --- slug: /dev/plugin-messaging -description: Plugin messaging allows communication with clients. If running a proxy, you can also communicate with the proxy. +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 Paper plugins to communicate with clients. When your servers are behind a proxy, -it will allow your Paper plugins to communicate with the proxy server. +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 +## BungeeCord channel -The BungeeCord channel is used for communication between your Paper server and a BungeeCord (Or protocol supporting) proxy. +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 Paper plugins should continue to use the `BungeeCord` channel. +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 +## Sending plugin messages -First, we're going to take a look at your Paper server. Your Paper plugin will need to register that it +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 @@ -38,7 +38,7 @@ public final class PluginMessagingSample extends JavaPlugin { 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. +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 @@ -59,14 +59,14 @@ public final class PluginMessagingSample extends JavaPlugin implements Listener 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://wiki.vg/Plugin_channels#Plugin_Messages). They piggyback on player connections, so if there is no +These channels rely on the Minecraft protocol, and are sent as a special type of packet called a +[Plugin Message](https://wiki.vg/Plugin_channels#Plugin_Messages). 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. ::: @@ -75,16 +75,16 @@ player connected to the server, it will not be able to send or receive plugin me 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 format sent our player to the `hub2` server. +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 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. -### BungeeCord Plugin Message Types +### Plugin message types -Although we sent a `Connect` message to the proxy, there are a few other cases that proxies will act on. +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 | @@ -105,16 +105,16 @@ These are the following: | `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` | -#### Example: `PlayerCount` +#### `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"); @@ -139,16 +139,16 @@ public class MyPlugin extends JavaPlugin implements PluginMessageListener { } ``` -#### Example: `Forward` +#### `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"); @@ -162,7 +162,7 @@ public class MyPlugin extends JavaPlugin implements PluginMessageListener { 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 } @@ -192,24 +192,24 @@ For example, if a certain player is banned on one server, you can forward a mess :::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, +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 +#### `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 +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"); @@ -222,4 +222,4 @@ public class MyPlugin extends JavaPlugin { } ``` -This will send the player a message saying "Click Me!" Where it is clickable and will open the URL https://papermc.io +This will send the player a clickable message saying "Click Me!" that opens `https://papermc.io` upon clicking. diff --git a/docs/paper/dev/api/roadmap.md b/docs/paper/dev/api/roadmap.md index f039043f9..9269a6b4a 100644 --- a/docs/paper/dev/api/roadmap.md +++ b/docs/paper/dev/api/roadmap.md @@ -5,48 +5,47 @@ description: Outlines the future intents and plans of the Paper project. # Roadmap -Paper offers a rich API that has a wide range of features that can help you unlock the full potential of your server. +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 +## Future plans +### Interface `ItemStack`s -### Interface ItemStacks +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. -When you create ItemStacks, you create an API representation of an ItemStack. -However, there are also places where you can obtain an ItemStack that is backed by an NMS object instead. -This can lead to inconsistencies and unnecessary upkeep since we need to maintain our own implementation of ItemStack and -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. +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 +- Avoid directly extending the `ItemStack` class. + - Custom implementations of this class are not supported. -### ServerPlayer Reusing +### `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 +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 being done to help reduce possible inconsistencies between world switching between Vanilla and Paper. +This is done to help reduce possible inconsistencies between world switching between Vanilla and Paper. ## Experimental API -### Teleport Flags +### 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. This API is currently finalized and will be marked as stable in a future release. -#### Player Teleportation -Teleport a player relatively, preventing velocity from being reset in the X, Y, and Z axis. +#### Player teleportation +Teleport a player relatively, preventing velocity from being reset in the X, Y and Z axes. ```java player.teleport(location, TeleportFlag.Relative.X, @@ -55,13 +54,13 @@ player.teleport(location, ); ``` -#### Vehicle Teleportation +#### Vehicle teleportation 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); ``` -## Deprecation Policy +## Deprecation policy :::warning @@ -74,19 +73,17 @@ You may also experience performance issues and other problems. To ensure the bes 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. +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(); +public void exampleMethod(); // Example deprecated method ``` -*Example deprecated method* -### Deprecated for Removal +### Deprecated for removal -In addition to being marked as ``@Deprecated``, api may be marked as `forRemoval` with a given ``@ScheduledForRemoval`` version. +In addition to being marked as `@Deprecated`, API may be marked as `forRemoval` with a given `@ScheduledForRemoval` 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. @@ -95,12 +92,10 @@ away from said API. ```java @ApiStatus.ScheduledForRemoval(inVersion = "1.20") @Deprecated(forRemoval = true) -public void exampleMethod(); +public void exampleMethod(); // Example method marked for removal in 1.20 ``` -*Example method marked for removal in 1.20* - -## Deprecation Reasons +## Deprecation reasons There are many possible reasons why an API might be deprecated. Some of the common reasons why API can be deprecated is: @@ -109,8 +104,8 @@ Some of the common reasons why API can be deprecated is: As the game evolves, the API may represent concepts that no longer exist in the core game. -Old API is no most likely not functional in newer versions of the game, which will behave unexpectedly on newer versions, -therefore may be scheduled for removal. +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 @@ -118,12 +113,12 @@ As Paper continues to upstream Spigot, it can occasionally include APIs that cla 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 +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 +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/paper/dev/api/scheduler.md b/docs/paper/dev/api/scheduler.md index e1ff5c7d8..4640d9e27 100644 --- a/docs/paper/dev/api/scheduler.md +++ b/docs/paper/dev/api/scheduler.md @@ -9,16 +9,16 @@ The `BukkitScheduler` can be used to schedule your code to be run later or repea :::info[Folia] -This guide is designed for Non-Folia Bukkit Servers. If you are using Folia, you should use its respective schedulers. +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. +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 one tick every 50 milliseconds. This means that the game loop is executed +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. @@ -45,7 +45,7 @@ You can also use the `Tick` class from Paper to convert between human units and ## Obtaining the scheduler -To obtain a scheduler you can use the `getScheduler` method on the `Server` class, e.g. in your `onEnable` method: +To obtain a scheduler, you can use the `getScheduler` method on the `Server` class, e.g. in your `onEnable` method: ```java @Override @@ -61,7 +61,7 @@ Scheduling a task requires you to pass: - Your plugin's instance - The code to run, either with a `Runnable` or `Consumer` - The delay in ticks before the task should run for the first time -- If you're scheduling a repeating task - the period in ticks between each execution of the task +- The period in ticks between each execution of the task, if you're scheduling a repeating task ### Difference between synchronous and asynchronous tasks @@ -71,7 +71,7 @@ Synchronous tasks are tasks that are executed on the main server thread. This is 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 +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) @@ -91,7 +91,7 @@ accesses the world state, it is not safe to be used from an asynchronous task. 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 +If you need a scheduler that runs independently of the server, consider using your own [`ScheduledExecutorService`](https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ScheduledExecutorService.html). You can follow [this guide](https://www.baeldung.com/java-executor-service-tutorial#ScheduledExecutorService) to learn how to use it. @@ -125,7 +125,7 @@ public class MyRunnableTask implements Runnable { scheduler.runTaskLater(plugin, new MyRunnableTask(plugin), 20); ``` -Or use a lambda expression which is great for simple and short tasks: +Or use a lambda expression, which is great for simple and short tasks: ```java scheduler.runTaskLater( @@ -167,7 +167,7 @@ public class MyConsumerTask implements Consumer { scheduler.runTaskTimer(plugin, new MyConsumerTask(someEntityId), 0, 20); ``` -Or use a lambda expression which again is much cleaner for short and simple tasks: +Or use a lambda expression, which again is much cleaner for short and simple tasks: ```java scheduler.runTaskTimer(plugin, /* Lambda: */ task -> { @@ -184,7 +184,7 @@ scheduler.runTaskTimer(plugin, /* Lambda: */ task -> { ##### Using BukkitRunnable -The `BukkitRunnable` class is a class that implements `Runnable` and holds a `BukkitTask` instance. This means that you do +`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 @@ -215,4 +215,4 @@ 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 -whilst the server is starting / before it is enabled it will be executed before the server is enabled. +while the server is starting, or before it is enabled, it will be executed before the server is enabled. diff --git a/docs/paper/dev/getting-started/README.mdx b/docs/paper/dev/getting-started/README.mdx index 7e0a195c8..1f89bab23 100644 --- a/docs/paper/dev/getting-started/README.mdx +++ b/docs/paper/dev/getting-started/README.mdx @@ -3,7 +3,7 @@ import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; # Development Guide -Welcome to the Paper Development Guide! This guide includes information and tutorials on +Welcome to the Paper development guide! This guide includes information and tutorials on how to start developing plugins for Paper. --- diff --git a/docs/paper/dev/getting-started/how-do-plugins-work.md b/docs/paper/dev/getting-started/how-do-plugins-work.md index 5dab8c676..c4a7ab3a1 100644 --- a/docs/paper/dev/getting-started/how-do-plugins-work.md +++ b/docs/paper/dev/getting-started/how-do-plugins-work.md @@ -21,7 +21,7 @@ do not call your plugin's constructor directly. This will cause issues with your ::: -## Plugin Lifecycle +## 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. @@ -48,7 +48,7 @@ When a plugin is disabled, its `onDisable` method is called. This method is used 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 +## 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, the `PlayerJoinEvent` is fired when a player joins the server. This is a more performant way to run code when @@ -102,7 +102,7 @@ plugin that adds a new block to the game might have a configuration file that st 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 +## 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 diff --git a/docs/paper/dev/getting-started/paper-plugins.mdx b/docs/paper/dev/getting-started/paper-plugins.mdx index 78dc375b9..f89c83834 100644 --- a/docs/paper/dev/getting-started/paper-plugins.mdx +++ b/docs/paper/dev/getting-started/paper-plugins.mdx @@ -19,12 +19,12 @@ This is experimental and may be subject to change. - [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. +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 you still have the ability to include both `paper-plugin.yml` and `plugin.yml` in the same jar. +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. +Here is an example configuration: ``` name: Paper-Test-Plugin @@ -37,16 +37,16 @@ loader: io.papermc.testplugin.TestPluginLoader ``` -### Dependency Declaration +### Dependency declaration -Paper Plugins change how to declare dependencies in your `paper-plugin.yml`: +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 + # 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 @@ -60,7 +60,7 @@ dependencies: join-classpath: false ``` -With Paper Plugins, dependencies are split into two sections: +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. @@ -72,7 +72,7 @@ RegistryPlugin: join-classpath: true # Defaults to true ``` -- `load`: (`BEFORE`|`AFTER`|`OMIT`) Specifies whether this plugin should load before or after **your** plugin. Note: Omit has undefined ordering behavior. +- `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. @@ -104,9 +104,9 @@ SuperDuperTacoParty: ``` ## 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). +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 @@ -126,8 +126,8 @@ public class TestPluginBootstrap implements PluginBootstrap { } ``` -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. +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 `io.papermc.paper.plugin.loader.PluginLoader` and adding @@ -150,42 +150,43 @@ public class TestPluginLoader implements PluginLoader { } } ``` -Currently, you are able to add two different library types, `JarLibrary`, and `MavenLibraryResolver`. +Currently, you are able to add two different library types: `JarLibrary` and `MavenLibraryResolver`. ## Differences -### Bukkit Serialization System +### 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`, +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 +### 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 +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 +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 ``` -to your ``paper-plugin.yml``. Note, other Paper plugins will still be unable to access your classloader. +Note, other Paper plugins will still be unable to access your classloader. -### Load Order Logic Split +### 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 +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 command map. -### Cyclic Plugin Loading +### Cyclic plugin loading -Cyclic loading describes the phenomena when a plugin loading causes a loop which eventually will cycle back to the original plugin. +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 diff --git a/docs/paper/dev/getting-started/plugin-yml.mdx b/docs/paper/dev/getting-started/plugin-yml.mdx index 2435a1c3a..14dada687 100644 --- a/docs/paper/dev/getting-started/plugin-yml.mdx +++ b/docs/paper/dev/getting-started/plugin-yml.mdx @@ -5,11 +5,11 @@ description: A guide to Bukkit's plugin.yml file. # Plugin YML -The plugin.yml file is the main configuration file for your plugin. +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. +The `plugin.yml` file is located in the `resources` directory of your project. ``` example-plugin ├── build.gradle.kts @@ -23,7 +23,7 @@ example-plugin ## Example -Here is an example of a plugin.yml file: +Here is an example of a `plugin.yml` file: ``` @@ -115,11 +115,11 @@ The prefix of the plugin. This is what will be displayed in the log instead of t :::warning -The use of this feature is *currently* against maven central's TOS. However, this feature is very likely to stay. +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 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 @@ -144,12 +144,13 @@ permissions : ``` 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. +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`. +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 @@ -165,22 +166,28 @@ commands: 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. +- `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: +## 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. +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. +Where `PluginA` and `PluginB` are plugins that depend on each other. ::: diff --git a/docs/paper/dev/getting-started/project-setup.mdx b/docs/paper/dev/getting-started/project-setup.mdx index 84239314e..3387245a8 100644 --- a/docs/paper/dev/getting-started/project-setup.mdx +++ b/docs/paper/dev/getting-started/project-setup.mdx @@ -1,6 +1,6 @@ --- slug: /dev/project-setup -description: Step-by-step instructions on how to setup a plugin development environment. +description: Step-by-step instructions on how to set up a plugin development environment. --- # Paper Project Setup @@ -16,7 +16,7 @@ Follow the guide [here](https://docs.gradle.org/current/userguide/migrating_from ## 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`. +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. @@ -202,6 +202,6 @@ 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. +The output JAR of your plugin will be in the `build/libs` directory. ::: diff --git a/docs/paper/dev/getting-started/userdev.mdx b/docs/paper/dev/getting-started/userdev.mdx index a95d2bfeb..831d3cc57 100644 --- a/docs/paper/dev/getting-started/userdev.mdx +++ b/docs/paper/dev/getting-started/userdev.mdx @@ -18,7 +18,7 @@ check out this [example plugin](https://github.com/PaperMC/paperweight-test-plug ::: ## Why this is useful -The Paper server jars we provide on the downloads page through the API are **paperclip** jars. These +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 @@ -77,22 +77,22 @@ You should remove any dependency on the Paper API, as the dev bundle includes th ::: -## Gradle Tasks +## Gradle tasks -### reobfJar +### `reobfJar` -This task creates a plugin jar that is re-obfuscated to Spigot's runtime mappings. +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. +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. +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. +The `-dev-all.jar` file in `build/libs` is the shaded, but not re-obfuscated JAR. ::: diff --git a/docs/paper/dev/misc/databases.mdx b/docs/paper/dev/misc/databases.mdx index a28462dc0..e91c238ef 100644 --- a/docs/paper/dev/misc/databases.mdx +++ b/docs/paper/dev/misc/databases.mdx @@ -27,12 +27,12 @@ It organizes data into structured tables with predefined schemas, where each tab 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 +## 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 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. @@ -41,7 +41,7 @@ Some examples of file-based databases are `SQLite` and `H2`.
Simple SQLite Setup -## SQLite +#### SQLite To work with SQLite, you will need a driver to connect / initialize the database. @@ -51,9 +51,9 @@ The JDBC Driver is bundled with Paper, so you do not need to shade/relocate it i ::: -### Usage +##### Usage -You must invoke a `Class.forName` on the driver to allow it to initialise and then create the connection to the database: +You must invoke a `Class.forName` on the driver to allow it to initialize and then create the connection to the database: ```java public class DatabaseManager { @@ -70,7 +70,7 @@ To learn more about the Java Database Connection, see [here](https://www.baeldun
-### Standalone Databases +### 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`. @@ -86,7 +86,7 @@ down connections repeatedly, leading to improved application performance and bet
Simple MySQL Setup -## MySQL +#### 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. @@ -99,7 +99,7 @@ This will require a running MySQL database to connect to. First, add the dependency to your project with the following dependency: -### Maven +##### Maven ```xml com.zaxxer @@ -109,7 +109,7 @@ First, add the dependency to your project with the following dependency: ``` -### Gradle +##### Gradle ```kotlin dependencies { implementation("com.zaxxer:HikariCP:4.0.3") @@ -118,13 +118,13 @@ dependencies { :::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 task. -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) +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 +##### Usage Once you have the dependency added, we can work with the connector in our code: @@ -154,7 +154,7 @@ public class DatabaseManager {
-## SQL Injection and Prepared Statements in Java +## Security ### SQL Injection @@ -185,9 +185,9 @@ 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: Why They Matter +### Prepared statements -Using prepared statements in Java with PreparedStatements helps prevent SQL injection. +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/paper/dev/misc/debugging.mdx b/docs/paper/dev/misc/debugging.mdx index f20f923d9..097941960 100644 --- a/docs/paper/dev/misc/debugging.mdx +++ b/docs/paper/dev/misc/debugging.mdx @@ -3,7 +3,7 @@ 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 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. diff --git a/docs/paper/dev/misc/reading-stacktraces.md b/docs/paper/dev/misc/reading-stacktraces.md index e8b1ef549..e0b2639df 100644 --- a/docs/paper/dev/misc/reading-stacktraces.md +++ b/docs/paper/dev/misc/reading-stacktraces.md @@ -12,9 +12,9 @@ Usually, the stacktrace will be printed to the console when an exception is not 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: +### Example -Here is an example of a stacktrace which has been caused due to a `NullPointerException`: +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 @@ -57,7 +57,7 @@ java.lang.NullPointerException: Cannot invoke "Object.toString()" because "playe - 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 +## 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: diff --git a/docs/velocity/README.mdx b/docs/velocity/README.mdx index 3ee0cb43b..7aadf86e2 100644 --- a/docs/velocity/README.mdx +++ b/docs/velocity/README.mdx @@ -19,7 +19,7 @@ We have put a lot of effort into documenting Velocity as much as possible with o our coverage will continue to expand. We strongly encourage you to check the sidebar of the docs for relevant resources. Helping yourself using the resources in these docs saves all of us time. -We recommend you visit the [frequently-asked questions](admin/getting-started/faq.mdx) to begin your +We recommend you visit the [frequently asked questions](admin/getting-started/faq.mdx) to begin your search. Most common issues with Velocity are answered there. Please do not be offended if we respond to your question linking back here. Asking us a question diff --git a/docs/velocity/admin/README.mdx b/docs/velocity/admin/README.mdx index 29d1948d5..d580b27cd 100644 --- a/docs/velocity/admin/README.mdx +++ b/docs/velocity/admin/README.mdx @@ -1,9 +1,9 @@ import DocCardList from "@theme/DocCardList"; import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; -# Velocity Proxy Administration +# Velocity Administration Guide -Welcome to the Velocity Proxy Administration Guide! This guide includes information and tutorials +Welcome to the Velocity administration guide! This guide includes information and tutorials regarding the administration of a Velocity proxy. --- diff --git a/docs/velocity/admin/getting-started/faq.mdx b/docs/velocity/admin/getting-started/faq.mdx index 32459d098..039fa36f7 100644 --- a/docs/velocity/admin/getting-started/faq.mdx +++ b/docs/velocity/admin/getting-started/faq.mdx @@ -31,7 +31,7 @@ natively by the latest versions of Velocity. There are a few common causes for why you can't connect to the server. -### Basic Troubleshooting +### Basic troubleshooting As a first step, you should verify: @@ -39,7 +39,7 @@ As a first step, you should verify: - that the proxy is started - that the server and proxy are bound to the appropriate port and IP -### Improper Player Information Forwarding Errors +### Improper player information forwarding errors ``` Can't connect to server lobby: If you wish to use IP forwarding, please enable it in your Bungeecord config as well! @@ -53,18 +53,16 @@ These errors are result of improper configuration. See [Player Information Forwarding](forwarding.md) to learn how to properly set up player information forwarding. -### Improper Modern Player Information Forwarding - ``` Can't connect to server lobby: This server requires you to connect with Velocity. ``` -This error is a result of enabling Velocity modern forwarding on your backend server but not +This error is a result of enabling Velocity modern forwarding on your backend server, but not enabling it in Velocity. To fix this error, ensure that you have set up the correct player information forwarding method on the proxy. See [Player Information Forwarding](forwarding.md) for more information. -### Invalid Payload Register +### Invalid payload `REGISTER` ``` [server connection] player1 -> hub has connected @@ -73,9 +71,10 @@ more information. This error typically occurs on Spigot-based servers when someone connects with a modded client. You can fix this issue if you use Paper (or a fork of Paper) 1.12.2 or above by adding the startup flag -`-Dpaper.disableChannelLimit=true` to the server's startup flags and restarting the server. +[`-Dpaper.disableChannelLimit=true`](/paper/reference/system-properties#paperdisablechannellimit) +to the server's startup flags and restarting the server. -### Argument type identifier XXX unknown +### Argument type identifier unknown ``` Argument type identifier : unknown. @@ -86,7 +85,7 @@ Fabric 1.16+ and above, update to at least Velocity 1.1.2 and install [CrossStitch](https://www.curseforge.com/minecraft/mc-mods/crossstitch). (If you are running any other kind of modded server and have it working with Velocity, let us know!) -If you receive this message but run a vanilla server, +If you receive this message but run a Vanilla server, [please report a bug to the Velocity issue tracker](https://github.com/PaperMC/Velocity/issues/new). ### Read time out while switching to a Forge server diff --git a/docs/velocity/admin/getting-started/forwarding.md b/docs/velocity/admin/getting-started/forwarding.md index e6f0ede3c..1e316c132 100644 --- a/docs/velocity/admin/getting-started/forwarding.md +++ b/docs/velocity/admin/getting-started/forwarding.md @@ -60,7 +60,8 @@ you're done editing `paper-global.yml`, reboot your server. :::info -If you are using Paper 1.18.2 or lower, you will find these options as `settings.velocity-support.enabled`, `settings.velocity-support.secret` and `settings.velocity-support.online-mode` in the `paper.yml` file. +If you are using Paper 1.18.2 or lower, you will find these options as `settings.velocity-support.enabled`, +`settings.velocity-support.secret` and `settings.velocity-support.online-mode` in the `paper.yml` file. ::: @@ -72,7 +73,7 @@ Velocity modern forwarding with a modded server using Fabric. ## Configuring modern forwarding for Forge A mod called [ProxyCompatibleForge](https://modrinth.com/mod/proxy-compatible-forge) allows you to use -Velocity modern forwarding with a modded server using Forge 1.16.5 or higher. +Velocity modern forwarding with a modded server using Forge 1.16.5 or higher. ## Configuring legacy BungeeCord-compatible forwarding diff --git a/docs/velocity/admin/getting-started/why-velocity.md b/docs/velocity/admin/getting-started/why-velocity.md index 14698ee69..7da487af5 100644 --- a/docs/velocity/admin/getting-started/why-velocity.md +++ b/docs/velocity/admin/getting-started/why-velocity.md @@ -15,7 +15,7 @@ This page is our answer to that question. The founder and primary developer of Velocity (Tux) has been active in developing proxy software for _Minecraft: Java Edition_ since 2013. They created the RedisBungee plugin, contributed to BungeeCord from 2014 to 2017, and also founded the Waterfall project and led it from 2016 to 2017. In fact, the -current maintainer of Waterfall helped encourage them to start a brand new proxy from the ground up! +current maintainer of Waterfall helped encourage them to start a brand-new proxy from the ground up! ## Leading performance diff --git a/docs/velocity/admin/how-to/migration.md b/docs/velocity/admin/how-to/migration.md index 0868ee4f3..a331c636c 100644 --- a/docs/velocity/admin/how-to/migration.md +++ b/docs/velocity/admin/how-to/migration.md @@ -6,7 +6,7 @@ description: How to migrate your proxy between different Velocity versions. # Migration Guide New to Velocity, or upgrading to a new version of Velocity? This page will briefly explore what you -need to be aware of for a successful migration +need to be aware of for a successful migration. ## Migrating from Velocity 1.0.x to Velocity 1.1.0 diff --git a/docs/velocity/admin/how-to/security.md b/docs/velocity/admin/how-to/security.md index ad306d4e8..3cf1b92bc 100644 --- a/docs/velocity/admin/how-to/security.md +++ b/docs/velocity/admin/how-to/security.md @@ -12,11 +12,11 @@ your servers. This guide will explore the various options for securing your backend servers so only your proxy can connect to them. Note that this is an _exploration_ of options, aiming to review the various options -and give you advantages and disadvantages to them so you can make an informed decision. +and give you advantages and disadvantages to them, so you can make an informed decision. This list is not in any particular order, and almost all of these methods can be combined as needed. -## Operating System Firewalls +## Operating system firewalls When properly configured, using the firewall facilities provided by your server's operating system is a highly effective way to protect your servers. The Velocity project **strongly recommends the @@ -40,7 +40,7 @@ Instructions for your operating system may vary. Solutions for major server OSes - Firewall configuration must be kept in sync with new servers and proxies - Not viable on a shared host -## Velocity Modern Forwarding +## Velocity modern forwarding If your server only supports Minecraft 1.13 and above, Velocity's modern forwarding can forward player information to your servers and provide a second layer of protection against someone trying @@ -65,7 +65,7 @@ firewall with any Minecraft proxy setup. - Requires Paper 1.13 or above, or FabricProxy-Lite if you use Fabric - Relies on the forwarding secret being kept secret -## Binding To `localhost` +## Binding to `localhost` If you are hosting your proxy on the same physical computer as your other servers (and nobody else is hosting servers on them), binding your servers to `localhost` is a very simple way of protecting @@ -89,9 +89,9 @@ Afterwards, open your `velocity.toml` file and ensure all the servers are pointi server) - Not viable on a shared host -## Using an Encrypted Tunnel +## Using an encrypted tunnel -This is a variation on "Binding To `localhost`", but instead of hosting all your servers on a single +This is a variation of binding to `localhost`, but instead of hosting all your servers on a single physical server, you will set up an encrypted tunnel between each of your servers, and make sure the server only listens for incoming connections from the tunnel. There are many different solutions, ranging from VPN solutions such as [WireGuard](https://www.wireguard.com), @@ -109,7 +109,7 @@ each of these solutions. - Very complex setup - Impossible to use on a shared host -## IP Whitelisting Plugins +## IP whitelisting plugins As a last line of defense, you can choose to restrict logins to users on an IP whitelist using a plugin like [IPWhitelist](https://www.spigotmc.org/resources/ipwhitelist.61/). @@ -122,7 +122,7 @@ plugin like [IPWhitelist](https://www.spigotmc.org/resources/ipwhitelist.61/). - Vulnerable to attack if the attacker can get a server on the same node as your proxy is on -## Other Important Security Advice +## Other important security advice This common-sense general advice goes without saying: diff --git a/docs/velocity/admin/how-to/tuning.md b/docs/velocity/admin/how-to/tuning.md index d5a119b42..866aed535 100644 --- a/docs/velocity/admin/how-to/tuning.md +++ b/docs/velocity/admin/how-to/tuning.md @@ -15,7 +15,7 @@ Velocity comes with high-performance, specially tuned native libraries for compr encryption, along with including native transports from Netty. However, due to support constraints, the compiled natives are only verified to work on Linux x86_64 and aarch64. While Velocity does not require the natives to work, you will suffer from degraded performance. For this reason, we strongly -recommend that all production deployments of Velocity run on x86-64 Linux. +recommend that all production deployments of Velocity run on x86_64 Linux. ## Allocate server resources appropriately @@ -63,7 +63,7 @@ to the proxy. Not doing this can induce lag and in severe cases may result in th terminated by the Java Virtual Machine because it ran out of memory. The general rule of thumb is that you allocate 512MB per 500 players, plus some extra to allow for -some room for error ( typically 1GB extra). For instance, if you want to handle 1,000 on a single +some room for error (typically 1GB extra). For instance, if you want to handle 1,000 on a single proxy, plan to allocate 2GB of heap. ### Special notes for containers diff --git a/docs/velocity/admin/reference/commands.md b/docs/velocity/admin/reference/commands.md index 27df8ec50..ddab1eb3d 100644 --- a/docs/velocity/admin/reference/commands.md +++ b/docs/velocity/admin/reference/commands.md @@ -10,7 +10,7 @@ based on how generally useful they are to most users. Of course, you can always install plugins to add more commands if you want. -## The `/velocity` command +## `/velocity` The `/velocity` command contains a number of subcommands to manage the proxy. @@ -21,7 +21,8 @@ active on the proxy using `/velocity plugins`, including the name, authors, and ### `/velocity version` -If the user has the `velocity.command.info` permission (by default, this is granted to all users), they can view the version of Velocity running on the proxy. +If the user has the `velocity.command.info` permission (by default, this is granted to all users), +they can view the version of Velocity running on the proxy. ### `/velocity reload` @@ -32,7 +33,7 @@ applied. ### `/velocity dump` If the user has the `velocity.command.plugins` permission, they can use this command to get an -anonymized dump of details on the proxy. This can be sent to the Velocity Discord to help us provide +anonymized dump of details on the proxy. This can be sent to the PaperMC Discord to help us provide support. ### `/velocity heap` diff --git a/docs/velocity/admin/reference/comparison.md b/docs/velocity/admin/reference/comparison.md index 0c3078023..66e657af3 100644 --- a/docs/velocity/admin/reference/comparison.md +++ b/docs/velocity/admin/reference/comparison.md @@ -81,7 +81,7 @@ Most BungeeCord plugins are deeply dependent on the specific behaviors and quirk exposes, which Velocity cannot perfectly emulate. As a result, the number of changes one can make to BungeeCord and have plugins retain the same behavior is minimal. -Suppose you have play a video game published by Company A. It runs on an operating system made by Company B. +Suppose you have played a video game published by Company A. It runs on an operating system made by Company B. One day, Company B releases a new version of their operating system, and you upgrade to it, only to recoil in horror as that video game no longer works. (Worse, Studio A might be out of business at that point, so no patch is forthcoming.) Who do you blame, Company A for producing a defective product, or Company B for @@ -102,7 +102,7 @@ project. We could have based Velocity on the BungeeCord API (or a derivative the Waterfall API) instead. This has the same problems as Waterfall, perhaps more as we would need to emulate _all_ the behavior -of the BungeeCord API independently. The Wine project has been trying over over 3 decades to provide +of the BungeeCord API independently. The Wine project has been trying for over 3 decades to provide a shim layer that allows Windows programs to run on Linux and other operating systems. Their efforts remain ongoing to this day. It is hard to emulate the behavior of another operating system's environment. The authors of ReactOS have it even worse, trying to emulate all the quirks of Windows, including its diff --git a/docs/velocity/admin/reference/configuration.md b/docs/velocity/admin/reference/configuration.md index 5be195112..3964f0fa9 100644 --- a/docs/velocity/admin/reference/configuration.md +++ b/docs/velocity/admin/reference/configuration.md @@ -32,39 +32,39 @@ instance, `127.0.0.1:25577` and `server01.example.com:25565` are valid addresses These settings mostly cover the basic, most essential settings of the proxy. -| Setting Name | Type | Description | -|-------------------------------| ------- |--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `config-version` | String | This is the current config version used by Velocity. You should not alter this setting. | -| `bind` | Address | This tells the proxy to accept connections on a specific IP. By default, Velocity will listen for connections on all IP addresses on the computer on port 25577. | -| `motd` | Chat | This allows you to change the message shown to players when they add your server to their server list. You can use [MiniMessage format](https://docs.advntr.dev/minimessage/format.html). | -| `show-max-players` | Integer | This allows you to customize the number of "maximum" players in the player's server list. Note that Velocity doesn't have a maximum number of players it supports. | -| `online-mode` | Boolean | Should we authenticate players with Mojang? By default, this is on. | -| `force-key-authentication` | Boolean | Should the proxy enforce the new public key security standard? By default, this is on. | -| `player-info-forwarding-mode` | Enum | See [Configuring player information forwarding](../getting-started/forwarding.md) for more information. | -| `prevent-client-proxy-connections` | Boolean | If client's ISP/AS sent from this proxy is different from the one from Mojang's authentication server, the player is kicked. This disallows some VPN and proxy connections but is a weak form of protection. | -| `forwarding-secret-file` | String | The name of the file in which the forwarding secret is stored. This secret is used to ensure that player info forwarded by Velocity comes from your proxy and not from someone pretending to run Velocity. See the "Player info forwarding" section for more info. | -| `announce-forge` | Boolean | This setting determines whether Velocity should present itself as a Forge/FML-compatible server. By default, this is disabled. | -| `kick-existing-players` | Boolean | Allows restoring the vanilla behavior of kicking users on the proxy if they try to reconnect (e.g. lost internet connection briefly). | -| `ping-passthrough` | String | Allows forwarding nothing (the default), the `MODS` (for Forge), the `DESCRIPTION`, or everything (`ALL`) from the `try` list (or forced host server connection order). | -| `enable-player-address-logging` | Boolean | If disabled (default is true), player IP addresses will be replaced by `` in logs. | +| Setting Name | Type | Description | +|------------------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `config-version` | String | This is the current config version used by Velocity. You should not alter this setting. | +| `bind` | Address | This tells the proxy to accept connections on a specific IP. By default, Velocity will listen for connections on all IP addresses on the computer on port 25577. | +| `motd` | Chat | This allows you to change the message shown to players when they add your server to their server list. You can use [MiniMessage format](https://docs.advntr.dev/minimessage/format.html). | +| `show-max-players` | Integer | This allows you to customize the number of "maximum" players in the player's server list. Note that Velocity doesn't have a maximum number of players it supports. | +| `online-mode` | Boolean | Should we authenticate players with Mojang? By default, this is on. | +| `force-key-authentication` | Boolean | Should the proxy enforce the new public key security standard? By default, this is on. | +| `player-info-forwarding-mode` | Enum | See [Configuring player information forwarding](../getting-started/forwarding.md) for more information. | +| `prevent-client-proxy-connections` | Boolean | If client's ISP/AS sent from this proxy is different from the one from Mojang's authentication server, the player is kicked. This disallows some VPN and proxy connections but is a weak form of protection. | +| `forwarding-secret-file` | String | The name of the file in which the forwarding secret is stored. This secret is used to ensure that player info forwarded by Velocity comes from your proxy and not from someone pretending to run Velocity. See the "Player info forwarding" section for more info. | +| `announce-forge` | Boolean | This setting determines whether Velocity should present itself as a Forge/FML-compatible server. By default, this is disabled. | +| `kick-existing-players` | Boolean | Allows restoring the Vanilla behavior of kicking users on the proxy if they try to reconnect (e.g. lost internet connection briefly). | +| `ping-passthrough` | String | Allows forwarding nothing (the default), the `MODS` (for Forge), the `DESCRIPTION`, or everything (`ALL`) from the `try` list (or forced host server connection order). | +| `enable-player-address-logging` | Boolean | If disabled (default is true), player IP addresses will be replaced by `` in logs. | ## `servers` section | Setting Name | Type | Description | -| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- | +|---------------|---------|----------------------------------------------------------------------------------------------------------------------------| | A server name | Address | This makes the proxy aware of a server that it can connect to. | | `try` | Array | This specifies what servers Velocity should try to connect to upon player login and when a player is kicked from a server. | ## `forced-hosts` section | Setting Name | Type | Description | -| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------------|----------|---------------------------------------------------------------------------------------------------------------------------------------------------| | A host name | Hostname | This configures the proxy to create a forced host for the specified hostname. An array of servers to try for the specified hostname is the value. | ## `advanced` section | Setting name | Type | Description | -| ------------------------------------------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +|--------------------------------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `compression-threshold` | Integer | This is the minimum size (in bytes) that a packet must be before the proxy compresses it. Minecraft uses 256 bytes by default. | | `compression-level` | Integer | This setting indicates what `zlib` compression level the proxy should use to compress packets. The default value uses the default zlib level. | | `login-ratelimit` | Integer | This setting determines the minimum amount of time (in milliseconds) that must pass before a connection from the same IP address will be accepted by the proxy. A value of `0` disables the rate limit. | @@ -82,7 +82,7 @@ These settings mostly cover the basic, most essential settings of the proxy. ## `query` section | Setting name | Type | Description | -| -------------- | ------- | ------------------------------------------------------------------------------------------------------------ | +|----------------|---------|--------------------------------------------------------------------------------------------------------------| | `enabled` | Boolean | Whether or not Velocity should reply to Minecraft query protocol requests. You can usually leave this false. | | `port` | Number | Specifies which port that Velocity should listen on for GameSpy 4 (Minecraft query protocol) requests. | | `map` | String | Specifies the map name to be shown to clients. | diff --git a/docs/velocity/admin/reference/libraries.md b/docs/velocity/admin/reference/libraries.md index d30f3fba9..5d6f16e05 100644 --- a/docs/velocity/admin/reference/libraries.md +++ b/docs/velocity/admin/reference/libraries.md @@ -22,7 +22,7 @@ Velocity uses a number of open-source libraries: | [Log4j](https://logging.apache.org/log4j/2.x/) | [Apache Log4j Team](https://logging.apache.org/log4j/2.x/team-list.html) | [Apache License 2.0](https://logging.apache.org/log4j/2.x/license.html) | | [TerminalConsoleAppender](https://github.com/Minecrell/TerminalConsoleAppender) | [Minecrell](https://github.com/Minecrell) | [MIT License](https://github.com/Minecrell/TerminalConsoleAppender/blob/master/LICENSE) | | [Configurate](https://github.com/SpongePowered/configurate) | [SpongePowered](https://github.com/SpongePowered) | [Apache License 2.0](https://github.com/SpongePowered/configurate/blob/master/LICENSE) | -| [SnakeYAML](https://bitbucket.org/snakeyaml/snakeyaml) | [SnakeYAML](https://bitbucket.org/snakeyaml) | [Apache License 2.0](https://bitbucket.org/snakeyaml/snakeyaml/src/master/LICENSE.txt) | +| [SnakeYAML](https://bitbucket.org/snakeyaml/snakeyaml) | [SnakeYAML](https://bitbucket.org/snakeyaml) | [Apache License 2.0](https://bitbucket.org/snakeyaml/snakeyaml/src/master/LICENSE.txt) | | [HOCON](https://github.com/lightbend/config) | [lightbend](https://github.com/lightbend) | [Apache License 2.0](https://github.com/lightbend/config/blob/master/LICENSE-2.0.txt) | | [toml4j](https://github.com/mwanji/toml4j) | [Moandji Ezana](https://github.com/mwanji) | [MIT License](https://github.com/mwanji/toml4j/blob/master/LICENSE) | | [Night-Config](https://github.com/TheElectronWill/night-config) | [TheElectronWill](https://github.com/TheElectronWill) | [GNU Lesser General Public License 3.0](https://github.com/TheElectronWill/night-config/blob/master/LICENSE) | diff --git a/docs/velocity/admin/reference/server-compatibility.mdx b/docs/velocity/admin/reference/server-compatibility.mdx index 796fd2460..480fce2b7 100644 --- a/docs/velocity/admin/reference/server-compatibility.mdx +++ b/docs/velocity/admin/reference/server-compatibility.mdx @@ -6,7 +6,7 @@ description: A guide to the server compatibility for Velocity. # Server Compatibility Velocity is compatible with many Minecraft server implementations. The expectation is that if the -server acts like vanilla, Velocity will work, and we make special provisions for modded setups where +server acts like Vanilla, Velocity will work, and we make special provisions for modded setups where we can. ## Compatible game versions @@ -15,24 +15,24 @@ As of this writing, Velocity is compatible with Minecraft 1.7.2 through diff --git a/docs/velocity/dev/api/component-api/i18n.mdx b/docs/velocity/dev/api/component-api/i18n.mdx index 680226c0d..b6b15535e 100644 --- a/docs/velocity/dev/api/component-api/i18n.mdx +++ b/docs/velocity/dev/api/component-api/i18n.mdx @@ -4,6 +4,6 @@ description: How to use Adventure's internationalization. title: Internationalization --- -import Internationalization from '@site/docs/paper/dev/api/component-api/i18n.md'; +import Internationalization from "@site/docs/paper/dev/api/component-api/i18n.md"; diff --git a/docs/velocity/dev/api/component-api/intro.mdx b/docs/velocity/dev/api/component-api/intro.mdx index a43f0a26e..be0ac3caa 100644 --- a/docs/velocity/dev/api/component-api/intro.mdx +++ b/docs/velocity/dev/api/component-api/intro.mdx @@ -4,6 +4,6 @@ description: An introduction to how components work. title: Introduction --- -import Introduction from '@site/docs/paper/dev/api/component-api/intro.md'; +import Introduction from "@site/docs/paper/dev/api/component-api/intro.md"; diff --git a/docs/velocity/dev/api/event.md b/docs/velocity/dev/api/event.md index 399f330c0..7d648029c 100644 --- a/docs/velocity/dev/api/event.md +++ b/docs/velocity/dev/api/event.md @@ -163,12 +163,12 @@ are urged to make the transition now. ::: -## Creating Events +## Creating events Creating events on Velocity is somewhat different than on other platforms. However, it is very similar for the most part. -### Creating the Event Class +### Creating the event class First we need to create a class for our event. In this tutorial we'll assume you're making a private messaging plugin, and thus use a `PrivateMessageEvent`. Most of this part is boilerplate. @@ -218,9 +218,9 @@ server.getEventManager().fire(new PrivateMessageEvent(sender, recipient, message }); ``` -### Using ResultedEvent +### Using `ResultedEvent` -Velocity uses the generalised `ResultedEvent` for events which have some sort of 'result'. The +Velocity uses the generalized `ResultedEvent` for events which have some sort of 'result'. The result type of the event is defined by its generic type; for example. `PrivateMessageEvent implements ResultedEvent`. diff --git a/docs/velocity/dev/api/plugin-messaging.md b/docs/velocity/dev/api/plugin-messaging.md index 535e5b56a..803e8f78d 100644 --- a/docs/velocity/dev/api/plugin-messaging.md +++ b/docs/velocity/dev/api/plugin-messaging.md @@ -6,7 +6,7 @@ description: How to handle and send plugin messages on Velocity. # 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 Velocity plugins to communicate with clients and backend servers. +Plugin messaging is a way for Velocity plugins to communicate with clients and backend servers. Velocity manages connections in both directions, for both the client and backend server. This means Velocity plugins need to consider 4 main cases: @@ -21,7 +21,8 @@ Additionally, BungeeCord channel compatibility is included, which may remove the ## Case 1: Receiving a plugin message from a player -This is for when you need to handle or inspect the contents of a plugin message sent by a player. It will require registering with the ChannelRegistrar for the event to be fired. +This is for when you need to handle or inspect the contents of a plugin message sent by a player. +It will require registering with the ChannelRegistrar for the event to be fired. An example use case could be logging messages from a mod that reports the enabled features. @@ -43,7 +44,7 @@ public void onPluginMessageFromPlayer(PluginMessageEvent event) { if (event.getIdentifier() != IDENTIFIER) { return; } - + ByteArrayDataInput in = ByteStreams.newDataInput(event.getData()); // handle packet data } @@ -53,7 +54,7 @@ public void onPluginMessageFromPlayer(PluginMessageEvent event) { This is for when you need to send a plugin message to a backend server. -There are two methods to send a plugin message to the backend, depending on what you need to achieve +There are two methods to send a plugin message to the backend, depending on what you need to achieve. :::warning @@ -97,7 +98,7 @@ public boolean sendPluginMessageToBackendUsingPlayer(Player player, ChannelIdent ## Case 3: Receiving a plugin message from a backend server -This is for when you need to receive plugin messages from your backend server. It will require registering with the ChannelRegistrar for the event to be fired. +This is for when you need to receive plugin messages from your backend server. It will require registering with the `ChannelRegistrar` for the event to be fired. An example use case could be handing a request to transfer the player to another server. @@ -124,6 +125,7 @@ public void onPluginMessageFromBackend(PluginMessageEvent event) { // handle packet data } ``` + ## Case 4: Sending a plugin message to a player This is for when you need to send a plugin message to a player. @@ -141,15 +143,15 @@ public boolean sendPluginMessageToPlayer(Player player, ChannelIdentifier identi } ``` -## BungeeCord Channel Compatibility +## BungeeCord channel compatibility This allows your backend servers to communicate with Velocity -in a way compatible with BungeeCord +in a way compatible with BungeeCord. -By default, your Velocity server will respond to the `bungeecord:main` channel if `bungee-plugin-message-channel` is enabled in [the configuration](/velocity/configuration#advanced-section). +By default, your Velocity server will respond to the `bungeecord:main` channel, if `bungee-plugin-message-channel` is enabled in [the configuration](/velocity/configuration#advanced-section). :::tip[The "bungeecord" specification] -See [here](/paper/dev/plugin-messaging#bungeecord-plugin-message-types) for a list of all the built-in plugin messages that BungeeCord / Velocity supports. +See [here](/paper/dev/plugin-messaging#plugin-message-types) for a list of all the built-in plugin messages that BungeeCord / Velocity supports. ::: diff --git a/docs/velocity/dev/api/scheduler.md b/docs/velocity/dev/api/scheduler.md index 47235f678..f5f81a42b 100644 --- a/docs/velocity/dev/api/scheduler.md +++ b/docs/velocity/dev/api/scheduler.md @@ -5,7 +5,7 @@ description: A guide to the Scheduler API within Velocity allowing tasks to be r # Using the Scheduler -The Velocity Scheduler lets you decide when and how your plugin tasks run, allowing fine control +The Velocity scheduler lets you decide when and how your plugin tasks run, allowing fine control over execution. On Velocity, there is no main thread. All tasks run using the Velocity Scheduler are thus run asynchronously. diff --git a/docs/velocity/dev/getting-started/api-basics.md b/docs/velocity/dev/getting-started/api-basics.md index 1f046d95f..6196a6323 100644 --- a/docs/velocity/dev/getting-started/api-basics.md +++ b/docs/velocity/dev/getting-started/api-basics.md @@ -46,7 +46,7 @@ bits: public class VelocityTest { ``` -This tells Velocity that this class contains your plugin (myfirstplugin) so that it can be loaded +This tells Velocity that this class contains your plugin (`myfirstplugin`) so that it can be loaded once the proxy starts up. Velocity will detect where the plugin will reside when you compile your plugin. @@ -63,14 +63,14 @@ public VelocityTest(ProxyServer server, Logger logger) { ``` This looks like magic! How is Velocity doing this? The answer lies in the `@Inject`, which indicates -that Velocity should inject a ProxyServer and the Logger when constructing your plugin. These two +that Velocity should inject a `ProxyServer` and the `Logger` when constructing your plugin. These two interfaces will help you out as you begin working with Velocity. We won't talk too much about dependency injection: all you need to know is that Velocity will do this. All you need to do is build your plugin, put it in your `plugins/` directory, and try it! Isn't that nice? In the next section you'll learn more about how to use the API. -## Choosing `@Plugin` Information +## Choosing `@Plugin` information Choose your plugin's ID wisely. Other plugins will use this ID to depend on yours. If you change it, you could break compatibility. @@ -110,7 +110,7 @@ public void onProxyInitialization(ProxyInitializeEvent event) { } ``` -## Getting your Plugin's Directory +## Getting your plugin's directory At some point you may need your plugin's directory. To do this, add `@DataDirectory Path dataDirectory` to your plugin's constructor parameters: 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 1dd91efcd..15e953ed7 100644 --- a/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx +++ b/docs/velocity/dev/getting-started/creating-your-first-plugin.mdx @@ -8,7 +8,7 @@ import TabItem from '@theme/TabItem'; # Creating Your First Plugin -It is very simple to create a plugin for Velocity. This section will teach you how to setup your +It is very simple to create a plugin for Velocity. This section will teach you how to set up your IDE, your plugin identifiers, and give you an introduction to the basics of the Velocity API. ## Before you continue... @@ -51,7 +51,7 @@ Javadocs are available at [jd.papermc.io/velocity/3.0.0](https://jd.papermc.io/v ## Set up your build system -You will need to setup a build system before you continue. While it is possible to write Velocity +You will need to set up a build system before you continue. While it is possible to write Velocity plugins without one, having a build system will make your life a lot less difficult. How to set up a build system is outside the scope of this page, but you can look at your build @@ -196,6 +196,6 @@ It will automatically download a Velocity 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. +The output JAR of your plugin will be in the `build/libs` directory. ::: diff --git a/docs/velocity/dev/getting-started/pitfalls.md b/docs/velocity/dev/getting-started/pitfalls.md index d1f1f3b26..f2667c69f 100644 --- a/docs/velocity/dev/getting-started/pitfalls.md +++ b/docs/velocity/dev/getting-started/pitfalls.md @@ -18,7 +18,7 @@ have a valid plugin registration, but Velocity can't register the plugin until t constructed. To break this cycle, you should always wait for initialization, which is indicated when Velocity -fires the ProxyInitializeEvent. We can do things on initialization by adding a listener for this +fires the `ProxyInitializeEvent`. We can do things on initialization by adding a listener for this event, as shown below. Note that Velocity automatically registers your plugin main class as a listener. @@ -33,5 +33,5 @@ public void onProxyInitialization(ProxyInitializeEvent event) { ## Audience operations not supported -Velocity only supports sending chat messages, action bar messages, titles, and boss bars through the +Velocity only supports sending chat messages, action bar messages, titles, and bossbars through the Adventure API. No other operations are supported. diff --git a/docs/velocity/dev/how-to/dependencies.md b/docs/velocity/dev/how-to/dependencies.md index c4f5e9437..8c2ffc6be 100644 --- a/docs/velocity/dev/how-to/dependencies.md +++ b/docs/velocity/dev/how-to/dependencies.md @@ -45,8 +45,8 @@ public class VelocityTest { The id of the dependency is the same as the other plugin's `id` from its `@Plugin` annotation. This is why having a stable plugin ID is important. -That's it! Now, your plugin will require wonderplugin to load, and when it does, it will load -_after_ wonderplugin. +That's it! Now, your plugin will require `wonderplugin` to load, and when it does, it will load +_after_ `wonderplugin`. To specify multiple dependencies, separate them by commas: `dependencies = {@Dependency(id = "wonderplugin"), @Dependency(id = "otherplugin")}` @@ -82,5 +82,5 @@ Dependencies on other libraries aren't handled by Velocity. You will need to add build system. If your plugin does not shade its dependencies, but rather attaches them from a directory, you may -use the PluginManager's `addToClasspath` method instead of using reflection to access the -ClassLoader. +use the `PluginManager`'s `addToClasspath` method instead of using reflection to access the +`ClassLoader`. 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 76efbb26b..bb3272da7 100644 --- a/docs/velocity/dev/how-to/porting-from-velocity-1.mdx +++ b/docs/velocity/dev/how-to/porting-from-velocity-1.mdx @@ -15,12 +15,12 @@ Velocity 3.3.x now requires Java and above ## Removal of legacy dependencies We removed all support for the old `text` 3 library. For `text` 3.x.x (and all the APIs that depend -on it), direct equivalents are available in [Adventure](https://docs.advntr.dev/) which was +on it), direct equivalents are available in [Adventure](https://docs.advntr.dev/), which was introduced in Velocity 1.1.0. `toml4j`, deprecated in Velocity 1.1.0 (as it is no longer maintained), has not been removed to -provide more time for plugins to migrate to Configurate 3. However, you should prepare to either -switch to Configurate 3 or shade toml4j into your plugin directly. +provide more time for plugins to migrate to Configurate. However, you should prepare to either +switch to Configurate or shade `toml4j` into your plugin directly. ## New asynchronous event system diff --git a/docs/waterfall/configuration.mdx b/docs/waterfall/configuration.mdx index b8d43ff51..7cee346d2 100644 --- a/docs/waterfall/configuration.mdx +++ b/docs/waterfall/configuration.mdx @@ -14,7 +14,7 @@ import WaterfallConfigSpec from '!!raw-loader!@site/config-specs/waterfall/water This page details the various configuration settings exposed by Waterfall. These settings can be found in waterfall.yml. -If you want information on settings in BungeeCord's config.yml you should see its respective +If you want information on settings in BungeeCord's config.yml, you should see its respective documentation pages. :::info diff --git a/docs/waterfall/getting-started.md b/docs/waterfall/getting-started.md index 1a17d580a..970cb46d4 100644 --- a/docs/waterfall/getting-started.md +++ b/docs/waterfall/getting-started.md @@ -25,18 +25,18 @@ Waterfall focuses on three main areas: Waterfall requires **Java 8** or newer to run. The Paper team recommends you run on Java 11 or higher. Generally, LTS versions of Java are targeted, though you may have luck on newer versions. -## Migrating From BungeeCord +## Migrating from BungeeCord Waterfall is a drop in replacements for BungeeCord, you don't need to make any changes to your configuration. -## Getting A Proxy Jar +## Getting a proxy JAR -Paper provides runnable proxy jars directly from our [downloads page](https://papermc.io/downloads#Waterfall). +Paper provides runnable proxy JARs directly from our [downloads page](https://papermc.io/downloads#Waterfall). Click on the build number to download a file. -## Running The Proxy +## Running the proxy To run the proxy, simply start it up like any other Java application. @@ -56,7 +56,7 @@ The amount of memory can be set by changing the numbers in the `-Xms` and `-Xmx` To configure your proxy, see the [configuration](configuration.mdx) page. -## Updating The Proxy +## Updating the proxy To update the proxy, first stop it safely by executing the `end` command. Then replace the old proxy -jar with a new one, and start the proxy. That's it. +JAR with a new one, and start the proxy. That's it. diff --git a/src/components/config/ConfigurationStructureDiagram.tsx b/src/components/config/ConfigurationStructureDiagram.tsx index 9fdea629c..257276bb0 100644 --- a/src/components/config/ConfigurationStructureDiagram.tsx +++ b/src/components/config/ConfigurationStructureDiagram.tsx @@ -37,7 +37,7 @@ const folderData: ExplorerNode[] = [ { name: "plugins", type: "folder", - description: "You can place your plugin jars here.", + description: "You can place your plugin JARs here.", }, { name: "",