Skip to main content
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

CommandDescription
./gradlew applyPatchesApply all patches to set up the development environment
./gradlew fixupSourcePatchesUpdate per-file patches based on your changes
./gradlew rebuildPatchesRebuild all patches after making changes
./gradlew runDevRun a test server with your changes
./gradlew publishToMavenLocalInstall 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.

Build docs developers (and LLMs) love

Get started for freeTalk to us