You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/paper/admin/getting-started/adding-plugins.md
+3-3
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@ slug: /adding-plugins
4
4
description: Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files.
5
5
---
6
6
7
-
# Adding Plugins
7
+
# Adding Plugins to your Paper Server
8
8
9
9
Plugins are the most powerful way to extend the functionality of Paper beyond the configuration
10
10
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
18
18
19
19
:::
20
20
21
-
## Finding plugins
21
+
## Finding Paper plugins for your server
22
22
23
23
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
24
24
on [SpigotMC](https://www.spigotmc.org/resources/),
@@ -35,7 +35,7 @@ mention Paper compatibility. It'll still work.
35
35
36
36
:::
37
37
38
-
## Installing plugins
38
+
## Installing plugins on your Paper server
39
39
40
40
1. Once you've found the plugin you'd like to install, download it. Ensure the file you have
41
41
downloaded ends in `.jar`. Some plugins also distribute as `.zip` files, in which case you will
Copy file name to clipboardexpand all lines: docs/paper/admin/misc/faq.md
+24-1
Original file line number
Diff line number
Diff line change
@@ -7,8 +7,31 @@ description: Questions frequently asked by our community, answered by us!
7
7
8
8
## Unsupported Java detected, what do I do?!
9
9
10
-
Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken.
10
+
Unsupported, early-access, or internal versions of Java are often missing features, have known issues or be straight up broken.
11
11
As such, we cannot provide support for servers running such versions.
12
12
You should install a supported version of Java as explained [here](/misc/java-install).
13
13
14
14
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).
15
+
16
+
## What is a Paper plugin?
17
+
18
+
A Paper plugin is a plugin that is compiled against the Paper API.<br>
19
+
Developers can find more info on how to get started writing Paper plugins [here](/paper/dev/getting-started).<br>
20
+
Server Admins can learn how to find and install Paper plugins [here](/paper/adding-plugins).
21
+
22
+
## What is a Spigot plugin?
23
+
24
+
A Spigot plugin is a plugin that is compiled against the Spigot API.
25
+
Most Spigot plugins are compatible with your Paper, but plugins that use Spigot API introduced after Minecraft 1.21.4 may not work correctly.
26
+
27
+
## What is a Bukkit plugin?
28
+
29
+
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.
30
+
When people say Bukkit plugin, they most likely refer to a [Paper plugin](#what-is-a-paper-plugin).
31
+
32
+
## What is a (Paper) lifecycle plugin? (formally known as experimental Paper plugins)
33
+
34
+
Lifecycle plugins are special kinds of Paper plugins that use advanced features of the Paper API to hook into the server's lifecycle.
35
+
They have been confusingly refered to as (experimental) Paper plugins or Paper manifest plugins before.<br>
36
+
Server Admins can find more information [here](/paper/reference/lifecycle-plugins).<br>
37
+
Plugin developers can learn how to write lifecycle plugins [here](/paper/dev/advanced/lifecycle-plugins).
description: A guide to the ins and outs of lifecycle plugins.
4
+
---
5
+
6
+
# Lifecycle Plugins
7
+
8
+
This documentation page serves to explain all the new semantics and possible confusions that lifecycle plugins may introduce.
9
+
10
+
:::info
11
+
12
+
Developers can get more information on lifecycle plugins [here](docs/paper/dev/advanced/lifecycle-plugins.mdx).
13
+
14
+
:::
15
+
16
+
## What are they?
17
+
18
+
Lifecycle plugins are plugins which are loaded by Paper's new plugin loading framework. Lifecycle plugins are used by developers to
19
+
take advantage of modern systems Mojang provides, for example, datapacks.
20
+
21
+
22
+
23
+
## What is the difference?
24
+
25
+
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
26
+
plugin is a traditional paper plugin or lifecycle plugin, they are both able to depend on each other just fine.
27
+
28
+
Lifecycle plugins only support being loaded by Paper's Plugin Loader and may use new API unavailable to Bukkit plugins.
29
+
30
+
### How do I add Lifecycle plugins?
31
+
32
+
Lifecycle plugins are added the same as traditional paper plugins, therefore, you can follow [this guide](docs/paper/admin/getting-started/adding-plugins.md).
33
+
34
+
### Cyclic plugin loading
35
+
36
+
With the introduction of lifecycle plugins, Paper introduces a new plugin loader that fixes some odd issues.
37
+
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.
38
+
39
+
If Paper detects a loop, your server will be shut down with an error.
40
+
41
+
:::danger[Legacy]
42
+
43
+
If your server **requires** this circular loading, you can enable this by adding the [`-Dpaper.useLegacyPluginLoading=true`](system-properties.md#paperuselegacypluginloading) startup flag.
44
+
Please note that this may not be supported in the future.
Copy file name to clipboardexpand all lines: docs/paper/admin/reference/system-properties.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -198,7 +198,7 @@ It also remaps plugin CB calls to remove the version information.
198
198
#### paper.useLegacyPluginLoading
199
199
200
200
-**default**: `false`
201
-
-**description**: Allows cyclic plugin loading. See [here](paper-plugins.md#cyclic-plugin-loading) for more info.
201
+
-**description**: Allows cyclic plugin loading. See [here](lifecycle-plugins.md#cyclic-plugin-loading) for more info.
202
202
203
203
#### Paper.DisableCommandConverter
204
204
@@ -213,7 +213,7 @@ It also remaps plugin CB calls to remove the version information.
213
213
#### paper.disablePluginRemapping
214
214
215
215
-**default**: `false`
216
-
-**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).
216
+
-**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).
Copy file name to clipboardexpand all lines: docs/paper/dev/advanced/lifecycle-plugins.mdx
+22-30
Original file line number
Diff line number
Diff line change
@@ -1,28 +1,25 @@
1
1
---
2
-
slug: /dev/getting-started/paper-plugins
3
-
description: A development guide for how to write Paper-specific plugins.
2
+
slug: /dev/advanced/lifecycle-plugins
3
+
description: A development guide for how to write lifecycle plugins.
4
4
---
5
5
6
-
# Paper Plugins (Experimental)
6
+
# Lifecycle Plugins
7
7
8
-
Paper plugins allow developers to take advantage of more modern concepts introduced by Mojang, such as datapacks, to
9
-
expand the field of what the Paper API is able to introduce.
10
-
11
-
:::danger[Experimental]
12
-
13
-
This is experimental and may be subject to change.
14
-
15
-
:::
8
+
## What is it used for?
9
+
Lifecycle plugins, as the name suggests, allow developers to have more control over their plugins lifecycle.
10
+
This is required to take advantage of some of the more modern concepts introduced by Mojang, such as datapacks.
11
+
Lifecycle plugins allow us to do just that by defining a new way to load plugin resources before the server
12
+
has started in form of [bootstrappers](#bootstrapper).
16
13
17
14
-[Bootstrapper](#bootstrapper)
18
15
-[Loader](#loaders)
19
16
-[Differences](#differences)
20
17
21
18
## How do I use them?
22
-
Similarly to Bukkit plugins, you have to introduce a `paper-plugin.yml` file into your JAR resources folder.
19
+
Similarly to traditional paper plugins, you have to introduce a `paper-plugin.yml` file into your JAR resources folder.
23
20
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.
24
21
25
-
It should be noted that you still have the ability to include both `paper-plugin.yml` and `plugin.yml` in the same JAR.
22
+
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.
and adding the class of your implementation to the loader field in the `paper-plugin.yml`.
137
129
@@ -159,40 +151,40 @@ Currently, you are able to add two different library types:
159
151
## Differences
160
152
161
153
### Bukkit serialization system
162
-
Paper plugins still support the serialization system (`org.bukkit.configuration.serialization`) that Bukkit uses. However, custom classes will not be
154
+
Lifecycle plugins still support the serialization system (`org.bukkit.configuration.serialization`) that Bukkit uses. However, custom classes will not be
163
155
automatically registered for serialization. In order to use <Javadoc name={"org.bukkit.configuration.ConfigurationSection#getObject(java.lang.String,java.lang.Class)"}>`ConfigurationSection#getObject`</Javadoc>,
164
156
you **must** call <Javadoc name={"org.bukkit.configuration.serialization.ConfigurationSerialization#registerClass(java.lang.Class)"}>`ConfigurationSerialization#registerClass(Class)`</Javadoc>
165
157
before you attempt to fetch objects from configurations.
166
158
167
159
### Classloading isolation
168
-
Paper plugins are not able to access each other unless given explicit access by depending on another plugin, etc. This
169
-
helps prevent Paper plugins from accidentally accessing each other's dependencies, and in general helps ensure that
160
+
Lifecycle plugins are not able to access each other unless given explicit access by depending on another plugin, etc. This
161
+
helps prevent Lifecycle plugins from accidentally accessing each other's dependencies, and in general helps ensure that
170
162
plugins are only able to access what they explicitly depend on.
171
163
172
-
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`.
164
+
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`.
173
165
174
166
```yml
175
167
Plugin:
176
168
join-classpath: true # Means you have access to their classpath
177
169
```
178
170
179
-
Note, other Paper plugins will still be unable to access your classloader.
171
+
Note, other Lifecycle plugins will still be unable to access your classloader.
180
172
181
173
### Load order logic split
182
-
In order to better take advantage of classloading isolation, Paper plugins do **not** use the `dependencies` field to determine load order.
174
+
In order to better take advantage of classloading isolation, Lifecycle plugins do **not** use the `dependencies` field to determine load order.
183
175
This was done for a variety of reasons, mostly to allow better control and allow plugins to properly share classloaders.
184
176
185
177
See [declaring dependencies](#dependency-declaration) for more information on how to declare the load order of your plugin.
186
178
187
179
### Commands
188
-
Paper plugins do not use the `commands` field to register commands. This means that you do not need to include all
180
+
Lifecycle plugins do not use the `commands` field to register commands. This means that you do not need to include all
189
181
of your commands in the `paper-plugin.yml` file. Instead, you can register commands using the
Copy file name to clipboardexpand all lines: docs/paper/dev/advanced/userdev.mdx
+5-5
Original file line number
Diff line number
Diff line change
@@ -1,13 +1,13 @@
1
1
---
2
-
slug: /dev/userdev
3
-
sidebar_label: Paperweight Userdev
2
+
slug: /dev/advanced/userdev
3
+
sidebar_label: Accessing Internals (NMS, Userdev)
4
4
description: A guide on how to use the paperweight-userdev Gradle plugin to access internal code.
5
5
---
6
6
7
-
# paperweight-userdev
7
+
# Accessing Internals (NMS, Userdev)
8
8
9
-
**paperweight**is the name of Paper's custom build tooling. The **paperweight-userdev** Gradle plugin part of that
10
-
provides access to internal code (also known as NMS) during development.
9
+
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).
10
+
This guide will show you how to use the **paperweight-userdev** Gradle plugin to access internal code during development.
Copy file name to clipboardexpand all lines: docs/paper/dev/getting-started/project-setup.mdx
+2-2
Original file line number
Diff line number
Diff line change
@@ -226,7 +226,7 @@ You will be asked to provide some information about your project.
226
226
|**Main Class**| The main class of your plugin. This should be the class that extends `JavaPlugin`. |
227
227
|**Optional Settings**| Here you can define things like authors, website, description, etc. These are optional and not required for the plugin to work. |
228
228
|**Build System**| The build system you want to use. Paper recommends using Gradle but you can use Maven if you prefer. |
229
-
|**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.|
229
+
|**Paper Manifest**| Whether you want your plugin to be a lifecycle plugin. Learn more about lifecycle plugins [here](../advanced/lifecycle-plugins.mdx)|
230
230
|**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.<yourname>` or if you don't have GitHub you can use `me.<yourname>`. |
231
231
|**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. |
232
232
|**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
245
245
246
246
:::info
247
247
248
-
`paperweight-userdev` already sets this attribute automatically. For more information see the [userdev](./userdev) documentation.
248
+
`paperweight-userdev` already sets this attribute automatically. For more information see the [userdev](./advanced/userdev) documentation.
Copy file name to clipboardexpand all lines: docs/paper/dev/misc/databases.mdx
+2-2
Original file line number
Diff line number
Diff line change
@@ -120,8 +120,8 @@ dependencies {
120
120
121
121
:::caution
122
122
123
-
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/).
124
-
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)
123
+
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/).
124
+
Alternatively, you can use the library loader with your lifecycle plugin to load the library at runtime. See [here](../../advanced/lifecycle-plugins#loaders)
Copy file name to clipboardexpand all lines: docs/paper/dev/misc/internal-code.mdx
+2-2
Original file line number
Diff line number
Diff line change
@@ -30,7 +30,7 @@ any time.
30
30
In order to use Mojang and CraftBukkit code, you may either use the `paperweight-userdev` Gradle plugin or use reflection.
31
31
[`paperweight-userdev`](https://github.com/PaperMC/paperweight-test-plugin) is the recommended way to access internal code
32
32
as it is easier to use due to being able to have the remapped code in your IDE. You can find
33
-
out more about this in the [`paperweight-userdev`](/paper/dev/userdev) section.
33
+
out more about this in the [`paperweight-userdev`](/paper/dev/advanced/userdev) section.
34
34
35
35
However, if you are unable to use `paperweight-userdev`, you can use reflection.
36
36
@@ -77,7 +77,7 @@ it makes the code easier to understand.
77
77
:::info[Mojang-mapped runtime as of 1.20.5]
78
78
79
79
As of 1.20.5, Paper ships with a Mojang-mapped runtime instead of reobfuscating the server to Spigot mappings.
80
-
For more information, see the [plugin remapping](./project-setup#plugin-remapping) section and [userdev](./userdev#1205-and-beyond) documentation covering these changes.
80
+
For more information, see the [plugin remapping](./project-setup#plugin-remapping) section and [userdev](./advanced/userdev#1205-and-beyond) documentation covering these changes.
Dependency declaration is specified a bit differently than Bukkit plugins, as you are
40
40
able to define if a dependency is required during bootstrapping. This means that any bootstrapping
41
-
logic for your dependencies will be run before yours is run.
41
+
logic for your dependencies will be run before yours is run.
42
42
```yml
43
43
dependencies:
44
44
- name: DependencyName
@@ -47,14 +47,14 @@ dependencies:
47
47
```
48
48
49
49
If a dependency is ``required`` it must be installed on the server or your plugin will fail to load. If marked otherwise, it will
50
-
ignore if the dependency isn't found.
50
+
ignore if the dependency isn't found.
51
51
Otherwise, your plugin will be loaded fine, in the same fashion as a plugin that is a ``soft-depend`` in a Bukkit plugin.yml
52
52
53
53
If a dependency is marked as ``bootstrap``, this indicates that this dependency is required during bootstrapping, which currently does not serve a purpose.
54
54
55
55
:::note[Plugin Loading Order]
56
56
57
-
Note that [unlike Bukkit plugins](#load-order-logic-split), dependencies are independent of the plugin load order.
57
+
Note that [unlike Bukkit plugins](#load-order-logic-split), dependencies are independent of the plugin load order.
58
58
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).
59
59
:::
60
60
@@ -68,17 +68,17 @@ you must set the ``bootstrap`` field to ``true``.
68
68
:::note[Cyclic Loading]
69
69
70
70
Note that in certain cases plugins may be able to introduce cyclic loading loops, which will prevent the server from starting.
71
-
Please read the [cyclic loading guide](docs/paper/admin/reference/paper-plugins.md#cyclic-plugin-loading) for more information.
71
+
Please read the [cyclic loading guide](docs/paper/admin/reference/lifecycle-plugins.md#cyclic-plugin-loading) for more information.
72
72
:::
73
73
74
74
#### load-before
75
-
You are able to define a list of plugins that your plugin should load before.
75
+
You are able to define a list of plugins that your plugin should load before.
76
76
```yml
77
77
load-before:
78
78
- name: PluginName
79
79
bootstrap: false
80
80
```
81
-
This means that your plugin will load **before** ``PluginName`` is loaded.
81
+
This means that your plugin will load **before** ``PluginName`` is loaded.
82
82
83
83
#### load-after
84
84
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 {
104
104
105
105
@Override
106
106
public void bootstrap(@NotNull PluginProviderContext context) {
107
-
107
+
108
108
}
109
109
110
110
@Override
111
111
public @NotNull JavaPlugin createPlugin(@NotNull PluginProviderContext context) {
112
112
return new TestPlugin("My custom parameter");
113
113
}
114
-
114
+
115
115
}
116
116
```
117
117
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.
121
121
Paper plugins are able to identify their own plugin loader by implementing ``io.papermc.paper.plugin.loader.PluginLoader`` and adding
122
122
the class of your implementation to the loader field in the ``paper-plugin.yml``.
123
123
124
-
The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into.
124
+
The goal of the plugin loader is the creation of an expected/dynamic environment for the plugin to load into.
125
125
This, as of right now, only applies to creating the expected classpath for the plugin, e.g. supplying external libraries to the plugin.
@@ -142,7 +142,7 @@ public class TestPluginLoader implements PluginLoader {
142
142
Currently, you are able to add two different library types, ``JarLibrary``, and ``MavenLibraryResolver``.
143
143
144
144
145
-
## Differences
145
+
## Differences
146
146
147
147
### Bukkit Serialization System
148
148
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
153
153
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
154
154
if they explicitly say that they're depending on it.
155
155
156
-
Paper plugins have the ability to bypass this, being able to access OTHER plugins classloaders by adding
156
+
Paper plugins have the ability to bypass this, being able to access OTHER plugins classloaders by adding
Copy file name to clipboardexpand all lines: docs/versioned/paper/content/1.20/admin/reference/paper-plugins.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -9,7 +9,7 @@ This documentation page serves to explain all the new semantics and possible con
9
9
10
10
:::info
11
11
12
-
Developers can get more information on Paper plugins [here](docs/paper/dev/getting-started/paper-plugins.mdx).
12
+
Developers can get more information on Paper plugins [here](/paper/dev/advanced/lifecycle-plugins).
13
13
14
14
:::
15
15
@@ -34,7 +34,7 @@ Paper plugins are added the same as Bukkit plugins, therefore, you can follow [t
34
34
### Cyclic plugin loading
35
35
36
36
With the introduction of Paper plugins, Paper introduces a new plugin loader that fixes some odd issues.
37
-
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.
37
+
However, as a result, this now causes [cyclic loading](/paper/dev/advanced/lifecycle-plugins#cyclic-plugin-loading) between plugins to no longer be supported.
38
38
39
39
If Paper detects a loop, your server will be shut down with an error.
0 commit comments