Référence de l’API développeur

Verité expose une API Java publique stable sous le paquet teacommontea.api. Chaque sous-système est une façade de méthodes statiques par-dessus des types publics stables, de sorte que vous pouvez faire tout ce que fait le plugin sans jamais référencer une classe d’implémentation interne.

Cette page est la surface complète, organisée pour la consultation. Deux sujets ont leurs propres guides dédiés et ne sont ici que référencés :

Le filtre de chat : Intégration d’un chat personnalisé.
L’application des sourdines, du mode lent et du gel : Application de la modération personnalisée.

Pour commencer

Ajouter Verité en tant que dépendance facultative

Ajoutez Verité à votre plugin.yml afin qu’il se charge avant votre plugin lorsqu’il est installé, sans devenir obligatoire :

softdepend:
  - Verite

Se prémunir contre l’indisponibilité

Si Verité est facultatif, vérifiez la présence d’une classe avant de toucher à l’API :

private static final boolean VERITE_AVAILABLE;

static {
    boolean available;
    try {
        Class.forName("teacommontea.api.VeriteAPI");
        available = true;
    } catch (ClassNotFoundException ignored) {
        available = false;
    }
    VERITE_AVAILABLE = available;
}

Chaque sous-système se dégrade également de lui-même : lorsque le module sous-jacent est désactivé, les méthodes de requête renvoient null, false ou une collection vide, les appels modifiants deviennent sans effet, et les appels d’émission renvoient un résultat en échec. Vous avez rarement à traiter un module désactivé comme un cas particulier.

VeriteAPI

VeriteAPI est le point d’entrée unique et global. Il indique la version de l’API, indique quels modules sont activés et renvoie la classe de chaque sous-système pour la découverte.

Membre	Renvoie	Signification
`VeriteAPI.VERSION`	`String`	La chaîne de version de l’API.
`moderationEnabled()`	`boolean`	Si le module de modération est chargé.
`vanishEnabled()`	`boolean`	Si le module d’invisibilité est chargé.
`captchaEnabled()`	`boolean`	Si le module de captcha est chargé.
`moderation()`	`Class<VeriteModeration>`	La classe du sous-système de modération.
`playerData()`	`Class<VeritePlayerData>`	La classe du sous-système de données de joueur.
`store()`	`Class<VeriteStore>`	La classe du sous-système de stockage.
`vanish()`	`Class<VeriteVanish>`	La classe du sous-système d’invisibilité.
`captcha()`	`Class<VeriteCaptcha>`	La classe du sous-système de captcha.
`filter()`	`Class<VeriteFilter>`	La classe du sous-système de filtre de chat.
`text()`	`Class<VeriteText>`	La classe du sous-système de mise en forme du texte.

Tous les sous-systèmes sont des façades statiques, vous les appelez donc directement (par exemple VeriteModeration.isBanned(uuid)). Les méthodes d’accès existent pour la découverte et les vérifications d’activation centralisées.

VeriteModeration

Le point d’entrée complet pour émettre, interroger et lever des sanctions. durationMillis utilise Punishment.PERMANENT pour une sanction permanente. Les méthodes de barrière renvoient true lorsqu’elles ont arrêté le joueur. Voir Application de la modération personnalisée pour le flux de travail des barrières et des écouteurs en détail.

État et requêtes

Méthode	Renvoie	Signification
`enabled()`	`boolean`	Si le module de modération est chargé.
`isBanned(UUID player)`	`boolean`	Si le joueur a un bannissement actif.
`isMuted(UUID player)`	`boolean`	Si le joueur a une sourdine active.
`activeBan(UUID player)`	`Punishment`	Le bannissement actif, ou `null`.
`activeMute(UUID player)`	`Punishment`	La sourdine active, ou `null`.
`history(UUID player, int limit)`	`List<Punishment>`	L’historique récent des sanctions du joueur.
`byIp(String ip, int limit)`	`List<Punishment>`	Les sanctions enregistrées contre une ip.
`byStaff(UUID staff, int limit)`	`List<Punishment>`	Les sanctions émises par un membre du personnel.
`activeWarnings(UUID player)`	`List<Punishment>`	Les avertissements actuellement actifs du joueur.
`activePunishments()`	`List<ActivePunishment>`	Des pointeurs légers vers chaque sanction active.
`activeOfType(PunishmentType type, long now)`	`List<Punishment>`	Les sanctions actives d’un type à un instant donné.
`loadPunishment(long id)`	`Punishment`	L’enregistrement complet pour un id numérique, ou `null`.
`altsOf(UUID player)`	`List<UUID>`	Les comptes partageant la première ip connue du joueur.
`pruneHistory(UUID player, long cutoff, long now)`	`int`	Supprime l’historique plus ancien que le seuil, renvoie le nombre supprimé.
`warningExpire()`	`long`	La fenêtre d’expiration des avertissements en millisecondes.

Émission de sanctions

Méthode	Renvoie
`ban(UUID target, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)`	`PunishmentResult`
`mute(UUID target, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)`	`PunishmentResult`
`ipban(UUID target, String ip, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)`	`PunishmentResult`
`ipmute(UUID target, String ip, String targetName, String reason, UUID executor, String executorName, long durationMillis, boolean silent)`	`PunishmentResult`
`warn(UUID target, String targetName, String reason, UUID executor, String executorName, boolean silent)`	`PunishmentResult`
`kick(UUID target, String targetName, String reason, UUID executor, String executorName, boolean silent)`	`PunishmentResult`

Levée de sanctions

Méthode	Renvoie	Signification
`unban(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Lève le bannissement actif, `true` en cas de succès.
`unmute(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Lève la sourdine active, `true` en cas de succès.
`unwarn(UUID target, String targetName, UUID removedBy, String removedByName, String reason)`	`PunishmentResult`	Retire un avertissement.

Rendu et avis

Méthode	Renvoie	Signification
`banScreen(Punishment ban)`	`String`	L’écran de bannissement complet pour un enregistrement de bannissement.
`muteLine(Punishment mute)`	`String`	Le résumé de sourdine sur une ligne.
`muteNotice(Punishment mute)`	`String`	L’avis de sourdine envoyé à un joueur réduit au silence.

Barrières de chat

Chaque barrière renvoie true lorsque le joueur devrait être arrêté et lui envoie la raison en effet de bord. Utilisez-les là où vous comptez appliquer.

Méthode	Renvoie	Signification
`muteGate(Player p)`	`boolean`	Le joueur est réduit au silence ; envoie l’avis de sourdine.
`chatMuteGate(Player p)`	`boolean`	Le gel du chat global est actif ; envoie l’avis de gel.
`slowmodeGate(Player p)`	`boolean`	Le joueur est retenu par le mode lent ; envoie l’attente restante.

Commandes de chat

Elles pilotent les propres commandes de chat du plugin pour un CommandSender.

Méthode	Signification
`broadcast(CommandSender sender, String[] args)`	Envoie une diffusion.
`chatClear(CommandSender sender)`	Efface le chat.
`chatMute(CommandSender sender)`	Bascule le gel du chat global.
`slowmode(CommandSender sender, String[] args)`	Règle le mode lent.

Écouteur

Méthode	Signification
`registerListener(ModerationListener listener)`	S’abonner à l’activité de sanction.
`unregisterListener(ModerationListener listener)`	Cesser de recevoir les événements.

VeritePlayerData

Lire et enregistrer les données de compte, de session et d’identité que le système de modération stocke. Les horodatages sont en millisecondes depuis l’époque. Lorsque le module est désactivé, les requêtes renvoient null ou vide et les appels d’enregistrement sont sans effet.

Méthode	Renvoie	Signification
`enabled()`	`boolean`	Si le magasin de données est ouvert.
`hasProfile(UUID player)`	`boolean`	Si un profil existe.
`profile(UUID player)`	`PlayerProfile`	Le profil complet, ou `null`.
`uuidByName(String name)`	`UUID`	Résoudre un uuid à partir d’un nom.
`nameOf(UUID player)`	`String`	Résoudre le nom actuel à partir d’un uuid.
`knownNames()`	`List<String>`	Tous les noms connus dans le magasin.
`namesOf(UUID player)`	`List<String>`	Tous les noms qu’un joueur a utilisés.
`ipsOf(UUID player)`	`List<String>`	Toutes les ip depuis lesquelles un joueur s’est connecté.
`usersOfIp(String ip)`	`List<UUID>`	Tous les utilisateurs ayant partagé une ip.
`clientsOf(UUID player)`	`List<String>`	Tous les clients qu’un joueur a utilisés.
`recordLogin(UUID player, String name, String ip, long now)`	`void`	Enregistrer une connexion.
`recordClient(UUID player, String brand, int protocol, String referrer, long now)`	`void`	Enregistrer la marque et le protocole d’un client.
`flushSession(UUID player, long now)`	`void`	Vider la session du joueur.
`recordLogout(UUID player, long now)`	`void`	Enregistrer une déconnexion.

VeriteStore et VeriteScope

VeriteStore ouvre des portées de données nommées dans le magasin clé-valeur persistant partagé du plugin, de sorte que votre plugin peut persister des données aux côtés de Verité sans base de données propre. Nommez vos portées avec un espace de noms pour éviter les collisions avec les données du plugin.

Méthode de `VeriteStore`	Renvoie	Signification
`available()`	`boolean`	Si le magasin est ouvert.
`scope(String name)`	`VeriteScope`	Ouvre une portée nommée, ou `null` si indisponible.

Un VeriteScope est une zone nommée que vous lisez et écrivez librement. Les écritures persistent à travers le cycle de vidage normal du plugin.

Méthode de `VeriteScope`	Renvoie	Signification
`set(String key, Object value)`	`void`	Stocker une valeur sous une clé.
`delete(String key)`	`void`	Retirer une clé.
`has(String key)`	`boolean`	Tester la présence d’une clé.
`get(String key)`	`Object`	La valeur brute stockée.
`getString(String key, String def)`	`String`	Lecture typée avec une valeur par défaut.
`getLong(String key, long def)`	`long`	Lecture typée avec une valeur par défaut.
`getInt(String key, int def)`	`int`	Lecture typée avec une valeur par défaut.
`getBoolean(String key, boolean def)`	`boolean`	Lecture typée avec une valeur par défaut.
`getBigDecimal(String key)`	`BigDecimal`	Lecture typée.
`entries()`	`List<ScopeEntry>`	Chaque paire clé-valeur de la portée.

VeriteScope scope = VeriteStore.scope("myplugin");
if (scope != null) {
    scope.set("greeting", "hello");
    String greeting = scope.getString("greeting", "");
}

VeriteVanish

État et contrôle de l’invisibilité du personnel. vanish, unvanish et toggle renvoient true lorsque l’état a réellement changé. Lorsque le module est désactivé, les requêtes renvoient false ou vide et les appels modifiants sont sans effet.

Méthode	Renvoie	Signification
`enabled()`	`boolean`	Si le module d’invisibilité est chargé.
`isVanished(UUID player)`	`boolean`	Si un joueur est invisible.
`isVanished(Player player)`	`boolean`	Surcharge pratique pour un joueur en ligne.
`getVanished()`	`Set<UUID>`	Chaque joueur actuellement invisible.
`vanish(Player p)`	`boolean`	Rendre un joueur invisible.
`unvanish(Player p)`	`boolean`	Rendre un joueur de nouveau visible.
`toggle(Player p)`	`boolean`	Basculer l’état d’invisibilité d’un joueur.
`registerPlaceholders()`	`void`	Enregistrer l’extension PlaceholderAPI de l’invisibilité.
`registerListener(VanishListener listener)`	`void`	S’abonner aux changements d’invisibilité.
`unregisterListener(VanishListener listener)`	`void`	Cesser de recevoir les événements d’invisibilité.

VeriteCaptcha

Émettre et suivre des captchas. Les méthodes challenge renvoient true lorsqu’un captcha a réellement été démarré. L’étiquette source enregistre la raison de l’ouverture du captcha et se propage jusqu’aux événements de complétion et de demande de sanction. Lorsque le module est désactivé, tous les appels renvoient false.

Membre	Renvoie	Signification
`VeriteCaptcha.BYPASS_PERMISSION`	`String`	Le nœud de permission qui contourne le captcha.
`VeriteCaptcha.NOTIFY_PERMISSION`	`String`	Le nœud de permission de notification du captcha.
`enabled()`	`boolean`	Si le module de captcha est chargé.
`isActive(UUID player)`	`boolean`	Si un captcha est actif pour le joueur.
`challengeStandard(Player player, String source)`	`boolean`	Ouvrir un captcha standard.
`challengeDetailed(Player player, String source)`	`boolean`	Ouvrir un captcha détaillé.
`challenge(Player player, CaptchaType type, String source)`	`boolean`	Ouvrir un captcha d’un type explicite.

VeriteFilter

Le filtre de chat conscient de l’évitement. Le flux de travail complet, y compris les vérifications anonymes, les vérifications tenant compte des répétitions et les assistants de message de blocage, est documenté dans Intégration d’un chat personnalisé. La surface :

Membre	Renvoie	Signification
`VeriteFilter.ANONYMOUS`	`UUID`	À passer comme joueur lorsqu’il n’y a aucun contrevenant à enregistrer.
`check(UUID player, String message)`	`FilterResult`	Classer un message et enregistrer le signalement contre le joueur.
`check(UUID player, String message, boolean repeatAware)`	`FilterOutcome`	Classification tenant compte des répétitions.
`count(UUID player)`	`int`	Combien de fois un joueur a été signalé.
`blockMessage()`	`String`	Le message de blocage configuré.
`repeatMessage()`	`String`	L’avis de répétition configuré.
`selfHarmMessage()`	`String`	L’avis d’automutilation configuré.
`blockNotice(FilterResult result, String message)`	`BaseComponent[]`	Le composant d’avis rendu pour un résultat.
`foldAccents(String s)`	`String`	Assistant de normalisation : retirer les accents.
`stripDeletes(String s)`	`String`	Assistant de normalisation : retirer les caractères de largeur nulle et de suppression.
`stripEntities(String s)`	`String`	Assistant de normalisation : retirer les entités de style html.
`reduceRuns(String s, int max)`	`String`	Assistant de normalisation : réduire les lettres répétées.
`fingerprint(String word)`	`String`	Signature de lettres indépendante de l’ordre pour la correspondance par transposition.
`trimEdges(String word)`	`String`	Rogner les extrémités non lettres d’un mot.

Les assistants de normalisation sont des fonctions pures et peuvent être appelés en toute sécurité hors du fil principal.

VeriteText

Analyser du texte a balises Verite et appliquer le préfixe du plugin comme le fait le plugin, afin que votre sortie soit stylisée à l’identique.

Méthode	Renvoie	Signification
`parse(String tagged)`	`BaseComponent[]`	Analyser les balises Verite vers un tableau de composants.
`prefixed(String tagged)`	`BaseComponent[]`	Analyser et ajouter le préfixe du plugin en tête.
`prefix()`	`String`	Le préfixe actuel.
`setPrefix(String prefix)`	`void`	Changer le préfixe.

Utilitaires

VeriteGeoIp

Rechercher le pays d’une ip et vérifier l’état de la base de données GeoIP.

Méthode	Renvoie	Signification
`country(String ip)`	`String`	Nom du pays pour une ip, ou `null` si non résolu.
`available()`	`boolean`	Si la base de données GeoIP est chargée.
`isPrivate(String ip)`	`boolean`	Si une ip est dans une plage privée ou réservée.
`attempted()`	`boolean`	Si un chargement de base de données a été tenté.

VeriteDuration

Analyser et formater des durées de sanction lisibles par un humain, avec des constantes d’unités en millisecondes : SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR.

Méthode	Renvoie	Signification
`suggestions()`	`List<String>`	Jetons de durée suggérés.
`parse(String token)`	`long`	Analyser un jeton tel que `7d` en millisecondes.
`parseTwoToken(String number, String unitWord)`	`long`	Analyser un nombre et un mot d’unité séparés en millisecondes.
`format(long millis)`	`String`	Formater des millisecondes en une chaîne lisible.

VeriteFormat

Formater des heures, mettre des noms au pluriel et nommer les versions de protocole client.

Méthode	Renvoie	Signification
`fancyTime(long millis)`	`String`	Une durée en millisecondes sous forme de chaîne lisible.
`plural(long count, String noun)`	`String`	Un nombre avec le nom au singulier ou au pluriel correct.
`pluralize(long count, String noun)`	`String`	Un nombre avec le nom au singulier ou au pluriel correct.
`versionName(int protocol)`	`String`	Le nom de version Minecraft pour un numéro de protocole client.

VeriteLimits

Appliquer les mêmes plafonds de durée et délais d’attente par émetteur que le plugin.

Méthode	Renvoie	Signification
`capDuration(CommandSender issuer, PunishmentType type, long requested)`	`DurationCheck`	Valider une durée demandée et renvoyer la valeur plafonnée.
`cooldownRemaining(CommandSender issuer, PunishmentType type, long now)`	`long`	Millisecondes avant que l’émetteur puisse agir de nouveau.
`markUsed(CommandSender issuer, PunishmentType type, long now)`	`void`	Enregistrer qu’un émetteur a utilisé son allocation.

VeriteMojang

Résoudre un nom d’utilisateur Minecraft contre Mojang, en utilisant le même chemin et le même cache que le plugin.

Méthode	Renvoie	Signification
`lookup(String name)`	`MojangProfile`	Résoudre un nom en un uuid, un nom canonique et un statut.

VeriteExempt

Vérifier si un émetteur est empêché de sanctionner une cible.

Méthode	Renvoie	Signification
`blockReason(CommandSender issuer, UUID target, PunishmentType type)`	`String`	La raison pour laquelle la sanction n’est pas permise, ou `null` lorsqu’elle est permise.

VeriteLockdown

Interroger et contrôler l’état de verrouillage du serveur. Couvert en contexte dans Application de la modération personnalisée.

Méthode	Renvoie	Signification
`active()`	`boolean`	Si un verrouillage est en vigueur.
`reason()`	`String`	La raison de verrouillage actuelle.
`begin(String why)`	`void`	Démarrer un verrouillage avec une raison.
`end()`	`void`	Lever le verrouillage.

VeriteConfig

Lire la configuration effective du module de modération.

Méthode	Renvoie	Signification
`banAlts()`	`boolean`	Si les comptes alts sont bannis.
`muteCommandBlacklist()`	`List<String>`	Les commandes bloquées pendant la sourdine.
`warningExpire()`	`long`	La fenêtre d’expiration des avertissements en millisecondes.
`useGroupWeights()`	`boolean`	Si les poids de groupe sont utilisés.
`permitSameWeight()`	`boolean`	Si les actions sur un poids égal sont permises.
`reduceToLimit()`	`boolean`	Si les durées sont réduites à la limite de l’émetteur.
`dupeipScanLimit()`	`int`	La limite du balayage dupeip.
`yaml()`	`YamlConfiguration`	La configuration brute sous-jacente.

Types

Punishment

Un enregistrement de modération immuable. PERMANENT est l’horodatage de fin sentinelle d’une sanction permanente (-1L). GLOBAL_SCOPE est la portée générique ("*"). Les horodatages sont en millisecondes depuis l’époque. Une ip cible null signifie que la sanction est portée sur l’uuid plutôt que sur l’ip.

Accesseurs : id(), randomId(), type(), uuid(), ip(), reason(), executorUuid(), executorName(), removedByUuid(), removedByName(), removalReason(), dateStart(), dateEnd(), serverScope(), serverOrigin(), template(), silent(), ipban(), active().

Assistants dérivés :

Méthode	Renvoie	Signification
`permanent()`	`boolean`	Si `dateEnd` vaut `PERMANENT`.
`expired(long now)`	`boolean`	Si une sanction temporaire a dépassé sa fin.
`inForce(long now)`	`boolean`	Si l’enregistrement est actif et non expiré.
`duration()`	`long`	La durée totale, ou `PERMANENT`.
`remaining(long now)`	`long`	Les millisecondes restantes, ou `PERMANENT`.
`hasTemplate()`	`boolean`	Si l’enregistrement porte un modèle.

PunishmentType

Énumération : BAN, MUTE, WARNING, KICK.

Méthode	Renvoie	Signification
`id()`	`String`	Le nom en minuscules dans la locale racine.
`PunishmentType.of(String s)`	`PunishmentType`	Analyser la forme en minuscules à l’envers, sans tenir compte de la casse.

PunishmentResult

Enregistrement : PunishmentResult(boolean ok, Punishment entry, String error). En cas de succès, ok vaut true, entry contient la sanction résultante, et error vaut null. En cas d’échec, entry vaut null et error contient la raison.

ActivePunishment

Enregistrement : ActivePunishment(PunishmentType type, UUID uuid, long entryId). Un pointeur léger ; chargez l’enregistrement complet avec VeriteModeration.loadPunishment(entryId).

FilterResult

Énumération : CLEAN, BLOCK, SELF_HARM, ABUSE, PROFANITY. blocks() renvoie true pour tout autre chose que CLEAN. Un message arrêté pour avoir répété un message récent est signalé ici comme BLOCK ; utilisez la surcharge check tenant compte des répétitions pour les distinguer. SELF_HARM et ABUSE marquent un locuteur qui pourrait être en crise ; ne les traitez pas comme des infractions ordinaires aux règles.

FilterOutcome

La valeur issue de VeriteFilter.check(player, message, true).

Méthode	Renvoie	Signification
`category()`	`FilterResult`	La catégorie de filtre ordinaire, jamais `null`.
`repeat()`	`boolean`	Si le blocage était une répétition (uniquement `true` lorsque `category()` vaut `BLOCK`).
`blocks()`	`boolean`	Si le message devrait être abandonné.

PlayerProfile

Enregistrement avec les champs : uuid, name, names, ips, lastIp, clients, lastClient, protocol, referrer, firstJoin, lastSeen, joinCount, playtimeMs, online, punishments. Les horodatages sont en millisecondes depuis l’époque. Les champs de liste ne sont jamais null mais peuvent être vides.

MojangProfile et MojangStatus

MojangProfile(UUID uuid, String name, MojangStatus status). Lorsque status n’est pas FOUND, uuid et name valent null.

MojangStatus : FOUND (résolu), NOT_FOUND (Mojang a confirmé l’absence d’un tel compte), UNKNOWN (la recherche n’a pas pu aboutir, par exemple une erreur réseau).

DurationCheck

Enregistrement : DurationCheck(boolean ok, long durationMillis, String error). Lorsque ok, durationMillis contient la durée éventuellement plafonnée à appliquer et error vaut null. Lorsque non ok, error explique le rejet.

ScopeEntry

Enregistrement : ScopeEntry(String key, Object value). Une paire clé-valeur d’une portée de magasin.

CaptchaType et CaptchaOutcomeType

CaptchaType : STANDARD (un captcha rapide à faible friction), DETAILED (un captcha plus strict en plusieurs étapes).

CaptchaOutcomeType : PASS, FAIL, TIMEOUT.

Écouteurs

ModerationListener

Implémentez et enregistrez via VeriteModeration.registerListener. Toutes les méthodes sont sans effet par défaut, alors ne redéfinissez que ce dont vous avez besoin. Les rappels peuvent s’exécuter sur le fil principal du serveur ; ne bloquez pas.

Méthode	Se déclenche quand
`entryAdded(Punishment punishment)`	Une sanction est émise.
`entryRemoved(Punishment punishment)`	Une sanction est levée, graciée ou expirée.
`broadcastSent(String message, String target)`	Le système de modération envoie une diffusion.

VanishListener

Implémentez et enregistrez via VeriteVanish.registerListener. Sans effet par défaut ; ne bloquez pas dans les rappels.

Méthode	Se déclenche quand
`vanished(UUID player)`	Un joueur devient invisible.
`unvanished(UUID player)`	Un joueur redevient visible.