feat: rebrand "paper plugins" as "lifecycle plugins"

_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

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"],
+        },
       ],
     },
     {

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.

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

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.
+
+:::

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
 

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.
+
+---
+
+<DocCardList items={useCurrentSidebarCategory().items} />

docs/paper/dev/getting-started/paper-plugins.mdx → 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:
 <VersionFormattedCode language={"yaml"}>
@@ -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
 <Javadoc name={"io.papermc.paper.plugin.bootstrap.PluginBootstrap"}>`PluginBootstrap`</Javadoc>
 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
 <Javadoc name={"io.papermc.paper.plugin.loader.PluginLoader"}>`PluginLoader`</Javadoc>
 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 <Javadoc name={"org.bukkit.configuration.ConfigurationSection#getObject(java.lang.String,java.lang.Class)"}>`ConfigurationSection#getObject`</Javadoc>,
 you **must** call <Javadoc name={"org.bukkit.configuration.serialization.ConfigurationSerialization#registerClass(java.lang.Class)"}>`ConfigurationSerialization#registerClass(Class)`</Javadoc>
 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;

docs/paper/dev/getting-started/userdev.mdx → 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
 

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.

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.

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`