Alpha · v0.6.0-alpha.2 · Paper 1.21.11
ForgeGuard records suspicious movement, combat and building activity on supported Paper servers. Review the evidence, tune your checks and take audited staff actions from one console. During an investigation, inspect a player's inventory and remove items your staff judge invalid. This is an alpha with documented coverage limits. Checks observe by default; automatic responses require an explicitly enabled response ladder.
The console opens in a labelled demo. Create an account, verify your purchase on a paid installation, then link each server with a code from its admin GUI and approve the website in Minecraft.
01 — Approach
A false ban costs a player their account and costs you a reputation. ForgeGuard is built on the assumption that the detector can be wrong. Retained cases carry the context a person can inspect and replay; bounded queues report dropped work. The judgement stays with your staff.
OBSERVE is the shipped mode. The optional response ladder is disabled by default; enabling it can apply setbacks, kicks or temporary bans at configured violation levels.
MITIGATE adds exactly one thing: cancelling movement packets that contain NaN or
infinity. Automatic responses are controlled separately in the documented response ladder.
Each case keeps a rolling 120-packet trace and the engine checkpoint preceding it.
/forgeguard replay <id> re-runs the same implementation over the same data,
so a finding can be reproduced rather than taken on trust.
Everyone signs in with their own account. Owners invite admins, moderators and viewers per server; two-factor is available, sessions can be revoked, and every web action is audited both on the website and inside Minecraft.
Original cases live under plugins/ForgeGuard/cases. Website pairing sends
status and requested case results through your Netlify relay, which temporarily retains results.
Case files exclude player IP addresses, chat history, inventory contents and credentials.
02 — How it works
Five stages, each with a bound on what it will consume. When a queue fills, work is dropped and the diagnostics say so — the engine degrades visibly rather than quietly falling behind.
STAGE 01
A PacketEvents adapter reads movement packets and takes an immutable snapshot of the surrounding world state.
STAGE 02
Non-finite values are rejected outright. In MITIGATE the offending packet is also cancelled.
STAGE 03
Coverage is checked first. Unsupported clients, stale snapshots, odd movement contexts and server stalls are excluded with a stated reason.
STAGE 04
Ordered, bounded workers run the experimental packet checks. A finding needs repeated deviation, not one bad sample.
STAGE 05
A bounded JSON case is written with its trace, thresholds and replay checkpoint, then surfaced in game and in this console.
03 — What actually ships today
Release 0.6.0-alpha.2 registers 31 check types: 25 server-event behaviour checks and 6
packet, movement and timing observations. Selected examples appear below. They use the server's positions,
hitboxes, timing and break speeds. Event guards cover inventory clicks and drags, item drops, interactions,
book edits, commands and book text limits.
HORIZONTAL_ENVELOPE
Broad horizontal displacement bounds on ordinary flat ground. Deliberately generous: it is designed to miss marginal cases rather than accuse a laggy player.
AIR_TRAJECTORY
Simple airborne movement against an expected trajectory envelope, over consecutive samples in clear air.
TIMER_WINDOW
Sustained movement-timing deviation across an observation window, rather than the jitter any real connection produces.
MOVEMENT_RATE
Coarse movement packet frequency and burst thresholds. This one still applies to players holding forgeguard.bypass.
combat.reach · combat.hit-angle
Hits measured from the eye to the server's hitbox, against the reach attribute plus the target's actual movement during the attacker's latency. Hits far outside the look direction are recorded separately.
combat.attack-rate · combat.multi-target
Sustained clicks per second and several distinct targets hit in a short window, with sweep attacks excluded.
world.fast-break · world.fast-place · world.scaffold
Breaks faster than the server's own break-speed calculation, placement floods, and placing against block faces the player could not have been looking at.
movement.ground-spoof · movement.hover
Claiming to stand on nothing to avoid fall damage, and holding a constant height in open air, with flight, gliding, liquids, vehicles, climbing and effects exempt.
OBSERVE. Their separate CANCEL mode can cancel an excess event or invalid book edit; it never automatically bans a player. These are bounded safeguards against specific abuse, not general duplication or packet-parser exploit prevention.
04 — The case record
The original case is a file on your server. Requested results pass through the Netlify relay's bounded storage. Here is a sample record and what each part is useful for.
{
"schema": 1,
"id": "f0a12c84-d660-4c3e-8559-321405c6c7d1",
"playerName": "LunarPixel",
"createdMillis": 1780000000000,
"build": "0.3.0-alpha.1",
"serverVersion": "1.21.11",
"clientVersion": "1.21.11",
"configRevision": "9f2c1ab4",
"finding": {
"check": "HORIZONTAL_ENVELOPE",
"confidence": "EXPERIMENTAL",
"severity": "REVIEW",
"observed": 1.12,
"limit": 0.80,
"sequence": 1842
},
"coverage": "SUPPORTED",
"trace": [ /* up to 120 movement packets */ ],
"checkpoint": { /* engine state before the window */ }
}replay deterministic.Gameplay context
On supported Paper 1.21.11 servers, save short gameplay snippets automatically with cases or start a capture from a player's profile. Pause, scrub, slow down and change cameras while reviewing recorded blocks, nearby entities and event markers.
The viewer reconstructs server observations with simplified geometry. It cannot show the player's screen or private cheat overlays. Missing data is marked, and the verdict stays with your staff.
How gameplay replays work05 — Honest limits
Being specific about the gaps is more useful than a feature list. If one of these matters to your server, ForgeGuard is not ready for you yet, and this page would rather say so now.
There is no acknowledged world timeline and no collision-shape simulator. The movement model covers native 1.21.11 clients on ordinary flat floors or clear air.
Combat and building signals are server-side geometry and timing, not a client simulation. There is no aim or rotation classifier, backtrack model, general item-duplication detection, X-ray protection, login-bot filtering or DDoS protection.
The modern core needs Paper, its required Java version and PacketEvents 2.14.0. Its movement model remains native 1.21.11 only. The universal loader's portable fallback supplies staff tools with detection unavailable; historical versions are not all certified. Forge, NeoForge, Fabric, Folia and native Bedrock runtimes are not supported.
Swimming, gliding, vehicles, flight, unusual poses, custom physics and uncertain Bedrock identification are outside the model and are not analysed.
This alpha has not been load-tested with 20, 50 or 100 live clients. Queues are bounded, so under pressure work is dropped and the diagnostics report it.
It records reviewable evidence with the values, bounds and context behind every finding, and gives your staff the same careful tools in-game and on the web. Automatic responses require an explicitly enabled response ladder; the shipped defaults only observe.
Investigation & moderation
Review a player's evidence, freeze them while investigating, and inspect their inventory or Ender Chest when needed. Authorised staff can remove items they judge invalid and apply moderation with a reason. Open /fg menu in Minecraft or the linked console; actions require the right permission or role and are audited.
Read a stack's name, lore, enchantments and count before deciding whether it belongs on your server. Authorised staff can remove it in the linked console or use /fg editinv and /fg editender in game. Inventory tools support your investigation; they do not automatically identify duplicated or illegal items.
Freeze and unfreeze, teleport and return, kick, temporarily ban, ban and unban. The preview records the target, reason and duration; confirm the exact action in the GUI or with /fg confirm <token>.
Live players with health, food and ping, moderation, ban records, evidence and settings. The server owner decides what any website may do under web: in config.yml.
Read the staff toolkit guide or try the inventory moderation demo. This is a modern Paper alpha; support for every historical server version and every exploit is not established.
06 — The control console
Keep evidence, detection settings and moderation together for each linked server. Create an account, link with a code and in-game approval, and invite staff with the role they need. Server credentials never reach the browser.
Owner manages members and linking. Admin also changes checks and edits inventories. Moderator freezes, kicks, bans and views inventories. Viewer reads status and evidence. Changes apply on the next request.
Standard TOTP from any authenticator app, with ten single-use recovery codes. A used code cannot be replayed inside its own window.
Sign-ins, invitations, role changes, pairing and every request sent to Minecraft with its result — each with an actor, a time and an address. Minecraft records the same actions with the member's e-mail.
The browser holds an opaque, HttpOnly, host-locked session cookie. The device credential stays on the Minecraft server and is only validated, as a hash, by the website backend. The server connects out; nothing needs to reach it.
07 — Questions
The shipped defaults observe and record findings. Optional cancel modes can reject a matching invalid event. An explicitly enabled response ladder can apply configured setbacks, kicks or temporary bans; leave it off until your staff have reviewed findings and tuned thresholds. Manual moderation requires permission, confirmation and an audit record.
No. This artifact is a Paper 1.21.11 plugin and needs Java 21 plus PacketEvents 2.14.0. Installing a Paper plugin into a Forge mod server will not work — it is a different runtime.
No. Your server connects out to the website over HTTPS, so there is no port to open. Run /fg link site with the website address, enter the admin GUI's code in Server setup, and approve it in Minecraft. You can also host your own private copy of the website.
Only the members you invite to that server, scoped by their role. Original cases stay on your server; requested results pass briefly through the relay's bounded queue.
Every website action is written to staff-audit.jsonl with via=web and the member's e-mail before it is applied. The website keeps its own audit log per server too.
Yes. Writes carry the current configuration revision. If the file changed on disk or another operator saved first, the write is refused with a conflict and your running settings are preserved.
Get started
Review sample findings, explore check settings and try staff moderation in the browser-only demo. For live use, install ForgeGuard, link your server and review the coverage limits for your runtime.