BlazeBans API

The API exists because a punishment is the most useful signal a moderation plugin has, and other plugins usually want to act on it. Things people build:

• Ban effects. Delay enforcement for a few seconds and play something before the player is removed. The ban effects addon is exactly this, built on this API and nothing private.
• Extra enforcement. Voice mutes, region restrictions, or blocking a feature while a player has an active warning.
• Appeal and web integrations. Read a record by ID, revoke it when an appeal is accepted, and attribute the action to the staff member who decided it.
• Exemptions. Let one command through while a player is muted, or stop a punishment being created under conditions only your plugin knows about.
• Analytics and alerting. Post punishments somewhere BlazeBans does not, or report on staff activity.

The API is Paper-only. Its events are Bukkit events, which Velocity does not have, so a Velocity plugin cannot use this. A proxy plugin that needs punishment data should read the shared database directly or talk to a backend that can.

Worth knowing before you plan around it.

Configuration. You cannot read or write settings.yml, templates.yml, or any other BlazeBans config through the API. Your addon keeps its own config.

Templates and ladders. Applying a template by ID is not exposed. Create the punishment you want with an explicit duration and reason, or run the command from console.

Messages and menus. BlazeBans' own output is not addressable. Your addon sends its own messages.

The internals. BlazeBans ships obfuscated, and everything outside net.blazebans.api is repackaged with no stable names. The API package is the whole supported surface, and the build fails if any of its class names change, so what you compile against will keep working. Reaching past it into an implementation class will break on the next release.

Three entry points, and everything hangs off them.

BlazeBansApi api = BlazeBansProvider.get();

api.version();      // the running BlazeBans version
api.punishments();  // PunishmentService: read and write records
api.players();      // PlayerService: profiles, name history, alts

Plus seven Bukkit events you register listeners for in the normal way, and a small addon-registration helper so your plugin appears in /blazebans addons.

Every service method returns a CompletableFuture, because all of them may hit the database. That is the single most important thing about using this API correctly, and it has its own page.

If you are starting a project, read these four in order:

1. Project setup to compile against BlazeBans.
2. Getting the API to obtain the instance safely.
3. Threading before you write anything real.
4. Build one end to end for a complete working addon.

If you have a specific job in mind, Recipes is probably faster.