Minecraft anticheat guide

FairPlay Config File Terms and Keys Explained

Plain definitions of FairPlay config files and keys, including punishments.yml, mitigations.yml, webhook.yml, and transaction.yml, and how to change them.

Updated 2026-11-07 · ~5 min read

anticheat config termsminecraft anticheat configpunishments.ymlmitigations.ymlFairPlay configuration terms

What do anticheat config terms mean?

Anticheat config files hold the settings for checks, punishments, alerts, and diagnostics. FairPlay generates these files and documents their key names. The table names each file or key, explains what it controls, and shows what you will see when you open it.

FairPlay config files and keys, with what each controls.
Term	Plain definition	What you will see in the file
config.yml	The main settings file. It covers Bedrock eligibility, cancellation messages, alerts, checks, confirmation handling, and diagnostics.	Groups for each area. Player logs in it can contain violations, chat, joins, and leaves.
punishments.yml	Controls violation timing, staff alert cooldowns, and shared punishment actions.	Action and tier entries, and a defaults-revision field that FairPlay manages.
mitigations.yml	Holds per-check mitigation controls, reach compensation, and separate kick and ban gates.	Per-check groups, an increaseReach setting, and totem, Elytra, and macro-spear controls.
hooks.yml	Settings for hooks into other anticheats, including which checks a hook excludes.	plugin-name, the event class, and blacklisted-checks.
webhook.yml	Discord alert delivery. It holds the URL, violation threshold, cooldown, and allowed role mentions.	enabled, minimum-vl, and cooldown-ms. Webhooks are disabled by default.
banwave.yml	Ban-wave scheduling and queue values.	An empty schedule list and a queue limit of 5,000 by default.
snapshot.yml	Coverage, expiry, and capture limits for the virtual world view used by checks that read snapshots.	Subchunk radius, expiry, and per-tick capture values.
transaction.yml	Transaction provider selection and native probe settings.	mode, probe-interval-ms, pending-timeout-ms, and pending-size.
Per-check YAML	The file for one check or a shared group of checks, located by its @ConfigInfo file name and YAML path.	A nested path under the file named by @ConfigInfo.
blacklisted-checks	A hook setting that lists checks to exclude from that hook.	A list key in hooks.yml.
defaults-revision	A migration value FairPlay manages.	A field in punishments.yml. Leave it unchanged.
Reload versus restart	Some settings apply after a reload. Others need a server restart.	The setting guide and the configuration troubleshooting guide say which applies.

How do you trace one setting in a real config file?

Start from the key you want to change, then find the file that owns it. The example below shows the documented webhook keys. Confirm the nesting and the current values in your own generated file before you edit.

Find the key in the table and note its file name.
Open the generated file and search for the key. If it is missing, check the per-check YAML path before assuming the setting does not exist.
Read the setting guide to see whether a reload applies the change.
Change one value, reload or restart as the guide says, and check the server response.
Record the file, key, old value, and new value for the staff log.

Documented webhook.yml sample defaults. Confirm nesting in the generated file.

# webhook.yml, documented sample defaults
enabled: false
minimum-vl: 2.0
cooldown-ms: 2000

Which config terms are easy to mix up?

Several files sound alike but cover different decisions. Use this table before you open a file, so you change the right setting the first time.

Commonly confused config file and key pairs.
Pair	The difference	Where to check
punishments.yml vs mitigations.yml	punishments.yml holds timing and tiered actions. mitigations.yml holds per-check controls and the kick and ban gates.	Tier entries versus per-check groups.
hooks.yml vs webhook.yml	hooks.yml connects FairPlay to other anticheat plugins. webhook.yml sends alerts to Discord.	plugin-name and event class versus URL and threshold.
banwave.yml vs punishment tiers	banwave.yml controls scheduled and queued ban waves. Tiers pick the action for one player at a level.	Schedule and queue values versus tier entries.
Per-check YAML vs main config	A per-check file sets one check or group. The main config covers the whole plugin.	The @ConfigInfo file name and YAML path.
Reload vs restart	A reload applies some settings immediately. A restart is needed for the rest.	The setting guide and the troubleshooting guide.
transaction.yml vs snapshot.yml	transaction.yml chooses the transaction provider. snapshot.yml sets virtual world coverage and capture limits.	Provider mode versus radius and expiry values.

How should you change a config file?

Change settings in small steps so you can tell which change caused a result. Back up the file first and record every change.

Back up the generated file before any edit.
Find the file in the table, then search for the key.
Change one value, then run the reload command if the setting supports it.
Restart the server when the setting guide says reload is not enough.
Log the key, the old value, and the new value for your staff.

What we have not verified

This page lists the documented key names and defaults for one FairPlay release. Nesting, defaults, and available values can change, so the generated file is the authority. This page makes no claim about the effect of any value on detection.

FAQ

Why did my config edit not take effect?

Check whether the setting supports reload. The configuration troubleshooting guide lists settings that need a restart.

Should I edit defaults-revision?

No. FairPlay manages that migration value. Leave it as generated.

Where do per-check settings live?

Find the check in the checks reference, then use its @ConfigInfo file name and YAML path. Confirm the exact key in the generated file before editing.

Is the Discord webhook on by default?

No. Webhook alerts are disabled by default. Set the URL, threshold, and cooldown before you enable them.

Which file should I open to stop one check from running through a hook?

Look at blacklisted-checks in hooks.yml. It lists checks excluded from that hook. Confirm the current list on your server, because the defaults are only a starting point.