§02 Configuration
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 offlagforge.admin) see one chat line a couple of seconds after they join, with a link to the release notes; /ff statusshows it on itsUpdates:line, which otherwise readsup to date,not checked yetorlast 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 toworld.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, whichinventory.reconciliation.aotherwise reports as unexplained. A gain withinitem-gain-windowof 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 whenitem-tagsis on. Reconciliation doesn't flag it, but it still counts towardeconomy.item_gain_rate.b's hard limits (as anUNKNOWNsource), 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 (
ActionDispatcherno-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. |