PaperLib

PaperLib is a plugin library for interfacing with Paper specific APIs (such as async chunk loading), with graceful fallbacks maintaining compatibility with both the Bukkit and Spigot API's.

Warning

PaperLib was meant as a temporary means of using more powerful Paper API while allowing full compatibility with Spigot as was necessary for a lot of people. Now, you're better off directly targeting Paper and uploading your plugin to one of the many other resource sites, such as Hangar, modrinth, BuiltByBit, or Polymart.

API

All API calls can be found as static util methods in the PaperLib class.

getChunkAtAsync

publicclassPaperLib {
publicstaticCompletableFuture<Chunk> getChunkAtAsync(Locationloc);
publicstaticCompletableFuture<Chunk> getChunkAtAsync(Locationloc, booleangen);
publicstaticCompletableFuture<Chunk> getChunkAtAsync(Worldworld, intx, intz);
publicstaticCompletableFuture<Chunk> getChunkAtAsync(Worldworld, intx, intz, booleangen); }

On Paper, loads (or generates on 1.13.1+) the chunk asynchronously if it is not loaded yet, then completes the returned future. Chunk will load synchronous on Spigot.

teleportAsync

publicclassPaperLib {
publicstaticCompletableFuture<Boolean> teleportAsync(Entityentity, Locationlocation);
publicstaticCompletableFuture<Boolean> teleportAsync(Entityentity, Locationlocation, TeleportCausecause);
}

Uses the Async Chunk Load API, and if possible, loads/generates the chunk asynchronously before teleporting. Will load synchronous on Spigot.

On 1.15+, this has an added improvement of also loading neighbor chunks to avoid collision checks loading chunks too.

isChunkGenerated

publicclassPaperLib {
publicstaticbooleanisChunkGenerated(Locationloc);
publicstaticbooleanisChunkGenerated(Worldworld, intx, intz);
}

Returns whether or not the chunk is generated. Only Supported in Paper 1.12+ and Spigot 1.13.1+

getBlockState

publicclassPaperLib {
publicstaticBlockStateSnapshotResultgetBlockState(Blockblock, booleanuseSnapshot);
}

Allows you to optionally avoid taking a snapshot of a TileEntity in a BlockState. Versions prior to 1.12 will always be false for the snapshot. In versions 1.12+ on Spigot, the snapshot will always be true. In Paper 1.12+, the snapshot will be whether or not you requested one in the API call.

getTileEntities

publicclassPaperLib {
publicstaticTileEntitiesSnapshotResultgetTileEntities(Chunkchunk, booleanuseSnapshot);
}

Allows you to optionally avoid taking a snapshot of a TileEntity in a BlockState. Versions prior to 1.13 will always be false for the snapshot. In versions 1.13+ on Spigot, the snapshot will always be true. In Paper 1.13+, the snapshot will be whether or not you requested one in the API call.

isSolid

publicclassPaperLib {
publicstaticbooleanisSolid(Blockblock);
}

Checks if a block is considered solid. On Paper 1.16.4+ this uses Block#isSolid, otherwise it falls back to Material#isSolid.

suggestPaper

publicclassPaperLib {
publicstaticvoidsuggestPaper(Pluginplugin);
}

Helps inform users who run your plugin on Spigot that your plugin will behave better on Paper! Calling this method will print out an informational message in the logs that they should switch to Paper, and will help users discover our software. We would appreciate it if you call this method, but it is optional.

Example Plugin

publicclassMyPluginextendsJavaPlugin {
publicvoidonEnable() {
PaperLib.suggestPaper(this);
}
publicvoiddoSomething(Entityentity, Locationlocation) {
PaperLib.teleportAsync(entity, location).thenAccept(result -> {
if (result) {
player.sendMessage("Teleported!");
} else {
player.sendMessage("Something went wrong!");
}
});
}
}

Build Script Setup

Add the Paper repository and the PaperLib dependency, then shade and relocate it to your own package. Relocation helps avoid version conflicts with other plugins using PaperLib. PaperLib is published on Maven Central, so no extra repository is needed for it.

Gradle

Repo:

repositories {
mavenCentral()
}

Dependency:

dependencies {
implementation "io.github.rvskele:PaperLib:2.1.0"
}

Shadow Jar and Relocate (Groovy Syntax):

plugins {
id "com.github.johnrengelman.shadow" version "9.3.1"// Make sure to always use the latest version (https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)
}
shadowJar {
relocate "com.github.rvsksle.paperlib", "[YOUR PLUGIN PACKAGE].paperlib"
}

Maven

Repo: Maven Central is used by default, no extra repository is needed. Dependency:

<dependencies>
<dependency>
<groupId>io.github.rvskele</groupId>
<artifactId>PaperLib</artifactId>
<version>2.1.0</version>
<scope>compile</scope>
</dependency>
</dependencies>

Shade & Relocate:

<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-shade-plugin</artifactId>
<version>3.6.1</version> <!-- Make sure to always use the latest version (https://maven.apache.org/plugins/maven-shade-plugin/) -->
<configuration>
<dependencyReducedPomLocation>${project.build.directory}/dependency-reduced-pom.xml</dependencyReducedPomLocation>
<relocations>
<relocation>
<pattern>io.github.rvskele.paperlib</pattern>
<shadedPattern>[YOUR PLUGIN PACKAGE].paperlib</shadedPattern> <!-- Replace this -->
</relocation>
</relocations>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>shade</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>

Compiling

PaperLib is compiled using Gradle:

./gradlew build

License

PaperLib is licensed under the MIT license