Referência da API para programadores

O Verité expõe uma API Java pública e estável no pacote teacommontea.api. Cada subsistema é uma fachada de métodos estáticos sobre tipos públicos estáveis, por isso pode fazer tudo o que o plugin faz sem nunca referenciar uma classe de implementação interna.

Esta página é a superfície completa, organizada para consulta. Dois temas têm os seus próprios guias dedicados e são apenas referenciados aqui:

O filtro de chat: Integração de chat personalizado.
Aplicação de silenciamentos, modo lento e congelamento: Aplicação de moderação personalizada.

Começar

Adicione o Verité como dependência opcional

Adicione o Verité ao seu plugin.yml para que carregue antes do seu plugin quando instalado, sem se tornar obrigatório:

softdepend:
  - Verite

Proteção quanto à disponibilidade

Se o Verité for opcional, verifique se existe uma classe antes de tocar na 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;
}

Cada subsistema também se degrada por conta própria: quando o módulo de suporte está desativado, os métodos de consulta devolvem null, false ou uma coleção vazia, as chamadas de mutação tornam-se inócuas e as chamadas de emissão devolvem um resultado falhado. Raramente tem de tratar um módulo desativado como caso especial.

VeriteAPI

VeriteAPI é o único ponto de entrada abrangente. Reporta a versão da API, reporta que módulos estão ativados e devolve a classe de cada subsistema para descoberta.

Membro	Devolve	Significado
`VeriteAPI.VERSION`	`String`	A string da versão da API.
`moderationEnabled()`	`boolean`	Se o módulo de moderação está carregado.
`vanishEnabled()`	`boolean`	Se o módulo de vanish está carregado.
`captchaEnabled()`	`boolean`	Se o módulo de captcha está carregado.
`moderation()`	`Class<VeriteModeration>`	A classe do subsistema de moderação.
`playerData()`	`Class<VeritePlayerData>`	A classe do subsistema de dados de jogadores.
`store()`	`Class<VeriteStore>`	A classe do subsistema de armazenamento.
`vanish()`	`Class<VeriteVanish>`	A classe do subsistema de vanish.
`captcha()`	`Class<VeriteCaptcha>`	A classe do subsistema de captcha.
`filter()`	`Class<VeriteFilter>`	A classe do subsistema de filtro de chat.
`text()`	`Class<VeriteText>`	A classe do subsistema de formatação de texto.

Todos os subsistemas são fachadas estáticas, por isso chama-os diretamente (por exemplo VeriteModeration.isBanned(uuid)). Os métodos de acesso existem para descoberta e verificações centralizadas de estado ativado.

VeriteModeration

O ponto de entrada completo para emitir, consultar e levantar castigos. durationMillis utiliza Punishment.PERMANENT para um castigo permanente. Os métodos de porta devolvem true quando pararam o jogador. Consulte Aplicação de moderação personalizada para o fluxo de trabalho de portas e ouvintes em profundidade.

Estado e consultas

Método	Devolve	Significado
`enabled()`	`boolean`	Se o módulo de moderação está carregado.
`isBanned(UUID player)`	`boolean`	Se o jogador tem um banimento ativo.
`isMuted(UUID player)`	`boolean`	Se o jogador tem um silenciamento ativo.
`activeBan(UUID player)`	`Punishment`	O banimento ativo, ou `null`.
`activeMute(UUID player)`	`Punishment`	O silenciamento ativo, ou `null`.
`history(UUID player, int limit)`	`List<Punishment>`	Histórico de castigos recente do jogador.
`byIp(String ip, int limit)`	`List<Punishment>`	Castigos registados contra um ip.
`byStaff(UUID staff, int limit)`	`List<Punishment>`	Castigos emitidos por um membro do pessoal.
`activeWarnings(UUID player)`	`List<Punishment>`	Avisos atualmente ativos do jogador.
`activePunishments()`	`List<ActivePunishment>`	Ponteiros leves para todos os castigos ativos.
`activeOfType(PunishmentType type, long now)`	`List<Punishment>`	Castigos ativos de um tipo num dado momento.
`loadPunishment(long id)`	`Punishment`	O registo completo de um id numérico, ou `null`.
`altsOf(UUID player)`	`List<UUID>`	Contas que partilham o primeiro ip conhecido do jogador.
`pruneHistory(UUID player, long cutoff, long now)`	`int`	Remove o histórico mais antigo do que o corte, devolve a quantidade removida.
`warningExpire()`	`long`	A janela de expiração de avisos em milissegundos.

Emitir castigos

Método	Devolve
`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`

Levantar castigos

Método	Devolve	Significado
`unban(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Levanta o banimento ativo, `true` em caso de sucesso.
`unmute(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Levanta o silenciamento ativo, `true` em caso de sucesso.
`unwarn(UUID target, String targetName, UUID removedBy, String removedByName, String reason)`	`PunishmentResult`	Remove um aviso.

Renderização e avisos

Método	Devolve	Significado
`banScreen(Punishment ban)`	`String`	O ecrã de banimento completo para um registo de banimento.
`muteLine(Punishment mute)`	`String`	O resumo de uma linha do silenciamento.
`muteNotice(Punishment mute)`	`String`	O aviso de silenciamento enviado a um jogador silenciado.

Portas de chat

Cada porta devolve true quando o jogador deve ser parado e envia-lhe o motivo como efeito secundário. Use-as onde pretende aplicar.

Método	Devolve	Significado
`muteGate(Player p)`	`boolean`	O jogador está silenciado; envia o aviso de silenciamento.
`chatMuteGate(Player p)`	`boolean`	O congelamento global do chat está ativo; envia o aviso de congelamento.
`slowmodeGate(Player p)`	`boolean`	O jogador está retido pelo modo lento; envia a espera restante.

Comandos de chat

Estes acionam os próprios comandos de chat do plugin para um CommandSender.

Método	Significado
`broadcast(CommandSender sender, String[] args)`	Envia uma difusão.
`chatClear(CommandSender sender)`	Limpa o chat.
`chatMute(CommandSender sender)`	Alterna o congelamento global do chat.
`slowmode(CommandSender sender, String[] args)`	Define o modo lento.

Ouvinte

Método	Significado
`registerListener(ModerationListener listener)`	Subscrever a atividade de castigos.
`unregisterListener(ModerationListener listener)`	Deixar de receber eventos.

VeritePlayerData

Ler e registar os dados de conta, sessão e identidade que o sistema de moderação armazena. Os carimbos temporais são milissegundos epoch. Quando o módulo está desativado, as consultas devolvem null ou vazio e as chamadas de registo são inócuas.

Método	Devolve	Significado
`enabled()`	`boolean`	Se o armazenamento de dados está aberto.
`hasProfile(UUID player)`	`boolean`	Se existe um perfil.
`profile(UUID player)`	`PlayerProfile`	O perfil completo, ou `null`.
`uuidByName(String name)`	`UUID`	Resolver um uuid a partir de um nome.
`nameOf(UUID player)`	`String`	Resolver o nome atual a partir de um uuid.
`knownNames()`	`List<String>`	Todos os nomes conhecidos no armazenamento.
`namesOf(UUID player)`	`List<String>`	Todos os nomes que um jogador utilizou.
`ipsOf(UUID player)`	`List<String>`	Todos os ips a partir dos quais um jogador se ligou.
`usersOfIp(String ip)`	`List<UUID>`	Todos os utilizadores que partilharam um ip.
`clientsOf(UUID player)`	`List<String>`	Todos os clientes que um jogador utilizou.
`recordLogin(UUID player, String name, String ip, long now)`	`void`	Registar um login.
`recordClient(UUID player, String brand, int protocol, String referrer, long now)`	`void`	Registar a marca e o protocolo do cliente.
`flushSession(UUID player, long now)`	`void`	Descarregar a sessão do jogador.
`recordLogout(UUID player, long now)`	`void`	Registar um logout.

VeriteStore e VeriteScope

VeriteStore abre âmbitos de dados nomeados no armazenamento persistente de chave-valor partilhado do plugin, para que o seu plugin possa persistir dados juntamente com o Verité sem uma base de dados própria. Atribua espaços de nome aos seus âmbitos para evitar colisões com os dados do plugin.

Método de `VeriteStore`	Devolve	Significado
`available()`	`boolean`	Se o armazenamento está aberto.
`scope(String name)`	`VeriteScope`	Abre um âmbito nomeado, ou `null` se indisponível.

Um VeriteScope é uma área nomeada que lê e escreve livremente. As escritas persistem através do ciclo normal de descarga do plugin.

Método de `VeriteScope`	Devolve	Significado
`set(String key, Object value)`	`void`	Armazenar um valor sob uma chave.
`delete(String key)`	`void`	Remover uma chave.
`has(String key)`	`boolean`	Testar a presença de uma chave.
`get(String key)`	`Object`	O valor armazenado em bruto.
`getString(String key, String def)`	`String`	Leitura tipada com predefinição.
`getLong(String key, long def)`	`long`	Leitura tipada com predefinição.
`getInt(String key, int def)`	`int`	Leitura tipada com predefinição.
`getBoolean(String key, boolean def)`	`boolean`	Leitura tipada com predefinição.
`getBigDecimal(String key)`	`BigDecimal`	Leitura tipada.
`entries()`	`List<ScopeEntry>`	Todos os pares chave-valor no âmbito.

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

VeriteVanish

Estado e controlo do vanish do pessoal. vanish, unvanish e toggle devolvem true quando o estado realmente mudou. Quando o módulo está desativado, as consultas devolvem false ou vazio e as chamadas de mutação são inócuas.

Método	Devolve	Significado
`enabled()`	`boolean`	Se o módulo de vanish está carregado.
`isVanished(UUID player)`	`boolean`	Se um jogador está em vanish.
`isVanished(Player player)`	`boolean`	Sobrecarga de conveniência para um jogador online.
`getVanished()`	`Set<UUID>`	Todos os jogadores atualmente em vanish.
`vanish(Player p)`	`boolean`	Colocar um jogador em vanish.
`unvanish(Player p)`	`boolean`	Retirar um jogador do vanish.
`toggle(Player p)`	`boolean`	Alternar o estado de vanish de um jogador.
`registerPlaceholders()`	`void`	Registar a expansão do vanish para o PlaceholderAPI.
`registerListener(VanishListener listener)`	`void`	Subscrever as alterações de vanish.
`unregisterListener(VanishListener listener)`	`void`	Deixar de receber eventos de vanish.

VeriteCaptcha

Emitir e acompanhar desafios de captcha. Os métodos challenge devolvem true quando um desafio foi realmente iniciado. O rótulo source regista por que motivo o desafio foi aberto e é transportado até aos eventos de conclusão e de pedido de castigo. Quando o módulo está desativado, todas as chamadas devolvem false.

Membro	Devolve	Significado
`VeriteCaptcha.BYPASS_PERMISSION`	`String`	O nó de permissão que ignora o captcha.
`VeriteCaptcha.NOTIFY_PERMISSION`	`String`	O nó de permissão de notificação de captcha.
`enabled()`	`boolean`	Se o módulo de captcha está carregado.
`isActive(UUID player)`	`boolean`	Se um desafio está ativo para o jogador.
`challengeStandard(Player player, String source)`	`boolean`	Abrir um desafio padrão.
`challengeDetailed(Player player, String source)`	`boolean`	Abrir um desafio detalhado.
`challenge(Player player, CaptchaType type, String source)`	`boolean`	Abrir um desafio de um tipo explícito.

VeriteFilter

O filtro de chat consciente de evasão. O fluxo de trabalho completo, incluindo verificações anónimas, verificações com deteção de repetição e os auxiliares de mensagem de bloqueio, está documentado em Integração de chat personalizado. A superfície:

Membro	Devolve	Significado
`VeriteFilter.ANONYMOUS`	`UUID`	Passe como o jogador quando não há infrator a registar.
`check(UUID player, String message)`	`FilterResult`	Classificar uma mensagem e registar o acerto contra o jogador.
`check(UUID player, String message, boolean repeatAware)`	`FilterOutcome`	Classificação com deteção de repetição.
`count(UUID player)`	`int`	Quantas vezes um jogador foi sinalizado.
`blockMessage()`	`String`	A mensagem de bloqueio configurada.
`repeatMessage()`	`String`	O aviso de mensagem repetida configurado.
`selfHarmMessage()`	`String`	O aviso de automutilação configurado.
`blockNotice(FilterResult result, String message)`	`BaseComponent[]`	O componente de aviso renderizado para um resultado.
`foldAccents(String s)`	`String`	Auxiliar de normalização: remover acentos.
`stripDeletes(String s)`	`String`	Auxiliar de normalização: remover caracteres de largura zero e de eliminação.
`stripEntities(String s)`	`String`	Auxiliar de normalização: remover entidades ao estilo html.
`reduceRuns(String s, int max)`	`String`	Auxiliar de normalização: colapsar letras repetidas.
`fingerprint(String word)`	`String`	Assinatura de letras independente da ordem para correspondência de transposição.
`trimEdges(String word)`	`String`	Cortar as extremidades não alfabéticas de uma palavra.

Os auxiliares de normalização são funções puras e é seguro chamá-los fora da thread principal.

VeriteText

Analisar texto com etiquetas do Verite e aplicar o prefixo do plugin da forma que o plugin faz, para que a sua saída fique estilizada de forma idêntica.

Método	Devolve	Significado
`parse(String tagged)`	`BaseComponent[]`	Analisar etiquetas do Verite num array de componentes.
`prefixed(String tagged)`	`BaseComponent[]`	Analisar e antepor o prefixo do plugin.
`prefix()`	`String`	O prefixo atual.
`setPrefix(String prefix)`	`void`	Alterar o prefixo.

Utilitários

VeriteGeoIp

Consultar o país de um ip e verificar o estado da base de dados GeoIP.

Método	Devolve	Significado
`country(String ip)`	`String`	Nome do país de um ip, ou `null` se não resolvido.
`available()`	`boolean`	Se a base de dados GeoIP foi carregada.
`isPrivate(String ip)`	`boolean`	Se um ip está num intervalo privado ou reservado.
`attempted()`	`boolean`	Se foi tentado um carregamento da base de dados.

VeriteDuration

Analisar e formatar durações de castigo humanas, com constantes de unidade em milissegundos: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR.

Método	Devolve	Significado
`suggestions()`	`List<String>`	Tokens de duração sugeridos.
`parse(String token)`	`long`	Analisar um token como `7d` em milissegundos.
`parseTwoToken(String number, String unitWord)`	`long`	Analisar um número e uma palavra de unidade separados em milissegundos.
`format(long millis)`	`String`	Formatar milissegundos numa string humana.

VeriteFormat

Formatar tempos, pluralizar substantivos e nomear versões de protocolo de cliente.

Método	Devolve	Significado
`fancyTime(long millis)`	`String`	Um intervalo em milissegundos como string humana.
`plural(long count, String noun)`	`String`	Uma contagem com o substantivo singular ou plural correto.
`pluralize(long count, String noun)`	`String`	Uma contagem com o substantivo singular ou plural correto.
`versionName(int protocol)`	`String`	O nome da versão do Minecraft para um número de protocolo de cliente.

VeriteLimits

Aplicar os mesmos limites de duração e tempos de espera por emissor que o plugin aplica.

Método	Devolve	Significado
`capDuration(CommandSender issuer, PunishmentType type, long requested)`	`DurationCheck`	Validar uma duração pedida e devolver o valor limitado.
`cooldownRemaining(CommandSender issuer, PunishmentType type, long now)`	`long`	Milissegundos até que o emissor possa atuar novamente.
`markUsed(CommandSender issuer, PunishmentType type, long now)`	`void`	Registar que um emissor usou a sua quota.

VeriteMojang

Resolver um nome de utilizador do Minecraft contra a Mojang, utilizando o mesmo caminho e cache que o plugin utiliza.

Método	Devolve	Significado
`lookup(String name)`	`MojangProfile`	Resolver um nome para um uuid, nome canónico e estado.

VeriteExempt

Verificar se um emissor está impedido de castigar um alvo.

Método	Devolve	Significado
`blockReason(CommandSender issuer, UUID target, PunishmentType type)`	`String`	O motivo pelo qual o castigo não é permitido, ou `null` quando permitido.

VeriteLockdown

Consultar e controlar o estado de bloqueio do servidor. Abordado em contexto em Aplicação de moderação personalizada.

Método	Devolve	Significado
`active()`	`boolean`	Se um bloqueio está em vigor.
`reason()`	`String`	O motivo atual do bloqueio.
`begin(String why)`	`void`	Iniciar um bloqueio com um motivo.
`end()`	`void`	Limpar o bloqueio.

VeriteConfig

Ler a configuração efetiva do módulo de moderação.

Método	Devolve	Significado
`banAlts()`	`boolean`	Se as contas alt são banidas.
`muteCommandBlacklist()`	`List<String>`	Comandos bloqueados enquanto silenciado.
`warningExpire()`	`long`	A janela de expiração de avisos em milissegundos.
`useGroupWeights()`	`boolean`	Se os pesos de grupo são utilizados.
`permitSameWeight()`	`boolean`	Se as ações de peso igual são permitidas.
`reduceToLimit()`	`boolean`	Se as durações reduzem ao limite do emissor.
`dupeipScanLimit()`	`int`	O limite de análise de dupeip.
`yaml()`	`YamlConfiguration`	A configuração de suporte em bruto.

Tipos

Punishment

Um registo de moderação imutável. PERMANENT é o carimbo temporal de fim sentinela para um castigo permanente (-1L). GLOBAL_SCOPE é o âmbito curinga ("*"). Os carimbos temporais são milissegundos epoch. Um ip de alvo null significa que o castigo é de âmbito uuid em vez de âmbito ip.

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

Auxiliares derivados:

Método	Devolve	Significado
`permanent()`	`boolean`	Se `dateEnd` é `PERMANENT`.
`expired(long now)`	`boolean`	Se um castigo temporário passou o seu fim.
`inForce(long now)`	`boolean`	Se o registo está ativo e não expirado.
`duration()`	`long`	Duração total, ou `PERMANENT`.
`remaining(long now)`	`long`	Milissegundos restantes, ou `PERMANENT`.
`hasTemplate()`	`boolean`	Se o registo carrega um modelo.

PunishmentType

Enum: BAN, MUTE, WARNING, KICK.

Método	Devolve	Significado
`id()`	`String`	O nome em minúsculas da localidade raiz.
`PunishmentType.of(String s)`	`PunishmentType`	Analisar a forma em minúsculas de volta, sem distinção de maiúsculas.

PunishmentResult

Record: PunishmentResult(boolean ok, Punishment entry, String error). Em caso de sucesso ok é true, entry contém o castigo resultante e error é null. Em caso de falha entry é null e error contém o motivo.

ActivePunishment

Record: ActivePunishment(PunishmentType type, UUID uuid, long entryId). Um ponteiro leve; carregue o registo completo com VeriteModeration.loadPunishment(entryId).

FilterResult

Enum: CLEAN, BLOCK, SELF_HARM, ABUSE, PROFANITY. blocks() devolve true para qualquer coisa que não seja CLEAN. Uma mensagem parada por repetir uma recente reporta-se aqui como BLOCK; use a sobrecarga check com deteção de repetição para as distinguir. SELF_HARM e ABUSE marcam um falante que pode estar em crise; não os trate como violações comuns das regras.

FilterOutcome

O valor de VeriteFilter.check(player, message, true).

Método	Devolve	Significado
`category()`	`FilterResult`	A categoria de filtro comum, nunca `null`.
`repeat()`	`boolean`	Se o bloqueio foi uma repetição (só é `true` quando `category()` é `BLOCK`).
`blocks()`	`boolean`	Se a mensagem deve ser descartada.

PlayerProfile

Record com campos: uuid, name, names, ips, lastIp, clients, lastClient, protocol, referrer, firstJoin, lastSeen, joinCount, playtimeMs, online, punishments. Os carimbos temporais são milissegundos epoch. Os campos de lista nunca são null mas podem estar vazios.

MojangProfile e MojangStatus

MojangProfile(UUID uuid, String name, MojangStatus status). Quando status não é FOUND, uuid e name são null.

MojangStatus: FOUND (resolvido), NOT_FOUND (a Mojang confirmou não existir tal conta), UNKNOWN (a consulta não pôde ser concluída, por exemplo um erro de rede).

DurationCheck

Record: DurationCheck(boolean ok, long durationMillis, String error). Quando ok, durationMillis contém a duração possivelmente limitada a aplicar e error é null. Quando não ok, error explica a rejeição.

ScopeEntry

Record: ScopeEntry(String key, Object value). Um par chave-valor de um âmbito de armazenamento.

CaptchaType e CaptchaOutcomeType

CaptchaType: STANDARD (um desafio rápido e de baixo atrito), DETAILED (um desafio mais rigoroso de vários passos).

CaptchaOutcomeType: PASS, FAIL, TIMEOUT.

Ouvintes

ModerationListener

Implemente e registe através de VeriteModeration.registerListener. Todos os métodos são inócuos por predefinição, por isso sobreponha apenas o que precisar. Os callbacks podem correr na thread principal do servidor; não bloqueie.

Método	Dispara quando
`entryAdded(Punishment punishment)`	Um castigo é emitido.
`entryRemoved(Punishment punishment)`	Um castigo é levantado, perdoado ou expira.
`broadcastSent(String message, String target)`	O sistema de moderação envia uma difusão.

VanishListener

Implemente e registe através de VeriteVanish.registerListener. Inócuos por predefinição; não bloqueie nos callbacks.

Método	Dispara quando
`vanished(UUID player)`	Um jogador entra em vanish.
`unvanished(UUID player)`	Um jogador sai do vanish.