McGuard 1.0.0

Event-based anticheat source wiki

McGuard is a lightweight Bukkit-family anticheat compiled against Paper API 1.20.1 and Java 17. It observes server events, keeps per-player rolling state, raises violation levels, and lets a central manager decide staff alerts, kicks, bans, CSV logging, and decay.

13 checks
4 event listeners
Java 17+ toolchain target
1.20.x Paper API

Runtime Shape

McGuardPlugin wires configuration, player data, the check engine, listeners, command handling, Folia-aware scheduling, and file logging during onEnable(). On reload, it seeds tracking state for players already online.

Platform Strategy

The jar is built against Paper because it covers the Bukkit and Folia scheduler surface. Paper-only behavior is guarded so the plugin can still load on Spigot-style servers and hybrids.

Safety Bias

Checks observe at event monitor priority and do not cancel gameplay directly. The defaults intentionally under-flag, with join and teleport grace windows to avoid spawn, portal, pearl, and chunk-load noise.

Check catalog

Detection Rules

Each check bails out on legitimate mechanics first, computes how far past the configured limit the player was, then reports a weighted severity to ViolationManager.

Violation lifecycle

From Event To Action

Checks only report. The violation manager owns totals, decay, alerts, kicks, bans, and log writes. This keeps noisy detection signals separate from player-impacting decisions.

Listeners Move, damage, break, place, join, quit, teleport

CheckEngine Runs enabled checks and exemption logic

ViolationManager Applies weights, clamps severity, decays clean play

StaffWarn at VL 10.0

KickKick at VL 35.0

BanBan at VL 100.0 if enabled

CSVviolations.log

Flag Amount

checkWeight * clamp(severity, 0.5, 5.0)

Decay

Violation levels decay by violations.decayPerSecond for each second of clean play.

Log Format

timestamp,player,uuid,check,vl,detail

Admin surface

Commands And Permissions

/mcguard is registered with aliases /mcg and /anticheat. All subcommands require mcguard.admin.

Command	Purpose	Source behavior

`mcguard.admin`

Default: op. Runs commands and receives staff violation alerts.

`mcguard.bypass`

Default: false. Exempts the holder from every check.

config.yml

Configuration Reference

The defaults are read by McGuardConfig.reload() and mirror the shipped src/main/resources/config.yml. Editing the server copy can be applied with /mcguard reload.

Key	Default	Meaning

Source map (If u download the source code from github)

Files And Responsibilities

The plugin is intentionally small: one bootstrap class, one typed config wrapper, one central check engine, listener adapters, command handling, and a few portability utilities.

Operations

Tuning Notes

McGuard is designed to start forgiving and become stricter after real server observation. For a live rollout, collect flags first, then tighten check thresholds once normal player behavior is visible in /mcguard status and violations.log.

Start With Observation

Use violations.banEnabled: false while testing player movement, PvP, mining, and building on your own server.

Respect High Ping

Leave latency.lagCompensation enabled unless the server has stable low-latency players.

Keep Grace Windows

joinGraceMs and teleportGraceMs prevent spawn, portals, pearls, and plugin teleports from reading as movement cheats.

Pair X-Ray Carefully

The X-Ray check is statistical. It is best as an audit signal and works better alongside ore obfuscation.

Build and install (If u download the source code from github)

Gradle Tasks

The build emits mcguard-1.0.0.jar. The convenience install task copies that jar into ../../server/plugins relative to the project root.

.\gradlew.bat build
.\gradlew.bat installToServer

Identity

plugin_id=mcguard, plugin_name=McGuard, plugin_version=1.0.0

Main Class

com.mcserver.mcguard.McGuardPlugin

Server Family

CraftBukkit, Spigot, Paper, Purpur, Pufferfish, Folia, Arclight, and Mohist-style Bukkit loaders.