DuckyAC

DuckyAC

Configurable protection for Minecraft servers, with packet-based checks and tools for staff review.

DuckyAC monitors movement, combat, block interactions and player actions. It combines packet history with server state, collision shapes and configurable evidence buffers to identify suspicious behavior and give staff useful alerts.

75 configurable check variants · Official release · Java 21 · PacketEvents

Download · Changelog · Source code · Report an issue · Discord

---

✨ Features

• Movement checks: speed, flight, strafing, wall climbing, liquid walking, knockback, collisions and boat flight.
• Combat checks: reach, hitbox angles, attacks through blocks, target switching, critical-hit patterns and packet bursts.
• Building and player checks: scaffold patterns, trap placement, mining, item-use timing and invalid packet sequences.
• Configurable responses: violation levels, alert-only operation, command punishments, event cancellation and setbacks where supported.
• Staff review: clickable controls to confirm detections, mark false positives and undo decisions.
• Detection records: local JSON Lines storage with movement measurements, ping, TPS and check-specific context.
• Server-aware checks: configurable TPS limits and check-specific handling of teleports, external motion, game modes and terrain.
• Integrations: Discord webhooks and a public Bukkit service API for add-ons.

All bundled check variants are part of the official release. Individual checks retain their own enable switches and response settings.

📦 Requirements and installation

1. Install PacketEvents in your server's plugins/ directory.
2. Download DuckyAC and place its JAR in the same directory.
3. Start the server and check that both plugins enable successfully.
4. Edit plugins/DuckyAntiCheat/config.yml to choose checks, alert thresholds and responses.
5. Grant staff the appropriate permissions and use /duckyac reload after configuration edits.

For an upgrade, back up the existing plugin configuration and learning-data/ directory, replace the JAR while the server is stopped, then start the server to run migrations. The current build target above describes this source tree; use the Minecraft compatibility listed for the specific downloadable version when choosing a release.

---

🔍 Checks

🏃 Movement and vehicles

Terrain-aware checks use collision shapes to account for partial blocks such as carpets, slabs and stairs. VehicleFlyA combines occupied-boat positions with fresh vehicle packets and grace periods for water, bubble launches, damage and server corrections.

⚔️ Combat

🪂 Elytra

🧱 Building and placement

⛏️ Player actions and packets

---

⚙️ Configuration

The default configuration contains the full list of settings and descriptions. Each check has its own section; additional options depend on the detector.

VehicleFlyA example:

vehicle-fly-a:
  enabled: true
  alert-only: false
  min-tps: 19.0
  window-ticks: 8
  required-samples: 3
  gravity-tolerance: 0.12
  buffer-threshold: 2.0
  alert-cooldown-ms: 300
  max-alerts: 5
  command: "kick %player% Invalid boat flight (VehicleFlyA)"
  debug: false

At 20 TPS, continuous unsupported flight can produce the first VehicleFlyA alert after approximately 550 ms of eligible sampling, following any grace period. Continued violations can alert at approximately 300 ms intervals.

• enabled controls whether a check runs.
• alert-only, where supported, keeps detections from executing the configured punishment command.
• cancel-event and setback-enabled, where supported, control separate prevention actions.
• max-alerts and command configure command-based punishment.
• min-tps, buffers, tolerances and grace periods control when evidence is accepted.

Several checks start in alert-only mode. KillAuraB and BadPacketsC start disabled and can be enabled individually. Review each check's response options when choosing your server policy.

🧑‍⚖️ Staff review and detection records

Authorized staff can use the controls attached to alerts to confirm a detection, mark a false positive or undo a label. Marking a false positive removes that alert's VL contribution when the stored violation is still active. Undo restores a contribution that was removed.

Detection records include the alert ID, player and check, plugin version, ping, TPS, game mode and available movement or check-specific measurements. Labels and detection features are restored after a restart. They provide a dataset for review and future model training.

machine-learning:
  enabled: true
  store-unlabeled: true
  storage-directory: "learning-data"

Records are stored under plugins/DuckyAntiCheat/learning-data/ by default. Button text, hover text and staff messages are configurable.

🛡️ Commands and permissions

Permission names can differ for legacy checks; the registered permission entries and each check's bypass lookup define the accepted names.

📩 Discord

Enable the discord section and provide a webhook URL to send configured violation and punishment messages to your staff channel. The webhook username, avatar and message templates are configurable.

🔌 Developer API

DuckyAC exposes its API through Bukkit's Services Manager. Add softdepend: [DuckyAntiCheat] or depend: [DuckyAntiCheat] to your plugin description and compile against the DuckyAC JAR.

import pl.barpad.duckyanticheat.api.DuckyAntiCheatAPI;
import pl.barpad.duckyanticheat.api.DuckyAntiCheatProvider;

DuckyAntiCheatAPI api = DuckyAntiCheatProvider.require();
int reachVl = api.getViolationLevel(player, "ReachB");
boolean vehicleFlyEnabled = api.isCheckEnabled("vehicle-fly-a");

The API supports check metadata and configuration, player violation profiles, violation reporting with detection context, punishment commands, clearing violations and runtime registration of external checks. Integrations can listen to DuckyViolationEvent and DuckyPunishmentEvent; violation events expose the associated alert ID.

Check IDs are normalized, so ReachB, reach-b and Reach B resolve to the same check. External check registrations last for the current plugin session.

🛠️ Build from source

With Java 21 or newer installed, run:

.\gradlew.bat clean build

On Linux or macOS:

./gradlew clean build

The JAR is written to build/libs/. Automated tests cover detection models, packet registration, configuration, permissions and learning-data persistence.

🤝 Support

Report bugs through GitHub Issues or join Discord. Include the DuckyAC and PacketEvents versions, server software, relevant check settings and steps to reproduce the behavior. Labeled detection records and debug measurements help investigate false positives.

📜 License

DuckyAC is licensed under GPL-3.0.