API et événements

CobaltStaff expose des événements Bukkit et des services Java pour que vos plugins réagissent aux actions du staff ou interrogent son état (mute, ban, vanish, mode staff…). Toutes les classes sont dans le package fr.cobaltia.staff.

Mise en place

1. Ajoutez le jar de CobaltStaff à votre projet en dépendance fournie (non incluse dans votre 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. Déclarez la dépendance dans le plugin.yml de votre plugin :

   softdepend: [CobaltStaff]   # ou depend si CobaltStaff est obligatoire

3. Récupérez le core puis le service voulu au moment où vous en avez besoin.

Accéder aux 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 si le plugin est arrêté
    }
    return null;
}

// Plus tard, au moment de l’usage :
SanctionQuery q = core.service(SanctionQuery.class);   // null si le module sanctions est désactivé
if (q != null && q.muet(player.getUniqueId())) {
    // le joueur est muet
}

Attention

Appelez core.service(...) au moment de l’usage, sans garder le résultat en cache : un service est absent si son module est désactivé. core.serviceOpt(...) renvoie un Optional.

Services disponibles

Socle (lecture simple)

Interfaces du package fr.cobaltia.staff.core, stables et faciles à utiliser :

Interface	Méthodes	Fournie par
SanctionQuery	resume(UUID) → score, muet, banni, banni IP, nombres de warns, mutes, bans, kicks ; score(UUID) ; muet(UUID) ; banni(UUID) ; bansActifs() ; mutesActifs()	sanctions
VanishQuery	vanish(Player), voit(Player observateur, Player cible)	staffmode
StaffModeQuery	enModeStaff(Player)	staffmode
FreezeQuery	gele(Player)	staffmode
SanctionMenuOpener	ouvrir(Player staff, UUID cible, String nomCible[, String raison]) : ouvre le menu de sanction	sanctions

Modules (complet)

Classe	Exemples de méthodes
sanctions.SanctionService	banActif(UUID), banActif(UUID, String ip), muteActif(UUID), muet(Player), score(UUID), casier(UUID), 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 canal, String message), filtrer(String)

Threads

• Les méthodes qui lisent la base renvoient un CompletableFuture, complété sur le thread de base de données de CobaltStaff. Pour toucher au monde, aux inventaires ou aux joueurs, revenez sur le thread du serveur :

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

• Les méthodes qui lisent le cache (muet, banni, bansActifs, muteActif, vanish, enModeStaff, gele…) sont instantanées et utilisables sur n’importe quel thread.

Événements

Tous les événements sont appelés sur le thread du serveur, après l’action (sauf indication contraire).

Événement	Quand	Accesseurs
sanctions.SanctionEvent	Ban, ban IP, mute ou kick créé, levé, prolongé ou réduit	sanction(), action() (CREATION, LEVEE, PROLONGATION, REDUCTION), auteur() (null si automatique)
sanctions.WarnEvent	Warn créé, expiré, supprimé, appel accepté ou refusé	warn(), action() (CREATION, EXPIRATION, SUPPRESSION, APPEL_ACCEPTE, APPEL_REFUSE), auteur(), score()
sanctions.ThresholdReachedEvent	Un palier de warns est lancé (avant ses actions)	joueur(), nom(), score(), palier(), warn()
reports.ReportCreatedEvent	Report ou ticket créé	report()
reports.ReportStatusEvent	Statut d’un report modifié	report(), ancien(), nouveau(), action(), acteur() (null = console), acteurNom()
staffmode.StaffModeEvent	Entrée ou sortie du mode staff	joueur(), mode(), entree()
staffmode.VanishEvent	Vanish activé ou retiré	joueur(), type() (TOTAL, LIST, PLAYER), actif()
staffmode.FreezeEvent	Freeze ou dégel	cible(), staff() (null = automatique), gele()
core.NomChangeEvent	Connexion avec un pseudo différent du dernier connu	joueur(), uuid(), ancien(), nouveau()

Exemple : relayer les 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() + " banni par " + s.staffNom() + " : " + s.raison());
        }
    }
}

Une Sanction donne notamment id(), type() (BAN, MUTE, KICK, WARN), cible(), cibleNom(), staffNom(), raison(), duree(), fin(), ipBan(), gravite(), points() et permanente(). Un Report donne id(), genre() (JOUEUR, GENERAL, TICKET), type(), raison(), reporter(), cible(), assigne(), statut() (OPEN, IN_PROGRESS, RESOLVED, REJECTED, DELETED).

Sans écrire de Java

• Les hooks lancent des commandes à chaque sanction, palier, report, enquête ou freeze : voir Hooks.
• Les placeholders donnent l’état des joueurs et du serveur à n’importe quel plugin compatible PlaceholderAPI : voir Placeholders.
• Les contextes LuckPerms cobaltstaff:staffmode, cobaltstaff:vanished et cobaltstaff:frozen conditionnent vos permissions.