feat: update for Paper 26.1 (#741)

Co-authored-by: Matouš Kučera <mk@kcra.me>

Author: Strokkur424

CONTRIBUTING.md

@@ -132,13 +132,15 @@ These constants can be imported and used in MDX, like so:
 import {
   LATEST_MC_RELEASE,
   LATEST_PAPER_RELEASE,
+  LATEST_PAPER_BUILD_API_VERSION,
   LATEST_VELOCITY_RELEASE,
   LATEST_FOLIA_RELEASE,
   LATEST_WATERFALL_RELEASE,
   LATEST_USERDEV_RELEASE,
 } from "/src/utils/versions";
 
 Latest Paper version is {LATEST_PAPER_RELEASE}.
+Latest Paper API build version is {LATEST_PAPER_BUILD_API_VERSION}
 Latest Velocity version is {LATEST_VELOCITY_RELEASE}.
 Latest Minecraft version is {LATEST_MC_RELEASE}.
 Latest Folia version is {LATEST_FOLIA_RELEASE}.

astro.config.ts

@@ -15,6 +15,7 @@ import {
   LATEST_ANSI_RELEASE,
   LATEST_FOLIA_RELEASE,
   LATEST_MC_RELEASE,
+  LATEST_PAPER_BUILD_API_VERSION,
   LATEST_PAPER_RELEASE,
   LATEST_USERDEV_RELEASE,
   LATEST_VELOCITY_RELEASE,
@@ -562,6 +563,7 @@ export default defineConfig({
           constants: {
             LATEST_MC_RELEASE,
             LATEST_PAPER_RELEASE,
+            LATEST_PAPER_BUILD_API_VERSION,
             LATEST_VELOCITY_RELEASE,
             LATEST_FOLIA_RELEASE,
             LATEST_WATERFALL_RELEASE,

src/content/docs/misc/java-install.md

@@ -1,6 +1,6 @@
 ---
 title: Installing or updating Java
-description: How to install or update to Java 21 on Linux (apt/rpm), Windows, or Mac.
+description: How to install or update to Java 25 on Linux (apt/rpm), Windows, or Mac.
 slug: misc/java-install
 ---
 
@@ -31,7 +31,7 @@ previous hostile licensing.
 
 ### Ubuntu/Debian
 
-Installing Java 21 on Debian-based Linux distributions is very simple. First, ensure your system has
+Installing Java 25 on Debian-based Linux distributions is very simple. First, ensure your system has
 all required tools to successfully install Java.
 
 ```bash
@@ -46,18 +46,18 @@ wget -O - https://apt.corretto.aws/corretto.key | sudo gpg --dearmor -o /usr/sha
 echo "deb [signed-by=/usr/share/keyrings/corretto-keyring.gpg] https://apt.corretto.aws stable main" | sudo tee /etc/apt/sources.list.d/corretto.list
 ```
 
-Then, install Java 21 and other dependencies using the following command:
+Then, install Java 25 and other dependencies using the following command:
 
 ```bash
 sudo apt-get update
-sudo apt-get install -y java-21-amazon-corretto-jdk libxi6 libxtst6 libxrender1
+sudo apt-get install -y java-25-amazon-corretto-jdk libxi6 libxtst6 libxrender1
 ```
 
 Proceed to [verify your installation](#verifying-installation).
 
 ### RPM-based
 
-To install Java 21 on CentOS, RHEL, Fedora, openSUSE, SLES, or any other RPM-based Linux
+To install Java 25 on CentOS, RHEL, Fedora, openSUSE, SLES, or any other RPM-based Linux
 distribution, execute the following commands depending on your package manager. Once you have
 finished, precede to [verify your installation](#verifying-installation).
 
@@ -68,7 +68,7 @@ DNF is used on Fedora, CentOS/RHEL 7+, and related distributions.
 ```bash
 sudo rpm --import https://yum.corretto.aws/corretto.key
 sudo curl -Lo /etc/yum.repos.d/corretto.repo https://yum.corretto.aws/corretto.repo
-sudo dnf -y install java-21-amazon-corretto-devel
+sudo dnf -y install java-25-amazon-corretto-devel
 ```
 
 #### Zypper
@@ -78,7 +78,7 @@ Zypper is used on openSUSE, SLES, and related distributions.
 ```bash
 sudo zypper addrepo https://yum.corretto.aws/corretto.repo
 sudo zypper refresh
-sudo zypper install java-21-amazon-corretto-devel
+sudo zypper install java-25-amazon-corretto-devel
 ```
 
 #### YUM
@@ -88,14 +88,14 @@ YUM is used on older releases of CentOS/RHEL, and excessively old releases of Fe
 ```bash
 sudo rpm --import https://yum.corretto.aws/corretto.key
 sudo curl -Lo /etc/yum.repos.d/corretto.repo https://yum.corretto.aws/corretto.repo
-sudo yum -y install java-21-amazon-corretto-devel
+sudo yum -y install java-25-amazon-corretto-devel
 ```
 
 ## Windows 10 & 11
 
 If you're on Windows 10 or 11, installing Java is just like installing any other program. Download
 the Amazon Corretto installer from
-[their website](https://corretto.aws/downloads/latest/amazon-corretto-21-x64-windows-jdk.msi).
+[their website](https://corretto.aws/downloads/latest/amazon-corretto-25-x64-windows-jdk.msi).
 
 Once you have run the installer, it is safe to click "next" through the whole process. No additional
 bloatware or toolbars will be installed, and all the required features are enabled out of the box.
@@ -109,7 +109,7 @@ If you're on macOS, the best way to manage Java installations is with a tool cal
 terminal run the following command:
 
 ```bash
-brew install openjdk@21
+brew install openjdk@25
 ```
 
 Once this command has completed, continue to [verify your installation](#verifying-installation).
@@ -129,36 +129,36 @@ prompt you to update like this:
 ![Pterodactyl Automatic Prompt](./assets/pterodactyl-prompt.png)
 
 If this does not show up for you, the Java version can be manually changed. Navigate to the
-"Startup" tab of your server, select `Java 21` from the "Docker Image"
+"Startup" tab of your server, select `Java 25` from the "Docker Image"
 dropdown as shown in the image below.
 
 ![Pterodactyl Manual Java Version Change](./assets/pterodactyl-manual.png)
 
 :::note
 
-If you don't see `Java 21` in the dropdown, an administrator account is required to update the Paper egg.
+If you don't see `Java 25` in the dropdown, an administrator account is required to update the Paper egg.
 
 :::
 
 The Verifying Installation section does not apply for Pterodactyl.
 
 ## Verifying installation
 
-Now that you have installed Java 21, run this command in your terminal to ensure the process was
+Now that you have installed Java 25, run this command in your terminal to ensure the process was
 successful.
 
 ```bash
 java -version
 ```
 
 The output should be similar to this. The important parts to look out for is that it starts with
-`openjdk 21` and contains `64-Bit` in the last line. If the output you get is similar to
+`openjdk 25` and contains `64-Bit` in the last line. If the output you get is similar to
 `java: command not found`, try creating a new terminal session.
 
 ```
-openjdk version "21" 2023-09-19 LTS
-OpenJDK Runtime Environment Corretto-21.0.0.35.1 (build 21+35-LTS)
-OpenJDK 64-Bit Server VM Corretto-21.0.0.35.1 (build 21+35-LTS, mixed mode, sharing)
+openjdk version "25" 2025-09-16
+OpenJDK Runtime Environment (build 25+36-3489)
+OpenJDK 64-Bit Server VM (build 25+36-3489, mixed mode, sharing)
 ```
 
 If your installation has failed, do not hesitate to reach out in the `#paper-help` channel of our

src/content/docs/paper/admin/getting-started/getting-started.mdx

@@ -8,7 +8,7 @@ slug: paper/getting-started
 
 :::tip
 
-Paper requires at least **Java 21** to run, which [is easy to download and install](/misc/java-install).
+Paper requires at least **Java 25** to run, which [is easy to download and install](/misc/java-install).
 
 :::
 

src/content/docs/paper/admin/getting-started/migration.md

@@ -16,33 +16,6 @@ See our [Backup Guide](/paper/updating#step-1-backup) for more information.
 
 ## Migrating to Paper
 
-### From CraftBukkit or Spigot
-
-It's easy to migrate from CraftBukkit or Spigot to Paper. Follow the steps below.
-
-1. Stop your server if it is running, and create a full backup.
-2. Download Paper from [our downloads page](https://papermc.io/downloads).
-3. Rename the downloaded file to match the name specified in the [start command](/paper/getting-started#running-the-server).
-4. Replace your existing JAR file with your freshly downloaded Paper JAR.
-5. Start your new server.
-
-Up until 1.20.5, Paper retained full compatibility with all Spigot plugins. However, plugins using Spigot API
-added **after** 1.20.5 version will not work. Such plugins may often provide Paper-compatible builds. If they
-do not do that, you will need to look for alternatives. However, nowadays most plugins are built and tested
-against Paper, so you typically will not encounter incompatible plugins.
-
-:::note
-
-Your new Paper server will still use [`bukkit.yml`](/paper/reference/bukkit-configuration)
-and [`spigot.yml`](/paper/reference/spigot-configuration).
-New configuration options can be found in [`config/paper-global.yml`](/paper/reference/global-configuration)
-and [`config/paper-world-defaults.yml`](/paper/reference/world-configuration).
-
-:::
-
-If you have any issues migrating from CraftBukkit or Spigot, do not hesitate to reach out for
-support on [our Discord server](https://discord.gg/papermc) (`#paper-help` channel).
-
 ### From Vanilla
 
 When migrating to Paper from Vanilla, the way worlds are stored will automatically be changed.
@@ -52,7 +25,8 @@ closely, as manual changes will be required.
 1. Stop your Vanilla server if it is running, and create a full backup.
 2. Download Paper from [our downloads page](https://papermc.io/downloads) and replace your Vanilla
    server JAR with your freshly downloaded Paper JAR.
-3. Rename the downloaded file to match the name specified in the [start command](/paper/getting-started#running-the-server).
+3. Rename the downloaded file to match the name specified in
+   the [start command](/paper/getting-started#running-the-server).
 4. Start your new Paper server.
 
 You have now successfully migrated to Paper. If you encounter any issues, do not hesitate to reach
@@ -69,10 +43,59 @@ Additionally, note that Paper does not support Fabric or Forge mods. You will ne
 replacements. Any hybrids that attempt to support both mods and plugins are fundamentally flawed and
 not recommended for use.
 
+### From Spigot/CraftBukkit
+
+Spigot and CraftBukkit modify the Vanilla world directory structure, making a direct migration as of `26.1`
+fundamentally impossible. If you wish to migrate from Spigot/CraftBukkit anyway, you will
+first need to **migrate from Spigot/CraftBukkit to Vanilla**, after which you can safely follow
+the [Vanilla Migration Guide](#from-vanilla). For instructions on how to do this, please
+refer to the Spigot documentation.
+
 ## Migrating from Paper
 
 ### To Vanilla
 
+Because Paper shares a similar world structure to Vanilla, all you need to do is move around some files.
+The following list shows which files you will need to move where. **Before you move around any files,
+make sure your server is fully stopped**.
+
+:::note
+
+These steps assume a `level-name` (as set in `server.properties`) of `world`. If this is not the
+case for you, replace `world` with your `level-name` for all steps below.
+
+:::
+
+The following files will need to be moved **from** `world/dimensions/minecraft/overworld/data/minecraft/`
+**into** `world/data/minecraft/`:
+
+- `game_rules.dat`
+- `scheduled_events.dat`
+- `wandering_trader.dat`
+- `weather.dat`
+- `world_gen_settings.dat`
+
+After you have moved these files, you can now replace the Paper server JAR with a Vanilla server JAR
+and start your Vanilla server!
+
+### To Fabric/Forge
+
+Because both Fabric and Forge use the same directory structure for world storage as Vanilla, follow
+the [Vanilla Migration Guide](#to-vanilla) for this process. Note that neither Fabric nor Forge will
+support Paper plugins! You will be required to find replacement mods.
+
+## Other Migration
+
+:::caution
+
+The guides below display outdated information no longer relevant for modern Paper servers. They are
+kept for historical purposes and people still using older versions. Please note that you will
+**not receive support for using outdated versions.**
+
+:::
+
+### To Vanilla (pre 26.1)
+
 Because Paper stores worlds slightly differently than Vanilla, manual work is required to migrate.
 If these steps are not taken, your nether and end will look like they have been reset. Don't worry!
 Even if this has happened, you haven't lost any data. The Vanilla server just doesn't know where to
@@ -81,7 +104,7 @@ find it.
 Here is a chart to show the difference between how Vanilla and Paper store worlds.
 
 | Server Software | Overworld | Nether                | End                   |
-| --------------- | --------- | --------------------- | --------------------- |
+|-----------------|-----------|-----------------------|-----------------------|
 | Vanilla         | `/world`  | `/world/DIM-1`        | `/world/DIM1`         |
 | Paper           | `/world`  | `/world_nether/DIM-1` | `/world_the_end/DIM1` |
 
@@ -106,12 +129,6 @@ case for you, replace `world` with your `level-name` for all steps below.
 
 ### To CraftBukkit or Spigot
 
-Paper does **not** support migration to either CraftBukkit or Spigot! While you may find success
-(both CraftBukkit and Spigot use the same directory structure as Paper), **do not** reach out for
+Paper does **not** support migration to either CraftBukkit or Spigot!
+While you may find success, **do not** reach out for
 support with issues you encounter and note that data loss is possible.
-
-### To Fabric/Forge
-
-Because both Fabric and Forge use the same directory structure for world storage as Vanilla, follow
-the [Vanilla Migration Guide](#to-vanilla) for this process. Note that neither Fabric nor Forge will
-support Paper plugins! You will be required to find replacement mods.