✦ Puff — Pure ML-Only Aim Anti-Cheat ✦
Status: Active Development (Beta / WiP)

Puff is a next-generation Spigot anti-cheat designed to detect aim assistance and cheats using pure machine learning. Unlike traditional anti-cheats that rely on hundreds of hardcoded rules, thresholds, and heuristic checks (which can be easily bypassed by advanced cheats), Puff utilizes a fully self-contained neural network to analyze mouse rotation patterns.

Using PacketEvents for low-level packet collection, Puff records high-frequency mouse movements, processes them into mathematical features (such as variance, entropy, and sensitivity finger-prints), and feeds them directly to an internal Feed-Forward Neural Network (FFNN) right on your server.

✦ Key Features
100% Machine Learning: No manual heuristics, no arbitrary thresholds.
Built-in Dataset Recorder: Collect legitimacy and cheat training data directly in-game using /puff record.
In-Game Model Training: Train the neural network directly on your server using /puff train and watch the validation metrics update in real-time.
Real-Time Hot-Swapping: Once training finishes, the new model weights are instantly hot-swapped into the detection engine without server restarts.
Low Overhead & Thread-Safe: Signal processing, feature extraction, and ML predictions run asynchronously in the background.
Unified Punishments & Alerts: Trigger custom console commands (e.g., kick/ban/flag) when player violation levels (VL) cross configured limits.

IMPORTANT: Please Read Before Using!
Puff represents a fundamental shift in how aim cheats are detected. Because it relies entirely on patterns rather than static rules, the quality of detection is completely dependent on your trained model.

WARNING!
Active Development / WIP: This plugin is currently in active development. If you experience false positives, it is most likely because the model has not been trained enough or is not yet capable of working well with the specific movement patterns that you recorded in your datasets.
To improve detection and eliminate false positives, simply record more data representing the false-positive movements (as `legit`), retrain the model via /puff train, and hot-swap the weights.

✦ How to Use (Workflow)

1. Install PacketEvents: Make sure you have PacketEvents installed on your server.
2. Record Data:
Record a clean player: /puff record Steve legit start (let them play naturally, PvP. for ~20-30 mins), then /puff record Steve legit stop.
Record a cheater (or test dummy using cheats): /puff record Dummy cheat start, then stop it when finished.
3. Train the Model:
Run the trainer: /puff train --epochs 200 --lr 0.001(check /puff mlparameters)
The server will log epoch loss and validation accuracy in real-time.
4. Instant Hot-Swap:
Upon successful training, the plugin will automatically swap the old weights with the newly optimized model.
Watch the alerts come in!

✦ Commands & Permissions
/puff alerts [on|off] — Toggle alerts for yourself ( puff.alert)
/puff info <player> — Show target player's current VL and recording status ( puff.admin)
/puff reset <player> — Reset a player's violation level ( puff.admin)
/puff debug <player> — Print real-time feature vector values and model confidence ( puff.admin)
/puff prob — Display the current VL and prediction confidence for all online players ( puff.admin)
/puff record <player> <class> <start|stop> — Start/stop recording movement samples ( puff.admin)
/puff train [options] — Start training the model ( puff.admin)
/puff train stop — Cancel the current training session ( puff.admin)
/puff reload — Reload config and model weights from disk ( puff.admin)

✦ Configuration Example (config.yml)

Code (YAML):

puff:
  poll-interval-ticks : 5
  buffer-size : 100
  analysis-stride : 25
  confidence-threshold : 0.85
  model-path : "plugins/Puff/model_weights.bin"
violations:
  alert-threshold : 50.0
  decay-multiplier : 0.95
  punish:
    enabled : false
    threshold : 100.0
    command : "kick %player% Puff ML: Aim detected"
alerts:
  format : "&8[&c✦ Puff&8] &7%player% &8| &cAimML &8| &7VL&8: &f%vl% &8| &7Conf&8: &f%conf%"
dataset:
  path : "plugins/Puff/datasets"