§04 Check Parameter Reference
Check Parameter Reference#
Every tunable checks.yml key for all 39 checks, with its shipped default and what it means. See
the Check Catalog for the browsable overview (evidence class,
enabled/experimental, one-line purpose) and the Tuning Guide for how
to use these safely (buffers, safety margins, quality gates).
Every check also accepts enabled: true|false and response-ceiling (see the Tuning Guide);
those two are omitted from the tables below since they're universal. A check with no table below
has no tunable parameters beyond those two.
Shared defaults#
These five keys live once, under checks.yml's top-level defaults: block, and apply to every
check — there is currently no per-check override for any of them:
| Key | Default | Meaning |
|---|---|---|
enabled |
true |
Fallback enabled-state for a check with no explicit enabled: of its own. In practice every shipped check sets its own, so this only matters for a check an administrator adds without one. |
min-tps |
18.0 |
Below this server TPS, finding confidence is automatically reduced across every check (lag looks like cheating; this compensates). |
max-ping-ms |
450 |
Above this ping, finding confidence is automatically reduced the same way. |
alert-cooldown |
5s |
Minimum time between two in-game staff alerts for the same player/check pairing. |
vl-half-life |
10m |
How long it takes a player's accumulated violation level to decay by half with no new findings. |
defaults.observe-only also appears in the shipped file but is not currently read anywhere in
FlagForge's config loader — the one switch that actually controls enforcement is config.yml's
operating-mode.observe-only (see Enforcement & First-Start).
Editing checks.yml's copy has no effect; this is disclosed here rather than left for you to
discover by testing it.
Economy and inventory#
economy.item_gain_rate.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: ITEM_GENERATION_RATE.
| Key | Default | Meaning |
|---|---|---|
materials.<material>.soft-limits |
see below | Map of window → item count. Crossing it flags a soft, notify-only anomaly for that material. |
materials.<material>.generation-sources |
see below | Which TransactionCause values count toward this material's rate (e.g. MINING, LOOT, PICKUP). |
Shipped for two materials:
| Material | Window | Soft limit | Generation sources |
|---|---|---|---|
diamond |
60s |
64 | MINING, LOOT, PICKUP |
diamond |
5m |
192 | MINING, LOOT, PICKUP |
ancient_debris |
60s |
12 | MINING |
ancient_debris |
5m |
36 | MINING |
economy.item_gain_rate.b#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family: ITEM_GENERATION_RATE.
The hard-ceiling sibling of economy.item_gain_rate.a — same material/window shape, but a harder
limit and it also counts UNKNOWN-source gains (a.'s soft limits deliberately don't, to avoid
flagging normal play before the hard ceiling is even close).
| Key | Default | Meaning |
|---|---|---|
materials.<material>.hard-limits |
see below | Map of window → item count. Crossing it is a much stronger signal than the .a soft limit. |
materials.<material>.generation-sources |
see below | Same as .a, but includes UNKNOWN. |
| Material | Window | Hard limit | Generation sources |
|---|---|---|---|
diamond |
60s |
256 | MINING, LOOT, PICKUP, UNKNOWN |
ancient_debris |
60s |
48 | MINING, UNKNOWN |
inventory.reconciliation.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family:
INVENTORY_CONSERVATION. Measures the player's whole inventory (storage, armor, offhand), the
item on their cursor, and the contents of any bundles in it. Creative and Spectator players are
not reconciled, and changing game mode starts over from a fresh baseline. See
API Integration for which gains
other plugins must declare.
| Key | Default | Meaning |
|---|---|---|
confirmation-snapshots |
2 |
Consecutive inventory snapshots that must agree before an unexplained delta is confirmed rather than treated as a transient inconsistency. |
minimum-positive-delta |
1 |
Smallest unexplained item-count increase worth evaluating at all. |
coverage-complete |
false |
Whether every legitimate cause of a positive delta is covered by a live adapter. Left false (caps confidence around 0.6, i.e. HEURISTIC) until every generation source in your setup is verified adapter-covered; only set true once you've confirmed that, since it unlocks up to SERVER_IMPOSSIBLE-tier confidence (~0.96). See the Tuning Guide for how this interacts with actions.yml's dupe correlation rules. |
inventory.illegal_stack.a#
SERVER_IMPOSSIBLE, enabled by default, response-ceiling NOTIFY. Evidence family:
INVALID_ITEM_STATE.
| Key | Default | Meaning |
|---|---|---|
stack-size-allowlist |
[] (empty) |
Materials permitted to exceed vanilla's own max-stack-size without flagging — e.g. a custom item plugin's own oversized stacks. Prefer the flagforge-api's authorizeItem (see API Integration) over hand-editing this for anything another plugin issues dynamically. |
inventory.illegal_item.a#
SERVER_IMPOSSIBLE, enabled by default, response-ceiling NOTIFY. Evidence family:
INVALID_ITEM_STATE.
| Key | Default | Meaning |
|---|---|---|
material-denylist |
minecraft:command_block, minecraft:chain_command_block, minecraft:repeating_command_block, minecraft:command_block_minecart, minecraft:jigsaw, minecraft:structure_block, minecraft:barrier, minecraft:light |
Materials that should never legitimately be in a player's inventory. Add your own server-specific admin-only items here if they're obtainable via /give but should never appear on a player. |
inventory.transaction_burst.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family: TRANSACTION_RATE.
| Key | Default | Meaning |
|---|---|---|
window |
1s |
Rolling window over which inventory transactions are counted. |
threshold |
20 |
Transactions within window before this flags. |
A transaction is one item type moved in one tick. Items moved in or out of a menu another plugin made (a shop, a crate, a custom crafter) and gains the plugin safety net put down to another plugin are not counted.
Movement#
movement.speed.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: MOVEMENT_KINEMATICS.
| Key | Default | Meaning |
|---|---|---|
safety-margin |
1.5 |
Multiplier over the mechanics-aware base speed before a sample even counts as anomalous. Raising it makes the check more lenient. |
buffer.flag-at |
6.0 |
Accumulated buffer value a player must cross before a finding actually fires — a single marginal sample never flags alone. |
buffer.decay-per-valid-sample |
0.25 |
How much the buffer decays back down on each clean (non-anomalous) sample. |
The base speed is scaled by the player's live movement_speed attribute relative to vanilla's
0.1, so Speed and Slowness, Soul Speed, and anything a plugin or /attribute changes are all
followed.
movement.flight.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family: MOVEMENT_KINEMATICS.
| Key | Default | Meaning |
|---|---|---|
required-consecutive-samples |
10 |
Consecutive airborne, unsupported, non-descending samples required before this counts as evidence rather than an ordinary jump. Each Jump Boost level adds 4. |
Ground support is tested against the player's full hitbox width and the real collision shape of the blocks beneath, so standing on a block edge, a fence, or a wall counts as supported. The streak also resets under Slow Falling, inside cobwebs, sweet berry bushes, and powder snow, and for 3 seconds after standing on a slime block or bed.
movement.nofall.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family: MOVEMENT_KINEMATICS.
| Key | Default | Meaning |
|---|---|---|
minimum-fall-distance |
3.5 |
Smallest fall distance (blocks) worth checking the resulting fall-damage sequence for consistency. Raised by however far the player's safe_fall_distance attribute exceeds vanilla's 3.0 (Jump Boost adds 1 per level). |
Any fall-damage event the server fires counts as confirmation, even one cancelled by another plugin
(for example a protected region or god mode) or reduced to zero by armor. Players who cannot take
fall damage at all (the fallDamage gamerule is off, they are invulnerable, or their fall-damage
multiplier is zero) are not checked. Slow Falling and slowing blocks (cobweb, sweet berry bush,
powder snow) reset the tracked fall, as they do in vanilla.
movement.timer.a#
HEURISTIC, enabled by default (requires PacketEvents — see
Getting Started), response-ceiling NOTIFY. Evidence family:
PACKET_VALIDITY_ORDER.
| Key | Default | Meaning |
|---|---|---|
balance-allowance-ms |
500 |
How far the client's clock may run ahead of real time before this flags. Each movement packet adds one 50 ms client tick; real time subtracts. |
max-deficit-ms |
1000 |
How far behind real time the balance may fall. Late packets after lag or a client freeze only repay this deficit, and the cap stops idle time from being banked for a later burst. |
Measured in real time, not server ticks, so a lagging or stalled server never makes a normal
client look fast. The old threshold key is no longer read.
movement.waterwalk.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: COLLISION_GROUND_STATE.
Promoted from experimental: false-positive fixtures cover the swimming/riptide/vehicle/flight
exemptions and sustained-vs-transient hover.
| Key | Default | Meaning |
|---|---|---|
required-consecutive-samples |
15 |
Consecutive samples of invalid sustained support over fluid required before flagging. |
max-surface-depth |
0.25 |
Only samples with the feet within this many blocks of the fluid surface count. Vanilla lifts a player holding jump only while they are more than 0.4 blocks under, so treading water bobs around that depth. |
Bubble columns are exempt.
movement.elytra.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: MOVEMENT_KINEMATICS.
Promoted from experimental — its ceiling is deliberately one-directional and generous, so it can
only ever under-detect, never falsely flag a legitimate dive.
| Key | Default | Meaning |
|---|---|---|
max-speed |
60.0 |
Elytra horizontal speed (blocks/second) beyond which acceleration is considered impossible. |
Vertical speed is not counted, since a straight dive is the fastest legitimate elytra movement. After a dive the ceiling is raised to that dive's speed, and the extra allowance fades at vanilla's elytra drag (1% per tick), so pulling out of a dive never flags.
movement.step.a — experimental#
ANOMALY, disabled by default, response-ceiling NOTIFY. Evidence family: MOVEMENT_KINEMATICS.
| Key | Default | Meaning |
|---|---|---|
max-step-height |
0.6 |
Largest instant upward step (blocks) considered vanilla-plausible. |
movement.phase.a — experimental#
SERVER_IMPOSSIBLE, disabled by default, response-ceiling NOTIFY. Evidence family:
COLLISION_GROUND_STATE. No tunable parameters beyond enabled/response-ceiling. Samples the
movement path every 0.25 blocks at three heights inside the player against each block's real
collision shape, so slabs, stairs, open doors and fence gates are judged by their actual shape.
Still not a full sweep of the whole hitbox — see
Known Limitations.
movement.suspicious_teleport.a — experimental#
ANOMALY, disabled by default, response-ceiling NOTIFY. Evidence family: not mapped
(UNKNOWN — see Tuning Guide for what that means
for correlation rules).
| Key | Default | Meaning |
|---|---|---|
minimum-distance-blocks |
30.0 |
Smallest teleport distance (blocks) with an unattributed (TeleportCause.UNKNOWN) cause worth flagging. |
Combat#
Every combat check below only evaluates player-versus-player attacks — see Known Limitations.
combat.reach.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: ATTACK_GEOMETRY.
| Key | Default | Meaning |
|---|---|---|
safety-margin |
1.2 |
Multiplier over the latency-compensated reach envelope before a sample counts as anomalous. |
flag-at |
3.0 |
Buffer value that must be crossed before a finding fires. |
decay-per-valid-sample |
0.5 |
Buffer decay on each clean sample. |
The envelope starts from the attacker's live entity_interaction_range attribute (vanilla 3.0),
so reach granted by a plugin, item or /attribute is followed.
combat.attack_rate.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family: ATTACK_GEOMETRY.
| Key | Default | Meaning |
|---|---|---|
window |
1s |
Rolling window over which attacks are counted. |
threshold |
15 |
Attacks within window before this flags. |
combat.multitarget.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family: ATTACK_GEOMETRY.
| Key | Default | Meaning |
|---|---|---|
window |
300ms |
Interval within which two distinct targets must be hit to be compared. |
min-angle-degrees |
100.0 |
Minimum angular separation between the two targets (from the attacker) before it's implausible to have hit both legitimately. |
combat.bad_order.a#
PROTOCOL_INVALID, enabled by default, response-ceiling NOTIFY. Evidence family:
PACKET_VALIDITY_ORDER. The vanilla 1.9+ client sends its attack packet first and its arm-swing
packet right after, so FlagForge waits up to 3 ticks after each attack for that trailing swing (a
swing in the 250 ms before the attack also counts). Only an attack with no swing on either side adds
to the buffer.
| Key | Default | Meaning |
|---|---|---|
flag-at |
2.0 |
Buffer level at which unswung attacks flag. Each unswung attack adds 1, so a single one never flags alone. |
decay-per-valid-sample |
0.25 |
Buffer decay per normally-swung attack. |
combat.totem_swap.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: REACTION_TIMING.
Promoted from experimental: fixtures directly cover a single instant rearm never flagging alone,
and one human-paced rearm resetting the streak.
| Key | Default | Meaning |
|---|---|---|
min-millis-since-pop |
300 |
Time since the previous totem popped, below which re-equipping a new one into the offhand is implausibly fast for a real player opening an inventory and clicking a slot. |
required-streak |
2 |
Consecutive fast re-equips required before flagging. |
combat.line_of_sight.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family: ATTACK_GEOMETRY.
Buffered like combat.reach.a — thin/irregular geometry (fence gates, trapdoors, doorways) can
legitimately obstruct line of sight occasionally, so one obstructed hit alone never flags.
Promoted from experimental: fixtures directly cover that buffering.
| Key | Default | Meaning |
|---|---|---|
flag-at |
4.0 |
Buffer value that must be crossed before a finding fires. |
decay-per-valid-sample |
0.5 |
Buffer decay on each clean sample. |
combat.rotation.a — experimental#
HEURISTIC, disabled by default, response-ceiling NOTIFY. Evidence family:
AIM_ROTATION_STATISTICS.
| Key | Default | Meaning |
|---|---|---|
max-degrees-per-second |
1800.0 |
Rotation speed beyond which a snap-onto-target turn is suspicious. |
target-tolerance-degrees |
4.0 |
How close the resulting aim must land to the target's actual position to count as a "snap". |
required-streak |
3 |
Consecutive snap-rotations required before flagging. |
combat.autoclicker.a — experimental#
HEURISTIC, disabled by default, response-ceiling NOTIFY. Evidence family:
AIM_ROTATION_STATISTICS.
| Key | Default | Meaning |
|---|---|---|
sample-window |
30 |
Number of click intervals sampled before computing statistics. |
max-coefficient-of-variation |
0.15 |
Click-timing variability below this is unnaturally regular (a human's timing varies more). |
max-mean-interval-ms |
200.0 |
Average click interval below this, combined with low variability, is considered suspicious. |
combat.velocity.a — experimental#
ANOMALY, disabled by default, response-ceiling NOTIFY. Evidence family: ATTACK_GEOMETRY. The
dominant false-positive source is a victim knocked back straight into a wall, which this check
cannot see — see the comment in checks.yml and the VelocityCheck javadoc before enabling.
| Key | Default | Meaning |
|---|---|---|
min-ratio |
0.35 |
Fraction of the server's own applied knockback the victim must actually exhibit to count as "received enough knockback". Below this, and buffered, it's anti-knockback evidence. |
flag-at |
4.0 |
Buffer value that must be crossed before a finding fires. |
decay-per-valid-sample |
0.5 |
Buffer decay on each clean sample. |
World and interaction#
world.fastbreak.a, world.nuker.a, world.fastplace.a, world.interaction_reach.a, and
combat.reach.a only evaluate players in Survival or Adventure: Creative breaks instantly, places
without delay, and reaches further.
world.fastbreak.a#
SERVER_IMPOSSIBLE, enabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING.
| Key | Default | Meaning |
|---|---|---|
safety-margin |
0.6 |
Fraction below the server's own computed minimum break time still tolerated before flagging. |
A break is only timed when FlagForge saw the player start digging that same block. Blocks broken on the player's behalf by another plugin (vein miners, tree fellers) are skipped, not treated as 0 ms.
world.nuker.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING.
| Key | Default | Meaning |
|---|---|---|
window |
1s |
Rolling window over which block breaks are counted. |
threshold |
8 |
Non-instant breaks within window before this flags. |
insta-break-threshold |
22 |
Instant breaks (grass, crops, insta-mine tools) within window before this flags. Counted separately, since a legitimate player can break one per tick. |
world.fastplace.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING.
| Key | Default | Meaning |
|---|---|---|
window |
1s |
Rolling window over which block placements are counted. |
threshold |
12 |
Placements within window before this flags. See the printer-mode worked example for how to exempt a legitimate high-rate placement tool instead of loosening this globally. |
world.interaction_reach.a#
ANOMALY, enabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING.
| Key | Default | Meaning |
|---|---|---|
safety-margin |
1.3 |
Multiplier over the conservative block-break reach envelope before a sample counts as anomalous. |
The envelope starts from the player's live block_interaction_range attribute (vanilla 4.5), and
distance is measured from the player's live position, including while riding a vehicle.
world.impossible_action.a#
SERVER_IMPOSSIBLE, enabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING.
| Key | Default | Meaning |
|---|---|---|
hard-ceiling-blocks |
8.0 |
Block-placement distance beyond which it's impossible regardless of latency — never adjusted for ping, unlike world.interaction_reach.a. Raised by however far the player's block_interaction_range attribute exceeds vanilla's 4.5. |
world.floating_place.a#
SERVER_IMPOSSIBLE, enabled by default, response-ceiling NOTIFY. Evidence family: not mapped
(UNKNOWN). No tunable parameters beyond enabled/response-ceiling. Promoted from experimental
— the concern about replaceable-block placements (tall grass, snow layers, water) doesn't apply:
Bukkit's getBlockAgainst() resolves to the real, non-air block in those legitimate cases too, so
this check never has to reason about block type at all (see FloatingPlaceCheck's javadoc).
Scaffolding is exempt, because extending a scaffolding column places the new piece away from the
clicked one.
world.tnt_prime_rate.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING. Server-load protection, not a cheat signature — TNT cannons/mass
explosions are legitimate on gamemodes like factions; only directly player-triggered priming is
counted (see checks.yml's comment). Promoted from experimental: same shape as the already-stable
world.nuker.a (a plain rate ceiling over player-attributed events).
| Key | Default | Meaning |
|---|---|---|
window |
2s |
Rolling window over which player-triggered TNT primes are counted. |
threshold |
5 |
Primes within window before this flags. |
world.scaffold.a — experimental#
HEURISTIC, disabled by default, response-ceiling NOTIFY. Evidence family:
WORLD_INTERACTION_TIMING.
| Key | Default | Meaning |
|---|---|---|
max-horizontal-distance |
1.5 |
Horizontal distance (blocks) still considered normal bridging. |
max-vertical-distance |
2.0 |
Vertical distance (blocks) still considered normal bridging. |
min-pitch-degrees |
60.0 |
How steeply the player must be looking down for a placement to count toward this check. |
min-speed-blocks-per-second |
3.0 |
Minimum movement speed while bridging for a placement to count. |
required-streak |
5 |
Consecutive qualifying placements required before flagging. |
world.pearl_clip.a — experimental#
ANOMALY, disabled by default, response-ceiling NOTIFY. Evidence family: COLLISION_GROUND_STATE.
No tunable parameters beyond enabled/response-ceiling. A landing can also embed an honest
player by accident (a known vanilla quirk) — see the PearlClipCheck javadoc for the exact,
deliberately narrow scope before enabling.
world.xray_ore_rate.a — experimental#
ANOMALY, disabled by default, response-ceiling NOTIFY. Evidence family: not mapped (UNKNOWN).
Inherently statistical, not proof — a player who already explored/mapped an area can legitimately
mine ore efficiently. Confidence is capped well below other checks.
| Key | Default | Meaning |
|---|---|---|
window |
10m |
Rolling window over which the ore ratio is computed. |
minimum-total-blocks |
100 |
Minimum blocks mined in window before the ratio is evaluated at all (avoids flagging a small sample). |
minimum-ore-blocks |
4 |
Minimum ore blocks mined in window before evaluation. |
max-legitimate-ratio |
0.05 |
Ore-to-total ratio above which mining efficiency is considered anomalous. |
Packet/protocol#
packet.rate.a#
HEURISTIC, enabled by default (requires PacketEvents), response-ceiling NOTIFY. Evidence family:
PACKET_VALIDITY_ORDER.
| Key | Default | Meaning |
|---|---|---|
threshold |
40 |
Combat/interaction packets/second ceiling before this flags a flood. |
packet.sequence.a#
PROTOCOL_INVALID, enabled by default (requires PacketEvents), response-ceiling NOTIFY. Evidence
family: PACKET_VALIDITY_ORDER. Counts attack packets targeting an entity ID the server never sent
to that client. Every spawn and destroy packet sent to the client is tracked, including packet-only
NPCs and holograms from other plugins, and an entity stays valid for 2 seconds after its destroy
packet so hitting a mob that just died is not invalid.
| Key | Default | Meaning |
|---|---|---|
window |
30s |
Rolling window over which invalid attacks are counted. |
threshold |
2 |
Invalid attacks within window before this flags. |
packet.payload.a#
SERVER_IMPOSSIBLE, enabled by default, response-ceiling CANCEL. Evidence family:
PACKET_VALIDITY_ORDER. No tunable parameters beyond enabled/response-ceiling — NaN/infinite
movement coordinates are unconditionally invalid.
This is the one check with a real, working cancel, but not through the normal policy pipeline: a
non-finite position is rejected by a hardcoded event.setCancelled(true) safety guard in
MovementListener itself, unconditionally and regardless of observe-only/
enforcement-enabled — the same way the server-version compatibility guard always applies. See
Known Limitations
for why every other check's CANCEL response-ceiling currently has no live trigger at all.
packet.payload.b#
PROTOCOL_INVALID, experimental and disabled by default (requires PacketEvents), response-ceiling
NOTIFY. Evidence family: PACKET_VALIDITY_ORDER. No tunable parameters beyond
enabled/response-ceiling — every value it reports is impossible for an unmodified client, so a
single packet is enough.
Reports what protection.yml's crash guard caught, one finding per broken rule per second, with
the packet type and a reason code (for example WINDOW_CLICK, slot_out_of_range) in its
evidence. The guard itself drops the packets whether or not this check is enabled, and regardless
of observe-only/enforcement-enabled; enabling this check only adds staff alerts and findings.
See Configuration § Crash guard for every
rule and whether it drops the packet or lets the server reject it.
packet.inventory_state.a#
HEURISTIC, enabled by default, response-ceiling NOTIFY. Evidence family:
PACKET_VALIDITY_ORDER. No tunable parameters beyond enabled/response-ceiling — flags an
inventory click Bukkit itself cannot classify. Promoted from experimental: a binary signal with no
statistical surface and no PacketEvents dependency.