diff --git a/_redirects b/_redirects index 71d9f81b8..ec3384f35 100644 --- a/_redirects +++ b/_redirects @@ -8,3 +8,6 @@ /paper/configuration /paper/reference/configuration /paper/reference/vanilla-command-permissions /paper/reference/permissions /paper/dev/commands /paper/dev/command-api/commands +/paper/dev/getting-started/paper-plugins /paper/dev/advanced/lifecycle-plugins +/paper/dev/userdev /paper/dev/advanced/userdev +/paper/admin/reference/paper-plugins /paper/admin/reference/lifecycle-plugins diff --git a/config/sidebar.paper.ts b/config/sidebar.paper.ts index 756be0385..26849b244 100644 --- a/config/sidebar.paper.ts +++ b/config/sidebar.paper.ts @@ -67,7 +67,7 @@ const paper: SidebarsConfig = { ], }, "admin/reference/system-properties", - "admin/reference/paper-plugins", + "admin/reference/lifecycle-plugins", "admin/reference/vanilla-command-permissions", ], }, @@ -100,11 +100,9 @@ const paper: SidebarsConfig = { id: "dev/getting-started/README", }, items: [ + "dev/getting-started/how-do-plugins-work", "dev/getting-started/project-setup", "dev/getting-started/plugin-yml", - "dev/getting-started/how-do-plugins-work", - "dev/getting-started/paper-plugins", - "dev/getting-started/userdev", ], }, { @@ -176,6 +174,16 @@ const paper: SidebarsConfig = { "dev/misc/internal-code", ], }, + { + type: "category", + label: "Advanced", + collapsed: true, + link: { + type: "doc", + id: "dev/advanced/README", + }, + items: ["dev/advanced/lifecycle-plugins", "dev/advanced/userdev"], + }, ], }, { diff --git a/docs/misc/hangar-publishing.md b/docs/misc/hangar-publishing.md index 8b125e92b..911a3091d 100644 --- a/docs/misc/hangar-publishing.md +++ b/docs/misc/hangar-publishing.md @@ -21,7 +21,7 @@ Your plugin project needs to use Gradle as its build tooling. If you are using Maven, [switching to a Gradle setup is easy](https://docs.gradle.org/current/userguide/migrating_from_maven.html) and in general recommended due to higher configurability and support for other plugins, such as -when [compiling against an unobfuscated Minecraft server](/paper/dev/userdev). +when [compiling against an unobfuscated Minecraft server](/paper/dev/advanced/userdev). The provided examples use Kotlin DSL, but you can also do the same using Groovy. Online converters (even ChatGPT) are able to convert the example code. diff --git a/docs/paper/admin/getting-started/adding-plugins.md b/docs/paper/admin/getting-started/adding-plugins.md index 133e30dcb..622ede027 100644 --- a/docs/paper/admin/getting-started/adding-plugins.md +++ b/docs/paper/admin/getting-started/adding-plugins.md @@ -4,7 +4,7 @@ slug: /adding-plugins description: Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files. --- -# Adding Plugins +# Adding Plugins to your Paper Server Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow, @@ -18,7 +18,7 @@ it is imperative that plugins only be installed from trusted sources. Be careful ::: -## Finding plugins +## Finding Paper plugins for your server 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 on your Paper server 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 diff --git a/docs/paper/admin/reference/lifecycle-plugins.md b/docs/paper/admin/reference/lifecycle-plugins.md new file mode 100644 index 000000000..f37c93a0d --- /dev/null +++ b/docs/paper/admin/reference/lifecycle-plugins.md @@ -0,0 +1,46 @@ +--- +slug: /reference/lifecycle-plugins +description: A guide to the ins and outs of lifecycle plugins. +--- + +# Lifecycle Plugins + +This documentation page serves to explain all the new semantics and possible confusions that lifecycle plugins may introduce. + +:::info + +Developers can get more information on lifecycle plugins [here](docs/paper/dev/advanced/lifecycle-plugins.mdx). + +::: + +## What are they? + +Lifecycle plugins are plugins which are loaded by Paper's new plugin loading framework. Lifecycle plugins are used by developers to +take advantage of modern systems Mojang provides, for example, datapacks. + +![Plugin List](assets/plugin-list.png) + +## What is the difference? + +When enabled, lifecycle plugins are **identical** to traditional paper plugins. This allows plugins to still fully communicate and support each other, meaning that even if a +plugin is a traditional paper plugin or lifecycle plugin, they are both able to depend on each other just fine. + +Lifecycle plugins only support being loaded by Paper's Plugin Loader and may use new API unavailable to Bukkit plugins. + +### How do I add Lifecycle plugins? + +Lifecycle plugins are added the same as traditional paper plugins, therefore, you can follow [this guide](docs/paper/admin/getting-started/adding-plugins.md). + +### Cyclic plugin loading + +With the introduction of lifecycle plugins, Paper introduces a new plugin loader that fixes some odd issues. +However, as a result, this now causes [cyclic loading](docs/paper/dev/advanced/lifecycle-plugins.mdx#cyclic-plugin-loading) between plugins to no longer be supported. + +If Paper detects a loop, your server will be shut down with an error. + +:::danger[Legacy] + +If your server **requires** this circular loading, you can enable this by adding the [`-Dpaper.useLegacyPluginLoading=true`](system-properties.md#paperuselegacypluginloading) startup flag. +Please note that this may not be supported in the future. + +::: diff --git a/docs/paper/admin/reference/paper-plugins.md b/docs/paper/admin/reference/paper-plugins.md deleted file mode 100644 index 52d527c09..000000000 --- a/docs/paper/admin/reference/paper-plugins.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -slug: /reference/paper-plugins -description: A guide to the ins and outs of Paper plugins. ---- - -# Paper Plugins - -This documentation page serves to explain all the new semantics and possible confusions that Paper plugins may introduce. - -:::info - -Developers can get more information on Paper plugins [here](docs/paper/dev/getting-started/paper-plugins.mdx). - -::: - -## What are they? - -Paper plugins are plugins which are loaded by Paper's new plugin loading framework. Paper plugins are used by developers to -take advantage of modern systems Mojang provides, for example, datapacks. - -![Plugin List](assets/plugin-list.png) - -## What is the difference? - -When enabled, Paper plugins are **identical** to Bukkit plugins. This allows plugins to still fully communicate and support each other, meaning that even if a -plugin is a Bukkit or Paper plugin, they are both able to depend on each other just fine. - -Paper plugins only support being loaded by Paper's Plugin Loader and may use new API unavailable to Bukkit plugins. - -### How do I add Paper plugins? - -Paper plugins are added the same as Bukkit plugins, therefore, you can follow [this guide](docs/paper/admin/getting-started/adding-plugins.md). - -### Cyclic plugin loading - -With the introduction of Paper plugins, Paper introduces a new plugin loader that fixes some odd issues. -However, as a result, this now causes [cyclic loading](docs/paper/dev/getting-started/paper-plugins.mdx#cyclic-plugin-loading) between plugins to no longer be supported. - -If Paper detects a loop, your server will be shut down with an error. - -:::danger[Legacy] - -If your server **requires** this circular loading, you can enable this by adding the [`-Dpaper.useLegacyPluginLoading=true`](system-properties.md#paperuselegacypluginloading) startup flag. -Please note that this may not be supported in the future. - -::: diff --git a/docs/paper/admin/reference/system-properties.md b/docs/paper/admin/reference/system-properties.md index d39fb27b7..e11332099 100644 --- a/docs/paper/admin/reference/system-properties.md +++ b/docs/paper/admin/reference/system-properties.md @@ -198,7 +198,7 @@ It also remaps plugin CB calls to remove the version information. #### paper.useLegacyPluginLoading - **default**: `false` -- **description**: Allows cyclic plugin loading. See [here](paper-plugins.md#cyclic-plugin-loading) for more info. +- **description**: Allows cyclic plugin loading. See [here](lifecycle-plugins.md#cyclic-plugin-loading) for more info. #### Paper.DisableCommandConverter @@ -213,7 +213,7 @@ It also remaps plugin CB calls to remove the version information. #### paper.disablePluginRemapping - **default**: `false` -- **description**: Disables plugin remapping introduced in 1.20.5. For more information see the [userdev](../../dev/getting-started/userdev.mdx#1205-and-beyond) documentation and the official [announcement](https://discord.com/channels/289587909051416579/976631292747735080/1232740079097876570). +- **description**: Disables plugin remapping introduced in 1.20.5. For more information see the [userdev](../../dev/advanced/userdev.mdx#1205-and-beyond) documentation and the official [announcement](https://discord.com/channels/289587909051416579/976631292747735080/1232740079097876570). #### paper.preferSparkPlugin diff --git a/docs/paper/dev/advanced/README.mdx b/docs/paper/dev/advanced/README.mdx new file mode 100644 index 000000000..ff56ec555 --- /dev/null +++ b/docs/paper/dev/advanced/README.mdx @@ -0,0 +1,11 @@ +import DocCardList from "@theme/DocCardList"; +import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; + +# Advanced Topics + +This section contains advanced topics for Paper plugin developers. +Be sure to read the [Getting Started](/paper/dev/getting-started) guide before diving into these topics. + +--- + + diff --git a/docs/paper/dev/getting-started/paper-plugins.mdx b/docs/paper/dev/advanced/lifecycle-plugins.mdx similarity index 77% rename from docs/paper/dev/getting-started/paper-plugins.mdx rename to docs/paper/dev/advanced/lifecycle-plugins.mdx index b24fbec07..4d4b36350 100644 --- a/docs/paper/dev/getting-started/paper-plugins.mdx +++ b/docs/paper/dev/advanced/lifecycle-plugins.mdx @@ -1,28 +1,25 @@ --- -slug: /dev/getting-started/paper-plugins -description: A development guide for how to write Paper-specific plugins. +slug: /dev/advanced/lifecycle-plugins +description: A development guide for how to write lifecycle plugins. --- -# Paper Plugins (Experimental) +# Lifecycle Plugins -Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to -expand the field of what the Paper API is able to introduce. - -:::danger[Experimental] - -This is experimental and may be subject to change. - -::: +## What is it used for? +Lifecycle plugins, as the name suggests, allow developers to have more control over their plugins lifecycle. +This is required to take advantage of some of the more modern concepts introduced by Mojang, such as datapacks. +Lifecycle plugins allow us to do just that by defining a new way to load plugin resources before the server +has started in form of [bootstrappers](#bootstrapper). - [Bootstrapper](#bootstrapper) - [Loader](#loaders) - [Differences](#differences) ## How do I use them? -Similarly to Bukkit plugins, you have to introduce a `paper-plugin.yml` file into your JAR resources folder. +Similarly to traditional paper plugins, you have to introduce a `paper-plugin.yml` file into your JAR resources folder. This will not act as a drop-in replacement for `plugin.yml`, as some things, as outlined in this guide, need to be declared differently. -It should be noted that you still have the ability to include both `paper-plugin.yml` and `plugin.yml` in the same JAR. +It should be noted that you still have the ability to include both `paper-plugin.yml` and `plugin.yml` in the same JAR, which can be useful for compatibility with older versions of Paper. Here is an example configuration: @@ -39,7 +36,7 @@ loader: io.papermc.testplugin.TestPluginLoader ### Dependency declaration -Paper plugins change how to declare dependencies in your `paper-plugin.yml`: +Lifecycle plugins change how to declare dependencies in your `paper-plugin.yml`: ```yml dependencies: @@ -60,7 +57,7 @@ dependencies: join-classpath: false ``` -With Paper plugins, dependencies are split into two sections: +With lifecycle 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. @@ -103,13 +100,8 @@ SuperDuperTacoParty: join-classpath: true ``` -## What is it used for? -Paper plugins lay down the framework for some future API. Our goals are to open more modern API that better aligns -with Vanilla. Paper plugins allow us to do just that by making a new way to load plugin resources before the server -has started by using [bootstrappers](#bootstrapper). - ## Bootstrapper -Paper plugins are able to identify their own bootstrapper by implementing +Lifecycle plugins are able to identify their own bootstrapper by implementing `PluginBootstrap` and adding the class of your implementation to the bootstrapper field in the `paper-plugin.yml`. ```java title="TestPluginBootstrap.java" @@ -131,7 +123,7 @@ A bootstrapper also allows you to change the way your plugin is initialized, all 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 +Lifecycle plugins are able to identify their own plugin loader by implementing `PluginLoader` and adding the class of your implementation to the loader field in the `paper-plugin.yml`. @@ -159,40 +151,40 @@ Currently, you are able to add two different library types: ## Differences ### Bukkit serialization system -Paper plugins still support the serialization system (`org.bukkit.configuration.serialization`) that Bukkit uses. However, custom classes will not be +Lifecycle plugins still support the serialization system (`org.bukkit.configuration.serialization`) that Bukkit uses. However, custom classes will not be automatically registered for serialization. In order to use `ConfigurationSection#getObject`, you **must** call `ConfigurationSerialization#registerClass(Class)` before you attempt to fetch objects from configurations. ### Classloading isolation -Paper plugins are not able to access each other unless given explicit access by depending on another plugin, etc. This -helps prevent Paper plugins from accidentally accessing each other's dependencies, and in general helps ensure that +Lifecycle plugins are not able to access each other unless given explicit access by depending on another plugin, etc. This +helps prevent Lifecycle plugins from accidentally accessing each other's dependencies, and in general helps ensure that plugins are only able to access what they explicitly depend on. -Paper plugins have the ability to bypass this, being able to access OTHER plugins' classloaders by adding a `join-classpath` option to their `paper-plugin.yml`. +Lifecycle plugins have the ability to bypass this, being able to access OTHER plugins' classloaders by adding a `join-classpath` option to their `paper-plugin.yml`. ```yml Plugin: join-classpath: true # Means you have access to their classpath ``` -Note, other Paper plugins will still be unable to access your classloader. +Note, other Lifecycle plugins will still be unable to access your classloader. ### Load order logic split -In order to better take advantage of classloading isolation, Paper plugins do **not** use the `dependencies` field to determine load order. +In order to better take advantage of classloading isolation, Lifecycle 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 +Lifecycle plugins do not use the `commands` field to register commands. This means that you do not need to include all of your commands in the `paper-plugin.yml` file. Instead, you can register commands using the [Brigadier Command API](../api/command-api/commands.mdx). ### Cyclic plugin loading Cyclic loading describes the phenomenon when a plugin loading causes a loop that eventually cycles back to the original plugin. -Unlike Bukkit plugins, Paper plugins will not attempt to resolve cyclic loading issues. +Unlike traditional paper plugins, lifecycle plugins will not attempt to resolve cyclic loading issues. ```mermaid graph LR; diff --git a/docs/paper/dev/getting-started/userdev.mdx b/docs/paper/dev/advanced/userdev.mdx similarity index 92% rename from docs/paper/dev/getting-started/userdev.mdx rename to docs/paper/dev/advanced/userdev.mdx index 87e42331e..ac41ba080 100644 --- a/docs/paper/dev/getting-started/userdev.mdx +++ b/docs/paper/dev/advanced/userdev.mdx @@ -1,13 +1,13 @@ --- -slug: /dev/userdev -sidebar_label: Paperweight Userdev +slug: /dev/advanced/userdev +sidebar_label: Accessing Internals (NMS, Userdev) description: A guide on how to use the paperweight-userdev Gradle plugin to access internal code. --- -# paperweight-userdev +# Accessing Internals (NMS, Userdev) -**paperweight** is the name of Paper's custom build tooling. The **paperweight-userdev** Gradle plugin part of that -provides access to internal code (also known as NMS) during development. +While it is generally recommended to use the Paper API for plugin development, there are some cases where you may need to access server internals, commonly referred to as NMS (short for net.minecraft.server). +This guide will show you how to use the **paperweight-userdev** Gradle plugin to access internal code during development. :::note diff --git a/docs/paper/dev/api/registries.mdx b/docs/paper/dev/api/registries.mdx index 0c282415c..90741b24f 100644 --- a/docs/paper/dev/api/registries.mdx +++ b/docs/paper/dev/api/registries.mdx @@ -101,7 +101,7 @@ Beyond plain reading access to registries, Paper also offers a way for plugins t :::warning Mutating registries needs to be done during the server's bootstrap phase. -As such, this section is only applicable to [Paper plugins](../getting-started/paper-plugins.mdx). +As such, this section is only applicable to [lifecycle plugins](../advanced/lifecycle-plugins.mdx). **Exceptions** thrown by plugins during this phase will cause the server to shutdown before loading, as missing values or modifications to the registries would otherwise cause data loss. diff --git a/docs/paper/dev/getting-started/README.mdx b/docs/paper/dev/getting-started/README.mdx index 1f89bab23..85246f8df 100644 --- a/docs/paper/dev/getting-started/README.mdx +++ b/docs/paper/dev/getting-started/README.mdx @@ -1,7 +1,7 @@ import DocCardList from "@theme/DocCardList"; import { useCurrentSidebarCategory } from "@docusaurus/theme-common"; -# Development Guide +# Getting Started with Paper Development 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.mdx b/docs/paper/dev/getting-started/how-do-plugins-work.mdx index be0419d78..26ef8c384 100644 --- a/docs/paper/dev/getting-started/how-do-plugins-work.mdx +++ b/docs/paper/dev/getting-started/how-do-plugins-work.mdx @@ -13,6 +13,11 @@ loaded from a `.jar` file. Each plugin has a main class that is specified in th class must extend JavaPlugin, and is the entry point for the plugin and is where the plugin's lifecycle methods are defined. +## 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. + :::warning We do not recommend writing code inside your main class's constructor as there are no guarantees about what @@ -21,11 +26,6 @@ do not call your plugin's constructor directly. This will cause issues with your ::: -## Plugin lifecycle - -Plugins are loaded and unloaded at runtime. When a plugin is loaded, it is initialized and enabled. When a plugin is -unloaded, it is disabled and finalized. - ### Initialization When a plugin is loaded, it is initialized. This means that the plugin is loaded into memory and its `onLoad` diff --git a/docs/paper/dev/getting-started/project-setup.mdx b/docs/paper/dev/getting-started/project-setup.mdx index ecdb23024..b75a7efb4 100644 --- a/docs/paper/dev/getting-started/project-setup.mdx +++ b/docs/paper/dev/getting-started/project-setup.mdx @@ -226,7 +226,7 @@ You will be asked to provide some information about your project. | **Main Class** | The main class of your plugin. This should be the class that extends `JavaPlugin`. | | **Optional Settings** | Here you can define things like authors, website, description, etc. These are optional and not required for the plugin to work. | | **Build System** | The build system you want to use. Paper recommends using Gradle but you can use Maven if you prefer. | -| **Paper Manifest** | Whether you want to use the new Paper plugins or not. For now this is not recommended as it is still in development. | +| **Paper Manifest** | Whether you want your plugin to be a lifecycle plugin. Learn more about lifecycle plugins [here](../advanced/lifecycle-plugins.mdx) | | **Group ID** | The group ID of your project. This is used for Maven and Gradle. This is usually your domain name in reverse. If you don't know what you should put here, you can use something like `io.github.` or if you don't have GitHub you can use `me.`. | | **Artifact ID** | The artifact ID of your project. This is used for Maven and Gradle. This is usually the name of your project. This is usually the same as the `Name` field. | | **Version** | The version of your project. This is used for Maven and Gradle. This is usually `1.0-SNAPSHOT` and does not really matter for now. | @@ -245,7 +245,7 @@ This means that the server will have to deobfuscate and remap the plugin JAR whe :::info -`paperweight-userdev` already sets this attribute automatically. For more information see the [userdev](./userdev) documentation. +`paperweight-userdev` already sets this attribute automatically. For more information see the [userdev](./advanced/userdev) documentation. ::: diff --git a/docs/paper/dev/misc/databases.mdx b/docs/paper/dev/misc/databases.mdx index 3a8e86c64..378d6066f 100644 --- a/docs/paper/dev/misc/databases.mdx +++ b/docs/paper/dev/misc/databases.mdx @@ -120,8 +120,8 @@ 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 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) +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://gradleup.com/shadow/). +Alternatively, you can use the library loader with your lifecycle plugin to load the library at runtime. See [here](../../advanced/lifecycle-plugins#loaders) for more information on how to use this. ::: diff --git a/docs/paper/dev/misc/internal-code.mdx b/docs/paper/dev/misc/internal-code.mdx index ca0d4f81d..6e2a1b2e3 100644 --- a/docs/paper/dev/misc/internal-code.mdx +++ b/docs/paper/dev/misc/internal-code.mdx @@ -30,7 +30,7 @@ any time. In order to use Mojang and CraftBukkit code, you may either use the `paperweight-userdev` Gradle plugin or use reflection. [`paperweight-userdev`](https://github.com/PaperMC/paperweight-test-plugin) is the recommended way to access internal code as it is easier to use due to being able to have the remapped code in your IDE. You can find -out more about this in the [`paperweight-userdev`](/paper/dev/userdev) section. +out more about this in the [`paperweight-userdev`](/paper/dev/advanced/userdev) section. However, if you are unable to use `paperweight-userdev`, you can use reflection. @@ -77,7 +77,7 @@ it makes the code easier to understand. :::info[Mojang-mapped runtime as of 1.20.5] As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings. -For more information, see the [plugin remapping](./project-setup#plugin-remapping) section and [userdev](./userdev#1205-and-beyond) documentation covering these changes. +For more information, see the [plugin remapping](./project-setup#plugin-remapping) section and [userdev](./advanced/userdev#1205-and-beyond) documentation covering these changes. ::: diff --git a/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md b/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md index 90d3a02e3..bec83622c 100644 --- a/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md +++ b/docs/versioned/paper/content/1.19/admin/reference/paper-plugins.md @@ -29,7 +29,7 @@ Paper plugins are added the same as Bukkit plugins, therefore, you can follow [t ### Cyclic Plugin Loading With the introduction of Paper plugins, Paper introduces a new plugin loader that fixes some odd issues. -However, as a result, this now causes [cyclic loading](#cyclic-plugin-loading) between plugins to no longer be supported. +However, as a result, this now causes [cyclic loading](#cyclic-plugin-loading) between plugins to no longer be supported. ![Cyclic Loading](assets/cyclic-loading.png) @@ -45,7 +45,7 @@ If you would like to still load these plugins, acknowledging that there may be u Failed to start the minecraft server ``` -It is up to plugin developers to resolve these circular loading issues, however, you are able to use the legacy plugin loader if you +It is up to plugin developers to resolve these circular loading issues, however, you are able to use the legacy plugin loader if you absolutely are unable to resolve this loading loop. diff --git a/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md b/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md index 944017289..9bfc9459a 100644 --- a/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md +++ b/docs/versioned/paper/content/1.19/dev/getting-started/paper-plugins.md @@ -4,7 +4,7 @@ slug: /dev/getting-started/paper-plugins # Paper Plugins -Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to +Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to expand the field of what the Paper API is able to introduce. :::info[Experimental] @@ -38,7 +38,7 @@ loader: io.papermc.testplugin.TestPluginLoader Dependency declaration is specified a bit differently than Bukkit plugins, as you are able to define if a dependency is required during bootstrapping. This means that any bootstrapping -logic for your dependencies will be run before yours is run. +logic for your dependencies will be run before yours is run. ```yml dependencies: - name: DependencyName @@ -47,14 +47,14 @@ dependencies: ``` If a dependency is ``required`` it must be installed on the server or your plugin will fail to load. If marked otherwise, it will -ignore if the dependency isn't found. +ignore if the dependency isn't found. Otherwise, your plugin will be loaded fine, in the same fashion as a plugin that is a ``soft-depend`` in a Bukkit plugin.yml If a dependency is marked as ``bootstrap``, this indicates that this dependency is required during bootstrapping, which currently does not serve a purpose. :::note[Plugin Loading Order] -Note that [unlike Bukkit plugins](#load-order-logic-split), dependencies are independent of the plugin load order. +Note that [unlike Bukkit plugins](#load-order-logic-split), dependencies are independent of the plugin load order. This means that although declaring a dependency will give you access to its classes, if you require it to be initialised before your plugin is loaded, see how to [declare load order](#load-order-declaration). ::: @@ -68,17 +68,17 @@ you must set the ``bootstrap`` field to ``true``. :::note[Cyclic Loading] Note that in certain cases plugins may be able to introduce cyclic loading loops, which will prevent the server from starting. -Please read the [cyclic loading guide](docs/paper/admin/reference/paper-plugins.md#cyclic-plugin-loading) for more information. +Please read the [cyclic loading guide](docs/paper/admin/reference/lifecycle-plugins.md#cyclic-plugin-loading) for more information. ::: #### load-before -You are able to define a list of plugins that your plugin should load before. +You are able to define a list of plugins that your plugin should load before. ```yml load-before: - name: PluginName bootstrap: false ``` -This means that your plugin will load **before** ``PluginName`` is loaded. +This means that your plugin will load **before** ``PluginName`` is loaded. #### load-after You are then able to define a list of plugins that your plugin should load after. @@ -104,14 +104,14 @@ public class TestPluginBootstrap implements PluginBootstrap { @Override public void bootstrap(@NotNull PluginProviderContext context) { - + } @Override public @NotNull JavaPlugin createPlugin(@NotNull PluginProviderContext context) { return new TestPlugin("My custom parameter"); } - + } ``` A Bootstrapper allows you to also override how your plugin is initiated, allowing you to pass values into your plugin constructor. @@ -121,7 +121,7 @@ Currently, bootstrappers do not offer much new API, and are highly experimental. Paper plugins are able to identify their own plugin loader by implementing ``io.papermc.paper.plugin.loader.PluginLoader`` and adding the class of your implementation to the loader field in the ``paper-plugin.yml``. -The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into. +The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into. This, as of right now, only applies to creating the expected classpath for the plugin, e.g. supplying external libraries to the plugin. ```java public class TestPluginLoader implements PluginLoader { @@ -142,7 +142,7 @@ public class TestPluginLoader implements PluginLoader { Currently, you are able to add two different library types, ``JarLibrary``, and ``MavenLibraryResolver``. -## Differences +## Differences ### Bukkit Serialization System Paper plugins do not support the serialization system (``org.bukkit.configuration.serialization``) that Bukkit uses. Your classes will not be able to be @@ -153,7 +153,7 @@ Paper plugins have isolated classloaders, meaning that relocating dependencies w by depending on another plugin, etc. This prevents plugins from accidentally accessing your dependencies, and in general helps ensure that plugins are only able to access your plugin if they explicitly say that they're depending on it. -Paper plugins have the ability to bypass this, being able to access OTHER plugins classloaders by adding +Paper plugins have the ability to bypass this, being able to access OTHER plugins classloaders by adding ```yml has-open-classloader: true ``` diff --git a/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md b/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md index 52d527c09..90d16974b 100644 --- a/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md +++ b/docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md @@ -9,7 +9,7 @@ This documentation page serves to explain all the new semantics and possible con :::info -Developers can get more information on Paper plugins [here](docs/paper/dev/getting-started/paper-plugins.mdx). +Developers can get more information on Paper plugins [here](/paper/dev/advanced/lifecycle-plugins). ::: @@ -34,7 +34,7 @@ Paper plugins are added the same as Bukkit plugins, therefore, you can follow [t ### 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](/paper/dev/advanced/lifecycle-plugins#cyclic-plugin-loading) between plugins to no longer be supported. If Paper detects a loop, your server will be shut down with an error. diff --git a/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx b/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx index dd1fe591a..70e1a36d7 100644 --- a/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx +++ b/docs/versioned/paper/content/1.20/dev/misc/internal-code.mdx @@ -30,7 +30,7 @@ any time. In order to use Mojang and CraftBukkit code, you may either use the `paperweight-userdev` Gradle plugin or use reflection. [`paperweight-userdev`](https://github.com/PaperMC/paperweight-test-plugin) is the recommended way to access internal code as it is easier to use due to being able to have the remapped code in your IDE. You can find -out more about this in the [`paperweight-userdev`](/paper/dev/userdev) section. +out more about this in the [`paperweight-userdev`](userdev) section. However, if you are unable to use `paperweight-userdev`, you can use reflection.