{"id":13428471,"url":"https://github.com/PaperMC/PaperLib","last_synced_at":"2025-03-16T01:32:29.186Z","repository":{"id":42513272,"uuid":"150285257","full_name":"PaperMC/PaperLib","owner":"PaperMC","description":"Plugin Library for interfacing with Paper Specific API's with graceful fallback that maintains Spigot Compatibility, such as Async Chunk Loading.","archived":false,"fork":false,"pushed_at":"2024-03-02T23:00:54.000Z","size":213,"stargazers_count":270,"open_issues_count":6,"forks_count":32,"subscribers_count":22,"default_branch":"master","last_synced_at":"2024-10-30T04:28:01.253Z","etag":null,"topics":["library","minecraft","paper","spigot"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PaperMC.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"github":"PaperMC","open_collective":"PaperMC"}},"created_at":"2018-09-25T15:08:23.000Z","updated_at":"2024-10-21T16:09:33.000Z","dependencies_parsed_at":"2023-01-31T19:45:16.665Z","dependency_job_id":"99b412da-44ac-495e-9008-72bfa50fb08a","html_url":"https://github.com/PaperMC/PaperLib","commit_stats":{"total_commits":57,"total_committers":16,"mean_commits":3.5625,"dds":"0.49122807017543857","last_synced_commit":"69e76fc9036e7b5f2c967bd21db31043724ef9e3"},"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FPaperLib","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FPaperLib/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FPaperLib/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PaperMC%2FPaperLib/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PaperMC","download_url":"https://codeload.github.com/PaperMC/PaperLib/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242953374,"owners_count":20212010,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["library","minecraft","paper","spigot"],"created_at":"2024-07-31T01:00:58.060Z","updated_at":"2025-03-16T01:32:29.180Z","avatar_url":"https://github.com/PaperMC.png","language":"Java","readme":"# PaperLib\nPaperLib 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.\n\n\u003e [!WARNING]\n\u003e 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.\n\u003e Now, you're better off directly targeting Paper and uploading your plugin to one of the many other resource sites, such as\n\u003e [Hangar](https://hangar.papermc.io/), [modrinth](https://modrinth.com/), [BuiltByBit](https://builtbybit.com/), or [Polymart](https://polymart.org/).\n\n## API\nAll API calls can be found as static util methods in the `PaperLib` class.\n\n### getChunkAtAsync\n```java\npublic class PaperLib {\n  public static CompletableFuture\u003cChunk\u003e getChunkAtAsync(Location loc);\n  public static CompletableFuture\u003cChunk\u003e getChunkAtAsync(Location loc, boolean gen);\n  public static CompletableFuture\u003cChunk\u003e getChunkAtAsync(World world, int x, int z);\n  public static CompletableFuture\u003cChunk\u003e getChunkAtAsync(World world, int x, int z, boolean gen); \n}\n```\nOn Paper, loads (or generates on 1.13.1+) the chunk asynchronously if it is not loaded yet, then completes the returned future.\nChunk will load synchronous on Spigot.\n\n### teleportAsync\n```java\npublic class PaperLib {\n  public static CompletableFuture\u003cBoolean\u003e teleportAsync(Entity entity, Location location);\n  public static CompletableFuture\u003cBoolean\u003e teleportAsync(Entity entity, Location location, TeleportCause cause);\n}\n```\nUses the Async Chunk Load API, and if possible, loads/generates the chunk asynchronously before teleporting.\nWill load synchronous on Spigot.\n\nOn 1.15+, this has an added improvement of also loading neighbor chunks to avoid collision checks loading chunks too.\n\n### isChunkGenerated\n```java\npublic class PaperLib {\n  public static boolean isChunkGenerated(Location loc);\n  public static boolean isChunkGenerated(World world, int x, int z);\n}\n```\nReturns whether or not the chunk is generated. Only Supported in Paper 1.12+ and Spigot 1.13.1+\n\n### getBlockState\n```java\npublic class PaperLib {\n  public static BlockStateSnapshotResult getBlockState(Block block, boolean useSnapshot);\n}\n```\n\nAllows you to optionally avoid taking a snapshot of a TileEntity in a BlockState. Versions prior to 1.12 will always be\nfalse for the snapshot. In versions 1.12+ on Spigot, the snapshot will always be true. In Paper 1.12+, the snapshot will\nbe whether or not you requested one in the API call.\n\n### suggestPaper\n```java\npublic class PaperLib {\n  public static void suggestPaper(Plugin plugin);\n}\n```\nHelps inform users who run your plugin on Spigot that your plugin will behave better on Paper! Calling this method\nwill print out an informational message in the logs that they should switch to Paper, and will help users discover\nour software. We would appreciate it if you call this method, but it is optional.\n\n## Example Plugin\n```java\npublic class MyPlugin extends JavaPlugin {\n    public void onEnable() {\n        PaperLib.suggestPaper(this);\n    }\n    \n    public void doSomething(Entity entity, Location location) {\n        PaperLib.teleportAsync(entity, location).thenAccept(result -\u003e {\n            if (result) {\n                player.sendMessage(\"Teleported!\");\n            } else {\n                player.sendMessage(\"Something went wrong!\");\n            }\n        });\n    }\n}\n```\n\n## Build Script Setup\nAdd the Paper repository and the PaperLib dependency, then shade and relocate it to your own package.\nRelocation helps avoid version conflicts with other plugins using PaperLib. \n\n### Gradle\n\nRepo:\n```groovy\nrepositories {\n    maven {\n        name \"papermc\"\n        url \"https://papermc.io/repo/repository/maven-public/\"\n    }\n}\n```\n\nDependency:\n```groovy\ndependencies {\n    implementation \"io.papermc:paperlib:1.0.7\"\n}\n```\n\nShadow Jar and Relocate (Groovy Syntax):\n```groovy\nplugins {\n  id \"com.github.johnrengelman.shadow\" version \"7.1.0\"\n  // Make sure to always use the latest version (https://plugins.gradle.org/plugin/com.github.johnrengelman.shadow)\n}\nshadowJar {\n   relocate \"io.papermc.lib\", \"[YOUR PLUGIN PACKAGE].paperlib\"\n}\n```\n\n### Maven\nRepo:\n```xml\n\u003crepositories\u003e\n    \u003crepository\u003e\n        \u003cid\u003epapermc\u003c/id\u003e\n        \u003curl\u003ehttps://papermc.io/repo/repository/maven-public/\u003c/url\u003e\n    \u003c/repository\u003e\n\u003c/repositories\u003e\n```\nDependency:\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eio.papermc\u003c/groupId\u003e\n        \u003cartifactId\u003epaperlib\u003c/artifactId\u003e\n        \u003cversion\u003e1.0.7\u003c/version\u003e\n        \u003cscope\u003ecompile\u003c/scope\u003e\n     \u003c/dependency\u003e\n \u003c/dependencies\u003e\n ```\n \nShade \u0026 Relocate:\n```xml\n\u003cbuild\u003e\n    \u003cplugins\u003e\n        \u003cplugin\u003e\n            \u003cgroupId\u003eorg.apache.maven.plugins\u003c/groupId\u003e\n            \u003cartifactId\u003emaven-shade-plugin\u003c/artifactId\u003e\n            \u003cversion\u003e3.2.4\u003c/version\u003e \u003c!-- Make sure to always use the latest version (https://maven.apache.org/plugins/maven-shade-plugin/) --\u003e\n            \u003cconfiguration\u003e\n                \u003cdependencyReducedPomLocation\u003e${project.build.directory}/dependency-reduced-pom.xml\u003c/dependencyReducedPomLocation\u003e\n                \u003crelocations\u003e\n                    \u003crelocation\u003e\n                        \u003cpattern\u003eio.papermc.lib\u003c/pattern\u003e\n                        \u003cshadedPattern\u003e[YOUR PLUGIN PACKAGE].paperlib\u003c/shadedPattern\u003e \u003c!-- Replace this --\u003e\n                    \u003c/relocation\u003e\n                \u003c/relocations\u003e\n            \u003c/configuration\u003e\n            \u003cexecutions\u003e\n                \u003cexecution\u003e\n                    \u003cphase\u003epackage\u003c/phase\u003e\n                    \u003cgoals\u003e\n                        \u003cgoal\u003eshade\u003c/goal\u003e\n                    \u003c/goals\u003e\n                \u003c/execution\u003e\n            \u003c/executions\u003e\n        \u003c/plugin\u003e\n    \u003c/plugins\u003e\n\u003c/build\u003e\n```\n\n## Compiling\nPaperLib is compiled using Gradle:\n```\n./gradlew build\n```\n\n## License\nPaperLib is licensed under the [MIT license](LICENSE)\n","funding_links":["https://github.com/sponsors/PaperMC","https://opencollective.com/PaperMC"],"categories":["Projects","Java"],"sub_categories":["Runtime"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPaperMC%2FPaperLib","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FPaperMC%2FPaperLib","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FPaperMC%2FPaperLib/lists"}