BlazeBans API/Getting started

Project setup

Getting a project compiling against BlazeBans. Download one jar, add one dependency line, and add one `plugin.yml` entry.

Download the API

DownloadsVersion 1.0.0

blazebans-api-1.0.0.jar
Compile against this. Everything you need to build a plugin or addon.
Download blazebans-api-1.0.0.jar
26.1 KBSHA-256 f2874ab18965e3636b055e78e662d7e924855f4e3e1b01c9ad648cf7ff58fd7e
blazebans-api-1.0.0-sources.jar
Optional. Attach in your IDE for inline signatures and documentation.
Download blazebans-api-1.0.0-sources.jar
13.3 KBSHA-256 5264ed5636a3890704a043d186df22acfb1a8e83c80344a2a2b2422cfde2ff91

The API jar contains the net.blazebans.api package and nothing else. No implementation, no obfuscated classes, roughly 27 KB. You compile against it and BlazeBans supplies the real classes at runtime.

The sources jar is optional. Attach it in your IDE and you get parameter names and signatures inline while you type.

Verify a download before you build against it:

bash

sha256sum blazebans-api-1.0.0.jar

The expected value is printed beside the file above.

Compile-only, never bundled

BlazeBans provides these classes at runtime. If you shade or bundle them into your own jar you end up with two copies on the classpath and your plugin fails to load.

Keep it compileOnly in Gradle and provided in Maven. If you use the Shadow plugin, make sure the API is not in a configuration it shades.

Gradle (Kotlin)

Put the jar in a libs/ directory beside your build script.

kotlin

repositories {
    mavenCentral()
    maven("https://repo.papermc.io/repository/maven-public/")
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT")
    compileOnly(files("libs/blazebans-api-1.0.0.jar"))
}

java {
    toolchain.languageVersion.set(JavaLanguageVersion.of(21))
}

tasks.withType<JavaCompile> {
    options.encoding = "UTF-8"
    options.release.set(21)
}

Match the Paper version to the server you target.

Gradle (Groovy)

groovy

repositories {
    mavenCentral()
    maven {
        name = "PaperMC"
        url = "https://repo.papermc.io/repository/maven-public/"
    }
}

dependencies {
    compileOnly("io.papermc.paper:paper-api:1.21.11-R0.1-SNAPSHOT")
    compileOnly(files("libs/blazebans-api-1.0.0.jar"))
}

java {
    toolchain.languageVersion = JavaLanguageVersion.of(21)
}

tasks.withType(JavaCompile).configureEach {
    options.encoding = "UTF-8"
    options.release.set(21)
}

Maven

Install the jar into your local repository once:

bash

mvn install:install-file -Dfile=libs/blazebans-api-1.0.0.jar \
  -DgroupId=net.blazebans -DartifactId=blazebans-api \
  -Dversion=1.0.0 -Dpackaging=jar

Then depend on it normally:

xml

<properties>
  <maven.compiler.release>21</maven.compiler.release>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<repositories>
  <repository>
    <id>papermc</id>
    <url>https://repo.papermc.io/repository/maven-public/</url>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>io.papermc.paper</groupId>
    <artifactId>paper-api</artifactId>
    <version>1.21.11-R0.1-SNAPSHOT</version>
    <scope>provided</scope>
  </dependency>
  <dependency>
    <groupId>net.blazebans</groupId>
    <artifactId>blazebans-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
  </dependency>
</dependencies>

Declaring the dependency

Your plugin.yml has to tell Paper about BlazeBans, or your plugin can load first and find nothing.

yaml

name: MyBlazeBansAddon
version: '1.0.0'
main: com.example.myaddon.MyAddon
api-version: '1.21'
depend:
  - BlazeBans

depend means Paper will not enable your plugin unless BlazeBans enabled first. That is what you want for an addon: with BlazeBans missing, your plugin has nothing to do.

Use softdepend only when your plugin is useful on its own and BlazeBans support is a bonus:

yaml

softdepend:
  - BlazeBans

With softdepend you have to handle the API being absent at every call site, and you may be enabled before BlazeBans is. See Getting the API.

Version compatibility

The class and member names in net.blazebans.api are frozen. BlazeBans ships obfuscated, and its release build fails outright if any public API name changes, so a plugin compiled against 1.0.0 keeps linking against later versions.

That guarantee covers the API package only. Everything else inside the BlazeBans jar is repackaged with names that change every release, so do not try to reach past the API into an implementation class.

Checking it compiles

The smallest thing that proves the wiring works:

java

package com.example.myaddon;

import net.blazebans.api.BlazeBansApi;
import net.blazebans.api.BlazeBansProvider;
import org.bukkit.plugin.java.JavaPlugin;

public final class MyAddon extends JavaPlugin {
    @Override
    public void onEnable() {
        BlazeBansApi api = BlazeBansProvider.get();
        getLogger().info("BlazeBans " + api.version());
    }
}

Build it, drop your jar and BlazeBans into a test server's plugins/, and start. The console should print the BlazeBans version.

If it does not, Getting the API covers every way that call can fail.

A test server in one command

The Gradle run-paper plugin is worth the four lines:

groovy

plugins {
    id 'java'
    id 'xyz.jpenilla.run-paper' version '3.0.2'
}

tasks {
    runServer {
        minecraftVersion("1.21.11")
    }
}

./gradlew runServer builds your plugin and starts a server with it loaded. Copy the BlazeBans jar into the generated run/plugins/ directory once and it stays there between runs.