ultimateac

# UltimateAntiCheat **ML-based KillAura Anti-Cheat for Paper 1.16.5** UltimateAntiCheat is a machine-learning-based Minecraft anti-cheat focused on detecting **KillAura** through temporal combat behavior rather than relying on a collection of hardcoded thresholds. **Platform:** Paper 1.16.5 **Java:** 8 / 11 **Model:** MLP neural network **Optional dependency:** ProtocolLib --- ## Overview UltimateAntiCheat learns from real player behavior. Instead of checking individual values such as CPS, reach, or rotation speed and immediately deciding whether a player is cheating, the system collects a sequence of combat-related telemetry, extracts temporal features, and passes them through a trained machine-learning model. The detection pipeline is: ```text Confirmed KillAura ↓ /uac rec ↓ Dataset ↓ /uac train ↓ ML Training ↓ Legitimate player attacks ↓ Temporal features ↓ Model ↓ KillAura probability ↓ Multiple predictions ↓ Violation buffer ↓ Detection ``` The model is trained on confirmed examples instead of depending exclusively on manually selected thresholds. --- # Installation ## Requirements * Paper 1.16.5 * Java 8 or Java 11 * Maven for building the project * ProtocolLib is optional ## Installing the Plugin Build the project: ```bash mvn package ``` After the build is complete, place the generated JAR file into: ```text plugins/ ``` Restart the server. --- # Machine Learning Model A pre-trained model is included with the project: ```text killaura_model.json ``` Extract the model and place it into: ```text plugins/UltimateAntiCheat/models/ ``` After installing the model, run: ```text /uac train ``` The training system can also create/update the model using the collected dataset. --- # Training the Model UltimateAntiCheat requires both positive and negative examples. ## 1. Record KillAura Data Start recording a confirmed cheater: ```text /uac rec CheaterNick ``` The player should use KillAura for approximately **3–5 minutes** and perform a significant number of attacks. Stop recording: ```text /uac stop CheaterNick ``` This creates training data for the `KILLAURA` class. --- ## 2. Record Legitimate PvP Data Record a legitimate player: ```text /uac reclegit GoodNick ``` The player should participate in normal, legitimate PvP. Stop recording: ```text /uac stop GoodNick ``` This creates training data for the `LEGIT` class. --- ## 3. Collect Multiple Sessions For better training data, repeat the process with at least: * 3 different KillAura players/sessions * 3 different legitimate players/sessions The dataset should contain multiple independent sessions rather than relying on a single player. --- ## 4. Train the Model Run: ```text /uac train ``` Training is performed asynchronously. The training process includes: ```text Dataset ↓ Class balancing ↓ Normalization ↓ Session split ↓ Adam optimizer ↓ Training ↓ Evaluation ↓ Metrics ↓ Model storage ``` The training output includes: * Precision * Recall * F1 score * Confusion matrix --- # Commands All commands require the `uac.admin` permission. | Command | Description | | ---------------------- | ------------------------------------------- | | `/uac rec ` | Record training data for the KILLAURA class | | `/uac reclegit ` | Record training data for the LEGIT class | | `/uac stop ` | Stop recording data for a player | | `/uac train` | Train the MLP model | | `/uac status ` | Display the detector status | | `/uac debug ` | Display live features, model score, and VL | | `/uac menu` | Open the suspicion/detection GUI | | `/uac reload` | Reload the configuration and model | --- # Detection System Detection does not depend on a single model prediction. For example: ```text p = 0.93 ``` does not automatically mean that a player is considered a cheater. Instead, predictions are aggregated over multiple observations. The detection flow is approximately: ```text Model prediction ↓ Prediction aggregation ↓ 5 consecutive predictions ↓ Confidence accumulation ↓ Violation Level (VL) ↓ VL decay ↓ Sustained detection ↓ Punishment ``` The system uses: ```text VL += confidence ``` and allows the violation level to decay over time. This makes the detector less dependent on isolated predictions. --- # Observation Mode By default, punishments are disabled: ```yaml violation: punish-enabled: false ``` In this mode: * No kicks are performed. * No bans are performed. * Staff members receive detection flags. * Violation Level continues to increase when detections occur. Punishments can be enabled later: ```yaml punish-enabled: true ``` --- # Reach Guard The default maximum hit distance is: ```yaml reach-guard.max-distance: 3.0 ``` Attacks beyond 3 blocks of eye-to-eye distance are cancelled. The counter is available through: ```text /uac menu ``` and: ```text /uac status ``` --- # Feature Extraction UltimateAntiCheat analyzes combat behavior using temporal windows rather than isolated clicks. Each training example contains **21 frames**: ```text T-10 ... T0 ... T+10 ``` where: ```text T0 = attack ``` The frames after the attack are collected during the following 10 ticks. --- ## Frame Features The feature extractor analyzes information such as: * Yaw * Pitch * ΔYaw * ΔPitch * Rotation speed * View direction * Distance to target * Angle to target * ΔAngle * Attacker movement speed * Target movement speed * Relative movement speed * Sprint state * Sneak state * Ground state * Jump state * Velocity * Knockback * Ticks after knockback * Target switching * Movement relative to view direction * Ping * TPS * Number of nearby players * Attack interval --- # Model Input The model uses **354 input features**. They consist of: ```text 21 × 16 per-frame features + 18 aggregated window features = 354 inputs ``` Aggregated features include information such as: * CPS * Attack regularity * Minimum snap angle * Target switches * Lag context * Other temporal statistics The raw `isAttack` value is **not** included as a model feature. --- # Neural Network Architecture The current model architecture is: ```text 354 → 64 → 32 → 1 ``` The network uses: * ReLU activation * Sigmoid output Conceptually: ```text Input 354 │ ▼ Dense Layer 64 │ ▼ Dense Layer 32 │ ▼ Output 1 │ ▼ Sigmoid │ ▼ KillAura probability ``` The implementation is written in pure Java and does not require native machine-learning dependencies. --- # Model Extensibility The model architecture is exposed through: ```text CheatModel ModelRegistry ``` This provides an extension point for additional cheat detection models, including: ```text AimAssist Reach AutoClicker Velocity Fly ``` The current documentation specifically describes the KillAura model. --- # Data Leakage Prevention The training pipeline uses `sessionId` to separate training and testing data. A single recording session is never simultaneously placed into both datasets. ```text Session A ──→ Train Session B ──→ Train Session C ──→ Test ``` This prevents the same session from appearing in both training and testing. Normalization is also calculated exclusively from the training set. The normalization method is: ```text z-score normalization ``` --- # Train / Serve Consistency The same components are used during both training and live detection: ```text FeatureExtractor + Normalizer ``` The telemetry collection pipeline is shared between training and serving. This prevents differences between the feature representation used to train the model and the representation used during live detection. --- # Anti-False-Positive System The detector does not make decisions solely from one metric. The model considers environmental and combat context such as: * Ping * TPS * Jitter * Knockback * Target switching * Nearby players * Crowd conditions Confidence can also be dampened when the environment is unstable. The system specifically avoids making decisions exclusively from: ```text CPS Reach Rotation ``` --- # Asynchronous Processing Dataset recording and model training are performed asynchronously. The server tick thread performs only lightweight sampling. This design keeps the more expensive operations away from the main tick-processing path. --- # ProtocolLib ProtocolLib is an optional soft dependency. When ProtocolLib is available, UltimateAntiCheat can obtain: * Precise click timing through `USE_ENTITY` * Raw rotation packets Without ProtocolLib, the plugin falls back to Bukkit events. ```text ProtocolLib available ↓ Precise packet-level telemetry ProtocolLib unavailable ↓ Bukkit events ``` --- # GUI The command: ```text /uac menu ``` opens the suspicion GUI. Players are separated visually according to the detector's current suspicion: ```text Top └── Red — higher detected cheater probability Bottom └── Green — lower detected cheater probability ``` Left-clicking a player allows staff to spectate them. --- # Debugging For live debugging, use: ```text /uac debug < ```