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 in checks.yml, one of NONE < STORE < NOTIFY < MONITOR < CANCEL < SETBACK < KICK < COMMAND): the strongest response that check's own findings may ever justify, regardless of actions.yml. A check shipped with ceiling NOTIFY can never kick a player no matter what policy rule you write.
  • actions.yml policies: 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.yml correlation 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's response-ceiling need not be punitive: suspected-dupe-backup-trigger uses COMMAND purely 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's safety-margin/buffer.flag-at/buffer.decay-per-valid-sample, combat.reach.a's equivalents): a buffer must cross flag-at before a finding fires at all (never a single marginal sample), then decays back down on clean samples. Raising safety-margin or flag-at makes 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, under checks.yml's top-level defaults: 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; their threshold values 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.