VelocityGuard

VelocityGuard Plugin

VelocityGuard is a Minecraft Paper 26.1.2 lenient anti-cheat plugin that prevents extreme speed and flight cheats. Although it was custom built for minecraftoffline.net, any server can use it. The plugin intercepts movement packets and runs a server-side physics simulation to predict the maximum displacement a player could legitimately produce each tick. It treats every movement packet as exactly one game tick and polices the rate of those packets against a server-anchored clock which means detection is consistent regardless of a player's ping and is immune to "timer" cheats that speed up the client's game loop. A developer API is also provided for other plugins to enforce flight checks on specific players on demand (e.g. within a no-fly zone).

Features

• Full 3D Physics Simulation: Speed and flight checks are based on Minecraft's actual movement equations for both horizontal and vertical axes.
• Ping-Independent Timer Check: Each movement packet represents one game tick (50 ms). VelocityGuard accumulates that claimed time and compares it against real time anchored to a server clock the client cannot speed up.
• Transaction-Based Timing: A ping/pong (transaction) packet is sent to each player every tick; the forced echo gives a server-anchored clock used to keep timing honest under network jitter.
• Direct Detection: Detects cheating at the packet level on the Netty thread before the server processes the move.
• Violation Buffer: Excess displacement accumulates in a buffer that decays on clean packets so a single lag spike should not trigger a false positive.
• Setback Enforcement: On a confirmed violation the player is rubber-banded to their last valid position.
• Adaptive Exemptions: Handles knockback, riptide, elytra landing, potions, boats, horses, swimming, levitation, and happy ghasts automatically.
• Leniency Multiplier: A single top-level knob to loosen all checks at once without touching individual parameters.
• Toggleable Flight Check: Physics-based Y simulation catches hover and ascent cheats.
• Developer API: Lets other plugins enforce no-fly zones on specific players on demand.

Installation

1. Download the latest release here.
2. Place the .jar file in your Minecraft server's plugins folder.
3. Restart your server.

Configuration

In config.yml:

checks:
  # Global leniency multiplier applied to every max-allowed displacement value.
  # Raise to allow more movement before a flag fires; lower toward 1.0 for
  # stricter enforcement. Must be >= 1.0.
  # For example 1.15 = 15% headroom above the raw physics prediction.
  # This is the main no-false-positive lever: raise it if legit movement
  # (jumps, stairs, ice) ever rubberbands; lower it toward 1.0 to catch
  # smaller speed advantages at the risk of occasional false flags.
  leniency-multiplier: 1.15

  speed:
    # Extra displacement slack (blocks) added per expected tick.
    # Absorbs sub-block floating-point variance between client and server.
    per-tick-tolerance: 0.12

    # Accumulated excess displacement (blocks) before a violation fires.
    # The buffer decays on clean packets so only *sustained* cheating reaches
    # this value.
    violation-threshold: 2.0

    # Blocks subtracted from the violation buffer per clean (normal) packet.
    violation-decay: 0.15

    # Knockback from being hit: the large initial velocity is modelled by
    # scaling the tracked speed; this controls how long and how strongly.
    knockback:
      multiplier: 6.0
      duration: 1000  # ms over which the allowance linearly fades to 0

    # Riptide trident boost.
    riptide:
      multiplier: 2.5
      duration: 3000

    elytra:
      # ms of post-landing buffer: horizontal momentum carries briefly after a glide.
      landing-duration: 1500

    # Vehicle speed multipliers (horse, boat, strider, pig, etc.).
    vehicle-speed-multiplier: 1.5

    # Boats on ice can reach much higher speeds; this multiplier is used instead.
    # Default allows up to ~4.0 b/t (80 b/s) to cover extreme ice-boat runs while
    # still catching blatant teleport-speed exploits.
    vehicle-ice-speed-multiplier: 4.3

  timer:
    # Each movement packet a client sends represents one game tick (50ms).
    # VelocityGuard accumulates that claimed time and compares it against real
    # time anchored to a server clock (transactions) the client cannot speed up.
    enabled: true

    # Network-jitter tolerance in milliseconds.
    drift-millis: 120

    # Consecutive too-fast packets before a setback fires. Higher is more lenient.
    max-violations: 5

  flight:
    # Physics-based vertical (Y-axis) flight simulation.
    # Simulates gravity each tick (vy = (vy - 0.08) * 0.98) and flags players
    # whose upward displacement exceeds what a legitimate jump trajectory allows.
    # Catches hover and ascent cheats.
    # Disable if you only want horizontal speed enforcement.
    enabled: true

settings:
  # Verbose per-packet logging. Enable only for testing.
  debug-mode: false

How It Works

1. The plugin intercepts ServerboundMovePlayerPacket on the Netty thread before the server processes it. Each position-changing packet is treated as exactly one game tick.
2. A transaction (ping) packet is sent to each player every server tick; the client must echo it back immediately, giving a server-anchored clock the client cannot speed up. Each movement packet adds 50 ms to a running balance and if that balance runs ahead of real time, the client is sending packets faster than 20/s and is flagged.
3. Minecraft's ground/air movement equations are run for the tick, applying block friction (normal, ice, blue ice, slime), air drag, sprint/jump boost, water drag, and Speed/Slowness potion modifiers. Whilst gliding, the elytra physics model is used instead (0.99 horizontal drag, dive-to-horizontal conversion, and firework thrust toward a terminal speed). The result is the maximum a player could legitimately move in that single tick.
4. The player's Y velocity is simulated under gravity (vy = (vy − 0.08) × 0.98 per tick), predicting the maximum upward displacement from the last known velocity. This catches both hover cheats and upward speed cheats.
5. Any excess in the speed/flight checks accumulates in a per-player violation buffer that decays on clean packets. When the buffer exceeds violation-threshold (or the timer check exceeds max-violations), the player is rubber-banded to their last valid position and the resulting teleport re-anchors their tracked state.

Commands

• /velocityguard reload: Reloads the plugin configuration (requires the velocityguard.admin permission).

Permissions

velocityguard.admin: Allows reloading the plugin configuration (default: op).

Developer API

Setup - add to your plugin.yml:

softdepend: [VelocityGuard]

Add the VelocityGuard jar to your compile classpath, then get the API instance:

import com.jellypudding.velocityGuard.VelocityGuard;
import com.jellypudding.velocityGuard.api.VelocityGuardAPI;

VelocityGuard vg = (VelocityGuard) Bukkit.getPluginManager().getPlugin("VelocityGuard");
if (vg == null) return;
VelocityGuardAPI api = vg.getAPI();

Methods:

// Enable flight enforcement for a player (e.g. on zone entry).
// Defaults: ground on violation, strict sensitivity (~1 s),
// and a periodic check every ~0.5 s for players who fly up and go stationary.
api.enableFlightEnforcement(player);

// Control what happens on violation:
//   true  = teleport to highest solid block (default)
//   false = standard VelocityGuard setback behaviour
api.enableFlightEnforcement(player, false);

// Also control sensitivity via air-tick threshold.
// One tick ≈ 50 ms at 20 TPS. A normal jump lands by ~tick 15,
// so values below 15 risk false positives. Named constants are provided:
//   STRICT_AIR_TICK_THRESHOLD  = 20  (~1 s, recommended for zones)
//   DEFAULT_AIR_TICK_THRESHOLD = 40  (~2 s, matches the global config default)
api.enableFlightEnforcement(player, true, VelocityGuardAPI.STRICT_AIR_TICK_THRESHOLD);

// fourth parameter disables the stationary check if unwanted.
// (groundOnViolation, airTickThreshold, groundWhenStationary)
api.enableFlightEnforcement(player, true, VelocityGuardAPI.STRICT_AIR_TICK_THRESHOLD, false);

// Remove enforcement (e.g. on zone exit).
api.disableFlightEnforcement(player);

// Query whether enforcement is currently active for a player.
api.isFlightEnforcementActive(player);

Player data is cleaned up automatically on disconnect, so you only need to call disableFlightEnforcement on zone exit, not on quit.

Support Me