TriggerGuard

TriggerGuard
The professional triggerbot detection utility for your server staff team.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

OVERVIEW

TriggerGuard is a lightweight, staff-oriented Minecraft plugin designed to help server administrators efficiently investigate and confirm suspected triggerbot users — without relying on automated bans or complex third-party anti-cheat systems.

Triggerbots are a form of cheating software that automatically fires a player's weapon the instant their crosshair lands on an enemy hitbox. They are notoriously difficult to detect automatically, which is why many competitive servers rely on manual staff checks. TriggerGuard gives your staff team a structured, professional workflow to carry out those checks in a controlled environment.

How it works: When staff suspect a player is using a triggerbot, they run a single command. The suspect is instantly teleported to a designated check arena, frozen so they cannot move, and presented with a forced informational book — informing them they are being reviewed. Simultaneously, the staff member is teleported to a pre-configured observation position directly facing the suspect, so they can watch for suspicious input behavior in real time. Once the check is complete, a second command releases the player — teleporting them to spawn, locking their head rotation briefly to prevent rapid pre-aim, and broadcasting a notification to all online staff.

TriggerGuard also supports NPC-based detection workflows. If your server uses an NPC that players are asked to shoot during a check (e.g., using Citizens or any command-capable NPC plugin), TriggerGuard tracks each hit via the /triggernpc command and immediately broadcasts a real-time alert to all staff with a running hit counter — while also logging the event to the server console for record-keeping.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

FEATURES

One-command freeze system —
Code:
```
/triggercheck <player>
```
instantly teleports the suspect to a dedicated check arena, freezes their movement entirely, auto-opens the check book, and teleports the issuing staff member to a facing observation position — all in a single command execution.
Forced book GUI — A fully customizable written book is force-opened for the suspect when the check begins. If the player attempts to close the book, it is automatically re-opened after a configurable delay (in ticks). The book's title, author, and all page content are fully editable in config.yml. You can write any instructions, rules, or warnings you want the suspect to read during the check.
Complete movement blocking — While frozen, the suspect's position is locked server-side. They cannot walk, jump, or change position in any way. Only head rotation (looking around) is permitted during the check, allowing staff to observe natural mouse movement for analysis.
Head lock on release — When a player is unchecked via
Code:
```
/triggeruncheck
```
, their head yaw and pitch are immediately snapped to a configurable angle. This prevents a checked player from rapidly flicking to a target the moment they are released, which could mask triggerbot behavior at the start of normal gameplay.
NPC hit detection & alerting — Integrates with any NPC plugin that supports hit-triggered commands (Citizens, FancyNPCs, etc.). Each time the NPC is hit,
Code:
```
/triggernpc detect +1 <player>
```
is called. TriggerGuard groups hits within a configurable time window (in ticks) and broadcasts a single alert to all online staff showing the player name and cumulative hit count. Console logging is also supported with a fully customizable log message format.
Disconnect detection — If a player who is currently under a trigger check disconnects from the server, all online staff with the
Code:
```
triggerguard.staff
```
permission immediately receive a highlighted warning message. This is a critical feature since disconnecting during a check is one of the most common evasion tactics used by cheaters.
Staff-wide notification system — Every significant event broadcasts to all players with
Code:
```
triggerguard.staff
```
: check started, player unchecked, player disconnected, NPC hit alert. Your entire moderation team stays informed in real-time without needing to be the one who issued the command.
Fully configurable messages — Every single plugin message is defined in config.yml and supports & color codes as well as {placeholder} variables including
Code:
```
{player}
```
,
Code:
```
{staff}
```
,
Code:
```
{count}
```
, and
Code:
```
{world}
```
. No hardcoded text anywhere.
Per-location teleport config — You set the exact world, X, Y, Z, yaw, and pitch for both the suspect's frozen position and the staff member's observation position. Fully independent coordinates so you can design any arena setup.
Live config reload —
Code:
```
/triggerreload
```
reloads the entire config.yml without restarting the server or reloading any other plugins. Location changes, message changes, and NPC settings all take effect immediately.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

COMMANDS

Command	Description	Permission
/triggercheck <player>	Teleports the target to the check arena, freezes them, opens the check book, and teleports the staff member to the observation position.	Code: `triggerguard.staff`
/triggeruncheck <player>	Unfreezes the target, teleports them to the configured spawn world, locks their head rotation, and notifies all online staff.	Code: `triggerguard.staff`
/triggernpc detect +1 <player>	Registers one NPC hit for the specified player. Groups hits within the alert window and broadcasts a staff alert with the running hit count. Also logs to console if enabled.	Code: `triggerguard.npc`
/triggerreload	Reloads the plugin configuration from disk without a server restart.	Code: `triggerguard.admin`

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

PERMISSIONS

Permission	Description	Default
Code: `triggerguard.admin`	Access to /triggerreload and receives all staff broadcast messages	OP
Code: `triggerguard.staff`	Access to /triggercheck and /triggeruncheck. Receives all staff broadcast alerts (check started, unchecked, disconnect warning, NPC hits).	OP
Code: `triggerguard.npc`	Access to /triggernpc — intended to be granted to NPC plugin command execution, not real players.	OP

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

CONFIGURATION

All settings live in a single config.yml that is auto-generated on first run. Below is a full breakdown of every configurable option:

Check & Staff Locations

Code:
```
trigger-check.location
```
— World, X, Y, Z, yaw, and pitch of the frozen suspect's position in the check arena.
Code:
```
trigger-check.staff-location
```
— World, X, Y, Z, yaw, and pitch of the staff member's observation position. Set this to face the suspect directly to maximize visibility.

Book Settings

Code:
```
trigger-check.book.title
```
— The display title of the written book item shown to the suspect.
Code:
```
trigger-check.book.author
```
— The author name displayed on the book.
Code:
```
trigger-check.book.pages
```
— A list of pages. Each page is a raw string supporting newlines (
Code:
```
\n
```
). Write your check procedure, server rules, or any instructions you want the suspect to read.
Code:
```
trigger-check.book-reopen-delay
```
— How many ticks after the suspect closes the book before it is force-reopened. Default is
Code:
```
1
```
tick. Increase this slightly if clients experience flicker.

Spawn & Head Lock

Code:
```
spawn.world
```
— The name of the world players are teleported to when unchecked. Their exact spawn point within that world is used.
Code:
```
head-lock.yaw
```
/
Code:
```
head-lock.pitch
```
— The exact head rotation applied when a player is unchecked. Use this to orient them toward a safe direction so they cannot instantly pre-aim on release.

NPC Detection

Code:
```
npc-detection.log-to-console
```
— Whether each NPC hit event is printed to the server console. Useful for logging suspected triggerbot sessions for later review.
Code:
```
npc-detection.alert-window-ticks
```
— The time window (in server ticks) within which multiple NPC hits are grouped into a single staff alert with a cumulative count. Prevents chat spam on rapid hits.
Code:
```
npc-detection.log-message
```
— The console log message format. Supports
Code:
```
{player}
```
and
Code:
```
{count}
```
placeholders.

Messages
Every message supports & color codes and relevant {placeholder} variables:

Code:
```
{player}
```
— The name of the player being checked or triggering the event.
Code:
```
{staff}
```
— The name of the staff member who issued the command.
Code:
```
{count}
```
— The NPC hit count in an alert window.
Code:
```
{world}
```
— A world name in error messages or notifications.

Configurable messages include: no-permission, command usage errors, player-not-found, already-being-checked, check started (sent to suspect and to staff), unchecked (sent to suspect and to staff), staff unchecked broadcast, config reloaded, NPC hit alert, and disconnect warning.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

REQUIREMENTS

Paper or Spigot 1.21+
Java 17+
No required external dependencies — works out of the box
Optional: Any NPC plugin that supports executing console commands on hit (e.g. Citizens, FancyNPCs) for use with
Code:
```
/triggernpc
```

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

INSTALLATION

Drop TriggerGuard.jar into your server's /plugins folder.
Start or restart your server. A default config.yml will be generated automatically.
Open
Code:
```
plugins/TriggerGuard/config.yml
```
and configure your check location, staff location, spawn world, and book content to match your server layout.
Assign
Code:
```
triggerguard.staff
```
to your moderator group via your permissions plugin (LuckPerms, etc.).
If using NPC-based detection, configure your NPC plugin to run
Code:
```
/triggernpc detect +1 <player>
```
as a console command when hit.
Use /triggerreload to apply any future config changes without restarting.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Developed by Lemnt — Built for serious anti-cheat workflows.

TriggerGuard v1.0.0

Overview History