Developer API Reference

Verité exposes a stable public Java API under the package teacommontea.api. Every subsystem is a facade of static methods over stable public types, so you can do everything the plugin does without ever referencing an internal implementation class.

This page is the full surface, organised for lookup. Two topics have their own dedicated guides and are only cross-linked here:

The chat filter: Custom Chat Integration.
Mute, slowmode, and freeze enforcement: Custom Moderation Enforcement.

Getting Started

Add Verité as a soft dependency

Add Verité to your plugin.yml so it loads before your plugin when installed, without becoming mandatory:

softdepend:
  - Verite

Guard for availability

If Verité is optional, check for a class before touching the 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;
}

Every subsystem also degrades on its own: when the backing module is disabled, query methods return null, false, or an empty collection, mutating calls become no-ops, and issuing calls return a failed result. You rarely have to special-case a disabled module.

VeriteAPI

VeriteAPI is the single umbrella entry point. It reports the API version, reports which modules are enabled, and returns the class of each subsystem for discovery.

Member	Returns	Meaning
`VeriteAPI.VERSION`	`String`	The API version string.
`moderationEnabled()`	`boolean`	Whether the moderation module is loaded.
`vanishEnabled()`	`boolean`	Whether the vanish module is loaded.
`captchaEnabled()`	`boolean`	Whether the captcha module is loaded.
`moderation()`	`Class<VeriteModeration>`	The moderation subsystem class.
`playerData()`	`Class<VeritePlayerData>`	The player-data subsystem class.
`store()`	`Class<VeriteStore>`	The store subsystem class.
`vanish()`	`Class<VeriteVanish>`	The vanish subsystem class.
`captcha()`	`Class<VeriteCaptcha>`	The captcha subsystem class.
`filter()`	`Class<VeriteFilter>`	The chat filter subsystem class.
`text()`	`Class<VeriteText>`	The text formatting subsystem class.

All subsystems are static facades, so you call them directly (for example VeriteModeration.isBanned(uuid)). The accessor methods exist for discovery and centralised enabled checks.

VeriteModeration

The complete entry point for issuing, querying, and lifting punishments. durationMillis uses Punishment.PERMANENT for a permanent punishment. Gate methods return true when they stopped the player. See Custom Moderation Enforcement for the gate and listener workflow in depth.

Status and queries

Method	Returns	Meaning
`enabled()`	`boolean`	Whether the moderation module is loaded.
`isBanned(UUID player)`	`boolean`	Whether the player has an active ban.
`isMuted(UUID player)`	`boolean`	Whether the player has an active mute.
`activeBan(UUID player)`	`Punishment`	The active ban, or `null`.
`activeMute(UUID player)`	`Punishment`	The active mute, or `null`.
`history(UUID player, int limit)`	`List<Punishment>`	Recent punishment history for the player.
`byIp(String ip, int limit)`	`List<Punishment>`	Punishments recorded against an ip.
`byStaff(UUID staff, int limit)`	`List<Punishment>`	Punishments issued by a staff member.
`activeWarnings(UUID player)`	`List<Punishment>`	Currently-active warnings for the player.
`activePunishments()`	`List<ActivePunishment>`	Lightweight pointers to every active punishment.
`activeOfType(PunishmentType type, long now)`	`List<Punishment>`	Active punishments of a type at a given time.
`loadPunishment(long id)`	`Punishment`	The full record for a numeric id, or `null`.
`altsOf(UUID player)`	`List<UUID>`	Accounts sharing the player's first known ip.
`pruneHistory(UUID player, long cutoff, long now)`	`int`	Removes history older than the cutoff, returns the count removed.
`warningExpire()`	`long`	The warning expiry window in milliseconds.

Issuing punishments

Method	Returns
`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`

Lifting punishments

Method	Returns	Meaning
`unban(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Lifts the active ban, `true` on success.
`unmute(UUID target, String targetName, UUID remover, String removerName, String reason)`	`boolean`	Lifts the active mute, `true` on success.
`unwarn(UUID target, String targetName, UUID removedBy, String removedByName, String reason)`	`PunishmentResult`	Removes a warning.

Rendering and notices

Method	Returns	Meaning
`banScreen(Punishment ban)`	`String`	The full ban screen for a ban record.
`muteLine(Punishment mute)`	`String`	The one-line mute summary.
`muteNotice(Punishment mute)`	`String`	The mute notice sent to a muted player.

Chat gates

Each gate returns true when the player should be stopped and sends them the reason as a side effect. Use them where you intend to enforce.

Method	Returns	Meaning
`muteGate(Player p)`	`boolean`	Player is muted; sends the mute notice.
`chatMuteGate(Player p)`	`boolean`	Global chat freeze is active; sends the frozen notice.
`slowmodeGate(Player p)`	`boolean`	Player is held by slowmode; sends the remaining wait.

Chat commands

These drive the plugin's own chat commands for a CommandSender.

Method	Meaning
`broadcast(CommandSender sender, String[] args)`	Sends a broadcast.
`chatClear(CommandSender sender)`	Clears chat.
`chatMute(CommandSender sender)`	Toggles the global chat freeze.
`slowmode(CommandSender sender, String[] args)`	Sets slowmode.

Listener

Method	Meaning
`registerListener(ModerationListener listener)`	Subscribe to punishment activity.
`unregisterListener(ModerationListener listener)`	Stop receiving events.

VeritePlayerData

Read and record the account, session, and identity data the moderation system stores. Timestamps are epoch milliseconds. When the module is disabled, queries return null or empty and record calls are no-ops.

Method	Returns	Meaning
`enabled()`	`boolean`	Whether the data store is open.
`hasProfile(UUID player)`	`boolean`	Whether a profile exists.
`profile(UUID player)`	`PlayerProfile`	The full profile, or `null`.
`uuidByName(String name)`	`UUID`	Resolve a uuid from a name.
`nameOf(UUID player)`	`String`	Resolve the current name from a uuid.
`knownNames()`	`List<String>`	Every known name in the store.
`namesOf(UUID player)`	`List<String>`	All names a player has used.
`ipsOf(UUID player)`	`List<String>`	All ips a player has connected from.
`usersOfIp(String ip)`	`List<UUID>`	All users who shared an ip.
`clientsOf(UUID player)`	`List<String>`	All clients a player has used.
`recordLogin(UUID player, String name, String ip, long now)`	`void`	Record a login.
`recordClient(UUID player, String brand, int protocol, String referrer, long now)`	`void`	Record a client brand and protocol.
`flushSession(UUID player, long now)`	`void`	Flush the player's session.
`recordLogout(UUID player, long now)`	`void`	Record a logout.

VeriteStore and VeriteScope

VeriteStore opens named data scopes in the plugin's shared persistent key-value store, so your plugin can persist data alongside Verité with no database of its own. Namespace your scope names to avoid collisions with plugin data.

`VeriteStore` method	Returns	Meaning
`available()`	`boolean`	Whether the store is open.
`scope(String name)`	`VeriteScope`	Opens a named scope, or `null` if unavailable.

A VeriteScope is a named area you read and write freely. Writes persist through the plugin's normal flush cycle.

`VeriteScope` method	Returns	Meaning
`set(String key, Object value)`	`void`	Store a value under a key.
`delete(String key)`	`void`	Remove a key.
`has(String key)`	`boolean`	Test key presence.
`get(String key)`	`Object`	The raw stored value.
`getString(String key, String def)`	`String`	Typed read with a default.
`getLong(String key, long def)`	`long`	Typed read with a default.
`getInt(String key, int def)`	`int`	Typed read with a default.
`getBoolean(String key, boolean def)`	`boolean`	Typed read with a default.
`getBigDecimal(String key)`	`BigDecimal`	Typed read.
`entries()`	`List<ScopeEntry>`	Every key-value pair in the scope.

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

VeriteVanish

Staff vanish state and control. vanish, unvanish, and toggle return true when the state actually changed. When the module is disabled, queries return false or empty and mutating calls are no-ops.

Method	Returns	Meaning
`enabled()`	`boolean`	Whether the vanish module is loaded.
`isVanished(UUID player)`	`boolean`	Whether a player is vanished.
`isVanished(Player player)`	`boolean`	Convenience overload for an online player.
`getVanished()`	`Set<UUID>`	Every currently-vanished player.
`vanish(Player p)`	`boolean`	Vanish a player.
`unvanish(Player p)`	`boolean`	Unvanish a player.
`toggle(Player p)`	`boolean`	Toggle a player's vanish state.
`registerPlaceholders()`	`void`	Register the vanish PlaceholderAPI expansion.
`registerListener(VanishListener listener)`	`void`	Subscribe to vanish changes.
`unregisterListener(VanishListener listener)`	`void`	Stop receiving vanish events.

VeriteCaptcha

Issue and track captcha challenges. challenge methods return true when a challenge was actually started. The source label records why the challenge was opened and rides through to the completion and punishment-request events. When the module is disabled, all calls return false.

Member	Returns	Meaning
`VeriteCaptcha.BYPASS_PERMISSION`	`String`	The permission node that bypasses captcha.
`VeriteCaptcha.NOTIFY_PERMISSION`	`String`	The captcha notify permission node.
`enabled()`	`boolean`	Whether the captcha module is loaded.
`isActive(UUID player)`	`boolean`	Whether a challenge is active for the player.
`challengeStandard(Player player, String source)`	`boolean`	Open a standard challenge.
`challengeDetailed(Player player, String source)`	`boolean`	Open a detailed challenge.
`challenge(Player player, CaptchaType type, String source)`	`boolean`	Open a challenge of an explicit type.

VeriteFilter

The evasion-aware chat filter. Full workflow, including anonymous checks, repeat-aware checks, and the block message helpers, is documented in Custom Chat Integration. The surface:

Member	Returns	Meaning
`VeriteFilter.ANONYMOUS`	`UUID`	Pass as the player when there is no offender to record against.
`check(UUID player, String message)`	`FilterResult`	Classify a message and record the hit against the player.
`check(UUID player, String message, boolean repeatAware)`	`FilterOutcome`	Repeat-aware classification.
`count(UUID player)`	`int`	How many times a player has been flagged.
`blockMessage()`	`String`	The configured block message.
`repeatMessage()`	`String`	The configured repeat-message notice.
`selfHarmMessage()`	`String`	The configured self-harm notice.
`blockNotice(FilterResult result, String message)`	`BaseComponent[]`	The rendered notice component for a result.
`foldAccents(String s)`	`String`	Normalization helper: remove accents.
`stripDeletes(String s)`	`String`	Normalization helper: remove zero-width and delete characters.
`stripEntities(String s)`	`String`	Normalization helper: remove html-style entities.
`reduceRuns(String s, int max)`	`String`	Normalization helper: collapse repeated letters.
`fingerprint(String word)`	`String`	Order-independent letter signature for transposition matching.
`trimEdges(String word)`	`String`	Trim non-letter edges from a word.

The normalization helpers are pure functions and are safe to call off the main thread.

VeriteText

Parse Verite tag text and apply the plugin's prefix the way the plugin does, so your output is styled identically.

Method	Returns	Meaning
`parse(String tagged)`	`BaseComponent[]`	Parse Verite tags to a component array.
`prefixed(String tagged)`	`BaseComponent[]`	Parse and prepend the plugin prefix.
`prefix()`	`String`	The current prefix.
`setPrefix(String prefix)`	`void`	Change the prefix.

Utilities

VeriteGeoIp

Look up the country of an ip and check the GeoIP database state.

Method	Returns	Meaning
`country(String ip)`	`String`	Country name for an ip, or `null` if unresolved.
`available()`	`boolean`	Whether the GeoIP database loaded.
`isPrivate(String ip)`	`boolean`	Whether an ip is in a private or reserved range.
`attempted()`	`boolean`	Whether a database load has been attempted.

VeriteDuration

Parse and format human punishment durations, with millisecond unit constants: SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR.

Method	Returns	Meaning
`suggestions()`	`List<String>`	Suggested duration tokens.
`parse(String token)`	`long`	Parse a token such as `7d` into milliseconds.
`parseTwoToken(String number, String unitWord)`	`long`	Parse a split number and unit word into milliseconds.
`format(long millis)`	`String`	Format milliseconds into a human string.

VeriteFormat

Format times, pluralize nouns, and name client protocol versions.

Method	Returns	Meaning
`fancyTime(long millis)`	`String`	A millisecond span as a human string.
`plural(long count, String noun)`	`String`	A count with the correct singular or plural noun.
`pluralize(long count, String noun)`	`String`	A count with the correct singular or plural noun.
`versionName(int protocol)`	`String`	The Minecraft version name for a client protocol number.

VeriteLimits

Enforce the same per-issuer duration caps and cooldowns the plugin does.

Method	Returns	Meaning
`capDuration(CommandSender issuer, PunishmentType type, long requested)`	`DurationCheck`	Validate a requested duration and return the capped value.
`cooldownRemaining(CommandSender issuer, PunishmentType type, long now)`	`long`	Milliseconds until the issuer may act again.
`markUsed(CommandSender issuer, PunishmentType type, long now)`	`void`	Record that an issuer used their allowance.

VeriteMojang

Resolve a Minecraft username against Mojang, using the same path and cache the plugin uses.

Method	Returns	Meaning
`lookup(String name)`	`MojangProfile`	Resolve a name to a uuid, canonical name, and status.

VeriteExempt

Check whether an issuer is blocked from punishing a target.

Method	Returns	Meaning
`blockReason(CommandSender issuer, UUID target, PunishmentType type)`	`String`	The reason the punishment is not permitted, or `null` when allowed.

VeriteLockdown

Query and control server lockdown state. Covered in context in Custom Moderation Enforcement.

Method	Returns	Meaning
`active()`	`boolean`	Whether a lockdown is in effect.
`reason()`	`String`	The current lockdown reason.
`begin(String why)`	`void`	Start a lockdown with a reason.
`end()`	`void`	Clear the lockdown.

VeriteConfig

Read the moderation module's effective configuration.

Method	Returns	Meaning
`banAlts()`	`boolean`	Whether alt accounts are banned.
`muteCommandBlacklist()`	`List<String>`	Commands blocked while muted.
`warningExpire()`	`long`	The warning expiry window in milliseconds.
`useGroupWeights()`	`boolean`	Whether group weights are used.
`permitSameWeight()`	`boolean`	Whether same-weight actions are permitted.
`reduceToLimit()`	`boolean`	Whether durations reduce to the issuer limit.
`dupeipScanLimit()`	`int`	The dupeip scan limit.
`yaml()`	`YamlConfiguration`	The raw backing configuration.

Types

Punishment

An immutable moderation record. PERMANENT is the sentinel end timestamp for a permanent punishment (-1L). GLOBAL_SCOPE is the wildcard scope ("*"). Timestamps are epoch milliseconds. A null target ip means the punishment is uuid-scoped rather than ip-scoped.

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

Derived helpers:

Method	Returns	Meaning
`permanent()`	`boolean`	Whether `dateEnd` is `PERMANENT`.
`expired(long now)`	`boolean`	Whether a temporary punishment has passed its end.
`inForce(long now)`	`boolean`	Whether the record is active and not expired.
`duration()`	`long`	Total duration, or `PERMANENT`.
`remaining(long now)`	`long`	Remaining milliseconds, or `PERMANENT`.
`hasTemplate()`	`boolean`	Whether the record carries a template.

PunishmentType

Enum: BAN, MUTE, WARNING, KICK.

Method	Returns	Meaning
`id()`	`String`	The lowercase root-locale name.
`PunishmentType.of(String s)`	`PunishmentType`	Parse the lowercase form back, case-insensitively.

PunishmentResult

Record: PunishmentResult(boolean ok, Punishment entry, String error). On success ok is true, entry holds the resulting punishment, and error is null. On failure entry is null and error holds the reason.

ActivePunishment

Record: ActivePunishment(PunishmentType type, UUID uuid, long entryId). A lightweight pointer; load the full record with VeriteModeration.loadPunishment(entryId).

FilterResult

Enum: CLEAN, BLOCK, SELF_HARM, ABUSE, PROFANITY. blocks() returns true for anything other than CLEAN. A message stopped for repeating a recent one reports as BLOCK here; use the repeat-aware check overload to tell those apart. SELF_HARM and ABUSE mark a speaker who may be in crisis; do not treat them as ordinary rule violations.

FilterOutcome

The value from VeriteFilter.check(player, message, true).

Method	Returns	Meaning
`category()`	`FilterResult`	The ordinary filter category, never `null`.
`repeat()`	`boolean`	Whether the block was a repeat (only ever `true` when `category()` is `BLOCK`).
`blocks()`	`boolean`	Whether the message should be dropped.

PlayerProfile

Record with fields: uuid, name, names, ips, lastIp, clients, lastClient, protocol, referrer, firstJoin, lastSeen, joinCount, playtimeMs, online, punishments. Timestamps are epoch milliseconds. List fields are never null but may be empty.

MojangProfile and MojangStatus

MojangProfile(UUID uuid, String name, MojangStatus status). When status is not FOUND, uuid and name are null.

MojangStatus: FOUND (resolved), NOT_FOUND (Mojang confirmed no such account), UNKNOWN (lookup could not be completed, for example a network error).

DurationCheck

Record: DurationCheck(boolean ok, long durationMillis, String error). When ok, durationMillis holds the possibly-capped duration to apply and error is null. When not ok, error explains the rejection.

ScopeEntry

Record: ScopeEntry(String key, Object value). One key-value pair from a store scope.

CaptchaType and CaptchaOutcomeType

CaptchaType: STANDARD (a quick low-friction challenge), DETAILED (a stricter multi-step challenge).

CaptchaOutcomeType: PASS, FAIL, TIMEOUT.

Listeners

ModerationListener

Implement and register through VeriteModeration.registerListener. All methods are default no-ops, so override only what you need. Callbacks may run on the server main thread; do not block.

Method	Fires when
`entryAdded(Punishment punishment)`	A punishment is issued.
`entryRemoved(Punishment punishment)`	A punishment is lifted, pardoned, or expired.
`broadcastSent(String message, String target)`	The moderation system sends a broadcast.

VanishListener

Implement and register through VeriteVanish.registerListener. Default no-ops; do not block in callbacks.

Method	Fires when
`vanished(UUID player)`	A player enters vanish.
`unvanished(UUID player)`	A player leaves vanish.