Install Swift
Swift is one server-side jar. Players install nothing, and PacketEvents is installed automatically when it is missing.
New in 2.3.7: fewer crystal PvP false flags.
In 2.3.6: six more cheat clients blocked on join, an opt-in keybind probe, and PacketEvents installs its newest release.
In 2.3.5: Minecraft 26.3 support, no more version lock, and bait stashes that catch base finders.
In 2.3.3: a flag's replay now draws the opponent on every tick, marks each hit with a line from the attacker's eye and the distance, and rebuilds the terrain around the flag — so a hit through a wall or a walk over nothing reads as what it was. Needs Swift Cloud from this release. 2.3.2 added the anti-freecam range and the Envelope/Speed fix.
Read the release notes.
| Server | Minecraft 1.21 to 26.3 on Paper or a Paper fork (Purpur, Pufferfish and others) |
| Java | 21 or newer, whatever your server version needs |
| Required | PacketEvents 2.13.0 or newer. Swift downloads and verifies it automatically if it is missing; one restart is needed so Paper can load it. |
| Optional | ViaVersion and ViaBackwards for players on other client versions; MySQL 8 for flag storage; Geyser and Floodgate for Bedrock players |
- Put
Swift-2.3.7.jar into plugins/. You can install packetevents-spigot-<version>.jar first to save a restart; otherwise Swift downloads the newest PacketEvents release for your server version from Modrinth and verifies its size and hash.
- Start the server. If Swift installed PacketEvents, it stops after asking for a restart; start the server again.
- On the boot where PacketEvents is loaded, Swift writes
plugins/Swift/config.yml. A new install has no key, so Swift disables itself after saying so.
- Put the licence key from your order in
licensing.key, then restart. The first activation binds the key to this installation and authenticates its Swift Cloud connection.
- Join as an operator and run
/swift. The control panel opens.
Command conflict? If another plugin or your server software already uses /swift, Swift says so at startup. Its commands then work as /sac or /swift:swift, and every hint Swift shows uses the label that works on your server.
Licence & Swift Cloud
Swift is licensed per server. The key in licensing.key is activated at startup and bound to this installation's server id, address, port and server directory. A copied jar and config will not activate on another server.
- Swift needs a successful activation before it starts, then rechecks every
check-minutes (default 60).
- If Swift Cloud is unreachable, the cached lease keeps the server running for
offline-grace-hours (default 72).
- A revoked or expired key disables the plugin at the next check.
/swift version shows the current status.
- Allow outbound HTTPS to
ac.swiftsmp.net on port 443; the first activation cannot complete without it.
- Moving to a replacement server: ask the licence administrator to unbind the licence in Swift Cloud, then use the same key on the new server. Do not copy
license.json; it is tied to the old fingerprint.
What the cloud adds
Every active licence joins Swift Cloud automatically using its licence key. Fights, flags, client evidence and bans feed the shared model and the live dashboard, with no second API key or server registration. The dashboard opens from /swift → Cloud.
Give each server a unique server-id. It is the name shown for it in the dashboard and shared data. If two licences present the same name, Swift Cloud adds a short licence suffix automatically so their data stays separate.
Fully local server? Set cloud.auto: false in config.yml. The licence check remains the only Swift Cloud traffic, and no player data, flags or bans leave the server.
The first week
Swift ships with automatic punishments off. That is deliberate: watch it on your own players before letting it act.
- Give your staff
swift.alerts. Every flag appears in their chat as one line. Hover to see the evidence, click to open the player's profile.
- Turn on
alerts.flag-log: true for a few days. Every flag is also written to plugins/Swift/flags.log, with the numbers behind it.
- Optionally connect a Discord channel with the webhook settings below.
- When the alerts match what your staff sees, turn punishments on with
/swift punish on or in the control panel.
Discord alerts
In Discord: Server Settings → Integrations → Webhooks → New Webhook, pick the channel, then copy the webhook URL into config.yml:
alerts:
discord:
enabled: true
webhook-url: "https://discord.com/api/webhooks/..."
min-tier: HIGH # LOW, MEDIUM, HIGH or BLATANT
min-interval-seconds: 30 # per player and check
punishments: true # also post kicks and bans
server-name: "Survival" # footer, to tell servers apart
Restart, then run /swift webhook test. No alert data is sent unless this is enabled, and messages never mention anyone.
Evidence, tiers & bans
Every flag has a tier. The tier is not a feeling: it is part of the shipped enforcement profile for that sub-check.
| Tier | What it means |
| Blatant | Impossible for any unmodified client, such as a forged fall path or an attack on an entity the client was never shown. |
| High | Deterministic evidence that needs no statistics. |
| Medium | Strong evidence built over several ticks or events. |
| Low | Statistical profiles such as click rhythm and aim shape. Evidence for staff; never bans on its own. |
A ban needs proof
- Certain: a packet-level finding no unmodified client can produce at any ping, seen three times (
proof.certain-flags).
- Corroborated: two different checks in two families, or three different checks, each with repeated flags on a clean connection, at least one High or Blatant.
- Persistent: one High check finding the same thing in three separate episodes a minute or more apart on a clean connection, backed by another check.
A clean flag is raised below 1000 ms of ping on a steady connection, so lag never builds proof. Physics findings stay evidence even when they look blatant, because a physics model can be wrong for everyone who does the same thing.
The outbreak guard
If one sub-check suddenly flags 8 or more different players within an hour, it is almost certainly wrong about something they all do. Its flags stop counting as proof for anyone until it settles, and staff are told.
What a punishment looks like
- Enforcement waits a random few seconds, so a cheater cannot tell which action triggered it.
- Every ban is announced to the server (
punishments.broadcast: message, sound, optionally kicks too).
- Every ban and kick plays the 4-second ban sequence first: the player is held while the screen decodes into SWIFT, the finding is typed out, then BANNED lands with the length and ban id.
/swift preview shows it without removing anyone.
- The staff alert, Discord message and ban record all say what proved it.
/swift inspect shows each player's evidence so far.
- Ban length grows with the tier, the score and the player's previous automated bans. Bans live in
plugins/Swift/bans.json and are enforced at login.
- A ban record carries its checks, timeline and a 3D camera replay — the opponent, every hit and the terrain around the flag — on a public page, with a one-click appeal. See a real record.
kick-score kicks only when the evidence is at least probable. ban-score no longer bans by itself; it makes a proven ban longer. /swift unban <player> lifts a ban and keeps the record, marked pardoned.
Setbacks & mitigation
Proof takes time, so Swift takes the advantage away first.
Movement setbacks
When Kinematics, NoFall, Liquid, ElytraTrident, Velocity, Vehicle or Timer flags a player, Swift teleports them back to the last position they held before they started failing those checks. The position only moves on after half a second without such a flag, so a cheater who keeps trying keeps landing where they started. Combat and placement checks already block the action itself and do not set back.
Prediction setbacks act faster: a move at least instant-offset blocks outside vanilla physics is undone on that same tick, before any flag. Swift never sets anyone back on an unstable connection, and a check flagging a wave of players stops setting anyone back until it calms down.
setback:
enabled: true
checks: [Kinematics, NoFall, Liquid, ElytraTrident, Velocity, Vehicle, Timer]
cooldown-ms: 250 # at most one setback per player in this time
instant-offset: 0.06 # undo a move this far outside physics at once (0 = off)
instant-offset-legacy: 0.2 # the same for older / ViaVersion clients
Setbacks apply live with /swift reload. Remove a check from the list to let it only alert.
Combat mitigation
While a player's own evidence in combat checks is repeated on a clean connection, the hits they deal silently count for less:
| Level | When | Effect |
| 1 suspected | A High finding twice, a repeated Medium one, or a deterministic one once | Damage ×0.85 |
| 2 likely | A High finding three times, or a deterministic one twice | Damage ×0.6, 15% of hits dropped, melee beyond 3.6 blocks dropped |
| 3 near-proven | Proof among combat checks | Damage ×0.35, half of all hits dropped |
It lifts 10 minutes after the last combat flag. Players are not told; staff get a notice when a level rises, and /swift inspect shows the current one. It works whether automatic punishments are on or off.
Latency abuse
Swift silently drops attacks made on a sudden backlog of unanswered transactions: that is how backtrack and fake-lag modules fight a target where it was a moment ago. A player's normal ping, however high, is never penalised.
Commands & permissions
All commands need swift.admin (operators by default), except alerts. The alias is /sac.
| Command | What it does |
/swift | Control panel: every check with its on/off switch, the punishment switch, your alert switch, the player browser |
/swift inspect <player> | Live profile: score, tier counts, top checks, latest flags, network quality, intelligence card |
/swift alerts | Turn your own alerts on or off (swift.alerts) |
/swift punish <on|off|status> | Automatic punishments switch |
/swift unban <player> | Pardon a Swift ban; the record stays, marked pardoned |
/swift trace <player> [seconds|stop] | Record a player's combat, tick by tick, to plugins/Swift/traces/ |
/swift webhook [test] | Discord alert status, or post a test message |
/swift model [player|reset] | Combat model training progress, a player's score, or start learning again |
/swift reload | Re-read config.yml; the reply names every changed setting that needs a restart |
/swift preview | Play the ban sequence on your own screen; nobody is removed |
/swift version | Version and licence status |
| Permission | Grants | Default |
swift.admin | Control panel, inspect, punish switch, unban, traces, webhook test | op |
swift.alerts | Receive alerts | op |
swift.bypass | Never punished automatically; still flagged and alerted | nobody |
Configuration & tuning
- A check you do not want: switch it off in the control panel (instant, until restart) or set
checks.<name>.enabled: false in config.yml (permanent).
- A flag that should weigh more or less: override its profile under
punishments.profiles. certain: true (High or Blatant) makes a finding proof on its own once repeated; instant-ban: true (Blatant only) gives a proven case the Blatant ban length.
- Thresholds: each check's section in
config.yml explains its settings. Change one at a time.
punishments:
profiles:
Reach/Reach:
tier: HIGH
family: AIM
points: 8
/swift reload applies alert, Discord, punishment and profile changes, and check on/off switches, while the server runs. Thresholds, network, anti-ESP and database settings are built into the running checks and need a restart; the reply lists exactly which of your changes those are.
Useful settings
licensing.key | Your server-bound licence key; restart after setting it |
cloud.auto | false keeps the server fully local |
server-id | The name this server shows in Swift Cloud; keep it unique |
alerts.flag-log | true writes every flag and its numbers to flags.log |
checks.combat-ai.learn | false freezes the self-learning model |
checks.combat-assist | The closet-helper checks (JumpReset, WTap, SwapReturn, WeaponSwap) and the samples each needs |
checks.combat-assist.weapon-swap-samples | How many of the last 5 flags (default 4) before a mace/spear auto-swap counts; MEDIUM, macro family |
checks.xray.anti-freecam | Off by default; underground sections beyond the range leave as plain stone so freecam, X-ray and base finders read nothing. Try one server first |
checks.xray.anti-freecam-range | 48 blocks by default: underground sections beyond this range are sent as stone; 0 restores the 2.3.0 sealed-only behaviour. Needs a restart |
punishments.animation | The ban sequence: on/off, 2 to 8 seconds, kicks too, sounds, what others see and the words on screen; applies live |
network.legacy-client-transactions | false turns off the pre-1.17 transaction handling; can be pushed from Swift Cloud (applies after restart) |
network.transaction-timeout-seconds | Disconnect a client that never answers a transaction (default 60, 0 = never); can be pushed from Swift Cloud (applies after restart) |
Updates
Swift checks the official release manifest at startup and every 60 minutes. A newer jar is downloaded, verified and staged; your server is never restarted by the plugin.
- Swift requests
https://ac.swiftsmp.com/downloads/update.json.
- The downloaded jar is checked for size, SHA-256, plugin name, main class and version.
- The verified jar is placed in
plugins/update. Paper applies it on your next restart.
updates:
auto-update:
enabled: true
manifest-url: "https://ac.swiftsmp.com/downloads/update.json"
channel: "stable"
check-interval-minutes: 60
install-on-restart: true
Set enabled: false to opt out, or install-on-restart: false to keep a verified jar for a manual install. /swift update shows the status and /swift update check checks immediately. Staff with swift.admin are told when an update is ready.
After the restart, new settings are written into your existing config.yml with their explanations. Values you set are never changed, and the previous file is kept as config.yml.backup-v<N>-<time>. The full release history is on Versions & updates.
Versions & Bedrock
Swift models the 26.2 and 26.3 clients exactly. Every other client version, natively on a 1.21.x server or through ViaVersion, is judged with a wider margin; the few checks that need exact 26.2 interpolation and hitboxes skip translated clients.
Every version runs fully: 1.21 to 26.3, with all checks, punishments and setbacks as you configure them. 26.2 and 26.3 clients share the reference physics; a 26.3 server needs PacketEvents 2.14 or newer.
Players on 1.8 to 1.16 (ViaBackwards)
Minecraft versions before 1.17 cannot answer the ping Swift uses to measure a player's connection. ViaBackwards answers it for them unless it is told to pass it to the client, and a player measured that way looks like a player with 0 ms of delay: everything that takes time to reach them looks like a cheat.
- ViaBackwards on the same server as Swift: nothing to do. Swift switches the option on at start-up and checks that it took. If your ViaBackwards is too old for that, the console says so once.
- ViaBackwards on your proxy (Velocity or BungeeCord): set
handle-pings-as-inv-acknowledgements: true in the proxy's plugins/ViaBackwards/config.yml and restart the proxy. Until you do, Swift says so once in the console and does not judge those players with its movement, combat or timing checks; anti-X-ray and anti-ESP still apply. /swift inspect shows such a connection as "answered in transit, not judged".
network.legacy-client-transactions: false switches this behaviour off. A client that keeps playing for 60 seconds without answering a single transaction is disconnected with "Timed out" (network.transaction-timeout-seconds, default 60, 0 = never). A vanilla client always answers; a frozen one stops playing and is left to Minecraft's own time-out.
Both settings can also be changed for every server at once in the Swift Cloud dashboard (Settings → Live tuning → Network). They are read when a server starts, so a value pushed from the dashboard takes effect at that server's next restart.
Bedrock players (Geyser)
Bedrock players move and fight under Bedrock's own physics, hitboxes and controls, and Geyser answers network traffic for them. Swift keeps every Java-model movement, combat, aim, click and timing check away from them: a Bedrock player is never flagged or punished by those checks.
Anti-X-ray and anti-ESP do not depend on the client and protect against Bedrock players as usual; Bedrock X-ray packs and ESP get nothing to show. Swift recognises Bedrock players before their first move is checked, using the Floodgate or Geyser API when installed, and otherwise Floodgate's UUIDs and the client brand Geyser sends at login.
Catching Bedrock-only cheats that exist entirely inside Geyser's translation is not claimed.
False flags & troubleshooting
Report a false flag
- Find the flag in
plugins/Swift/flags.log (turn on alerts.flag-log first). The line contains the numbers the check saw.
- If it is a combat check, record the player with
/swift trace <player> 60 while it happens again.
- Send both to support on Discord. The trace lets the check be replayed tick by tick.
Quick fixes
/swift does not work | Another plugin owns the label. Use /sac or /swift:swift; Swift's own hints use the working label. |
| Swift disabled itself at startup | No licence key yet. Put the key in licensing.key and restart. The first activation needs outbound HTTPS to ac.swiftsmp.net. |
| Licence will not activate on a new server | The key is bound to the old installation. Ask an administrator to unbind it, then reuse the key. Never copy license.json. |
| Staff get no alerts | Give them swift.alerts; use /swift alerts to toggle their own. |
| A check is too noisy for your server | Turn that check off in the panel, raise its threshold in config.yml, or override its profile. Change one setting at a time. |
| Punishments do nothing | Automatic punishments ship off. Check /swift punish status. |
| 1.8 to 1.16 players look unjudged | ViaBackwards is answering their pings on the proxy. Set handle-pings-as-inv-acknowledgements: true there; /swift inspect shows "answered in transit, not judged" until you do. |
Privacy: never send license.json, your licence key or full server logs to anyone but Swift support.
Files & performance
| File | What it is |
config.yml | Settings |
license.json | Cached, server-bound licence lease (never the key) |
bans.json | Swift's bans and their history |
flags.log | Every flag with its numbers, when alerts.flag-log is on |
calibration.log | Movement and aim calibration data, when checks.intelligence.calibration-log is on |
traces/ | /swift trace recordings |
Performance
Every check runs on the network threads, never on the main thread, and the checks keep fixed per-player arrays instead of allocating objects for each packet. The main thread only does light scheduling work: one transaction per player per tick, a per-player environment sync every five ticks, commands, the control panel and the final kick.
Swift sends anonymous bStats statistics (server count, versions, whether punishments are on) once the plugin has a bStats id. Set metrics: false, or opt out for every plugin in plugins/bStats/config.yml.