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/misc/faq.md

@@ -7,8 +7,31 @@ description: Questions frequently asked by our community, answered by us!
 
 ## Unsupported Java detected, what do I do?!
 
-Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken. 
+Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken.
 As such, we cannot provide support for servers running such versions.
 You should install a supported version of Java as explained [here](/misc/java-install).
 
 If you still wish to continue, knowing that you are on your own and will receive NO support, you can disable the check with a system property, as explained [here](/paper/reference/system-properties#paperignorejavaversion).
+
+## What is a Paper plugin?
+
+A Paper plugin is a plugin that is compiled against the Paper API.<br>
+Developers can find more info on how to get started writing Paper plugins [here](/paper/dev/getting-started).<br>
+Server Admins can learn how to find and install Paper plugins [here](/paper/adding-plugins).
+
+## What is a Spigot plugin?
+
+A Spigot plugin is a plugin that is compiled against the Spigot API.
+Most Spigot plugins are compatible with your Paper, but plugins that use Spigot API introduced after Minecraft 1.21.4 may not work correctly.
+
+## What is a Bukkit plugin?
+
+The term Bukkit plugin is a bit missleading. The Bukkit project died in 2014. The Bukkit API lives on in our fork of it, called Paper API.
+When people say Bukkit plugin, they most likely refer to a [Paper plugin](#what-is-a-paper-plugin).
+
+## What is a (Paper) lifecycle plugin? (formally known as experimental Paper plugins)
+
+Lifecycle plugins are special kinds of Paper plugins that use advanced features of the Paper API to hook into the server's lifecycle.
+They have been confusingly refered to as (experimental) Paper plugins or Paper manifest plugins before.<br>
+Server Admins can find more information [here](/paper/reference/lifecycle-plugins).<br>
+Plugin developers can learn how to write lifecycle plugins [here](/paper/dev/advanced/lifecycle-plugins).

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.