Developer API

Developer API

If you're writing your own plugin and want to hook into SXBans — check if a player's banned, issue a punishment programmatically, pull history for your own UI — this is how.

Adding it as a dependency

Add SXBans as a depend (or softdepend if you want your plugin to work with it absent) in your plugin.yml:

depend: [SXBans]

Getting the API

import ir.sxtm.sxbans.api.SXBansAPI;

SXBansAPI api = SXBansAPI.getInstance();

From there you've got two things to work with: a set of quick lookup methods directly on SXBansAPI, and the full PunishmentAPI for anything that actually issues or modifies punishments.

Quick lookups

api.isPlayerBanned(uuid);
api.isPlayerMuted(uuid);
api.isIpBanned("123.45.67.89");
api.isIpMuted("123.45.67.89");

Punishment ban = api.getActiveBan(uuid);     // null if not banned
Punishment mute = api.getActiveMute(uuid);   // null if not muted

List<Punishment> history = api.getPlayerPunishments(uuid);
int warnings = api.getWarningCount(uuid);

Issuing punishments

Everything punishment-related lives on PunishmentAPI:

PunishmentAPI punishments = api.getPunishmentAPI();

// Ban an online player
punishments.banPlayer(targetPlayer, "Cheating", executorPlayer);

// Ban someone who isn't online
punishments.banPlayer(targetUUID, "Steve", "Cheating", executorUUID, "AdminName");

// Temp ban, mute, temp mute, kick, warn all follow the same pattern
punishments.tempBanPlayer(targetPlayer, "Spamming", TimeUnit.HOURS.toMillis(6), executorPlayer);
punishments.mutePlayer(targetPlayer, "Toxicity", executorPlayer);
punishments.warnPlayer(targetPlayer, "First offense", executorPlayer);

// IP ban
punishments.banIP("123.45.67.89", "Ban evasion", executorPlayer);

// Remove a punishment by its ID
punishments.removePunishment(punishmentId, executorPlayer, "Appeal accepted");

Every "online player" overload has a matching UUID/name overload for when the target isn't connected — duration values are always in milliseconds.

Reading punishment data

Punishment p = punishments.getPunishment(punishmentId);
List<Punishment> active = punishments.getActivePunishments(targetPlayer);
List<Punishment> all = punishments.getAllPunishments();
List<HistoryEntry> history = punishments.getPlayerHistory(targetPlayer);

Checking bypass status

boolean exempt = punishments.isExempt(player, PunishmentType.BAN);

Useful if you're building your own moderation feature and want to respect the same bypass permissions (sxbans.bypass.*) that SXBans itself honors.

A note on threading

Punishment application does I/O (writing to whatever database backend you're using). If you're calling these methods from a hot path or an async context, keep in mind the same threading rules that apply to the rest of Bukkit's API — don't touch Bukkit API objects like Player off the main thread. The UUID/name overloads are generally the safer choice if you're not certain what thread you're on.

Events

SXBans doesn't currently fire custom Bukkit events for punishments — if you need to react to a punishment happening elsewhere in your plugin (logging it, triggering a Discord webhook, whatever), the cleanest approach right now is polling getAllPunishments()/getPlayerHistory() on your own schedule, or wrapping calls that go through your own code with your own event. Native event support may come in a future version.