§08 Tuning Guide
Tuning Guide#
Every check's envelope is deliberately generous out of the box: prefer a smaller set of
explainable, tested checks over many aggressive checks that create false positives. Tune down
only after confirming false positives are actually gone on your own hardware/TPS/player base —
start with observe-only still effectively true (leave enforcement off) while you do. For every
check's actual tunable keys and their defaults, see the
Check Parameter Reference.
response-ceiling(every check inchecks.yml, one ofNONE < STORE < NOTIFY < MONITOR < CANCEL < SETBACK < KICK < COMMAND): the strongest response that check's own findings may ever justify, regardless ofactions.yml. A check shipped with ceilingNOTIFYcan never kick a player no matter what policy rule you write.actions.ymlpolicies: declarative rules (check,min-evidence-class,min-escalation-stage,response) that can escalate a finding's response up to (never past) its check's ceiling. None ship enabled by default — permanent punishment is always an explicit opt-in.actions.ymlcorrelation rules: match independent evidence families within a short window (e.g. a sustained item-generation-rate finding plus a confirmed inventory-conservation mismatch, or a killaura-class combat finding plus an auto-totem-macro finding —combo-hack-signature) and can justify a stronger ceiling than any single contributing check — this is how FlagForge turns "several individually-weak signals" into one confident incident instead of either ignoring them or overreacting to one alone. A correlation'sresponse-ceilingneed not be punitive:suspected-dupe-backup-triggerusesCOMMANDpurely to fire an admin-configured console command — e.g. a backup plugin's snapshot command — on evidence far weaker than any actual CANCEL/KICK would require, since a snapshot is cheap and non-destructive. See Triggering a backup on suspected dupe evidence below.combo-hack-signature, the third shipped correlation, is currently inert in practice: every contributing check on both sides ships experimental/disabled by default. See Configuration § actions.yml for the full rule-shape reference and all three shipped correlations' exact thresholds.- Movement/combat/world safety margins and buffers (
checks.yml, e.g.movement.speed.a'ssafety-margin/buffer.flag-at/buffer.decay-per-valid-sample,combat.reach.a's equivalents): a buffer must crossflag-atbefore a finding fires at all (never a single marginal sample), then decays back down on clean samples. Raisingsafety-marginorflag-atmakes a check strictly more lenient; lowering either makes it strictly stricter. Quality gates (min-tps/max-ping-ms) reduce confidence automatically during lag — they live once, underchecks.yml's top-leveldefaults:block, and apply globally to every check; there is currently no per-check override for either. You generally don't need to touch these unless your server runs sustained low TPS. - Packet-adapter checks (
movement.timer.a,packet.rate.a,packet.sequence.a): only meaningful with PacketEvents installed; theirthresholdvalues are packets/second ceilings.
Triggering a backup on suspected dupe evidence#
FlagForge does not implement backup or rollback itself — that's an explicit non-goal, and the
plugin is designed to integrate with whatever backup tooling you already run, not replace it.
actions.yml's suspected-dupe-backup-trigger correlation rule is the integration point: it
matches the same evidence-family combination as confirmed-inventory-generation (a sustained
item-generation-rate finding plus an inventory-conservation mismatch), but at much lower confidence
thresholds, since firing a cheap, non-destructive snapshot is reasonable on far weaker evidence
than an actual CANCEL/KICK would justify.
It ships fully inert on every install via two independent gates: the global enforcement
switch/observe-only mode (like every other COMMAND-class rule in actions.yml), and having no
command: configured at all. To opt in, set command: to your backup plugin's manual-snapshot
console command, or the vanilla fallback:
suspected-dupe-backup-trigger:
# ...
command: "save-all"
The two dupe-related correlations intentionally sit at different confidence bars because of
checks.yml's coverage-complete flag on inventory.reconciliation.a: with the shipped default
(coverage-complete: false), that check's confidence tops out around 0.6 (HEURISTIC evidence),
so confirmed-inventory-generation's 0.90 bar realistically requires coverage-complete: true
(and verified full adapter coverage) to ever match, while suspected-dupe-backup-trigger's 0.55
bar is reachable on a default install. Run /ff correlations to see every configured correlation
rule's thresholds and whether a rule's confidence requirement is currently unreachable given your
coverage-complete setting.
Evidence families#
A correlation rule's require: list (actions.yml) names independent evidence families, not raw
checks — this matters because two variants derived from the same underlying observation and
algorithm share a correlation key and must never be treated as two independent confirmations of
the same thing. Family membership is hardcoded per check ID, not administrator-configurable, since
it's an architectural fact about what a check measures rather than a tunable value.
| Family | Contributing checks |
|---|---|
ITEM_GENERATION_RATE |
economy.item_gain_rate.a, economy.item_gain_rate.b |
INVENTORY_CONSERVATION |
inventory.reconciliation.a |
INVALID_ITEM_STATE |
inventory.illegal_stack.a, inventory.illegal_item.a |
TRANSACTION_RATE |
inventory.transaction_burst.a |
MOVEMENT_KINEMATICS |
movement.speed.a, movement.flight.a, movement.nofall.a, movement.step.a, movement.elytra.a |
COLLISION_GROUND_STATE |
movement.phase.a, movement.waterwalk.a, world.pearl_clip.a |
ATTACK_GEOMETRY |
combat.reach.a, combat.attack_rate.a, combat.multitarget.a, combat.velocity.a, combat.line_of_sight.a |
AIM_ROTATION_STATISTICS |
combat.rotation.a, combat.autoclicker.a |
REACTION_TIMING |
combat.totem_swap.a |
PACKET_VALIDITY_ORDER |
movement.timer.a, packet.rate.a, packet.payload.a, packet.payload.b, combat.bad_order.a, packet.sequence.a, packet.inventory_state.a |
WORLD_INTERACTION_TIMING |
world.fastbreak.a, world.nuker.a, world.fastplace.a, world.interaction_reach.a, world.impossible_action.a, world.scaffold.a, world.tnt_prime_rate.a |
UNKNOWN |
Every check not listed above — currently movement.suspicious_teleport.a, world.floating_place.a, world.xray_ore_rate.a. A check with no declared family mapping is never counted toward any correlation-rule match. |
Writing your own correlation rule (actions.yml's correlations:) means picking two or more of
these families whose checks are independently plausible confirmations of the same underlying
abuse — see Configuration § actions.yml for the exact
rule shape.