Plugin documentation
FairPlay quick start
Combat anticheat that applies mitigation against flagged players, with built-in checks and optional GrimAC or Vulcan flag hooks.
Documentation and contents
FairPlay is a combat anticheat. Detection feeds mitigation, such as synthetic hit opportunities for a clean player against a flagged target. It also ships conventional check modules for aimbot, autoclicker, autototem, fastbreak, hitbox, killaura, scaffold, and timer.
Requirements
- A Bukkit, Spigot, or Paper server.
plugin.ymlresolvesapi-versionto1.13andfolia-supportedtotrue. - PacketEvents installed.
plugin.ymldeclaresdepend: [packetevents]. Startup will not proceed without it. - Optional integrations declared as soft dependencies: LuckPerms, Geyser-Spigot, floodgate, GrimAC, Vulcan, NoCheatPlus, PolarLoader, Intave, Matrix, Spartan. It loads without GrimAC or Vulcan. Missing hooks are expected.
- Minecraft 1.8–1.21, with a Java 8 build target.
- Java 8 is the compiler source and target. The repo documents no runtime Java requirement beyond that.
Install
No numbered install guide ships in the repo. What the source documents:
- Build the reactor from the parent POM. Modules are
models,fairplay-api, andfairplay. - Run
./build.sh. It refuses to build without the real bundled model files. A failure readsERROR: Missing/empty bundled FairPlay model: <path>. Recover them withFAIRPLAY_MODELS_SOURCE_JAR=/path/to/FairPlay.jar ./build.shorFAIRPLAY_MODELS_SOURCE_DIR=/path/to/plugins/FairPlay/models ./build.sh. - Install only the FairPlay plugin jar in
plugins/. Do not install the API jar as a plugin or shade its classes. - The first start writes
config.ymlinto the plugin data folder. Training window output goes toplugins/FairPlay/windows/global/<player>/<UTC-date-and-session>.json.
Configure
No YAML is bundled. The config is generated from annotated Java classes, and defaults come from field initializers. A missing path logs [FairPlay] Missing config value for path '…'.
bedrock-check: true
show-cancel-messages: false
auto-update-models: true
player-logs-enabled: true
cancel-message-cooldown-ms: 60000
machine-learning-training only affects training error costs, not runtime detection. The deprecated confirmation and client-tick-sync blocks remain for compatibility with older configs.
Commands
Root is /fairplay, aliases /fp and /anticheat.
| Command | Purpose |
|---|---|
/fp checks <enable|disable|toggle> <check|category> |
Toggle checks |
/fp alerts <enable|disable|toggle|inspect|clear> [player] |
Alert subscriptions |
/fp punishments <list|add|remove|clear> [value] |
Punishment rules |
/fp toggle <check|category> |
Toggle a check or category |
/fp kick <enable|disable|toggle> |
Kick behavior |
/fp damagecancel <enable|disable|toggle> |
Damage cancellation |
/fp blockcancel <enable|disable|toggle> |
Block cancellation |
/fp ml <aim|click> |
ML inspection |
/fp latency <player> <seconds 1..120> |
Latency handling |
/fp banwave run |
Run a ban wave |
/fp ml aim window record GLOBAL |
Start global AIM window recording |
/fp ml aim window stop / status |
Stop recording / inspect completion |
The global window commands require fairplay.command.ml.global, default operator.
Permissions
Every node is declared with default op, except the exemptions: fairplay.admin, fairplay.train, fairplay.check, fairplay.notify, fairplay.command.ml, fairplay.command.ml.global, fairplay.command.damagecancel, fairplay.command.blockcancel, fairplay.command.latency, fairplay.command.rotations, and fairplay.command.banwave. The exemptions are fairplay.exempt, fairplay.nosetback, and fairplay.nomodifypacket, all default false.
fairplay.command appears in the README and as a child of several nodes. It has no standalone declaration or default in plugin.yml. Grant it explicitly if needed.
Troubleshooting
| Symptom | Cause and diagnostic |
|---|---|
| No GrimAC or Vulcan detection | Expected when neither plugin is installed. FairPlay still loads. |
| Missing config warning | [FairPlay] Missing config value for path '…'. The generated config lacks that key. |
| Build stops on models | Missing/empty bundled FairPlay model. Restore the trained .nn assets. Do not substitute blank artifacts. |
| Reach diagnostics look ambiguous | reach-increase applied, range, aim, visibility_*, and candidate do not prove a hit. Only reach-increase damage-applied confirms a MONITOR-confirmed applied hit. |