Riferimento dell'API per sviluppatori

Verité espone un'API Java pubblica e stabile nel package teacommontea.api. Ogni sottosistema è una facciata di metodi statici su tipi pubblici stabili, così puoi fare tutto ciò che fa il plugin senza mai fare riferimento a una classe di implementazione interna.

Questa pagina è l'intera superficie, organizzata per la consultazione. Due argomenti hanno le proprie guide dedicate e qui sono solo collegati in modo incrociato:

Il filtro chat: Integrazione della chat personalizzata.
Applicazione di mute, slowmode e freeze: Applicazione della moderazione personalizzata.

Per iniziare

Aggiungi Verité come dipendenza opzionale

Aggiungi Verité al tuo plugin.yml così che venga caricato prima del tuo plugin quando è installato, senza diventare obbligatorio:

softdepend:
  - Verite

Protezione per la disponibilità

Se Verité è opzionale, verifica la presenza di una classe prima di toccare 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;
}

Ogni sottosistema degrada anche per conto proprio: quando il modulo di supporto è disabilitato, i metodi di interrogazione restituiscono null, false o una collezione vuota, le chiamate di modifica diventano no-op e le chiamate di emissione restituiscono un risultato fallito. Raramente devi gestire come caso speciale un modulo disabilitato.

VeriteAPI

VeriteAPI è l'unico punto di ingresso generale. Riporta la versione dell'API, riporta quali moduli sono abilitati e restituisce la classe di ciascun sottosistema per la scoperta.

Membro	Restituisce	Significato
`VeriteAPI.VERSION`	`String`	La stringa della versione dell'API.
`moderationEnabled()`	`boolean`	Se il modulo di moderazione è caricato.
`vanishEnabled()`	`boolean`	Se il modulo di vanish è caricato.
`captchaEnabled()`	`boolean`	Se il modulo captcha è caricato.
`moderation()`	`Class<VeriteModeration>`	La classe del sottosistema di moderazione.
`playerData()`	`Class<VeritePlayerData>`	La classe del sottosistema dei dati dei giocatori.
`store()`	`Class<VeriteStore>`	La classe del sottosistema dello store.
`vanish()`	`Class<VeriteVanish>`	La classe del sottosistema di vanish.
`captcha()`	`Class<VeriteCaptcha>`	La classe del sottosistema captcha.
`filter()`	`Class<VeriteFilter>`	La classe del sottosistema del filtro chat.
`text()`	`Class<VeriteText>`	La classe del sottosistema di formattazione del testo.

Tutti i sottosistemi sono facciate statiche, quindi li chiami direttamente (per esempio VeriteModeration.isBanned(uuid)). I metodi accessori esistono per la scoperta e per i controlli centralizzati di abilitazione.

VeriteModeration

Il punto di ingresso completo per emettere, interrogare e revocare le punizioni. durationMillis usa Punishment.PERMANENT per una punizione permanente. I metodi gate restituiscono true quando hanno fermato il giocatore. Vedi Applicazione della moderazione personalizzata per il flusso di lavoro di gate e listener in dettaglio.

Stato e interrogazioni

Metodo	Restituisce	Significato
`enabled()`	`boolean`	Se il modulo di moderazione è caricato.
`isBanned(UUID player)`	`boolean`	Se il giocatore ha un ban attivo.
`isMuted(UUID player)`	`boolean`	Se il giocatore ha un mute attivo.
`activeBan(UUID player)`	`Punishment`	Il ban attivo, oppure `null`.
`activeMute(UUID player)`	`Punishment`	Il mute attivo, oppure `null`.
`history(UUID player, int limit)`	`List<Punishment>`	Cronologia recente delle punizioni del giocatore.
`byIp(String ip, int limit)`	`List<Punishment>`	Punizioni registrate su un ip.
`byStaff(UUID staff, int limit)`	`List<Punishment>`	Punizioni emesse da un membro dello staff.
`activeWarnings(UUID player)`	`List<Punishment>`	Avvertimenti attualmente attivi per il giocatore.
`activePunishments()`	`List<ActivePunishment>`	Puntatori leggeri a ogni punizione attiva.
`activeOfType(PunishmentType type, long now)`	`List<Punishment>`	Punizioni attive di un tipo a un dato momento.
`loadPunishment(long id)`	`Punishment`	Il record completo per un id numerico, oppure `null`.
`altsOf(UUID player)`	`List<UUID>`	Account che condividono il primo ip noto del giocatore.
`pruneHistory(UUID player, long cutoff, long now)`	`int`	Rimuove la cronologia più vecchia del cutoff, restituisce il numero rimosso.
`warningExpire()`	`long`	La finestra di scadenza degli avvertimenti in millisecondi.

Emissione delle punizioni

Metodo	Restituisce
`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`

Revoca delle punizioni

Metodo	Restituisce	Significato
`unban(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Revoca il ban attivo, `true` in caso di successo.
`unmute(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Revoca il mute attivo, `true` in caso di successo.
`unwarn(UUID target, String targetName, UUID removedBy, String removedByName, String reason)`	`PunishmentResult`	Rimuove un avvertimento.

Rendering e avvisi

Metodo	Restituisce	Significato
`banScreen(Punishment ban)`	`String`	La schermata di ban completa per un record di ban.
`muteLine(Punishment mute)`	`String`	Il riepilogo del mute su una riga.
`muteNotice(Punishment mute)`	`String`	L'avviso di mute inviato a un giocatore mutato.

Gate della chat

Ogni gate restituisce true quando il giocatore deve essere fermato e gli invia il motivo come effetto collaterale. Usali dove intendi applicare la regola.

Metodo	Restituisce	Significato
`muteGate(Player p)`	`boolean`	Il giocatore è mutato; invia l'avviso di mute.
`chatMuteGate(Player p)`	`boolean`	Il freeze della chat globale è attivo; invia l'avviso di chat bloccata.
`slowmodeGate(Player p)`	`boolean`	Il giocatore è trattenuto dallo slowmode; invia l'attesa rimanente.

Comandi della chat

Questi guidano i comandi della chat del plugin stesso per un CommandSender.

Metodo	Significato
`broadcast(CommandSender sender, String[] args)`	Invia una trasmissione.
`chatClear(CommandSender sender)`	Pulisce la chat.
`chatMute(CommandSender sender)`	Attiva o disattiva il freeze della chat globale.
`slowmode(CommandSender sender, String[] args)`	Imposta lo slowmode.

Listener

Metodo	Significato
`registerListener(ModerationListener listener)`	Iscriviti all'attività di punizione.
`unregisterListener(ModerationListener listener)`	Smetti di ricevere eventi.

VeritePlayerData

Leggi e registra i dati di account, sessione e identità che il sistema di moderazione memorizza. I timestamp sono in millisecondi epoch. Quando il modulo è disabilitato, le interrogazioni restituiscono null o vuoto e le chiamate di registrazione sono no-op.

Metodo	Restituisce	Significato
`enabled()`	`boolean`	Se lo store dei dati è aperto.
`hasProfile(UUID player)`	`boolean`	Se esiste un profilo.
`profile(UUID player)`	`PlayerProfile`	Il profilo completo, oppure `null`.
`uuidByName(String name)`	`UUID`	Risolve un uuid da un nome.
`nameOf(UUID player)`	`String`	Risolve il nome attuale da un uuid.
`knownNames()`	`List<String>`	Ogni nome noto nello store.
`namesOf(UUID player)`	`List<String>`	Tutti i nomi che un giocatore ha usato.
`ipsOf(UUID player)`	`List<String>`	Tutti gli ip da cui un giocatore si è connesso.
`usersOfIp(String ip)`	`List<UUID>`	Tutti gli utenti che hanno condiviso un ip.
`clientsOf(UUID player)`	`List<String>`	Tutti i client che un giocatore ha usato.
`recordLogin(UUID player, String name, String ip, long now)`	`void`	Registra un login.
`recordClient(UUID player, String brand, int protocol, String referrer, long now)`	`void`	Registra il brand e il protocollo di un client.
`flushSession(UUID player, long now)`	`void`	Scarica la sessione del giocatore.
`recordLogout(UUID player, long now)`	`void`	Registra un logout.

VeriteStore e VeriteScope

VeriteStore apre scope di dati con nome nello store chiave-valore persistente e condiviso del plugin, così il tuo plugin può conservare dati insieme a Verité senza un proprio database. Assegna un namespace ai nomi dei tuoi scope per evitare collisioni con i dati del plugin.

Metodo `VeriteStore`	Restituisce	Significato
`available()`	`boolean`	Se lo store è aperto.
`scope(String name)`	`VeriteScope`	Apre uno scope con nome, oppure `null` se non disponibile.

Un VeriteScope è un'area con nome che leggi e scrivi liberamente. Le scritture persistono attraverso il normale ciclo di flush del plugin.

Metodo `VeriteScope`	Restituisce	Significato
`set(String key, Object value)`	`void`	Memorizza un valore sotto una chiave.
`delete(String key)`	`void`	Rimuove una chiave.
`has(String key)`	`boolean`	Verifica la presenza di una chiave.
`get(String key)`	`Object`	Il valore grezzo memorizzato.
`getString(String key, String def)`	`String`	Lettura tipizzata con un valore predefinito.
`getLong(String key, long def)`	`long`	Lettura tipizzata con un valore predefinito.
`getInt(String key, int def)`	`int`	Lettura tipizzata con un valore predefinito.
`getBoolean(String key, boolean def)`	`boolean`	Lettura tipizzata con un valore predefinito.
`getBigDecimal(String key)`	`BigDecimal`	Lettura tipizzata.
`entries()`	`List<ScopeEntry>`	Ogni coppia chiave-valore nello scope.

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

VeriteVanish

Stato e controllo del vanish dello staff. vanish, unvanish e toggle restituiscono true quando lo stato è effettivamente cambiato. Quando il modulo è disabilitato, le interrogazioni restituiscono false o vuoto e le chiamate di modifica sono no-op.

Metodo	Restituisce	Significato
`enabled()`	`boolean`	Se il modulo di vanish è caricato.
`isVanished(UUID player)`	`boolean`	Se un giocatore è invisibile.
`isVanished(Player player)`	`boolean`	Overload di comodità per un giocatore online.
`getVanished()`	`Set<UUID>`	Ogni giocatore attualmente invisibile.
`vanish(Player p)`	`boolean`	Rende invisibile un giocatore.
`unvanish(Player p)`	`boolean`	Rende visibile un giocatore.
`toggle(Player p)`	`boolean`	Attiva o disattiva lo stato di vanish di un giocatore.
`registerPlaceholders()`	`void`	Registra l'espansione PlaceholderAPI del vanish.
`registerListener(VanishListener listener)`	`void`	Iscriviti ai cambiamenti di vanish.
`unregisterListener(VanishListener listener)`	`void`	Smetti di ricevere gli eventi di vanish.

VeriteCaptcha

Emetti e traccia le sfide captcha. I metodi challenge restituiscono true quando una sfida è stata effettivamente avviata. L'etichetta source registra perché la sfida è stata aperta e viene trasportata fino agli eventi di completamento e di richiesta di punizione. Quando il modulo è disabilitato, tutte le chiamate restituiscono false.

Membro	Restituisce	Significato
`VeriteCaptcha.BYPASS_PERMISSION`	`String`	Il nodo di permesso che aggira il captcha.
`VeriteCaptcha.NOTIFY_PERMISSION`	`String`	Il nodo di permesso di notifica captcha.
`enabled()`	`boolean`	Se il modulo captcha è caricato.
`isActive(UUID player)`	`boolean`	Se una sfida è attiva per il giocatore.
`challengeStandard(Player player, String source)`	`boolean`	Apre una sfida standard.
`challengeDetailed(Player player, String source)`	`boolean`	Apre una sfida dettagliata.
`challenge(Player player, CaptchaType type, String source)`	`boolean`	Apre una sfida di un tipo esplicito.

VeriteFilter

Il filtro chat consapevole dell'evasione. Il flusso di lavoro completo, inclusi i controlli anonimi, i controlli consapevoli delle ripetizioni e gli helper del messaggio di blocco, è documentato in Integrazione della chat personalizzata. La superficie:

Membro	Restituisce	Significato
`VeriteFilter.ANONYMOUS`	`UUID`	Passalo come giocatore quando non c'è un trasgressore da registrare.
`check(UUID player, String message)`	`FilterResult`	Classifica un messaggio e registra la corrispondenza a carico del giocatore.
`check(UUID player, String message, boolean repeatAware)`	`FilterOutcome`	Classificazione consapevole delle ripetizioni.
`count(UUID player)`	`int`	Quante volte un giocatore è stato segnalato.
`blockMessage()`	`String`	Il messaggio di blocco configurato.
`repeatMessage()`	`String`	L'avviso di messaggio ripetuto configurato.
`selfHarmMessage()`	`String`	L'avviso di autolesionismo configurato.
`blockNotice(FilterResult result, String message)`	`BaseComponent[]`	Il componente di avviso renderizzato per un risultato.
`foldAccents(String s)`	`String`	Helper di normalizzazione: rimuove gli accenti.
`stripDeletes(String s)`	`String`	Helper di normalizzazione: rimuove i caratteri a larghezza zero e di cancellazione.
`stripEntities(String s)`	`String`	Helper di normalizzazione: rimuove le entità in stile html.
`reduceRuns(String s, int max)`	`String`	Helper di normalizzazione: comprime le lettere ripetute.
`fingerprint(String word)`	`String`	Firma delle lettere indipendente dall'ordine per la corrispondenza delle trasposizioni.
`trimEdges(String word)`	`String`	Rimuove dai bordi di una parola i caratteri non alfabetici.

Gli helper di normalizzazione sono funzioni pure ed è sicuro chiamarli al di fuori del thread principale.

VeriteText

Analizza il testo con tag Verite e applica il prefisso del plugin nel modo in cui lo fa il plugin, così il tuo output ha uno stile identico.

Metodo	Restituisce	Significato
`parse(String tagged)`	`BaseComponent[]`	Analizza i tag Verite in un array di componenti.
`prefixed(String tagged)`	`BaseComponent[]`	Analizza e antepone il prefisso del plugin.
`prefix()`	`String`	Il prefisso attuale.
`setPrefix(String prefix)`	`void`	Cambia il prefisso.

Utilità

VeriteGeoIp

Cerca il paese di un ip e controlla lo stato del database GeoIP.

Metodo	Restituisce	Significato
`country(String ip)`	`String`	Nome del paese per un ip, oppure `null` se non risolto.
`available()`	`boolean`	Se il database GeoIP è stato caricato.
`isPrivate(String ip)`	`boolean`	Se un ip è in un intervallo privato o riservato.
`attempted()`	`boolean`	Se è stato tentato un caricamento del database.

VeriteDuration

Analizza e formatta le durate delle punizioni leggibili dall'uomo, con costanti di unità in millisecondi: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR.

Metodo	Restituisce	Significato
`suggestions()`	`List<String>`	Token di durata suggeriti.
`parse(String token)`	`long`	Analizza un token come `7d` in millisecondi.
`parseTwoToken(String number, String unitWord)`	`long`	Analizza un numero e una parola di unità separati in millisecondi.
`format(long millis)`	`String`	Formatta i millisecondi in una stringa leggibile dall'uomo.

VeriteFormat

Formatta i tempi, pluralizza i sostantivi e assegna un nome alle versioni di protocollo del client.

Metodo	Restituisce	Significato
`fancyTime(long millis)`	`String`	Un intervallo in millisecondi come stringa leggibile dall'uomo.
`plural(long count, String noun)`	`String`	Un conteggio con il sostantivo singolare o plurale corretto.
`pluralize(long count, String noun)`	`String`	Un conteggio con il sostantivo singolare o plurale corretto.
`versionName(int protocol)`	`String`	Il nome della versione di Minecraft per un numero di protocollo del client.

VeriteLimits

Applica gli stessi limiti di durata e cooldown per emittente che applica il plugin.

Metodo	Restituisce	Significato
`capDuration(CommandSender issuer, PunishmentType type, long requested)`	`DurationCheck`	Valida una durata richiesta e restituisce il valore limitato.
`cooldownRemaining(CommandSender issuer, PunishmentType type, long now)`	`long`	Millisecondi finché l'emittente può agire di nuovo.
`markUsed(CommandSender issuer, PunishmentType type, long now)`	`void`	Registra che un emittente ha usato la propria disponibilità.

VeriteMojang

Risolve un nome utente di Minecraft su Mojang, usando lo stesso percorso e la stessa cache che usa il plugin.

Metodo	Restituisce	Significato
`lookup(String name)`	`MojangProfile`	Risolve un nome in un uuid, nome canonico e stato.

VeriteExempt

Verifica se un emittente è bloccato dal punire un bersaglio.

Metodo	Restituisce	Significato
`blockReason(CommandSender issuer, UUID target, PunishmentType type)`	`String`	Il motivo per cui la punizione non è consentita, oppure `null` quando è consentita.

VeriteLockdown

Interroga e controlla lo stato di blocco del server. Trattato nel contesto in Applicazione della moderazione personalizzata.

Metodo	Restituisce	Significato
`active()`	`boolean`	Se un blocco è in vigore.
`reason()`	`String`	Il motivo attuale del blocco.
`begin(String why)`	`void`	Avvia un blocco con un motivo.
`end()`	`void`	Rimuove il blocco.

VeriteConfig

Leggi la configurazione effettiva del modulo di moderazione.

Metodo	Restituisce	Significato
`banAlts()`	`boolean`	Se gli account alt vengono bannati.
`muteCommandBlacklist()`	`List<String>`	Comandi bloccati durante il mute.
`warningExpire()`	`long`	La finestra di scadenza degli avvertimenti in millisecondi.
`useGroupWeights()`	`boolean`	Se vengono usati i pesi dei gruppi.
`permitSameWeight()`	`boolean`	Se le azioni di pari peso sono permesse.
`reduceToLimit()`	`boolean`	Se le durate si riducono al limite dell'emittente.
`dupeipScanLimit()`	`int`	Il limite di scansione dupeip.
`yaml()`	`YamlConfiguration`	La configurazione di supporto grezza.

Tipi

Punishment

Un record di moderazione immutabile. PERMANENT è il timestamp di fine sentinella per una punizione permanente (-1L). GLOBAL_SCOPE è lo scope jolly ("*"). I timestamp sono in millisecondi epoch. Un ip di bersaglio null significa che la punizione ha come scope l'uuid anziché l'ip.

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

Helper derivati:

Metodo	Restituisce	Significato
`permanent()`	`boolean`	Se `dateEnd` è `PERMANENT`.
`expired(long now)`	`boolean`	Se una punizione temporanea ha superato la sua fine.
`inForce(long now)`	`boolean`	Se il record è attivo e non scaduto.
`duration()`	`long`	Durata totale, oppure `PERMANENT`.
`remaining(long now)`	`long`	Millisecondi rimanenti, oppure `PERMANENT`.
`hasTemplate()`	`boolean`	Se il record porta con sé un template.

PunishmentType

Enum: BAN, MUTE, WARNING, KICK.

Metodo	Restituisce	Significato
`id()`	`String`	Il nome nella locale root in minuscolo.
`PunishmentType.of(String s)`	`PunishmentType`	Analizza di nuovo la forma minuscola, senza distinzione tra maiuscole e minuscole.

PunishmentResult

Record: PunishmentResult(boolean ok, Punishment entry, String error). In caso di successo ok è true, entry contiene la punizione risultante ed error è null. In caso di fallimento entry è null ed error contiene il motivo.

ActivePunishment

Record: ActivePunishment(PunishmentType type, UUID uuid, long entryId). Un puntatore leggero; carica il record completo con VeriteModeration.loadPunishment(entryId).

FilterResult

Enum: CLEAN, BLOCK, SELF_HARM, ABUSE, PROFANITY. blocks() restituisce true per qualsiasi cosa diversa da CLEAN. Un messaggio fermato perché ripete uno recente viene riportato qui come BLOCK; usa l'overload di check consapevole delle ripetizioni per distinguerli. SELF_HARM e ABUSE segnalano un interlocutore che potrebbe essere in crisi; non trattarli come normali violazioni delle regole.

FilterOutcome

Il valore restituito da VeriteFilter.check(player, message, true).

Metodo	Restituisce	Significato
`category()`	`FilterResult`	La normale categoria del filtro, mai `null`.
`repeat()`	`boolean`	Se il blocco era una ripetizione (`true` solo quando `category()` è `BLOCK`).
`blocks()`	`boolean`	Se il messaggio deve essere scartato.

PlayerProfile

Record con campi: uuid, name, names, ips, lastIp, clients, lastClient, protocol, referrer, firstJoin, lastSeen, joinCount, playtimeMs, online, punishments. I timestamp sono in millisecondi epoch. I campi lista non sono mai null ma possono essere vuoti.

MojangProfile e MojangStatus

MojangProfile(UUID uuid, String name, MojangStatus status). Quando status non è FOUND, uuid e name sono null.

MojangStatus: FOUND (risolto), NOT_FOUND (Mojang ha confermato che non esiste tale account), UNKNOWN (la ricerca non ha potuto essere completata, per esempio un errore di rete).

DurationCheck

Record: DurationCheck(boolean ok, long durationMillis, String error). Quando ok, durationMillis contiene la durata possibilmente limitata da applicare ed error è null. Quando non ok, error spiega il rifiuto.

ScopeEntry

Record: ScopeEntry(String key, Object value). Una coppia chiave-valore da uno scope dello store.

CaptchaType e CaptchaOutcomeType

CaptchaType: STANDARD (una sfida rapida e a basso attrito), DETAILED (una sfida più rigorosa a più passaggi).

CaptchaOutcomeType: PASS, FAIL, TIMEOUT.

Listener

ModerationListener

Implementa e registra tramite VeriteModeration.registerListener. Tutti i metodi sono no-op predefiniti, quindi sovrascrivi solo ciò di cui hai bisogno. Le callback possono essere eseguite sul thread principale del server; non bloccare.

Metodo	Si attiva quando
`entryAdded(Punishment punishment)`	Viene emessa una punizione.
`entryRemoved(Punishment punishment)`	Una punizione viene revocata, perdonata o scaduta.
`broadcastSent(String message, String target)`	Il sistema di moderazione invia una trasmissione.

VanishListener

Implementa e registra tramite VeriteVanish.registerListener. No-op predefiniti; non bloccare nelle callback.

Metodo	Si attiva quando
`vanished(UUID player)`	Un giocatore entra nel vanish.
`unvanished(UUID player)`	Un giocatore esce dal vanish.