Skip to content

Plugin development

How to use Maven dependencies in Minecraft plugins

Understand provided and compile scopes, shading and plugin.yml dependencies when your Minecraft plugin uses another plugin's API.

  • Maven
  • Gradle
  • Java

A Minecraft plugin usually depends on two kinds of libraries: APIs provided by the server or other plugins at runtime, and libraries that your plugin must carry inside its JAR.

Provided vs compile

ScopeWhenExample
provided (Maven) / compileOnly (Gradle)The class already exists on the server at runtimeSpigot/Paper API, another plugin's API
compile (Maven) / implementation (Gradle)Your plugin must bring itA JSON or HTTP library

If you include another plugin's API in your JAR, two copies of the same classes exist at runtime, which causes class conflicts. Always use provided for plugin APIs.

Shading and relocation

Libraries you do bring are often shaded into the JAR and relocated to a private package so they do not collide with another plugin that bundles a different version. sofyCore itself relocates its database and network libraries for this reason.

Declare the plugin dependency

Compiling against an API is not enough: Bukkit must also load the other plugin first. Declare it in plugin.yml:

plugin.ymlYAML
depend: [sofyCore]     # required
# softdepend: [sofyCore]  # optional integration

Example with sofyCore

See Maven & Gradle setup for the exact coordinates of sofycore-api.