Package io.papermc.lib

Class PaperLib

  • public class PaperLib
extends java.lang.Object
    Utility methods that assist plugin developers accessing Paper features. Bridges backwards compatability with Spigot and CraftBukkit so your plugin will still work on those platforms, and fall back to less performant methods.

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static java.util.concurrent.CompletableFuture<org.bukkit.Location> getBedSpawnLocationAsync​(org.bukkit.entity.Player player, boolean isUrgent)
      Gets the location where the target player will spawn at their bed, asynchronously if needed
      static BlockStateSnapshotResult getBlockState​(org.bukkit.block.Block block, boolean useSnapshot)
      Get's a BlockState, optionally not using a snapshot
      static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(org.bukkit.Location loc)
      Gets the chunk at the target location, loading it asynchronously if needed.
      static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(org.bukkit.Location loc, boolean gen)
      Gets the chunk at the target location, loading it asynchronously if needed.
      static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(org.bukkit.World world, int x, int z)
      Gets the chunk at the target location, loading it asynchronously if needed.
      static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(org.bukkit.World world, int x, int z, boolean gen)
      Gets the chunk at the target location, loading it asynchronously if needed.
      static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(org.bukkit.World world, int x, int z, boolean gen, boolean isUrgent)
      Gets the chunk at the target location, loading it asynchronously if needed.
      static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsyncUrgently​(org.bukkit.World world, int x, int z, boolean gen)
      Gets the chunk at the target location, loading it asynchronously if needed, with highest priority if supported
      static Environment getEnvironment()
      Gets a reference to the current environment.
      static int getMinecraftPatchVersion()
      Gets the current Minecraft Patch version.
      static int getMinecraftVersion()
      Gets the current Minecraft Minor version.
      static boolean isChunkGenerated​(org.bukkit.Location loc)
      Checks if the chunk has been generated or not.
      static boolean isChunkGenerated​(org.bukkit.World world, int x, int z)
      Checks if the chunk has been generated or not.
      static boolean isPaper()
      Check if the server has access to the Paper API
      static boolean isSpigot()
      Check if the server has access to the Spigot API
      static boolean isVersion​(int minor)
      Detects if the current MC version is at least the following version.
      static boolean isVersion​(int minor, int patch)
      Detects if the current MC version is at least the following version.
      static void setCustomEnvironment​(Environment environment)
      If you have need to inject a custom Environment, such as running on your own fork, or unit tests, do it here.
      static void suggestPaper​(org.bukkit.plugin.Plugin plugin)
      Can be called during plugin initialization to inform the server owner they should switch to Paper If you do not mind helping spread Paper, please call this in your plugin onEnable to help spread awareness about Paper, and encourage them that your plugin is better when used with Paper!
      static java.util.concurrent.CompletableFuture<java.lang.Boolean> teleportAsync​(org.bukkit.entity.Entity entity, org.bukkit.Location location)
      Teleports an Entity to the target location, loading the chunk asynchronously first if needed.
      static java.util.concurrent.CompletableFuture<java.lang.Boolean> teleportAsync​(org.bukkit.entity.Entity entity, org.bukkit.Location location, org.bukkit.event.player.PlayerTeleportEvent.TeleportCause cause)
      Teleports an Entity to the target location, loading the chunk asynchronously first if needed.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Method Detail

      • getEnvironment

        @Nonnull
public static Environment getEnvironment()
        Gets a reference to the current environment. All of the static util methods in this class points to this environment.
        Returns:
        The Environment

      • setCustomEnvironment

        public static void setCustomEnvironment​(@Nonnull
                                        Environment environment)
        If you have need to inject a custom Environment, such as running on your own fork, or unit tests, do it here.
        Parameters:
        environment - Custom Environment

      • teleportAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<java.lang.Boolean> teleportAsync​(@Nonnull
                                                                                      org.bukkit.entity.Entity entity,
                                                                                      @Nonnull
                                                                                      org.bukkit.Location location)
        Teleports an Entity to the target location, loading the chunk asynchronously first if needed.
        Parameters:
        entity - The Entity to teleport
        location - The Location to Teleport to
        Returns:
        Future that completes with the result of the teleport

      • teleportAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<java.lang.Boolean> teleportAsync​(@Nonnull
                                                                                      org.bukkit.entity.Entity entity,
                                                                                      @Nonnull
                                                                                      org.bukkit.Location location,
                                                                                      org.bukkit.event.player.PlayerTeleportEvent.TeleportCause cause)
        Teleports an Entity to the target location, loading the chunk asynchronously first if needed.
        Parameters:
        entity - The Entity to teleport
        location - The Location to Teleport to
        cause - The cause for the teleportation
        Returns:
        Future that completes with the result of the teleport

      • getChunkAtAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(@Nonnull
                                                                                       org.bukkit.Location loc)
        Gets the chunk at the target location, loading it asynchronously if needed.
        Parameters:
        loc - Location to get chunk for
        Returns:
        Future that completes with the chunk

      • getChunkAtAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(@Nonnull
                                                                                       org.bukkit.Location loc,
                                                                                       boolean gen)
        Gets the chunk at the target location, loading it asynchronously if needed.
        Parameters:
        loc - Location to get chunk for
        gen - Should the chunk generate or not. Only respected on some MC versions, 1.13 for CB, 1.12 for Paper
        Returns:
        Future that completes with the chunk, or null if the chunk did not exists and generation was not requested.

      • getChunkAtAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(@Nonnull
                                                                                       org.bukkit.World world,
                                                                                       int x,
                                                                                       int z)
        Gets the chunk at the target location, loading it asynchronously if needed.
        Parameters:
        world - World to load chunk for
        x - X coordinate of the chunk to load
        z - Z coordinate of the chunk to load
        Returns:
        Future that completes with the chunk

      • getChunkAtAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(@Nonnull
                                                                                       org.bukkit.World world,
                                                                                       int x,
                                                                                       int z,
                                                                                       boolean gen)
        Gets the chunk at the target location, loading it asynchronously if needed.
        Parameters:
        world - World to load chunk for
        x - X coordinate of the chunk to load
        z - Z coordinate of the chunk to load
        gen - Should the chunk generate or not. Only respected on some MC versions, 1.13 for CB, 1.12 for Paper
        Returns:
        Future that completes with the chunk, or null if the chunk did not exists and generation was not requested.

      • getChunkAtAsync

        @Nonnull
public static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsync​(@Nonnull
                                                                                       org.bukkit.World world,
                                                                                       int x,
                                                                                       int z,
                                                                                       boolean gen,
                                                                                       boolean isUrgent)
        Gets the chunk at the target location, loading it asynchronously if needed.
        Parameters:
        world - World to load chunk for
        x - X coordinate of the chunk to load
        z - Z coordinate of the chunk to load
        gen - Should the chunk generate or not. Only respected on some MC versions, 1.13 for CB, 1.12 for Paper
        Returns:
        Future that completes with the chunk, or null if the chunk did not exists and generation was not requested.

      • getChunkAtAsyncUrgently

        @Nonnull
public static java.util.concurrent.CompletableFuture<org.bukkit.Chunk> getChunkAtAsyncUrgently​(@Nonnull
                                                                                               org.bukkit.World world,
                                                                                               int x,
                                                                                               int z,
                                                                                               boolean gen)
        Gets the chunk at the target location, loading it asynchronously if needed, with highest priority if supported
        Parameters:
        world - World to load chunk for
        x - X coordinate of the chunk to load
        z - Z coordinate of the chunk to load
        gen - Should the chunk generate or not. Only respected on some MC versions, 1.13 for CB, 1.12 for Paper
        Returns:
        Future that completes with the chunk, or null if the chunk did not exists and generation was not requested.

      • isChunkGenerated

        public static boolean isChunkGenerated​(@Nonnull
                                       org.bukkit.Location loc)
        Checks if the chunk has been generated or not. Only works on Paper 1.12+ or any 1.13.1+ version
        Parameters:
        loc - Location to check if the chunk is generated
        Returns:
        If the chunk is generated or not

      • isChunkGenerated

        public static boolean isChunkGenerated​(@Nonnull
                                       org.bukkit.World world,
                                       int x,
                                       int z)
        Checks if the chunk has been generated or not. Only works on Paper 1.12+ or any 1.13.1+ version
        Parameters:
        world - World to check for
        x - X coordinate of the chunk to check
        z - Z coordinate of the chunk to checl
        Returns:
        If the chunk is generated or not

      • getBlockState

        @Nonnull
public static BlockStateSnapshotResult getBlockState​(@Nonnull
                                                     org.bukkit.block.Block block,
                                                     boolean useSnapshot)
        Get's a BlockState, optionally not using a snapshot
        Parameters:
        block - The block to get a State of
        useSnapshot - Whether or not to use a snapshot when supported
        Returns:
        The BlockState

      • getBedSpawnLocationAsync

        public static java.util.concurrent.CompletableFuture<org.bukkit.Location> getBedSpawnLocationAsync​(@Nonnull
                                                                                                   org.bukkit.entity.Player player,
                                                                                                   boolean isUrgent)
        Gets the location where the target player will spawn at their bed, asynchronously if needed
        Parameters:
        player - The player whose bed spawn location to get.
        isUrgent - Whether or not this should be performed with highest priority when supported
        Returns:
        Future that completes with the location of the bed spawn location, or null if the player has not slept in a bed or if the bed spawn is invalid.

      • isVersion

        public static boolean isVersion​(int minor)
        Detects if the current MC version is at least the following version. Assumes 0 patch version.
        Parameters:
        minor - Min Minor Version
        Returns:
        Meets the version requested

      • isVersion

        public static boolean isVersion​(int minor,
                                int patch)
        Detects if the current MC version is at least the following version.
        Parameters:
        minor - Min Minor Version
        patch - Min Patch Version
        Returns:
        Meets the version requested

      • getMinecraftVersion

        public static int getMinecraftVersion()
        Gets the current Minecraft Minor version. IE: 1.13.1 returns 13
        Returns:
        The Minor Version

      • getMinecraftPatchVersion

        public static int getMinecraftPatchVersion()
        Gets the current Minecraft Patch version. IE: 1.13.1 returns 1
        Returns:
        The Patch Version

      • isSpigot

        public static boolean isSpigot()
        Check if the server has access to the Spigot API
        Returns:
        True for Spigot and Paper environments

      • isPaper

        public static boolean isPaper()
        Check if the server has access to the Paper API
        Returns:
        True for Paper environments

      • suggestPaper

        public static void suggestPaper​(@Nonnull
                                org.bukkit.plugin.Plugin plugin)
        Can be called during plugin initialization to inform the server owner they should switch to Paper If you do not mind helping spread Paper, please call this in your plugin onEnable to help spread awareness about Paper, and encourage them that your plugin is better when used with Paper!
        Parameters:
        plugin - Your plugin object