Confirmed cheat bans

#What counts as a ban

Only a confirmed ban is reported. A violation level is not a ban and a kick is not a ban, so neither is ever sent on its own. A ban carries the check that fired and the violation level at that moment, and those are what the Check and Level columns on Fair Play show.

The connector decides by watching which punishment command actually ran. You control that list, so a network with its own punishment plugin can name its own ban command.

#Configuration

The anticheat block lives in the Paper connector config. The connector attaches to whichever supported anticheat it finds at startup, and /mca status says which one it attached to and how many confirmed bans it has reported since.

anticheat:
  enabled: true

  # A punishment counts as a ban only when it runs one of these.
  ban-commands:
    - "ban"
    - "tempban"
    - "banip"
    - "litebans:ban"

  # Only needed when your build's class names differ from the known ones.
  grim:
    event-classes: []

  # The same for Polar.
  polar:
    event-classes: []

#Which anticheats are found

From connector 1.0.16 a Paper or Folia server looks for anticheat plugins when it starts and again whenever a plugin is enabled. It sends what it found with each heartbeat, and the Anticheats detected card on Fair Play and on Settings > Servers lists every server with each anticheat, its version, and one plain status line.

A proxy does not run an anticheat, so it reports none. A connector older than 1.0.16 reports nothing and the card leaves its server out. Detection shows on every plan. Below Network the card says so, because the bans themselves are part of Network and up.

• Bans are attributed: the connector is listening to this anticheat and each confirmed ban it runs is reported.
• Detected. Waiting for the first ban to confirm it works: the listener was accepted, but nothing has come through it yet. Polar starts here.
• Detected, not supported yet: the connector knows the plugin but has no ban adapter for it. Vulcan, Matrix, Spartan, Themis, Verus, Intave, Karhu, NoCheatPlus and AAC are found this way.
• Could not attach, with a short reason: the anticheat block is off, the anticheat had not finished loading, or its punishment event was not found.
• Last ban seen: the time of the newest ban the connector reported from it.

#Polar

Polar does not document its punishment event, so the connector tries the class names Polar has used and any you add under anticheat.polar.event-classes. Polar also finishes loading a little after its plugin starts, so the connector tries again every 15 seconds for about five minutes.

Because the event is a guess, Polar shows Detected. Waiting for the first ban to confirm it works until the first punishment comes through. After that it reads Bans are attributed, and it keeps that after a restart until the Polar version changes.

• Run /mca status on the server. The Anticheats found line names Polar, its version and its state.
• Open Fair Play or Settings > Servers. The card shows the same state within a heartbeat.
• Ban a test account with Polar using a command from ban-commands. The line changes to Bans are attributed and Last ban seen shows the time.
• If it says Could not attach, set anticheat.polar.event-classes to the punishment event class your Polar build publishes and restart.

#What Fair Play shows

Fair Play counts confirmed bans in the range, the ban rate for premium, cracked, and Bedrock players, the checks behind the bans, the bans by source, and a log you can filter and export. Each ban opens the player, whose profile names the address they first joined through, and the export has a First source column. A ban also keeps the name of the anticheat that reported it, GrimAC or Polar, and Player lookup shows it.

The page also has room for flags: the Flags, Players flagged, and Flags per 100 players cards and the Flags tab of the log. A flag is an anticheat alert that did not end in a ban. The connector sends confirmed bans only, and the API accepts nothing else, so those flag numbers stay at zero for now.

#Reading bans by source

The Bans by source card counts each confirmed ban under the address the banned player first joined through. It follows the range and the server you picked at the top of the page, and lists only addresses with at least one ban in the range, most bans first. Players with no recorded address are counted under Unknown / Direct.

• Confirmed bans: ban events in the range. A player banned twice counts twice.
• Banned players: the players behind those bans, each counted once. Added up over every address, this is the Confirmed bans card.
• New players: players whose first join came through the address in the range, the same count as New players on Growth.
• Bans per 100 new players: banned players divided by new players, times 100. Under 20 new players it reads Not enough players, because one ban would move it by five or more.

#Why a ban can arrive early

A session is posted when the player joins and again when they leave. Behind a proxy that session comes from the proxy, so a ban caught on a backend can still reach us before the record that would create the player. The API answers 425 in that case and the connector retries, rather than dropping the first offence of every cheater it catches.

A ban never creates a player, because inventing a first join time and an empty acquisition source would corrupt the numbers this product exists to report.