API and events

CobaltStaff exposes Bukkit events and Java services so your plugins can react to staff actions or query its state (mute, ban, vanish, staff mode…). All classes live in the fr.cobaltia.staff package. Method names are in French; their meaning is given below.

Setup

1. Add the CobaltStaff jar to your project as a provided dependency (not shaded into your jar).

   Maven

   <dependency>
     <groupId>fr.cobaltia</groupId>
     <artifactId>CobaltStaff</artifactId>
     <version>1.0.0</version>
     <scope>system</scope>
     <systemPath>${project.basedir}/libs/CobaltStaff-1.0.0.jar</systemPath>
   </dependency>

   Gradle

   dependencies {
       compileOnly(files("libs/CobaltStaff-1.0.0.jar"))
   }

2. Declare the dependency in your plugin’s plugin.yml:

   softdepend: [CobaltStaff]   # or depend if CobaltStaff is mandatory

3. Get the core, then the service you need, at the time you need it.

Accessing services

import fr.cobaltia.staff.CobaltStaff;
import fr.cobaltia.staff.core.Core;
import fr.cobaltia.staff.core.SanctionQuery;
import org.bukkit.Bukkit;

Core core() {
    if (Bukkit.getPluginManager().getPlugin("CobaltStaff") instanceof CobaltStaff cs) {
        return cs.core();          // null if the plugin is stopped
    }
    return null;
}

// Later, when needed:
SanctionQuery q = core.service(SanctionQuery.class);   // null if the sanctions module is disabled
if (q != null && q.muet(player.getUniqueId())) {       // muet = muted
    // the player is muted
}

Caution

Call core.service(...) when you need it, without caching the result: a service is missing when its module is disabled. core.serviceOpt(...) returns an Optional.

Available services

Core (simple reads)

Interfaces of the fr.cobaltia.staff.core package, stable and easy to use:

Interface	Methods	Provided by
SanctionQuery	resume(UUID) → score, muted, banned, IP-banned, warn/mute/ban/kick counts; score(UUID); muet(UUID) (muted); banni(UUID) (banned); bansActifs(); mutesActifs()	sanctions
VanishQuery	vanish(Player), voit(Player viewer, Player target) (can see)	staffmode
StaffModeQuery	enModeStaff(Player) (in staff mode)	staffmode
FreezeQuery	gele(Player) (frozen)	staffmode
SanctionMenuOpener	ouvrir(Player staff, UUID target, String targetName[, String reason]): opens the sanction menu	sanctions

Modules (full)

Class	Example methods
sanctions.SanctionService	banActif(UUID), banActif(UUID, String ip), muteActif(UUID), muet(Player), score(UUID), casier(UUID) (record), sanction(long id), compteursActifs(), recentes(TypeSanction, int), totaux()
reports.ReportService	ouverts(), enCours(), ticketsOuverts(), ouvertsSur(UUID), totalSur(UUID), actifsPar(UUID), assignesA(UUID), actifs(), actif(long id), charger(long id), rechercher(Criteres, int)
staffmode.StaffmodeApi	modeCourant(Player), modeExiste(String), entrerMode(Player, String), sortirMode(Player), typeVanish(Player), vanish(Player, String), unvanish(Player), basculerGel(CommandSender, Player), spectate(Player, Player)
investigation.InvestigationService	protege(UUID), enEnquete(UUID), trace(UUID), nombreNotes(UUID), lieu(String), lieux(), teleporter(Player, Location), examiner(Player, Player), fiche(Player, UUID, String), cps(Player, Player), lierPreuve(Player, String, String)
chat.ChatService	canalActif(Player), canalMuet(Player, String), verrouille(), intervalleSlow(), envoyerStaffChat(CommandSender, String channel, String message), filtrer(String)

Threads

• Methods that read the database return a CompletableFuture, completed on CobaltStaff’s database thread. To touch the world, inventories or players, go back to the server thread:

  q.resume(uuid).thenAccept(r ->
      Bukkit.getScheduler().runTask(myPlugin, () -> player.sendMessage("Score: " + r.score())));

• Methods that read the cache (muet, banni, bansActifs, muteActif, vanish, enModeStaff, gele…) are instant and usable from any thread.

Events

All events are called on the server thread, after the action (unless stated otherwise).

Event	When	Accessors
sanctions.SanctionEvent	Ban, IP ban, mute or kick created, lifted, extended or reduced	sanction(), action() (CREATION, LEVEE, PROLONGATION, REDUCTION), auteur() (null if automatic)
sanctions.WarnEvent	Warn created, expired, deleted, appeal accepted or rejected	warn(), action() (CREATION, EXPIRATION, SUPPRESSION, APPEL_ACCEPTE, APPEL_REFUSE), auteur(), score()
sanctions.ThresholdReachedEvent	A warn threshold is triggered (before its actions)	joueur(), nom(), score(), palier(), warn()
reports.ReportCreatedEvent	Report or ticket created	report()
reports.ReportStatusEvent	A report’s status changed	report(), ancien(), nouveau(), action(), acteur() (null = console), acteurNom()
staffmode.StaffModeEvent	Staff mode entry or exit	joueur(), mode(), entree()
staffmode.VanishEvent	Vanish enabled or removed	joueur(), type() (TOTAL, LIST, PLAYER), actif()
staffmode.FreezeEvent	Freeze or unfreeze	cible(), staff() (null = automatic), gele()
core.NomChangeEvent	Login with a name different from the last known one	joueur(), uuid(), ancien(), nouveau()

Example: relaying bans

import fr.cobaltia.staff.sanctions.SanctionEvent;
import fr.cobaltia.staff.sanctions.TypeSanction;
import org.bukkit.Bukkit;
import org.bukkit.event.EventHandler;
import org.bukkit.event.Listener;

public final class BanListener implements Listener {
    @EventHandler
    public void onSanction(SanctionEvent e) {
        var s = e.sanction();
        if (s.type() == TypeSanction.BAN && e.action() == SanctionEvent.Action.CREATION) {
            Bukkit.getLogger().info(s.cibleNom() + " banned by " + s.staffNom() + ": " + s.raison());
        }
    }
}

A Sanction notably provides id(), type() (BAN, MUTE, KICK, WARN), cible() (target), cibleNom(), staffNom(), raison() (reason), duree() (duration), fin() (end), ipBan(), gravite() (severity), points() and permanente(). A Report provides id(), genre() (JOUEUR, GENERAL, TICKET), type(), raison(), reporter(), cible(), assigne(), statut() (OPEN, IN_PROGRESS, RESOLVED, REJECTED, DELETED).

Without writing Java

• Hooks run commands on every sanction, threshold, report, investigation or freeze: see Hooks.
• Placeholders expose player and server state to any PlaceholderAPI-compatible plugin: see Placeholders.
• LuckPerms contexts cobaltstaff:staffmode, cobaltstaff:vanished and cobaltstaff:frozen condition your permissions.