Nimbus AntiCheat

# ============================================================
#  Nimbus Anticheat
# ============================================================
settings:
  prefix: "&8[&bNimbus&8] &r"
  alerts-on-by-default: true     # staff with nimbus.alerts get alerts on join
  decay-per-minute: 2.0          # violation level decay (0 = never)
  debug: false                   # log check exceptions to console
update-checker:
  enabled: true
  # Your SpigotMC resource ID (the number in your plugin page URL).
  # Leave 0 until the plugin is published - the checker stays idle.
  resource-id: 136631
  # Shown in /nimbus info and the update message.
  download-url: "https://www.spigotmc.org/resources/nimbus-anticheat.136631/"
punishments:
  # IMPORTANT: left OFF so you can tune thresholds by watching /nimbus alerts first.
  # Set to true once you trust the thresholds and want Nimbus to auto-ban.
  enabled: false
  # Dry-run: when true, Nimbus logs + Discords the punishment it WOULD issue but does not run
  # the ban commands. Ideal final step before going live -- enable punishments with dry-run on,
  # watch for a day, then turn dry-run off once you trust it.
  dry-run: false
  # Command routing: "per-check" lets any check define its own punish-commands in the checks:
  # section below (checks WITHOUT their own list fall back to the global commands here);
  # "global" ignores every per-check list and always runs the global commands.
  mode: per-check
  # Same switch for the broadcast: "per-check" (use a check's punish-broadcast when set,
  # else the global one) or "global" (always the global broadcast).
  broadcast-mode: per-check
  # Punish once a player's TOTAL violation level across ALL checks reaches this (0 = disabled).
  # This is in ADDITION to each check's own max-vl below -- whichever trips first punishes.
  # Useful for catching players who trip several checks a little each without maxing any one.
  global-max-vl: 0
  # GLOBAL/DEFAULT commands -- run from CONSOLE when a check passes its max-vl and that check
  # has no punish-commands of its own (or mode is "global").
  # Per-check syntax -- add inside any check's block in the checks: section below:
  #   punish-commands:
  #     - "litebans:tempban %player% 7d -s &cNimbus &7| Unfair Advantage &8(&7%check%&8)"
  #   punish-broadcast: "&8[&bNimbus&8] &f%player% &7was temp-banned &8(&7%check%&8)"
  # Lighter tier (good for spammy packet checks like BadPackets):
  #   punish-commands:
  #     - "kick %player% &cNimbus &7| Suspicious activity &8(&7%check%&8)"
  # Placeholders: %player% %check% %vl% %ping% %id%
  #   %id% = the LiteBans punishment id (e.g. for /unban #123). Requires LiteBans.
  #   Any command or the broadcast using %id% is sent a moment later (id-delay-ticks),
  #   after LiteBans has assigned the id.
  # The litebans: prefix forces LiteBans to handle the ban.
  commands:
    - "litebans:ban %player% -s &cNimbus &7| Unfair Advantage &8(&7%check%&8)"
  broadcast: "&8[&bNimbus&8] &f%player% &7was banned by Nimbus &8(&7%check% &8| &7#%id%&8)"
  id-delay-ticks: 10        # ticks to wait for LiteBans to report the ban id before using %id%
# Mitigation (both OFF by default -- turn on only after tuning, like punishments).
setback:
  enabled: false            # rubber-band players back to their last valid ground position when a movement check flags
cancel-actions:
  enabled: false            # cancel the illegal block place/break when a world check flags (stops Nuker/Scaffold mid-action)
# Lag leniency -- movement checks stand down while the server is struggling, since movement
# physics (and so the prediction engine) can't be trusted during lag. A major FP source.
# Violation storage
violations:
  # Hard-wipe ALL violation levels on a schedule -- a safety net so occasional false flags can
  # never slowly stack into a punishment. This runs on top of the gradual per-minute decay in
  # settings.decay-per-minute; the reset also clears check buffers and punished-state.
  auto-reset:
    enabled: true
    interval-minutes: 60    # wipe everything this often
    notify-staff: true      # message staff with nimbus.alerts when the wipe happens
lag:
  tps-threshold: 18.0       # pause movement checks while the 1-minute TPS average is under this
  spike-ms: 110             # a server tick taking longer than this (ms) counts as a lag spike (normal = 50)
  spike-grace-ms: 1000      # keep movement checks paused for this long after a spike
  reset-buffers-on-spike: true  # zero movement buffers on a spike so none can flag on the first clean tick
# Logging  (files live under plugins/Nimbus/ in logs/, violations/ and bans/ folders)
logging:
  violations-file: false    # append every flag to plugins/Nimbus/violations/violations.log
                            # (great for offline calibration: play, then grep the file for the worst cases)
  max-file-mb: 10.0         # rotate a log into logs/ with a timestamp once it passes this size (0 = never)
# Discord webhooks. Create a webhook in your Discord channel (Channel Settings -> Integrations
# -> Webhooks -> New Webhook -> Copy URL) and paste it below. Flag and punishment webhooks can
# point at the same channel or different ones. Both are OFF until you enable them and set a URL.
discord:
  username: "Nimbus"            # name the messages post under
  flags-enabled: false
  flag-webhook: ""             # webhook URL for flag alerts
  flag-cooldown-ms: 5000       # min gap between flag posts per player+check (protects Discord's rate limit)
  punishments-enabled: false
  punish-webhook: ""           # webhook URL for punishments (real and dry-run)
# Staff freeze (/nimbus freeze <player>)
freeze:
  ban-on-logout: true       # if a frozen player disconnects, ban them (escaping = guilty)
  ban-command: "ban %player% Logging out while frozen by staff"
# Player reports (/report <player> <hack>) -- opens a short watch window on the target for the
# named check and pings staff who hold nimbus.reports. Review/close them with /reports.
report:
  gui-enabled: true         # /report <player> with no hack opens a clickable report menu (Hypixel-style)
  cooldown-seconds: 60      # per-reporter cooldown between reports
  watch-seconds: 60         # how long the reported check is watched closely on the target
  expiry-minutes: 30        # how long a report stays in the /reports list
checks:
  Reach:
    enabled: true
    max-vl: 15
    max-reach: 3.1          # blocks (vanilla ~3.0); distance is measured against the target's
                            # recent server positions, so a strafing target won't false-flag
    buffer: 3               # consecutive over-reach hits before a flag (stops one-off spikes)
    ping-comp-per-ms: 0.003 # extra reach tolerance per ms of ping (laggy attackers see a stale target)
    ping-comp-max: 0.8      # cap on that ping tolerance (blocks)
  Criticals:
    enabled: false          # DISABLED until tuned: flags critical hits landed while server-side on the ground
    max-vl: 20
    buffer: 4               # consecutive ground-state crits before a flag
  AutoClicker:
    enabled: true
    max-vl: 20
    max-cps: 16             # clicks per second
    min-consistency-ms: 8   # flag robotically even click spacing
  KillAura:
    enabled: true
    max-vl: 15
    max-angle: 75           # degrees off-aim allowed when hitting
  HitThroughWalls:
    enabled: true
    max-vl: 12
  InvalidAttack:
    enabled: true
    max-vl: 10
  Speed:
    enabled: true
    max-vl: 25
    # Example per-check punishment (uncomment to use; needs punishments.mode: per-check):
    # punish-commands:
    #   - "litebans:tempban %player% 7d -s &cNimbus &7| Unfair Advantage &8(&7%check%&8)"
    # punish-broadcast: "&8[&bNimbus&8] &f%player% &7was temp-banned &8(&7%check%&8)"
  Flight:
    enabled: true
    max-vl: 18
  MotionY:
    enabled: true
    max-vl: 15
  NoFall:
    enabled: true
    max-vl: 15
  Step:
    enabled: true
    max-vl: 12
    max-step: 0.65         # max height gained in one tick while grounded
  Jesus:
    enabled: true
    max-vl: 12
  FastClimb:
    enabled: true
    max-vl: 12
    max-speed: 0.13         # ladder climb is ~0.118/tick
  NoWeb:
    enabled: true
    max-vl: 12
    max-speed: 0.15         # cobweb caps movement at ~0.05/tick
  NoSlow:
    enabled: true
    max-vl: 12
    max-speed: 0.15         # using an item should slow you well below this
  Phase:
    enabled: true
    max-vl: 15
  Velocity:
    enabled: true
    max-vl: 12
    min-ratio: 0.20         # must travel >=20%% of applied knockback (tuning-sensitive)
  Spider:
    enabled: true
    max-vl: 12
    min-ticks: 8            # sustained against-wall ascent ticks (FP-sensitive; raise to loosen)
  InventoryMove:
    enabled: true
    max-vl: 12
    max-speed: 0.08         # movement allowed while a container GUI is open
  HighJump:
    enabled: true
    max-vl: 12
    max-height: 1.3         # max blocks gained above takeoff (vanilla jump ~1.25)
  # --- Prediction engine consumers (server-side physics; tune tolerance live) ---
  # CALIBRATION: set debug: true here, run /nimbus verbose, then move legitimately. You'll get
  # rate-limited [calib] lines showing the peak actual/predicted ratio whenever real movement
  # beats the raw physics prediction. Set tolerance just above the highest peakx you see during
  # normal play (plus a small margin). debug never flags or punishes -- it only reports.
  Prediction:
    enabled: true
    max-vl: 15
    tolerance: 1.25         # air speed may exceed predicted by this factor before flagging
    slack: 0.05             # absolute blocks/tick added on top of the tolerance
    buffer: 5               # sustained ticks over prediction before a flag
    debug: false            # log peak actual/predicted ratio to /nimbus verbose (calibration only)
  BunnyHop:
    enabled: true
    max-vl: 15
    tolerance: 1.20         # ground speed may exceed predicted by this factor (skips friction)
    slack: 0.04
    buffer: 4
    debug: false            # log peak actual/predicted ratio to /nimbus verbose (calibration only)
  Nuker:
    enabled: true
    max-vl: 12
    max-bps: 12            # blocks broken per second
    max-angle: 80          # flag breaking blocks outside this view angle
  BlockReach:
    enabled: true
    max-vl: 12
    max-reach: 6.0         # blocks; survival is ~4.5
  Scaffold:
    enabled: true
    max-vl: 15
    max-angle: 75          # flag placing blocks outside this view angle
  FastPlace:
    enabled: true
    max-vl: 15
    max-pps: 10            # blocks placed per second
  AirPlace:
    enabled: true
    max-vl: 15
  PlaceReach:
    enabled: true
    max-vl: 12
    max-reach: 6.0
  GhostPlace:
    enabled: true
    max-vl: 12
  Tower:
    enabled: true
    max-vl: 12
    max-gap-ms: 180         # min ms between under-foot placements (FP-sensitive; raise to loosen)
    min-streak: 5           # consecutive fast under-foot placements before flagging
  ThroughWallBreak:
    enabled: true
    max-vl: 12
  # --- packet checks (powered by PacketEvents) ---
  Timer:
    enabled: true
    max-vl: 15
    # Timer speeds up movement just like Speed/BunnyHop -- same punishment tier fits:
    # punish-commands:
    #   - "litebans:tempban %player% 7d -s &cNimbus &7| Unfair Advantage &8(&7%check%&8)"
    balance-limit-ms: 180   # higher = more lenient (was 150; raised to cut lag-driven falses)
    min-tps: 19.5           # Timer only runs when TPS is near-perfect; below this it stands down
    max-bank-per-packet: 25 # cap on credit a single fast packet can bank (stops post-lag bursts spiking it)
  GroundSpoof:
    enabled: false          # DISABLED until tuned: client claims on-ground while server sees air (NoFall spoof)
    max-vl: 15
    buffer: 8               # sustained client/server ground disagreements before a flag
  BadPackets:
    enabled: true
    max-vl: 5
  # --- action checks ---
  FastBow:
    enabled: true
    max-vl: 12
    min-force: 0.85         # near-full draw
    min-draw-ms: 850        # min time to reach that draw
  FastEat:
    enabled: true
    max-vl: 12
    min-use-ms: 1200        # vanilla eat/drink is ~1600ms
  AutoTotem:
    enabled: true
    max-vl: 12
    max-reequip-ticks: 2    # flag if the off-hand totem returns within this many ticks
  AutoArmor:
    enabled: true
    max-vl: 15
    window-ms: 300          # equipping this many pieces within this window flags
    min-pieces: 3
  ChestStealer:
    enabled: true
    max-vl: 15
    window-ms: 1000
    max-clicks: 12          # container clicks per second before flagging
  AutoPotion:
    enabled: true
    max-vl: 12
    min-gap-ms: 150         # min ms between splash-potion throws (FP-sensitive)
  AutoFish:
    enabled: true
    max-vl: 12
    min-reaction-ms: 90     # reeling faster than this after a bite is non-human
  # Spawns invisible Citizens NPCs that orbit players in combat. KillAura / aim-assist
  # attacks it repeatedly; a legit player can't land hits-to-flag attacks on its short,
  # fast orbit (a stray click is ignored). Requires the Citizens plugin.
  KillAuraNPC:
    enabled: true
    max-vl: 12
    # Bait styles -- enable either or both; every spawn randomly picks one of the enabled
    # styles. Mixing them is harder to evade: many auras deliberately skip invisible entities.
    visible-baits: true     # fast-orbiting bait players can see (needs hits-to-flag attacks)
    invisible-baits: false  # classic hidden bait (can't be seen, so the lower bar below applies)
    hits-to-flag: 4         # attacks on one VISIBLE bait before it flags (stray clicks stay safe)
    invisible-hits-to-flag: 2  # attacks on an INVISIBLE bait before it flags
    vl-per-hit: 8           # vl added when the hit threshold is reached
    interval-ticks: 300     # how often a bait may spawn for an active fighter
    lifetime-ticks: 40      # ticks a bait orbits before despawning (40 = 2 seconds)
    orbit-speed: 0.9        # radians per tick (0.9 = a full circle every ~0.35s -- very fast)
    radius: 2.0
  # Raised when a player's reported client brand matches brand-checker.blocked-brands.
  ClientBrand:
    enabled: true
    max-vl: 20
    vl-per-hit: 10
# ---------------------------------------------------------------------------
# Client brand checker
# Reads the brand each client reports on join and logs it. If a brand contains
# any entry in blocked-brands (case-insensitive), the ClientBrand check flags it.
#
# IMPORTANT: injected clients like Vape report "vanilla" and CANNOT be caught
# this way. This is for visibility and catching un-spoofed clients only -- the
# NPC bait and behavioural checks are what actually catch good cheat clients.
# ---------------------------------------------------------------------------
brand-checker:
  enabled: true
  log-brands: true          # log each player's client brand to console
  blocked-brands: []        # e.g. ["wurst", "aristois"] -- add brands you want flagged
  log-channels: false       # log every plugin channel a client registers (noisy)
  blocked-channels: []      # e.g. ["wurst"] -- flag clients that register these channels