Anti-cheat setup & staff guide

Connect your server. Review findings. Moderate with context.

• The anti-cheat plugin runs on your Paper server. Its supported checks record reviewable evidence, and /fg menu provides the staff toolkit. Once linked, it connects out to this website over HTTPS. You don't need port forwarding.
• The control console brings together evidence, detection settings, player investigations and audited moderation. Create an account, add your servers as private workspaces, and invite staff with a role per server.
• Linking needs a code from the Minecraft admin GUI and approval inside Minecraft. The server owner also chooses in config.yml what any website may do.

Before you rely on it, read the exploit coverage, version support and staff guide. ForgeGuard is an alpha: findings are evidence for your staff; automatic responses remain off unless you enable the response ladder.

1 · Install the plugin

1. Stop your Paper server (1.21.11 uses Java 21+).
2. Put packetevents-spigot-2.14.0.jar and the ForgeGuard 0.6.0-alpha.2 protected JAR in plugins/.
3. Start the server and run /forgeguard health.
4. Leave protection.mode, guards.mode and behaviour.mode at OBSERVE while you learn what normal play looks like.

It is a Paper plugin, not a Forge mod. The universal loader's portable fallback cannot link to the website.

2 · Create your account

Create a free account with your e-mail and a password (12+ characters). Then turn on two-factor authentication under Your account and keep the recovery codes somewhere safe.

On a paid installation, verify your purchase through the store account that owns ForgeGuard before adding and linking your server. Email alone does not prove a purchase. Invited staff use the linked owner's licence. The site owner must configure the store integration using the purchase setup guide.

3 · Link your server

1. In the console, Add a server. Its Server setup page shows a command for you to run in Minecraft: /fg link site https://this-site.
2. In Minecraft open /fg menu → Link web console → Generate pairing code. You need forgeguard.staff and forgeguard.link.
3. Enter the 10-character code on the Server setup page. It expires after ten minutes.
4. Back in Minecraft, check the website address and your e-mail, read what the website will be allowed to do, and approve.

Players appear within seconds. The plugin polls every five seconds when idle and every second while someone is using the console, so actions land quickly. Unlink at any time from either side; the plugin and its in-game tools keep running.

4 · Choose what the web may do

In plugins/ForgeGuard/config.yml, then /fg reload:

web:
  allow-config: true          # change detection settings and reload
  allow-moderation: true      # freeze, kick, ban, unban
  allow-inventory-view: true  # read inventories and Ender Chests
  allow-inventory-edit: true  # change them
  notify-staff: true          # tell /fg alerts subscribers about web inventory edits
  blocked-items: [command_block, structure_block, jigsaw, debug_stick]

Every website action is written to staff-audit.jsonl with the member's e-mail before it is applied.

5 · Invite your staff

In Members, invite someone by e-mail and choose their role. You get a one-time link to send them; it expires in seven days and only works for that address. No e-mail is sent by the site. They create an account (or sign in) and join straight away.

Website roles never grant Minecraft permissions, and Minecraft permissions never grant website access.

Roles

Roles are per server. A change applies to the member's next request, and work they queued but Minecraft hasn't run is checked again before it runs.

Gameplay replays

On a supported linked server with recording enabled, open a player's Gameplay replays tab. Use Save replay snippet to capture an online player with a reason. Cases can also have automatic snippets: open a case and choose Watch gameplay replay.

Playback includes pause, seeking, speed controls, camera views and event markers. It reconstructs recorded player positions, nearby entities and blocks with simplified geometry. It cannot show private cheat menus, X-ray textures or the player's screen. Missing data is marked; treat a replay as investigation context alongside the evidence, not proof of cheating.

A pending capture is still collecting or saving data. Wait for ready or partial; partial clips carry warnings. After a connection failure, retry the same capture request instead of making another one. Retained clips can be watched while the player is offline and downloaded as JSON replay data, not video.

Older cases may have no visual clip. Recording is a modern-core feature and is unavailable in the portable staff adapter. See the capture limits and configuration guide.

Player-enabled screenshots

On an updated linked server, open an online player's Screen capture tab and send a private invitation. The player enables sharing and chooses their Minecraft window. Staff can then request and view screenshots; the in-game player menu also has invitation and screenshot buttons.

The player can stop at any time. Sharing is visible, has no audio, and expires after 30 minutes. Only the latest screenshot is kept for up to 15 minutes. Images are client-supplied evidence, not proof that a client is cheat-free. Read the screen capture guide for requirements and limits.

Inventory inspection and removal

Use inventory inspection alongside a player's evidence when investigating suspected abuse. In Players, open an online player and load their inventory or Ender Chest. Inspect the actual stack, including its name, lore, enchantments, damage and count. Inventory access requires a staff role and the server's permission.

If your staff decide an item should be removed, select the stack and choose Remove, or right-click its slot. Review the draft, then choose Apply to player. Only authorised owners and admins can apply web inventory edits, and the server records the action in its audit log.

These tools let staff act on an investigation. ForgeGuard does not automatically identify an item as duplicated, illegally obtained or evidence of cheating.

• If the player changed a slot after you loaded it, that edit is refused and your draft is kept. Refresh, review and apply again.
• Moving an existing stack keeps any plugin data on it.
• Items in web.blocked-items can't be created; protected players can't be edited from the web.
• The separate inventory moderation demo uses a browser-only draft. Its exports and share links do not apply changes to a server.

Icons, item text and tooltip artwork use verified Minecraft Java 1.21.11 client assets. Custom resource-pack fonts and models are not fully reproduced. To use different item textures, choose Import textures and select your client .jar or resource pack; it is unpacked in your browser and never uploaded.

Item restoration and delivery remain available through Give items in a linked player's profile. Online players receive a delivery when their inventory has room; offline deliveries wait for a later join. After a lost connection, check or retry the same delivery ID. Needs staff review means the outcome is uncertain: inspect the real inventory before issuing anything again.

Moderation

Freeze (timed), unfreeze, kick, temporary ban, permanent ban and unban, each with a reason. The server's own admin: limits apply. Website bans work for offline players by UUID and appear under Bans. Supported linked servers also allow staff to teleport and return online players. Players with forgeguard.protected can't be targeted from the web.

In-game toolkit

Staff tools are also available in Minecraft, starting at /fg menu. Gameplay clips are watched in the website viewer:

/fg players · /fg player <name>
/fg inventory <name> · /fg enderchest <name>          (forgeguard.inventory)
/fg editinv <name> · /fg editender <name>            (forgeguard.inventory.edit)
/fg staff freeze <name> <seconds> <reason>
/fg staff kick|ban <name> <reason> · tempban <name> <seconds> <reason>
/fg staff unban <uuid> <reason> · /fg confirm <token>

The live editor shows the player's inventory as you both use it. If you both change the same slot at once, the player's item is kept and yours comes back to you.

Behaviour checks

The behaviour: section adds server-side signals, judged from the server's own positions, hitboxes and break speeds: reach, hit angle, attack rate, multi-target, fast break, fast place, scaffold, ground spoof and hover. Each needs repeated violations, and players who are flying, gliding, swimming, in vehicles, climbing, affected by levitation, in grace or on translated clients are exempt.

OBSERVE records cases. CANCEL also cancels the offending hit or block action. Neither kicks or bans. See the exploit coverage for defaults and limits.

Event guards

Per-player budgets for inventory clicks, drops, interactions, book edits and commands, plus book size limits. Tune guards: while in OBSERVE, then opt in to CANCEL. They are not a duplication, X-ray, login-bot or DDoS solution.

Security model

• Sessions: an opaque HttpOnly; Secure; SameSite=Strict cookie, a CSRF token on every change, a 45-minute idle timeout and a 12-hour limit.
• Passwords and two-factor: scrypt hashing, lockout after repeated failures, TOTP with single-use recovery codes.
• Isolation: every server request checks your membership; a server you don't belong to looks exactly like one that doesn't exist.
• What reaches Minecraft: supported, permission-checked operations for status, evidence and replay, the item catalogue, bans, player details, inventories, item deliveries, moderation, player travel, configuration and reload. There is no arbitrary console-command, operator or file access.
• Local presentation assets: UI fonts, verified Minecraft item textures and bitmap glyphs are hosted with the site. Item inspection does not load a third-party texture CDN.

Host your own site

You can run a private ForgeGuard site on Netlify with Blobs:

cd site
npm ci && npm test && npm run build
netlify deploy --prod

Upgrading from 0.4 turns your existing link, accounts and roles into one workspace automatically. The full guide is deployment.md. To try everything locally without Minecraft, run npm run dev and node scripts/simulate-server.mjs --auto-approve.

Troubleshooting

Waiting for Minecraft approval

Open Link web console in Minecraft and approve the claim. If it expired, generate a new code.

Linked but offline

Check the server is running, the plugin log, the configured site address and that the server can make outbound HTTPS requests.

“Slot N changed in-game after you loaded it”

The player moved items while you edited. Your draft is kept: choose Refresh from server, review, apply again.

“This server does not allow … from the website”

The server owner switched that off under web:, or the player is protected.

“The ForgeGuard functions are not deployed on this site”

Only the static pages were uploaded; deploy with the functions directory.