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 MiniMessage text and apply the plugin's prefix the way the plugin does, so your output is styled identically.

Method	Returns	Meaning
`parse(String miniMessage)`	`BaseComponent[]`	Parse MiniMessage to a component array.
`prefixed(String miniMessage)`	`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.