Skip to main content

​
Overview

Paper is built on a modular architecture that separates API definitions from their implementation. This design enables plugin developers to write code against a stable API while Paper maintains the complex Minecraft server implementation.

​
Module Structure

Paper consists of two primary modules:

​
paper-api

The paper-api module contains the public-facing API that plugin developers interact with. This includes:
  • Event classes (extending org.bukkit.event.Event)
  • Plugin interfaces and abstract classes
  • Service definitions and contracts
  • Public data structures and enums
The API is designed to remain stable across minor version updates, allowing plugins to function without recompilation when Paper updates.
The API module has no direct dependencies on Minecraft code, making it clean and version-independent.

​
paper-server

The paper-server module implements the API and contains:
  • Patched Minecraft source code in paper-server/src/minecraft
  • Implementation of API interfaces using Minecraft internals
  • Performance optimizations and bug fixes
  • Configuration system (io.papermc.paper.configuration package)
Only changes made in paper-server/src/minecraft interact with the patch system. Other changes in paper-server are direct modifications.

​
How Modules Work Together

The relationship between the modules follows this flow:
  1. Plugin Code → Uses paper-api interfaces and classes
  2. paper-api → Defines contracts without implementation
  3. paper-server → Implements API contracts using Minecraft code
  4. Minecraft Source → Patched with Paper’s modifications
Plugin
  ↓ (uses)
paper-api (interfaces, events)
  ↓ (implemented by)
paper-server (implementation + Minecraft patches)
  ↓ (modifies)
Minecraft Server (patched source)

​
Source Code Organization

​
Minecraft Patched Source

The paper-server/src/minecraft directory contains decompiled and deobfuscated Minecraft source files with Paper’s patches applied. This directory structure:
  • Starts with vanilla Minecraft source as the initial commit
  • Has per-file patches applied as a single large commit
  • Contains individual feature patch commits on top
This git-based structure allows Paper to track exactly what changed and rebase patches when Minecraft updates.

​
Configuration System

The configuration architecture uses the ConfigurationPart pattern:
  • GlobalConfiguration - Server-wide settings (in io.papermc.paper.configuration)
  • WorldConfiguration - Per-world settings that can differ between dimensions
Both extend the abstract ConfigurationPart class, which serves as a marker interface for configuration sections.

​
Build System

Paper uses Gradle with specialized tasks:
  • ./gradlew applyPatches - Applies all patches to Minecraft source
  • ./gradlew rebuildPatches - Converts commits back into patch files
  • ./gradlew fixupSourcePatches - Automatically fixes per-file patches
The build system uses Gradle’s Toolchains feature to automatically provision JDK 21 for compilation, even if you only have JRE 17 installed.

​
Access Transformers

Paper uses access transformers (build-data/paper.at) to modify visibility of Minecraft classes, methods, and fields without patching. This allows:
  • Changing private fields to protected/public
  • Removing final modifiers
  • Accessing internal Minecraft APIs safely
Access transformers are applied during the applyPatches task.

​
Key Design Principles

The API and implementation are strictly separated, allowing the API to remain stable while implementation details can change.
All Minecraft changes are tracked as patches, making it possible to rebase changes when Minecraft updates.
Paper maintains backward compatibility in the API while fixing bugs and adding features in the server implementation.
Paper’s architecture enables performance optimizations in the server module without affecting plugin compatibility.

Build docs developers (and LLMs) love

Get started for freeTalk to us