Creating and Modifying Patches

Guide to working with Paper’s patch system

Paper uses a patch-based system for modifying Minecraft source files. This guide explains how to create and modify patches effectively.

Understanding Patch Types

Paper uses three types of patches:

• sources: Per-file patches to Minecraft Java classes
• resources: Per-file patches to Minecraft data files
• features: Larger patches that modify multiple Minecraft classes for complex features

Feature patches are used for large-scale changes that can be optionally dropped during Minecraft updates. This makes updating Paper easier since these patches can be temporarily removed and reapplied later.

Modifying Per-File Minecraft Patches

This is the most common workflow when editing Minecraft files.

1. Make Your Changes

   Edit the files in paper-server/src/minecraft as needed.

2. Fixup Source Patches

   Run the fixup command from the root directory:

   ./gradlew fixupSourcePatches
   

   This automatically updates the per-file patches based on your changes.

3. Rebuild Patches

   If the fixup succeeded without conflicts, rebuild all patches:

   ./gradlew rebuildPatches
   

Resolving Rebase Conflicts

If fixupSourcePatches encounters conflicts, you’ll need to manually resolve them:

1. Stash Your Changes (Optional)

   If you have uncommitted changes you want to preserve:

   git stash
   

   You can restore your changes later with git stash pop.

2. Start Interactive Rebase

   Navigate to the minecraft directory and start an interactive rebase:

   cd paper-server/src/minecraft/java
   git rebase -i base
   

   If you’re unfamiliar with vim (the default editor), press :q! and Enter to exit. Then run export EDITOR=nano before trying again for an easier editor.

3. Mark Commit for Editing

   In the editor, replace pick with edit for the commit you want to modify (typically the first commit, paper File Patches). Save and close the editor.

4. Make Your Changes

   Edit the files as needed to resolve conflicts or make your modifications.

5. Stage and Amend

   Add your changes and amend the commit:

   git add .
   git commit --amend
   
6. Continue Rebase

   git rebase --continue
   
7. Rebuild Patches

   Return to the root directory and rebuild:

   cd ../../../..
   ./gradlew rebuildPatches
   

Adding Larger Feature Patches

Feature patches are used for substantial changes that are difficult to track in per-file patches.

Most contributions won’t require feature patches. Only use them for large-scale optimizations or features that can be optionally dropped during updates.

1. Make Your Changes

   Modify files in paper-server/src/minecraft as needed.

2. Stage Your Changes

   cd paper-server/src/minecraft
   git add .
   
3. Create a Commit

   git commit -m "Your descriptive patch message"
   

   If you have specific implementation details to document, include them in the commit message or in code comments.

4. Rebuild Patches

   Return to the root directory and rebuild:

   cd ../../..
   ./gradlew rebuildPatches
   

   Your commit will be converted into a patch file that you can submit in a PR.

Modifying Larger Feature Patches

You can modify existing feature patches using either the manual rebase method (see Resolving Rebase Conflicts) or the fixup method below.

Fixup Method (Manual)

1. Make Your Changes

   Edit the necessary files.

2. Create Temporary Commit

   git commit -a -m "temp"
   
3. Interactive Rebase

   git rebase -i base
   

   Move (cut and paste) your temporary commit under the patch you want to modify.

4. Change Pick to Fixup/Squash

   • f or fixup: Merge changes without modifying the commit message
   • s or squash: Merge changes and edit the commit message
5. Rebuild Patches

   ./gradlew rebuildPatches
   

Fixup Method (Automatic)

1. Make Your Changes

   Edit the necessary files.

2. Create Fixup Commit

   git commit -a --fixup <hash-of-patch-to-fix>
   

   For per-file patches, use git commit -a --fixup file. Use --squash instead of --fixup if you want to modify the commit message too.

   You can find the hash using:

   • git log or git blame
   • Your IDE’s git integration
   • Commit subject: git commit -a --fixup "Subject of Patch name"
3. Autosquash Rebase

   git rebase -i --autosquash base
   

   This automatically moves your fixup commit to the correct location. Just save and close the editor.

4. Rebuild Patches

   ./gradlew rebuildPatches
   

Rebasing Your PR

When you need to update your PR with the latest changes from main:

These steps assume origin is your fork and upstream is the official PaperMC repository.

1. Fetch Upstream Changes

   git fetch upstream
   
2. Rebase Your Branch

   git switch patch-branch
   git rebase upstream/main
   
3. Apply Patches

   ./gradlew applyPatches
   
4. Fix Conflicts

   If there are conflicts, resolve them following the steps in Resolving Rebase Conflicts.

5. Ensure Patch Order (Feature Patches Only)

   If your PR creates new feature patches, ensure your patch is the last commit:

   Option A: Rename the patch file with a high number (e.g., 9999-Patch-to-add-some-new-stuff.patch) and re-apply patches.

   Option B: Run interactive rebase and move commits to the end:

   git rebase --interactive base
   
6. Rebuild Patches

   ./gradlew rebuildPatches
   
7. Commit Modified Patches

   git add .
   git commit -m "Rebase on upstream/main"
   
8. Force Push

   git push --force
   

   Double-check that you’re not deleting any of your commits or changes!

Access Transformers

Sometimes Vanilla code contains fields, methods, or types with insufficient visibility (e.g., private fields you need to access).

Paper uses Access Transformers (ATs) to change visibility or remove final modifiers without directly patching every reference.

1. Edit the AT File

   Open build-data/paper.at and add your access transformer.

   Read about the AT format in the Access Transformers documentation.

2. Apply Patches

   ./gradlew applyPatches
   

   The access transformers will be applied automatically.

Common Gradle Commands

Command	Description
./gradlew applyPatches	Apply all patches to set up the development environment
./gradlew fixupSourcePatches	Update per-file patches based on your changes
./gradlew rebuildPatches	Rebuild all patches after making changes
./gradlew runDev	Run a test server with your changes
./gradlew publishToMavenLocal	Install Paper to your local Maven repository for testing

Never use interactive git commands (like git rebase -i or git add -i) with the -i flag in automated scripts, as they require interactive input.