PaperLib

PaperLib is a plugin library designed to interface with Paper-specific APIs (like asynchronous chunk loading) while providing graceful fallbacks for Spigot and Bukkit. This allows your plugin to use powerful Paper features without breaking compatibility for Spigot users.

Note: The maintainers suggest that for new projects, it is often better to target Paper directly and distribute your plugin on platforms like Hangar, Modrinth, BuiltByBit, or Polymart rather than using PaperLib for cross-compatibility.

To use PaperLib in a Gradle project, add the PaperMC repository and the dependency. Crucially, you must shade and relocate PaperLib to your own package to avoid version conflicts with other plugins.

1. Add the repository.
2. Add the dependency.
3. Use the shadow plugin to relocate io.papermc.lib to [YOUR_PLUGIN_PACKAGE].paperlib.

// 1. Repositories
repositories {
    maven {
        name "papermc"
        url "https://papermc.io/repo/repository/maven-public/"
    }
}

// 2. Dependencies
dependencies {
    implementation "io.papermc:paperlib:1.0.7"
}

// 3. Shadow and Relocate
plugins {
  id "com.github.johnrengelman.shadow" version "7.1.0"
}

shadowJar {
   relocate "io.papermc.lib", "com.example.myplugin.paperlib"
}

Use PaperLib.teleportAsync to teleport an entity to a location using the Async Chunk Load API. This ensures the destination chunk is loaded before the teleport occurs.

• On Paper: Loads/generates the chunk asynchronously before teleporting. On 1.15+, it also loads neighbor chunks to prevent collision checks from triggering synchronous chunk loading.
• On Spigot: Falls back to synchronous loading.

Returns a CompletableFuture<Boolean> indicating if the teleport was successful.

Available overloads:

• teleportAsync(Entity entity, Location location)
• teleportAsync(Entity entity, Location location, TeleportCause cause)

PaperLib.teleportAsync(entity, location).thenAccept(success -> {
    if (success) {
        // Teleport successful
    }
});

Use PaperLib.getChunkAtAsync to load or generate chunks without blocking the main server thread.

• On Paper: Loads (or generates on 1.13.1+) the chunk asynchronously and completes a CompletableFuture<Chunk>.
• On Spigot: Falls back to loading the chunk synchronously.

Available overloads:

• getChunkAtAsync(Location loc)
• getChunkAtAsync(Location loc, boolean gen)
• getChunkAtAsync(World world, int x, int z)
• getChunkAtAsync(World world, int x, int z, boolean gen)

CompletableFuture<Chunk> future = PaperLib.getChunkAtAsync(location);

Allows you to retrieve a BlockState with the option to avoid taking a snapshot of the TileEntity.

Behavior by version/platform:

• Versions prior to 1.12: useSnapshot is always false.
• Spigot 1.12+: useSnapshot is always true.
• Paper 1.12+: Respects the useSnapshot boolean provided in the call.

Available overload:

• getBlockState(Block block, boolean useSnapshot)

Calling PaperLib.suggestPaper(Plugin plugin) prints an informational message in the logs when your plugin is running on Spigot. This informs users that the plugin will behave better on Paper and helps them discover the Paper platform. This is optional.

@Override
public void onEnable() {
    PaperLib.suggestPaper(this);
}

Returns whether or not a specific chunk has been generated.

Compatibility:

• Supported in Paper 1.12+
• Supported in Spigot 1.13.1+

Available overloads:

• isChunkGenerated(Location loc)
• isChunkGenerated(World world, int x, int z)