Purpur Documentation

To install the purpur-api and purpur dependencies into your local Maven repository (useful for local development of other projects that depend on Purpur), run the following command.

./gradlew publishToMavenLocal

To build the API and server components, use the ./gradlew build command.

Note: The resulting JARs are for development/reference and are not used to start a server.

• API JARs: Located in purpur-api/build/libs
• Server JARs: Located in purpur-server/build/libs

To set up the Purpur development environment, you must first clone the repository (do not download it as a ZIP). Once cloned, run the following command in the root directory to apply all necessary patches. After this step, the project is ready to be opened in your IDE.

./gradlew applyAllPatches

Purpur builds can be obtained via the official downloads page or through the Downloads API. Use the API to programmatically retrieve version lists, specific builds, or the latest available build for a Minecraft version.

API Endpoints:

• List Minecraft versions with available builds: https://api.purpurmc.org/v2/purpur
• List builds for a specific Minecraft version: https://api.purpurmc.org/v2/purpur/<version>
• Download a specific build: https://api.purpurmc.org/v2/purpur/<version>/<build>/download
• Download the latest build for a version: https://api.purpurmc.org/v2/purpur/<version>/latest/download

To use the Purpur API in your development environment, add the Purpur snapshot repository and the purpur-api dependency to your build configuration. The Purpur API includes all APIs provided by Paper, Spigot, and Bukkit.

Maven Configuration:

<repository>
    <id>purpur</id>
    <url>https://repo.purpurmc.org/snapshots</url>
</repository>

<dependency>
    <groupId>org.purpurmc.purpur</groupId>
    <artifactId>purpur-api</artifactId>
    <version>[26.2.build,)</version>
    <scope>provided</scope>
</dependency>

Gradle Configuration:

repositories {
    maven("https://repo.purpurmc.org/snapshots")
}

dependencies {
    compileOnly("org.purpurmc.purpur:purpur-api:26.2.build.+")
}

To create a JAR that is ready to be used to run a server, run the following command. The resulting purpurclip jar will be located in purpur-server/build/libs.

./gradlew createMojmapBundlerJar

Purpur includes a feature that allows server administrators to prevent players from being targeted by entity selectors (used in commands like /tp, /kill, or /effect) if they are not visible to the command sender.

This behavior is controlled by the hideHiddenPlayersFromEntitySelector configuration setting. When enabled, if a player is hidden (e.g., via invisibility or other mechanics that make them unseeable to the sender), they will be excluded from the results of entity selector arguments in commands.

Purpur provides configuration options to control the registration of certain Minecraft commands that are otherwise disabled or reserved for debugging. These settings are managed via org.purpur.PurpurConfig.

• registerMinecraftDisabledCommands: When enabled, allows the registration of commands that are normally disabled in standard Minecraft (e.g., ChaseCommand).
• registerMinecraftDebugCommands: When enabled, allows the registration of Minecraft debug commands (e.g., RaidCommand, DebugPathCommand, DebugMobSpawningCommand).

Purpur provides a configuration option to control whether items granted via the /give command are dropped on the ground if the player's inventory is full. By default, if an item cannot be added to the inventory, it is dropped as an item entity. You can disable this behavior using the disableGiveCommandDrops configuration key.

PurpurConfig.disableGiveCommandDrops

By default, the /enchant command prevents users from applying enchantment levels higher than the enchantment's defined maximum level or applying incompatible enchantments.

Purpur provides a configuration option allowUnsafeEnchantCommand to bypass these restrictions. When enabled, the /enchant command will allow:

1. Enchantment levels exceeding the standard maxLevel.
2. Enchantments that are otherwise incompatible with the item's current enchantment set.

Purpur provides an additional permission layer for the /gamemode command. When commandGamemodeRequiresPermission is enabled in the Purpur configuration, players must possess specific permissions to change their game mode or the game mode of others.

To change to a specific game mode, the player needs: minecraft.command.gamemode.<mode> (e.g., minecraft.command.gamemode.creative)

To change the game mode of other players, the player needs an additional permission: minecraft.command.gamemode.<mode>.other (e.g., minecraft.command.gamemode.creative.other)

Note: These permissions are only checked if commandGamemodeRequiresPermission is set to true in the Purpur configuration.

The testPermission method allows checking for both Minecraft native permissions and legacy Bukkit-style permission strings. If the permission check fails, it attempts to send a formatted failure message to the command source, replacing the <permission> placeholder with the actual Bukkit permission string provided.

public boolean testPermission(net.minecraft.server.permissions.Permission permission, String bukkitPermission)