VectorGuard

Production-grade combat anti-cheat for Paper servers.

VectorGuard is a 100% server-side anti-cheat plugin focused exclusively on combat detection. It uses packet-level analysis, tick-based telemetry, and multi-signal detection to identify cheaters with high accuracy and minimal false positives.

Built from the ground up for modern Paper servers (1.20.x–1.21.x) with Java 21.

---

Product Overview

VectorGuard is a combat-only anti-cheat designed to catch the most common PvP exploits while staying light on performance and fair on legitimate players. Every check uses multiple independent signals (rotation, timing, movement, cooldown usage, and hit validation) and applies buffered violations with decay, so one-off spikes do not punish normal players. Ping-aware thresholds and packet-timing compensation reduce false positives for high-latency players.

Administrators get a fast response workflow: clickable in-game alerts with action buttons, a threat score that aggregates risk across checks, and a visual report command for quick evidence review. A built-in GUI lets staff adjust thresholds, toggle checks, and tune punishments without editing files or restarting the server. Alerts can also be mirrored to Discord for off-server monitoring.

VectorGuard ships as a single jar with no external dependencies. PacketEvents is embedded, and the plugin runs entirely server-side with no client mod required.

---

Features

Detection Engine

• 19 combat checks targeting the most common cheat modules including Mace PvP exploits, crystal PvP automation, bow manipulation, and inventory exploits
• Multi-signal compound detection — each check combines multiple independent signals for high confidence
• Buffered violation system with configurable decay — prevents single-tick flukes from triggering punishments
• Latency compensation — all checks account for player ping to avoid false-flagging high-ping players
• Tick-based analytics with per-player position history and rotation profiling

Admin Experience

• Clickable chat alerts with action buttons: [TP] [VL] [DBG] [RPT]
• Threat score system — composite 0–100% risk assessment across all checks
• Visual threat reports via /vg report <player>
• Sound alerts for online admins (configurable)
• Discord webhook integration for off-server monitoring
• In-game GUI for editing thresholds, toggling checks, and tuning punishments

Architecture

• 100% server-side — no client mod required
• PacketEvents embedded and shaded — zero external dependencies
• Modular check system — each check is independent and fully configurable
• Performance profiler built-in (/vg profile)
• Multi-version support — Paper 1.20.x through 1.21.x

---

Checks

Combat

Check	Description
Aimbot	Detects snap rotations, acceleration spikes, over-smooth curves, and precision patterns consistent with aim assistance
TriggerBot	Identifies automated attack timing with near-zero reaction delay after crosshair alignment
AutoTotem	Catches unrealistically fast offhand totem swaps during lethal damage windows
Reach	Eye-to-hitbox distance verification with ping, sprint, and movement leniency
Velocity	Detects Anti-Knockback by verifying displacement after server-sent velocity packets
Criticals	Identifies fake critical hits via spoofed position packets (abnormal crit rate, ground-flag oscillation, tiny Y offsets)
AutoClicker	Catches robotic click patterns through timing variance analysis (stddev, CPS, coefficient of variation)
KillAura	Detects multi-target attacks, angle mismatch, wall attacks, and perfect cooldown abuse
Sprint	Identifies backwards sprinting, KeepSprint, and sprint-toggle patterns around attacks
MaceSpoof	Detects spoofed fall-distance position packets for fake Mace smash damage (Criticals-Mace exploit)
MaceNoFall	Catches NoFall + Mace combos: players deal Mace fall-bonus damage but evade fall damage on landing
MaceSwap	Identifies automated weapon switching to Mace during falls (AttributeSwap / auto-swap patterns)
CrystalAura	Detects automated crystal place-and-break cycles (superhuman crystal attacks/sec, place→break pairing, fast-break ratio)
BowManipulation	Catches BowSpam and BowAimbot via charge variance analysis, fire rate, and abnormal hit rates at distance
InventoryCleaner	Identifies inhuman inventory manipulation speed (AutoTotem swaps, chest stealing, combat inventory use)
AutoWeapon	Detects automated weapon switching around attacks (pre-attack swap ratio, A→B→A swap-back patterns)
HitboxExpand	Catches expanded entity hitboxes via lateral offset analysis and edge-hit rate tracking
AutoArmor	Detects automated armor equipping during combat (rapid armor clicks, anti-break durability swaps)

Packet

Check	Description
Timer	Detects game speed manipulation via packet rate analysis (burst, sustained, and average rate monitoring)

---

Requirements

• Java 21+
• Paper 1.20.x – 1.21.x (or forks: Purpur, Pufferfish, etc.)
• No external dependencies — PacketEvents is embedded

---

Installation

1. Download VectorGuard-x.y.z.jar
2. Place it in your server's plugins/ folder
3. Start or restart the server
4. Edit plugins/VectorGuard/config.yml to customize thresholds
5. Use /vg reload to apply changes without restarting

---

Commands

Command	Description
/vg reload	Reload configuration
/vg debug <player|*>	Toggle debug output for a player (or all)
/vg vl <player>	View violation levels
/vg report <player>	Generate a visual threat report
/vg gui	Open the in-game config editor
/vg profile [seconds]	Run performance profiler

---

Permissions

Permission	Default	Description
vectorguard.admin	op	Access to all /vg commands and GUI
vectorguard.alert	op	Receive in-game cheat alerts with action buttons
vectorguard.debug.view	op	View debug output
vectorguard.report	true	Allows using /vg report to generate threat reports

---

Configuration

All settings are in plugins/VectorGuard/config.yml.

Check Configuration

Each check has:

• enabled — toggle the check on/off
• buffer-threshold — buffer must exceed this to flag
• buffer-decay-per-tick — buffer decreases each tick
• vl-per-breach — violation level added per flag
• vl-decay-per-tick — VL decreases each tick
• thresholds.* — check-specific tuning values

Punishment Stages

punishments:
  alert-vl: 2.5      # Send alert to admins
  setback-vl: 6.0     # Teleport player to last safe position
  punish-vl: 12.0     # Execute punishment command
  punish-command: "kick %player% Unfair combat behavior detected by VectorGuard."

Discord Webhooks

notifications:
  discord:
    enabled: true
    webhook-url: "https://discord.com/api/webhooks/..."
    min-vl: 5.0
    cooldown-ms: 10000

Admin Alerts

notifications:
  admin:
    sound-enabled: true
    clickable-actions: true
    show-threat-score: true

---

GUI Config Editor

Run /vg gui to open an interactive GUI where you can:

• Toggle checks on/off
• Edit buffer thresholds and VL values
• Adjust punishment thresholds and cooldowns
• Save changes to config and reload

---

FAQ

Q: Does this require players to install anything? A: No. VectorGuard is 100% server-side.

Q: Is PacketEvents required as a separate plugin? A: No. PacketEvents is embedded inside the VectorGuard jar.

Q: Does it work with Purpur/Pufferfish/other Paper forks? A: Yes, any Paper fork should work.

Q: Will it conflict with other anti-cheats? A: VectorGuard focuses only on combat. It can coexist with movement-focused anti-cheats, but running two combat anti-cheats may cause duplicate flagging.

Q: How do I reduce false positives? A: Increase the buffer-threshold and ping-cutoff-ms values for checks that are flagging incorrectly. The defaults are tuned conservatively.

---

Credits

Created by Mr. Dev

---

License

Copyright (c) 2025 NeonDev. All Rights Reserved.

This software and its source code are the exclusive property of NeonDev.

No part of this software, including but not limited to the source code, compiled binaries, documentation, configuration files, or any associated assets, may be used, copied, modified, merged, published, distributed, sublicensed, sold, or otherwise exploited for any purpose without the prior written permission of the copyright holder.

Unauthorized use, reproduction, or distribution of this software, or any portion of it, is strictly prohibited and may result in civil and criminal penalties.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.