Configuration#

Configuration files#

File Covers
config.yml Operating mode (observe-only/enforcement/version-override), server identity, and the update check.
checks.yml Per-check enablement, response ceiling, and tuning parameters (thresholds, safety margins, buffers).
actions.yml Declarative policy rules, correlation rules, and the command-placeholder allowlist.
alerts.yml In-game/Discord alert routing, aggregation, and role-mention configuration.
messages.yml In-game/console message templates (MiniMessage format).
storage.yml Database dialect/connection, retention windows, persistence queue sizing.
protection.yml Packet-level protection: Anti-Xray, Anti-ESP, and the crash guard.

All six supplemental files use checks.yml's literal-dotted-key convention for check/policy IDs (e.g. movement.speed.a:), not Bukkit's default .-as-nesting behavior — this is deliberate and regression-tested (SupplementalConfigFilesTest), so keep check/rule IDs as one flat key when hand-editing.

checks.yml's own key reference lives on the Check Parameter Reference page (one section per check, plus the shared defaults: block) rather than here, since it's large enough to deserve its own page. Every other file's full key reference follows below.

config.yml#

Key Default Meaning
config-version 1 Schema version marker, bumped only if FlagForge ever needs a breaking config migration. Not administrator-editable in any meaningful sense today.
server.id "" (blank) Free-form identifier stored alongside findings/sessions. Leave blank to have FlagForge generate and persist a stable random identifier on first start.
operating-mode.observe-only true Learning/observe-only mode never cancels, sets back, kicks, or runs a command, regardless of any other configuration.
operating-mode.enforcement-enabled false Global enforcement circuit breaker. Independent of observe-only: even with this true, observe-only still wins and blocks every preventable action.
operating-mode.unsupported-version-override false Allows the jar to boot on a Minecraft/Paper version other than the locked 1.21.10 target, for development only. Never enables gameplay listeners or enforcement by itself — it only prevents the plugin from refusing to load. Do not use on a production server.
update-check.enabled true Checks for a newer FlagForge release 30 seconds after startup and then every 12 hours (see Update check below). false stops it entirely.
plugin-compatibility.attacks true Skips attacks another plugin fires on a player's behalf (see Plugin safety net below).
plugin-compatibility.block-breaks true Skips blocks another plugin breaks on a player's behalf.
plugin-compatibility.item-gains true Puts an item gain right after the player used another plugin down to that plugin.
plugin-compatibility.item-gain-window 10s How soon after that use a gain still counts as the plugin's.
plugin-compatibility.item-tags true Also puts a gain down to a plugin when the item carries that plugin's own data tags.

See Enforcement & First-Start for how the two operating-mode switches interact, and their hardcoded exceptions.

Update check#

FlagForge asks https://flagforge.szalik.dev/latest.json which version is the latest release. That file only ever names a version with a published release, never one still being tested. When the release is newer than the running jar:

  • console logs one warning naming both versions (once per new release, not every 12 hours);
  • staff with flagforge.notify.update (default: op, part of flagforge.admin) see one chat line a couple of seconds after they join, with a link to the release notes;
  • /ff status shows it on its Updates: line, which otherwise reads up to date, not checked yet or last check failed (<reason>).

A server running a newer build than the latest release (a test build) counts as up to date. The request is a plain HTTPS GET whose only identifying content is User-Agent: FlagForge/<version>; it runs off the main thread, and nothing is ever downloaded or installed. If the site can't be reached, console says so once and the check quietly retries 12 hours later.

Plugin safety net#

Many public plugins act on a player's behalf in ways that look like cheating when read as the player's own actions. The plugin-compatibility section stops FlagForge reading them that way, with no setup and no knowledge of the particular plugin:

  • Attacks (attacks). An area attack such as mcMMO's Serrated Strikes or Skull Splitter, or a custom enchant's area damage, hits nearby players by firing a new attack while the player's own attack is still being handled. Those extra hits would otherwise look like reach, multi-target or attack-rate cheats. FlagForge skips an attack fired inside another one by the same player, and a plugin's own subclass of the attack event. The player's own attack is still checked.
  • Block breaks (block-breaks). Vein miners and tree fellers break more blocks the same way, and mcMMO fires its own "fake" break events for protection plugins. The world checks skip those, so they no longer add up to world.nuker.a; the block the player broke themselves is still checked, and keeps its dig timing.
  • Item gains (item-gains). Kits, crates, shops, quests and vote rewards usually add items straight into the inventory, which inventory.reconciliation.a otherwise reports as unexplained. A gain within item-gain-window of the player running a command another plugin registered, or opening, clicking in or closing a plugin's menu, is put down to that plugin, as is a gain of an item carrying a plugin's own data tags when item-tags is on. Reconciliation doesn't flag it, but it still counts toward economy.item_gain_rate.b's hard limits (as an UNKNOWN source), so a duplication exploit that floods items through a plugin's menu is still caught there.

/ff status shows which parts are on and how many attacks, breaks and gains each skipped this session. Console names each excused gain at the FINE log level.

What it can't tell apart: an extra attack or break a plugin fires later than the player's own event (from a scheduled task, for example) is checked like a real one, and a duplication exploit inside a plugin's menu that stays under the hard gain limits isn't flagged by reconciliation. If a plugin you rely on still causes flags, its developers can declare its actions through the API, which is always exact. Set item-tags: false if a plugin's custom items, such as crate keys, are valuable enough that duplicating them matters.

actions.yml#

Key Default Meaning
config-version 1 Schema version marker.
policies [] (empty) Declarative response rules, evaluated by the policy engine for every finding. See below for the rule shape. No policy ships enabled by default.
correlations 3 rules shipped Evidence-family correlation rules. See below for the rule shape and the shipped rules.
command-safety.allowed-placeholders %player_uuid%, %player_name%, %finding_id%, %incident_id% The only placeholders a command: value (in a policy or correlation) may contain. Configuration referencing any other %...%-shaped placeholder is rejected — this is the one thing standing between a COMMAND response and letting arbitrary player-controlled text reach a console command, so it is not user-extensible.

A policy rule (policies: list entry):

Field Meaning
id Unique identifier for the rule (for logs//ff status, not a check ID).
check The check ID this rule reacts to.
min-evidence-class Minimum evidence class (ANOMALY/HEURISTIC/PROTOCOL_INVALID/SERVER_IMPOSSIBLE) a finding must carry for this rule to match.
min-escalation-stage Minimum escalation stage (0–3: how many of the fixed violation-level thresholds — 1.0/3.0/8.0 — the player's current, decaying VL for this check has crossed) required before this rule matches. checks.yml's vl-half-life controls how fast VL (and so this stage) decays back down between findings; the three thresholds themselves aren't currently configurable.
response The response to apply if every condition matches — capped at that check's own response-ceiling (checks.yml) and at MONITOR while enforcement is off.

Example (inert until inventory.illegal_item.a's own ceiling is raised above its shipped NOTIFY):

policies:
  - id: repeated-illegal-item-kick
    check: inventory.illegal_item.a
    min-evidence-class: SERVER_IMPOSSIBLE
    min-escalation-stage: 2
    response: KICK

A correlation rule (correlations: map entry):

Field Meaning
within Time window inside which every required family's evidence must land to count as correlated.
require List of {family, min-confidence} pairs — independent evidence families that must each contribute a finding at or above min-confidence within within.
add-risk Risk added to the player's aggregate score when this correlation matches, on top of each contributing finding's own risk.
response-ceiling Strongest response this correlation's match can justify — independent of any single contributing check's own ceiling, and still capped by the global observe-only/enforcement-enabled switches.
command Only meaningful when response-ceiling: COMMAND. Console command to run, using only allowlisted placeholders (above). Unset by default on every shipped correlation.

The three shipped correlations:

ID Requires (within) Response ceiling Purpose
confirmed-inventory-generation INVENTORY_CONSERVATION ≥ 0.90 + ITEM_GENERATION_RATE ≥ 0.60 (15s) CANCEL Strong dupe evidence — a sustained generation-rate finding plus a confirmed, persistent unexplained inventory delta.
suspected-dupe-backup-trigger INVENTORY_CONSERVATION ≥ 0.55 + ITEM_GENERATION_RATE ≥ 0.50 (15s) COMMAND (unset by default) Much weaker-evidence trigger for an external backup/snapshot tool — see Tuning Guide.
combo-hack-signature ATTACK_GEOMETRY ≥ 0.5 + REACTION_TIMING ≥ 0.5 (30s) NOTIFY Classic "all-in-one" cheat-client combo signature (killaura-class combat finding plus an auto-totem-macro finding). Currently inert in practice: every contributing check on both sides ships experimental/disabled by default.

Run /ff correlations to see every configured correlation rule's thresholds live, and whether a rule's confidence requirement is currently unreachable given your checks.yml settings.

alerts.yml#

In-game alerts (ingame.*)#

Key Default Meaning
ingame.enabled true Master switch for in-game staff alerts (/ff alerts still gates individual staff members' own delivery on top of this).
ingame.minimum-confidence 0.50 Findings below this confidence never generate an in-game alert.
ingame.alert-cooldown 5s Parsed but not currently consumed anywhere — see Known Limitations. Each alert-eligible finding sends an in-game alert immediately, with no per-player/check cooldown of its own beyond checks.yml's own alert-cooldown upstream (which gates whether a finding is alert-eligible at all).
ingame.aggregate-window 3s Parsed but not currently consumed anywhere — see Known Limitations. In-game alerts are not currently aggregated; only Discord delivery aggregates (discord.aggregate-window, below, which is live).

Discord alerts (discord.*)#

Key Default Meaning
discord.enabled false Master switch — off until an administrator sets up a webhook. See Discord Staff Alerts.
discord.webhook-url "${FLAGFORGE_DISCORD_WEBHOOK_URL}" Environment-variable reference by default; can be replaced with a literal URL (then the file holds a plaintext secret — see Discord Staff Alerts).
discord.delivery-mode ALWAYS One of OFF, ALWAYS, WHEN_NO_INGAME_STAFF, HIGH_RISK_ONLY.
discord.minimum-confidence 0.60 Findings below this confidence never generate a Discord alert.
discord.minimum-vl-delta 1.0 Findings whose violation-level delta is below this never generate a Discord alert, even if confidence qualifies.
discord.include-coarse-location true Whether the embed includes coarse (block-level, not exact) coordinates when a finding carries a position.
discord.aggregate-window 3s Same aggregation behavior as ingame.aggregate-window, applied to Discord delivery.
discord.role-mention.enabled false Whether serious findings ping a configured role.
discord.role-mention.role-id "${FLAGFORGE_DISCORD_STAFF_ROLE_ID}" Numeric Discord role ID only — never a role name, and never derived from player-controlled text. Same environment-variable-or-literal choice as webhook-url.
discord.role-mention.minimum-confidence 0.90 Confidence floor for a role mention, independent of (and stricter than) discord.minimum-confidence.
discord.role-mention.minimum-incident-risk 70 Aggregate incident risk floor for a role mention.
discord.role-mention.evidence-classes [SERVER_IMPOSSIBLE, PROTOCOL_INVALID] Only findings in one of these evidence classes can ever trigger a role mention, regardless of confidence/risk.
discord.role-mention.mention-on-test false Whether /ff discord test itself pings the role — left off by default so testing delivery doesn't wake staff up.
discord.outbound-queue.capacity 1000 Maximum queued-but-undelivered Discord messages before new ones are dropped (logged, never silently lost without a trace).
discord.outbound-queue.request-timeout 10s Per-request HTTP timeout to Discord's webhook endpoint.
discord.outbound-queue.maximum-attempts 5 Retry ceiling per message before it's given up on.
discord.outbound-queue.maximum-backoff 2m Retry backoff cap — see Discord Staff Alerts for the full retry/circuit-breaker behavior.
discord.privacy.include-player-uuid true Whether the embed includes the player's UUID.
discord.privacy.include-world true Whether the embed includes the world name.
discord.privacy.include-exact-coordinates false Parsed and stored, but not currently read by the Discord embed builder — only discord.include-coarse-location (above) actually affects what's sent. See Known Limitations.

storage.yml#

Key Default Meaning
config-version 1 Schema version marker.
dialect SQLITE One of SQLITE, POSTGRESQL, MYSQL (MariaDB-compatible).
sqlite.file "flagforge.db" Path (relative to the plugin's data folder) to the SQLite database file. Ignored for other dialects.
sql.host "localhost" PostgreSQL/MySQL host. Ignored for SQLite.
sql.port 5432 for PostgreSQL, 3306 for MySQL Database port. Left unset (commented out) in the shipped file so the dialect's standard port applies; set it only if your database listens elsewhere.
sql.database "flagforge" Database name.
sql.username "flagforge" Database username.
sql.password "${FLAGFORGE_DB_PASSWORD}" Environment-variable reference by default; a literal value works too, at the same plaintext-secret-on-disk cost as the Discord webhook URL.
sql.pool.maximum-pool-size 10 Maximum concurrent database connections.
sql.pool.minimum-idle 2 Minimum idle connections kept warm in the pool.
sql.pool.connection-timeout 10s How long to wait for a connection from the pool before failing that operation.
retention.detailed-evidence-days 14 How long a finding's full evidence (ff_findings) is kept before the scheduled purge task deletes it. The only retention window currently enforced by any purge logic — see Known Limitations.
retention.aggregate-statistics-days 90 Parsed, but no aggregate-statistics purge logic currently exists in the codebase (there is no dedicated aggregate-statistics table to purge from either — see Data Model).
retention.ledger-entries-days 14 Parsed, but ff_actions (the action ledger) has no retention-expiry column and is never purged by the scheduled task — it currently grows unbounded. Only /ff purge (manual, and scoped to findings) touches stored data otherwise.
retention.check-interval 6h How often the scheduled async purge task runs (currently: ff_findings only). Clamped to a 60-second floor regardless of a lower configured value. A plain interval rather than a cron expression, to keep FlagForge free of a cron-parsing dependency for something that only needs to happen periodically.
queue.capacity 5000 Maximum queued-but-unwritten persistence records before new ones are dropped (logged).
queue.batch-size 200 Records written per database batch.
queue.batch-interval 500ms Maximum time a partial batch waits before flushing, even if batch-size isn't reached.

See Privacy & Retention for what's actually retained, and the Data Model page for the underlying table schema these settings govern.

If the database is unreachable or migration fails, FlagForge disables persistence for that session (logging why) rather than blocking plugin startup or gameplay — a database outage degrades to silent-observation-only, it never freezes or punishes:

  • Detection still runs, but findings are never stored.
  • Alerts and Discord delivery are disabled.
  • No preventable action ever executes (ActionDispatcher no-ops entirely without storage).

messages.yml#

Staff-facing and console text, in MiniMessage format (e.g. <gold>...</gold>, <red>...</red>) where noted. Every value is a plain string template with <placeholder>-style tokens substituted at send time — editing the text is safe; removing a placeholder just means that piece of information no longer appears in the message.

Key Purpose Placeholders
prefix Prepended to compact alert lines. Default: "<gray>[<gold>FlagForge</gold>]</gray> ". —
startup.enabled Startup banner shown when the plugin finishes enabling. <observe_only>, <enforcement_enabled>
startup.disabled Shown when the plugin disables. —
startup.unsupported-version Shown when the running server version doesn't match the locked target (see Enforcement & First-Start). <server_version>, <target_version>
alerts.ingame-compact The one in-game staff alert line format. <player>, <check_id>, <vl_delta>, <vl_total>, <explanation>, <confidence>, <tps>, <ping>, <finding_id> (plus <prefix>, expanded from the prefix key above)
commands.no-permission Shown when a sender lacks the permission for a /ff subcommand. —
commands.reload-success Shown after a successful /ff reload. —
commands.reload-failure Shown after a rejected /ff reload (the previous configuration stays active). <reason>

protection.yml#

Preventive protection at the packet level, rather than detection after the fact. All three features need PacketEvents installed (see Getting Started); without it they stay loaded but inactive. protection.yml is read once at startup, so changes need a restart — /ff reload does not reload it.

Crash guard (crash-guard.*)#

Refuses client packets carrying values no unmodified client sends, before the server handles them. On by default: it never touches a packet a vanilla client can send.

Key Default Meaning
crash-guard.enabled true Turns the guard on. A protection.yml from before 1.1.0 has no crash-guard section, and the guard is then on.
crash-guard.log-drops true Writes a console line, at most once a minute per player, whenever the guard catches a packet.

What it holds packets to:

Packet Caught when What happens
Inventory click Window ID outside 0–100; slot outside the largest menu (90 slots) other than -1 and -999; more than 90 changed slots; a button its click mode never uses; an unknown click mode Dropped
Creative inventory Slot outside -1–45 Dropped
Held item Slot outside 0–8 Let through: Paper disconnects the client ("Invalid hotbar selection")
Command suggestion (Tab) Brackets nested more than 64 deep outside quoted text Dropped
Command suggestion (Tab) Longer than 2048 characters Let through: Paper's decoder disconnects the client
Book edit Slot other than the hotbar or offhand Dropped
Book edit More than 100 pages, a page over 1024 characters, or a title over 32 Let through: the server's own decoder disconnects the client
Anvil rename Name over 50 characters Dropped
Plugin message Channel name over 256 characters, on the message or inside a channel registration (in play or during configuration) Dropped
Plugin message A channel registration listing more than 128 channels (in play or during configuration) Let through: Paper disconnects the client ("Invalid custom payload")
Plugin message Payload over 32767 bytes Let through: the server disconnects the client
Player rotation Pitch beyond ±90° Let through: the server clamps it
Player rotation, vehicle move NaN or infinite values Let through: the server disconnects the client

A drop is data-validity protection, the same as packet.payload.a's NaN guard: it applies regardless of observe-only/enforcement-enabled, and to flagforge.bypass holders too. Packets the server already answers with a disconnect are only recorded, so that disconnect still happens. A packet PacketEvents cannot decode is left alone for the server to judge. Which packets Paper 1.21.10 already disconnects for was measured against a live server, one crafted packet at a time.

The guard drops packets whether or not packet.payload.b is enabled; enable that check (see the Check Parameter Reference) to also get staff alerts and findings for what it catches.

Paper has its own limits that work alongside the guard. In config/paper-global.yml, packet-limiter kicks a client sending more than 500 packets a second in total and drops recipe book spam, spam-limiter limits Tab completion, and item-validation caps book and item text sizes. Leave them at their defaults.

Anti-Xray (anti-xray.*)#

Masks configured ore blocks in outgoing chunk data unless they are exposed to air. Off by default.

Key Default Meaning
anti-xray.enabled false Turns Anti-Xray on.
anti-xray.worlds [] Worlds it applies to; empty means every world. Names must match World#getName().
anti-xray.blocks the overworld and nether ores Block IDs to mask unless exposed to air on at least one face.
anti-xray.replacements stone, deepslate or netherrack per ore What each masked block is disguised as. A block in blocks without a replacement is skipped, with a startup warning.

Anti-ESP (anti-esp.*)#

Hides players from each other while a wall is between them. Off by default.

Key Default Meaning
anti-esp.enabled false Turns Anti-ESP on.
anti-esp.worlds [] Worlds it applies to; empty means every world.
anti-esp.max-distance 64 Players farther apart than this (blocks) are never checked against each other.
anti-esp.scan-interval-ticks 4 How often each viewer/target pair in range is re-checked.
anti-esp.occluded-checks-to-hide 3 Consecutive blocked checks before a visible target is hidden.
anti-esp.visible-checks-to-reveal 1 Consecutive clear checks before a hidden target is shown again.