Installation

Sentinel is a normal Paper/Purpur plugin: no extra dependencies to install (PacketEvents is shaded and relocated inside the jar).

Requirements

• Paper or Purpur, 1.21+
• Java 21 runtime (Sentinel emits Java 21 bytecode; Paper 1.21+ builds may require a newer JDK to run the server itself)
• Plain Spigot/CraftBukkit is not supported — anti-xray and a few checks use Paper-only APIs

Steps

1. Stop the server.
2. Drop Sentinel.jar into plugins/ and remove any older Sentinel build. Don't hot-swap a loaded plugin jar.
3. Start the server. Watch the startup log for the packet engine, storage, and license lines.
4. Run /sentinel activate <your-key> in console (Free tier can skip this).
5. Review plugins/Sentinel/config.yml, then /ac info, /ac checks, and /ac shadow.

Configuration

Everything lives in plugins/Sentinel/config.yml, generated with commented defaults on first boot. Run /sentinel reload after editing (new check toggles still need a restart).

Per-check settings

Every check lives under checks.<id>.*:

Lag compensation

lag-compensation.min-tps suspends timing-sensitive checks below that TPS floor; soft-ping widens tolerances for laggy connections, hard-ping exempts them outright.

Punishment thresholds

suspicion.thresholds.* sets the alert/kick/tempban/ban score cutoffs. punishments.* controls tempban duration, escalation after repeat kicks/tempbans, and whether punishments broadcast server-wide.

Commands

Root command /sentinel (alias /ac). Works in-game and from console. Tab-completion covers every sub-command and player-name argument.

F Free   P Pro/Ultimate   U Ultimate only

Inspection

Client / cheat-client control

Moderation

License & admin

Permissions

Core Concepts

Confidence scoring

A single detection never punishes anyone. Each check adds vl × weight to a hidden, decaying suspicion score. Kick, tempban, and ban have separate thresholds, escalating only as evidence accumulates.

Shadow / canary mode

Any check can run observe-only: it records evidence and replay clips, but adds zero suspicion and can never cancel or punish. New or materially changed checks ship shadowed until proven on real traffic. /ac shadow shows what's currently shadowed.

Second-opinion ban gate

Reaching the permanent-ban threshold doesn't ban outright. It also needs a second opinion: two distinct checks flagging within a short window, or one check whose own confidence clears a high bar. If neither is met, Sentinel issues a tempban instead and logs a held-back-ban entry for staff to review. This only gates permanent bans — kicks and tempbans are unaffected.

Alt-account correlation

When a player joins from an IP already linked to another known account, staff (and optionally Discord) get a heads-up. This never adds suspicion, cancels anything, or punishes — shared IPs are routine (siblings, schools, VPNs, CGNAT). The one case worth acting on is called out visually: a linked account that's currently banned or tempbanned. IPs are stored as a salted hash by default, never in plaintext.

Combat

Aim, reach, click-rate, and attack-state cheats.

• Reach (hitbox raytrace + ping leniency)
• KillAura A–D: state, angle, multi-target, raytrace
• AutoClicker (CPS + click-interval + pattern)
• Criticals, Velocity, VelocityV (partial anti-knockback)
• NoSwing, AutoBlock, AimSnap, AimGcd (aim quantization)
• BowSpam, BowAimbot, CrystalAura, AutoTotem
• BedAura, AutoAnchor, AutoPot, AutoWeapon, Honeypot

Movement

Rebuilt around physics prediction: checks forecast the expected next-tick position from real gravity/velocity math rather than flat thresholds, and read the server's actual gravity/speed attributes so a legitimate effect is never mistaken for a hack.

• Flight A (gravity prediction) + Flight B (hover/anti-kick)
• Speed A (rolling-window) + Speed B (friction prediction)
• NoFall, Jesus, Step, Spider A–B, HighJump, Strafe
• NoSlow, FastClimb, BoatFly, ElytraFly, ElytraSpeed
• Timer, Phase, VClip, Bhop, AutoWalk, SafeWalk, Glide
• LongJump, AutoJump, AntiVoid, Riptide, KeepSprint

Packet Layer

Runs on a shaded PacketEvents pipeline, off the main thread where needed, all timing measured with monotonic clocks (immune to system clock adjustments).

• BadPackets A–E: invalid rotation, non-finite position, malformed slot, implausible position jump, self-attack
• AbilitiesA — forged flight-abilities packet
• Crash-book & sign-exploit protection
• Illegal creative-action drop
• GCD aim analyzer + rotation spoof (advisory)
• Blink/phase teleport detection (TimerA/TimerB)

World & Economy

• X-ray ore-exposure scoring (advisory — Paper's own anti-xray engine does the actual obfuscation; see /ac antixray)
• Anti-ESP / freecam occlusion — mitigation, not detection: hides entities a viewer genuinely can't see rather than trying to detect the renderer
• Dupe watermarking and audit
• Nuker, FastBreak, FastPlace, FastUse, Scaffold
• AutoFish, Tower, AutoEat, AutoInteract
• IllegalItems / NBT scan, GhostBlock

Config Presets

/ac preset lists the bundled profiles; /ac preset <name> applies one. Every preset backs up your live config.yml first, then overwrites only top-level tunables — lag tolerance, suspicion pacing, corroboration strictness, alert noise, client-brand policy. A preset never touches an individual check's weight or threshold, so switching profiles can never make Sentinel worse at catching a real cheater — only how eagerly it punishes and how much latency it tolerates.

Bedrock & Geyser

Bedrock players reach the server through fundamentally different input hardware (touch screen or a game controller, translated by Geyser), and their movement/interaction timing genuinely differs from mouse-and-keyboard Java play — a known false-ban source for anti-cheats that treat every client identically.

Detection — three independent signals

1. Floodgate API (authoritative when present) — a soft dependency reached only via reflection.
2. Client brand — Geyser sets its own outgoing brand regardless of whether Floodgate is installed, so a Geyser-only setup is still caught.
3. UUID version heuristic (fallback, needs neither plugin) — Floodgate issues version-0 UUIDs, a value no Mojang-issued or offline-mode account ever produces.

However detected, every violation level a Bedrock player generates is scaled down before it reaches their suspicion score (bedrock.vl-multiplier, default 0.7). This can only make Sentinel more lenient toward a detected Bedrock player, never more aggressive. Disable with bedrock.enabled: false.

Localization

All player-facing text lives under messages.* in config.yml using MiniMessage formatting, so you can already reword or fully translate kick/ban screens and chat notices yourself.

Dashboard Remote Actions

Ultimate's web dashboard can moderate your server without you being in-game. The plugin never opens an inbound port — it dials out to the dashboard on a short timer and drains a queue of actions a moderator queued in the browser.

Available actions

kick · tempban · ban · unban · freeze · notify · broadcast · setcheck · setconfig · addbannedword · removebannedword · reload

Plus two read-only queries used by the Player Inspector: inspect and peekcontainer, and explain for the evidence-timeline lookup behind the Ask Sentinel chat.

Safety model

• Fixed whitelist — only the actions above are ever honoured, re-validated on the plugin side even though the backend already validated them. There is deliberately no "run arbitrary console command" action.
• Config changes are allow-listed to a safe subset of paths — sync/license settings can never be rewritten remotely.
• Fails quietly — a dashboard outage never touches the anti-cheat itself.

API & Events

Sentinel fires standard, cancellable Bukkit events so other plugins can observe — or veto — a detection or punishment before it takes effect. No separate API jar needed; depend on Sentinel and listen normally.

SentinelViolationEvent

Fired synchronously before a live check violation is accepted. Cancelling it rejects the detection completely — no suspicion change, no evidence write, no staff alert.

@EventHandler
public void onViolation(SentinelViolationEvent e) {
    Player p = e.getPlayer();
    String checkId = e.getCheckId();
    double projected = e.getProjectedSuspicion();
    // e.setCancelled(true) to veto this detection
}

Exposes getRawViolationLevel(), getEffectiveViolationLevel() (after platform dampening, e.g. Bedrock scaling), getWeightedViolationLevel(), current/projected check total, and current/projected suspicion.

SentinelPunishmentEvent

Fired before a kick/tempban/ban is actually applied. Cancelling it blocks the punishment; the player is never touched.

@EventHandler
public void onPunishment(SentinelPunishmentEvent e) {
    if (e.getAction() == SentinelPunishmentEvent.Action.BAN) {
        // inspect e.getReason(), e.getSuspicion(), e.getExpiresAt()
    }
}

SentinelAlertEvent

Fired when a staff alert is generated, letting a network plugin mirror alerts elsewhere (a cross-server staff channel, a custom overlay, etc).

Reporting a Bug

Email sentinel.support.help@gmail.com with:

• Your Sentinel version (/ac info) and Paper/Purpur build
• What happened, and what you expected instead
• For a false positive: the player's /ac logs <player> output or, better, ask the dashboard's Ask Sentinel chat to explain <player> for the full timeline
• Anything unusual about the setup (Bedrock/Geyser, a custom preset, disabled regions)

Pro and Ultimate licenses get priority replies. See also the Q&A for common issues before reporting.