How does Paperweight work?

I will try give an easy explanation of how Paperweight works, and especially how you will use it 99% of the time.

This is useful if you want to make your own Minecraft server implementation fork, or if you want to make pull requests for existing forks, like Gale.

Requirements beforehand

    ✔  You need to know how to open a command terminal and run commands

    ✔  You will need 6+ GB of free RAM

    ✔  You must have installed Java JDK 17 or higher

    ✔  You must have installed Git (or a Git client like GitHub Desktop, Sourcetree or IntelliJ IDEA).

    ✔  You need to know how to use Git.
           If you don't know Git, check out a tutorial online (for example this one).
           Specifically, you should know how to do an interactive rebase in Git: git rebase -i
           (Check out this video, for example)

Why use patches?

It is not legal to simply decompile the Minecraft server source code, throw it on a GitHub repository and start editing. So another method to do this was needed. The method the Paper developers decided on is: take the Minecraft server source code, make some modifications, and then only share the modifications on GitHub.

The easiest method to do that is using Git patches. A patch file is just a commit in file form. Normally, Git commits are hidden away in the .git folder somewhere where you should not tamper with it. But if you want to share a commit, you can let Git create a patch file for it, and someone else can then turn the patch file into a commit again on their side.

So, in Paper and its forks, the GitHub repository will only contain the patches for the modifications they want to make.

What does Paperweight do?

Editing patches by hand is not really possible. Paperweight is a piece of software that most importantly does the following 3 steps for you:

1. Automatically download and decompile Minecraft, and create a Git repository for it
2. Apply the Paper patch files to the Minecraft source code, each patch as a Git commit
3. After you have changed the source code and committed your changes: turn your commits into patch files again so you can share it (and make a pull request, for example)

Where is what?

In a Paperweight project (like Gale) you will notice there is the following folder structure:

Gale/
    patches/
        api/
        server/

Each of the api and server folders contains a bunch of .patch files. These patches are the modifications that the project makes to Minecraft:

• api contains changes to the Bukkit API
• server contains changes to the Minecraft server source.

After cloning the project, your usual first step is:

./gradlew applyPatches

This performs step 1 (getting the Minecraft source code) and step 2 (applying the patch files as commits) mentioned above.

Afterwards, you will have the following folders added:

Gale/
    gale-api/
    gale-server/

gale-api contains the full Bukkit API source code, and gale-server contains the full Minecraft server source code.

Now, if you check the Git history of gale-server (like with git log --oneline), the history will contain the patches like (in order from last applied to first applied):

<last Gale patch>
<Gale patch before that>
<another Gale patch>
...
<first Gale patch>
<last Paper patch>
<Paper patch before that>
...
<first Paper patch>
<last Spigot/Bukkit patch>
<Spigot patch before that>
...
<first Spigot/Bukkit patch>
<patch containing Minecraft vanilla code>

In other words, Paperweight has created a Git project that starts with a single commit adding the Minecraft source code, and then one by one all the changes that were made by Spigot/Bukkit, then Paper, and then Gale.

Now, you are free to make changes in the gale-api and gale-server folders. In between, you can run ./gradlew runDev in the Gale top folder to start a test server with your current code. You can use Git edit commands to edit the commit history (or just add new commits on top). Especially Git interactive rebasing (git rebase -i HEAD~50 to do something with the latest 50 commits) is very useful.

After making some changes and having committed them, run ./gradlew rebuildPatches in the Gale top folder, which replaces the content of the patches folder with new .patch files based on the updated list of commits in the gale-api and gale-server folders. Then, you can use git commit in the Gale top folder to commit your changes to the patch files and push your project to remote.

_{© Gale 2023}