https://github.com/papermc/paperlib

Plugin Library for interfacing with Paper Specific API's with graceful fallback that maintains Spigot Compatibility, such as Async Chunk Loading.
https://github.com/papermc/paperlib

library minecraft paper spigot

Last synced: 27 days ago
JSON representation

Plugin Library for interfacing with Paper Specific API's with graceful fallback that maintains Spigot Compatibility, such as Async Chunk Loading.

• Host: GitHub
• URL: https://github.com/papermc/paperlib
• Owner: PaperMC
• License: mit
• Created: 2018-09-25T15:08:23.000Z (about 6 years ago)
• Default Branch: master
• Last Pushed: 2024-03-02T23:00:54.000Z (8 months ago)
• Last Synced: 2024-04-14T07:01:01.510Z (7 months ago)
• Topics: library, minecraft, paper, spigot
• Language: Java
• Size: 208 KB
• Stars: 264
• Watchers: 22
• Forks: 32
• Open Issues: 5
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# 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.

## API

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

### getChunkAtAsync

```java

public class PaperLib {

  public static CompletableFuture getChunkAtAsync(Location loc);

  public static CompletableFuture getChunkAtAsync(Location loc, boolean gen);

  public static CompletableFuture getChunkAtAsync(World world, int x, int z);

  public static CompletableFuture getChunkAtAsync(World world, int x, int z, boolean gen); 

}

```

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

```java

public class PaperLib {

  public static CompletableFuture teleportAsync(Entity entity, Location location);

  public static CompletableFuture teleportAsync(Entity entity, Location location, TeleportCause cause);

}

```

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

```java

public class PaperLib {

  public static boolean isChunkGenerated(Location loc);

  public static boolean isChunkGenerated(World world, int x, int z);

}

```

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

### getBlockState

```java

public class PaperLib {

  public static BlockStateSnapshotResult getBlockState(Block block, boolean useSnapshot);

}

```

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.

### suggestPaper

```java

public class PaperLib {

  public static void suggestPaper(Plugin plugin);

}

```

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

```java

public class MyPlugin extends JavaPlugin {

    public void onEnable() {

        PaperLib.suggestPaper(this);

    }

    

    public void doSomething(Entity entity, Location location) {

        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. 

### Gradle

Repo:

```groovy

repositories {

    maven {

        name "papermc"

        url "https://papermc.io/repo/repository/maven-public/"

    }

}

```

Dependency:

```groovy

dependencies {

    implementation "io.papermc:paperlib:1.0.7"

}

```

Shadow Jar and Relocate (Groovy Syntax):

```groovy

plugins {

  id "com.github.johnrengelman.shadow" version "7.1.0"

  // Make sure to always use the latest version (https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)

}

shadowJar {

   relocate "io.papermc.lib", "[YOUR PLUGIN PACKAGE].paperlib"

}

```

### Maven

Repo:

```xml

    

        papermc

        https://papermc.io/repo/repository/maven-public/

    

```

Dependency:

```xml

    

        io.papermc

        paperlib

        1.0.7

        compile

     

 

 ```

 

Shade & Relocate:

```xml

    

        

            org.apache.maven.plugins

            maven-shade-plugin

            3.2.4 

            

                ${project.build.directory}/dependency-reduced-pom.xml

                

                    

                        io.papermc.lib

                        [YOUR PLUGIN PACKAGE].paperlib 

                    

                

            

            

                

                    package

                    

                        shade

                    

                

            

        

    

```

## Compiling

PaperLib is compiled using Gradle:

```

./gradlew build

```

## License

PaperLib is licensed under the [MIT license](LICENSE)