Development Environment Setup

Set up your IDE and development environment for Paper development

This guide covers setting up your development environment for contributing to Paper, including IDE configuration, repository setup, and best practices.

Requirements

Before starting, ensure you have:

• Git - Version control system
• JDK 21 or later - Required for building Paper
  • Adoptium provides builds for most operating systems
  • Paper uses Gradle’s Toolchains feature
• IntelliJ IDEA (recommended) - Most of the Paper team uses IntelliJ

While other IDEs may work, IntelliJ IDEA is the recommended and officially supported IDE for Paper development.

Windows-Specific Setup

If you’re on Windows, WSL 2 (Windows Subsystem for Linux) is highly recommended for significantly faster build and patch times.

Setting up WSL 2

WSL 2 is available on Windows 10 version 2004 (build 19041) or higher. Check your version by running winver.

1. Install WSL 2

   Follow the official Microsoft WSL installation guide.

2. Install Ubuntu

   Install Ubuntu from the Microsoft Store (or your preferred Linux distribution).

3. Install development tools

   In your WSL terminal:

   sudo apt-get update
   sudo apt-get install git -y
   

   Then install JDK 21 from Adoptium.

4. Access WSL files in Windows

   You can access your WSL files from Windows File Explorer:

   explorer.exe .
   

   Important: Do NOT use the /mnt/ directory in WSL for development. This path accesses Windows files through WSL, which is extremely slow. Always work in your WSL home directory (~) or other native WSL paths.

Repository Setup

Use a Personal Fork, Not an Organization

Paper team members routinely modify PRs for quick fixes and rebases. GitHub prevents modifications to PRs from organization repositories. Always fork Paper to your personal GitHub account.

1. Fork the repository

   Fork the PaperMC/Paper repository to your personal GitHub account.

2. Clone your fork

   git clone https://github.com/YOUR_USERNAME/Paper.git
   cd Paper
   
3. Add upstream remote

   git remote add upstream https://github.com/PaperMC/Paper.git
   

   This allows you to pull the latest changes from the official repository.

4. Apply patches

   ./gradlew applyPatches
   

   This creates the paper-server/src/minecraft directory with Paper’s patched Minecraft source.

IntelliJ IDEA Configuration

Recommended Settings

1. Import the project

   Open IntelliJ IDEA and import the Paper project as a Gradle project. IntelliJ should automatically detect the Gradle configuration.

2. Disable sync external changes

   This is critical for performance during patch operations.

   Navigate to:

   Settings > Appearance & Behavior > System Settings
   

   Disable this option:

   • ☐ Sync external changes: Periodically when the IDE is inactive (experimental)

   When this setting is enabled, IntelliJ attempts to reindex files while patches are being applied, causing severe slowdowns and freezes.

3. Disable reopen projects on startup (optional)

   To avoid freeze loops when patches fail:

   Navigate to:

   Settings > Appearance & Behavior > System Settings
   

   Disable this option:

   • ☐ Reopen projects on startup

   This prevents IntelliJ from automatically opening Paper if patches are in a broken state.

4. Configure Java toolchain

   IntelliJ should automatically detect your JDK 21 installation through Gradle’s toolchain configuration.

   Verify under:

   Settings > Build, Execution, Deployment > Build Tools > Gradle
   

   Gradle JVM should be set to JDK 21 or use the Gradle default.

IDE Features

IntelliJ IDEA provides excellent support for:

• Git integration and conflict resolution
• Gradle task execution
• Debugging Paper server instances
• Code navigation in Paper’s patched Minecraft source
• Automatic code formatting according to Paper’s style

Understanding the Project Structure

Paper uses a patch-based development workflow:

Paper/
├── paper-api/           # Bukkit API implementation
├── paper-server/        # Server implementation
│   └── src/
│       └── minecraft/   # Patched Minecraft source (generated)
├── patches/             # Paper's patch files
│   ├── api/            # API patches
│   ├── server/         # Server patches
│   │   ├── sources/    # Per-file patches
│   │   ├── resources/  # Resource patches
│   │   └── features/   # Feature patches
├── build-data/          # Build configuration
│   └── paper.at        # Access transformers
└── test-plugin/         # Optional test plugin module

Important Directories

• paper-api/ - Changes to the Bukkit API
• paper-server/src/minecraft/ - Minecraft source modifications (patch-tracked)
• paper-server/src/main/ - Non-Minecraft server code (regular Git)
• patches/ - Actual patch files that get applied

Only changes in paper-server/src/minecraft/ use the patch system. Other directories use standard Git tracking.

Development Workflow

Making Changes

1. Create a feature branch

   git checkout -b my-feature-branch
   
2. Make your changes

   • For API changes: Edit files in paper-api/
   • For Minecraft changes: Edit files in paper-server/src/minecraft/
   • For other server changes: Edit files in paper-server/src/main/
3. Test your changes

   ./gradlew runDevServer
   

   This runs a development server with your changes without creating a JAR.

4. Rebuild patches

   If you modified files in paper-server/src/minecraft/:

   ./gradlew fixupSourcePatches
   ./gradlew rebuildPatches
   

   For other changes, commit normally with Git.

5. Commit your changes

   git add .
   git commit -m "Description of your changes"
   

Modifying Minecraft Patches

For per-file patches (most common):

1. Make changes to files in paper-server/src/minecraft/
2. Run ./gradlew fixupSourcePatches
3. Run ./gradlew rebuildPatches
4. Commit the updated patch files

See the CONTRIBUTING.md for detailed information on:

• Handling rebase conflicts
• Creating feature patches
• Using fixup commits
• Patch formatting guidelines

Using the Test Plugin

Paper includes an optional test plugin module for testing API changes.

1. Enable the test plugin

   Enable it in test-plugin.settings.gradle.kts (generated after running Gradle once).

2. Edit the test plugin

   Make changes to test-plugin/src/main/java/.

3. Run with the test plugin

   ./gradlew runDevServer
   

   The run tasks automatically include the test plugin when enabled.

Testing API Changes Locally

To test your Paper changes in external plugins:

1. Publish to Maven Local

   ./gradlew publishToMavenLocal
   
2. Configure your plugin project

   For Gradle:

   Add mavenLocal() as the first repository:

   repositories {
       mavenLocal()  // Must be first
       maven("https://repo.papermc.io/repository/maven-public/")
   }
   

   Remove mavenLocal() when done testing. See the Gradle docs for why.

3. Use Paper in your plugin

   Your plugin will now use your locally-built Paper version.

Git Workflow Tips

Keeping Your Fork Updated

# Fetch latest changes from upstream
git fetch upstream

# Update your main branch
git checkout main
git merge upstream/main

# Rebase your feature branch
git checkout my-feature-branch
git rebase upstream/main

Understanding Git Basics

Paper’s patch system is built on Git. If you’re new to Git, review this tutorial: https://git-scm.com/docs/gittutorial

Common Issues

IntelliJ freezes during patch application

Solution: Disable “Sync external changes” in IntelliJ settings (see IntelliJ IDEA Configuration).

Patch conflicts during rebase

See the CONTRIBUTING.md rebase conflict resolution guide.

Build fails with “JAVA_HOME not set”

Solution: Ensure JDK 21 is installed and JAVA_HOME points to it:

export JAVA_HOME=/path/to/jdk-21

Next Steps

• Read the CONTRIBUTING.md for detailed contribution guidelines
• Learn about code formatting and style requirements
• Explore available Gradle tasks
• Join the Paper Discord for help and discussion