Skip to content

Commit b051389

Browse files
authored
chore: increment paper version (#424)
1 parent 99acf2e commit b051389

File tree

78 files changed

+6401
-1
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

78 files changed

+6401
-1
lines changed

docs/versioned/paper.json

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
[
2+
"1.20",
23
"1.19",
34
"1.18"
45
]
Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
import DocCardList from "@theme/DocCardList";
2+
3+
# Welcome to the Paper Docs
4+
5+
Paper is a high performance fork of Spigot that aims to fix gameplay and
6+
mechanic inconsistencies as well as to improve performance. Paper contains numerous features, bug
7+
fixes, exploit preventions and major performance improvements not found in Spigot.
8+
9+
---
10+
11+
<DocCardList items={[
12+
{
13+
"type": "link",
14+
"label": "Administration",
15+
"href": "/paper/admin",
16+
"customEmoji": "mdi:account-cog",
17+
},
18+
{
19+
"type": "link",
20+
"label": "Development",
21+
"href": "/paper/dev",
22+
"customEmoji": "mdi:code-braces",
23+
},
24+
{
25+
"type": "link",
26+
"label": "Contributing",
27+
"href": "/paper/contributing",
28+
"customEmoji": "mdi:comment-edit",
29+
},
30+
]}/>
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
slug: /admin
3+
---
4+
5+
import DocCardList from "@theme/DocCardList";
6+
import { useCurrentSidebarCategory } from "@docusaurus/theme-common";
7+
8+
# Paper Administration Guide
9+
10+
Welcome to the Paper administration guide! This guide includes information and tutorials
11+
regarding the administration of a Paper server.
12+
13+
---
14+
15+
<DocCardList items={useCurrentSidebarCategory().items} />
Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
---
2+
toc_max_heading_level: 4
3+
slug: /adding-plugins
4+
description: Plugins are the most powerful way to extend the functionality of Paper beyond the configuration files.
5+
---
6+
7+
# Adding Plugins
8+
9+
Plugins are the most powerful way to extend the functionality of Paper beyond the configuration
10+
files. Functionality added by plugins can range from making milk restore hunger or dead bushes grow,
11+
to adding entirely new and original game modes or items.
12+
13+
:::danger[Malicious Plugins]
14+
15+
Ensure you fully trust the source of any plugin before installing it. Plugins are given **full and
16+
unrestricted** access to not only your server but also the machine that it runs on. Because of this,
17+
it is imperative that plugins only be installed from trusted sources. Be careful!
18+
19+
:::
20+
21+
## Finding plugins
22+
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+
on [SpigotMC](https://www.spigotmc.org/resources/),
25+
[BukkitDev](https://dev.bukkit.org/bukkit-plugins), or the
26+
[PaperMC Forums](https://forums.papermc.io/forums/paper-plugin-releases/), while other plugins may
27+
release on [GitHub](https://github.com). One of the best ways to find plugins isn't to browse any of
28+
these sites directly but to search for plugins using a search engine. Searching for the function you
29+
desire followed by `Minecraft plugin` will often yield good results.
30+
31+
:::tip[Spigot and Bukkit Plugins]
32+
33+
Paper is compatible with both Spigot and Bukkit plugins. It's okay if a plugin does not explicitly
34+
mention Paper compatibility. It'll still work.
35+
36+
:::
37+
38+
## Installing plugins
39+
40+
1. Once you've found the plugin you'd like to install, download it. Ensure the file you have
41+
downloaded ends in `.jar`. Some plugins also distribute as `.zip` files, in which case you will
42+
need to extract the file and locate the `.jar` for your platform, often labelled `bukkit` or
43+
`paper`.
44+
2. Once you have the plugin downloaded locally, locate the `plugins` folder from the root directory
45+
of your Paper server.
46+
3. Drag and drop the plugin file (`.jar`) into the `plugins` folder. If you are using a shared
47+
hosting service, you may need to use their web panel or SFTP to upload the plugin; however, the
48+
procedure will be the same.
49+
4. Restart your server. The plugin should load.
50+
5. Check your work. Once the server has finished loading, run the `/plugins` command in-game or type
51+
`plugins` into the console. You should see your freshly installed plugin listed in green. If it
52+
is not listed or is colored red, continue to [troubleshooting](#troubleshooting). A plugin listed
53+
in red means that it is not currently enabled. For a freshly installed plugin, this often means
54+
that the plugin failed to load.
55+
56+
## Troubleshooting
57+
58+
### Check your logs
59+
60+
The first step to troubleshooting installing plugins is to check the log of your server. Your
61+
server's most recent logs will be stored to the `logs/latest.log` file. You may need to scroll near
62+
the beginning of this file to see when plugins were loaded.
63+
64+
#### Missing dependencies
65+
66+
If you see something like this:
67+
68+
```log
69+
[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins'
70+
[00:00:00] [Server thread/WARN] org.bukkit.plugin.UnknownDependencyException: Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'.
71+
```
72+
73+
This means that the plugin you tried to install is missing a dependency. A dependency, in this case,
74+
is another plugin that you must install for the first to function. While you will get a big scary
75+
error, the important line to look at is:
76+
77+
```log
78+
[00:00:00] [Server thread/WARN] Unknown/missing dependency plugins: [Vault]. Please download and install these plugins to run 'MyAwesomePlugin'.
79+
```
80+
81+
This is telling you that in order to load `MyAwesomePlugin`, you must first install `Vault`.
82+
83+
#### Invalid `plugin.yml`
84+
85+
If you see something closer to this:
86+
87+
```log
88+
[00:00:00] [Server thread/WARN] Could not load 'plugins/MyAwesomePlugin-1.0.0.jar' in folder 'plugins'
89+
[00:00:00] [Server thread/WARN] org.bukkit.plugin.InvalidDescriptionException: Invalid plugin.yml
90+
```
91+
92+
This means that what you have downloaded isn't a valid Paper plugin. This is generally caused by one
93+
of the following:
94+
95+
1. The plugin you downloaded isn't a plugin at all, but instead a mod for Forge, Fabric, or similar.
96+
These will not run on Paper.
97+
2. The plugin failed to download completely. Especially when using tools such as `curl` or `wget`,
98+
you can easily download error pages rather than the plugin you intended. This may also be caused
99+
by a network issue. Attempt to download the plugin again. If you are using FTP (not SFTP or a web
100+
panel) to upload your plugin to a shared hosting service, ensure your FTP client is in `binary`
101+
and not `ASCII` mode. Consult the documentation for your FTP client for details.
102+
103+
#### Ambiguous plugin name
104+
105+
If you see something like this:
106+
107+
```log
108+
[00:00:00] [Server thread/WARN] Ambiguous plugin name `Essentials' for files `plugins/EssentialsX-2.19.4.jar' and `plugins/Essentialsx-2.20.0-dev.jar' in `plugins'
109+
```
110+
111+
This means you have two plugins with the same name, which is not supported. In this case, two
112+
versions of EssentialsX are installed. Both the release `2.19.4`, and a development build of
113+
`2.20.0`. Ensure you only have one version of each plugin installed at one time. Delete the older
114+
version of the duplicate plugin, and restart your server.
115+
116+
To prevent accidentally installing two versions of one plugin while updating, you can use
117+
the `update` folder as described in the [Update Guide](/paper/updating#step-2-update-plugins).
118+
119+
#### Something else
120+
121+
If you see an error, but it isn't similar to one of the above, attempt to read it yourself. While
122+
the full error may be large and scary, you likely only have to read the first one or two lines to
123+
understand what is going on. If you're not sure, do not hesitate to reach out for support on our
124+
[Discord](https://discord.gg/papermc) in the `#paper-help` channel.
125+
126+
### If nothing is logged
127+
128+
If nothing is logged, your server is likely not attempting to load any plugins. The conditions
129+
needed for the server to load a plugin are as follows:
130+
131+
1. The file is at the root of the `plugins` folder, relative to its working directory. This is
132+
usually the same folder as the server JAR file. **Subdirectories of the `plugins` folder will not
133+
be checked.** All plugins must be in the root folder.
134+
2. The file ends in `.jar`. If your plugin does not end in `.jar`, what you have downloaded may not
135+
be a plugin. Note that some plugins distribute multiple JARs as `.zip` files. If this is the
136+
case, you have to extract them before installing the plugin.
137+
138+
If both of these are true, and you still see no logs, please reach out for support on our
139+
[Discord](https://discord.gg/papermc) server in the `#paper-help` channel. We will be happy to
140+
assist you.
260 KB
Loading
Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
slug: /getting-started
3+
description: How to get started with downloading and setting up a Paper server.
4+
---
5+
6+
# Getting Started
7+
8+
## Requirements
9+
10+
:::tip
11+
12+
Paper requires at least **Java <Property name="PAPER_JAVA_MIN" />** to run, which [is easy to download and install](/misc/java-install).
13+
14+
:::
15+
16+
| Paper Version | Recommended Java Version |
17+
|----------------|-----------------------------------------|
18+
| 1.8 to 1.11 | Java 8 |
19+
| 1.12 to 1.16.4 | Java 11 |
20+
| 1.16.5 | Java 16 |
21+
| 1.17.1-1.18.1+ | Java <Property name="PAPER_JAVA_MIN" /> |
22+
23+
## Downloading Paper
24+
25+
Paper provides runnable server JARs directly from our
26+
[website's downloads page](https://papermc.io/downloads).
27+
28+
Click on the build number to download a file.
29+
30+
## Running the server
31+
32+
To run the server you will need to either create a startup script
33+
or run a command in your terminal.
34+
35+
You can generate a startup script using our [Startup Script Generator](/misc/tools/start-script-gen).
36+
You can also obtain the optimized terminal command to run the server there.
37+
38+
If you're just looking for a short command:
39+
```bash
40+
java -Xms4G -Xmx4G -jar paper.jar --nogui
41+
```
42+
Ensure you navigated your terminal to the directory of your server
43+
and that you have replaced `paper.jar` with the name of the JAR you have downloaded.
44+
45+
The amount of RAM can be set by changing the numbers in the `Xmx` and `Xms` arguments.
46+
`--nogui` disables Vanilla's GUI, so you don't get double interfaces when using the command line.
47+
48+
To configure your server, see the [Global Configuration](../reference/configuration/global-configuration.mdx) and
49+
[Per World Configuration](../reference/configuration/world-configuration.mdx) pages.
50+
51+
## Updating the server
52+
53+
Updating Paper is simple! See our [Update Tutorial](../how-to/update.md) for more information.
54+
55+
## Migrating to Paper
56+
57+
### From Vanilla
58+
59+
Migrating from Vanilla is easy, but there are some differences, namely in world saves. Paper (and
60+
CraftBukkit and Spigot) separate out each dimension of a world (nether, the end, etc.) into separate
61+
world folders.
62+
63+
Paper will handle this conversion for you automatically. No additional consideration is required.
64+
65+
### From CraftBukkit or Spigot
66+
67+
Paper is a drop in replacement for both CraftBukkit and Spigot, you don't need to make any changes.
68+
69+
## Next steps
70+
71+
Take a look at our [Next Steps](/paper/next-steps) guide to get your server up and running with the best performance and
72+
features.
Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
slug: /migration
3+
title: Migrating to or from Paper
4+
description: It's simple to migrate your server to or from Paper. This page will help you get started.
5+
---
6+
7+
It's simple to migrate your server to or from Paper. The steps below will help you get started.
8+
9+
:::caution[Backup your data before you start!]
10+
11+
Before you begin, please ensure you have a full backup of your server.
12+
13+
See our [Backup Guide](/paper/updating#step-1-backup) for more information.
14+
15+
:::
16+
17+
## Migrating to Paper
18+
19+
### From CraftBukkit or Spigot
20+
21+
It's easy to migrate from CraftBukkit or Spigot to Paper. Follow the steps below.
22+
23+
1. Stop your server if it is running, and create a full backup.
24+
2. Download Paper from [our downloads page](https://papermc.io/downloads).
25+
3. Rename the downloaded file to match the name specified in the [start command](getting-started.mdx#running-the-server).
26+
4. Replace your existing JAR file with your freshly downloaded Paper JAR.
27+
5. Start your new server.
28+
29+
Paper retains full compatibility with all Spigot plugins, allowing a seamless transition.
30+
31+
:::info
32+
33+
Your new Paper server will still use [`bukkit.yml`](../reference/configuration/bukkit-configuration.mdx)
34+
and [`spigot.yml`](../reference/configuration/spigot-configuration.mdx).
35+
New configuration options can be found in [`config/paper-global.yml`](../reference/configuration/global-configuration.mdx)
36+
and [`config/paper-world-defaults.yml`](../reference/configuration/world-configuration.mdx).
37+
38+
:::
39+
40+
If you have any issues migrating from CraftBukkit or Spigot, do not hesitate to reach out for
41+
support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel).
42+
43+
### From Vanilla
44+
45+
When migrating to Paper from Vanilla, the way worlds are stored will automatically be changed.
46+
Should you ever want to go back to Vanilla, follow the [Vanilla Migration Guide](#to-vanilla)
47+
closely, as manual changes will be required.
48+
49+
1. Stop your Vanilla server if it is running, and create a full backup.
50+
2. Download Paper from [our downloads page](https://papermc.io/downloads) and replace your Vanilla
51+
server JAR with your freshly downloaded Paper JAR.
52+
3. Rename the downloaded file to match the name specified in the [start command](getting-started.mdx#running-the-server).
53+
4. Start your new Paper server.
54+
55+
You have now successfully migrated to Paper. If you encounter any issues, do not hesitate to reach
56+
out for support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel).
57+
58+
### From Fabric/Forge
59+
60+
Because both Fabric and Forge use the Vanilla world directory structure, the same steps as the
61+
[Vanilla Migration Guide](#from-vanilla) may be used, with one caveat. If your Fabric or Forge
62+
server used mods that added new blocks, items, or other data to the game, Paper will be unable to
63+
load these features.
64+
65+
Additionally, note that Paper does not support Fabric or Forge mods. You will need to find plugin
66+
replacements. Any hybrids that attempt to support both mods and plugins are fundamentally flawed and
67+
not recommended for use.
68+
69+
## Migrating from Paper
70+
71+
### To Vanilla
72+
73+
Because Paper stores worlds slightly differently than Vanilla, manual work is required to migrate.
74+
If these steps are not taken, your nether and end will look like they have been reset. Don't worry!
75+
Even if this has happened, you haven't lost any data. The Vanilla server just doesn't know where to
76+
find it.
77+
78+
Here is a chart to show the difference between how Vanilla and Paper store worlds.
79+
80+
| Server Software | Overworld | Nether | End |
81+
| --------------- | --------- | --------------------- | --------------------- |
82+
| Vanilla | `/world` | `/world/DIM-1` | `/world/DIM1` |
83+
| Paper | `/world` | `/world_nether/DIM-1` | `/world_the_end/DIM1` |
84+
85+
Follow these steps to migrate from Paper to Vanilla:
86+
87+
:::note
88+
89+
These steps assume a `level-name` (as set in `server.properties`) of `world`. If this is not the
90+
case for you, replace `world` with your `level-name` for all steps below.
91+
92+
:::
93+
94+
1. Stop your Paper server, if it is running.
95+
2. If you have already started your server with Vanilla, enter the `world` folder and delete both
96+
the `DIM-1` and `DIM1` folders. This step is only necessary should you have started your server
97+
with Vanilla.
98+
3. Copy the `/world_nether/DIM-1` folder into the `/world` folder.
99+
4. Copy the `/world_the_end/DIM1` folder into the `/world` folder.
100+
5. Delete both the `/world_nether` and `/world_the_end` folders.
101+
6. Replace your Paper JAR with a Vanilla server JAR.
102+
7. Start your Vanilla server.
103+
104+
### To CraftBukkit or Spigot
105+
106+
Paper does **not** support migration to either CraftBukkit or Spigot! While you may find success
107+
(both CraftBukkit and Spigot use the same directory structure as Paper), **do not** reach out for
108+
support with issues you encounter and note that data loss is possible.
109+
110+
### To Fabric/Forge
111+
112+
Because both Fabric and Forge use the same directory structure for world storage as Vanilla, follow
113+
the [Vanilla Migration Guide](#to-vanilla) for this process. Note that neither Fabric nor Forge will
114+
support Paper plugins! You will be required to find replacement mods.

0 commit comments

Comments
 (0)