BeansAC

A server-side anticheat for Minecraft. Drop in, configure via TOML, and it works pretty good.

---

Philosophy

Most anticheats fail on modded servers because they hardcode Vanilla assumptions. BeansAC takes a different approach:

• Registry-scanning at startup, scans all Forge registries for modded blocks, items, enchants, and effects. Adapts detection thresholds dynamically rather than maintaining compatibility lists.
• Physics simulation runs a per-player movement simulation accounting for active effects, enchants, and environmental conditions. Flags deviations from expected behavior, not the average hardcoded speed caps. (this took hours for me to make.)
• Transaction-based latency tracks per-player RTT at the connection level. Uses this to adjust reach, velocity, and timing checks, preventing false positives on high-ping players.
• Server-lag resilience all checks skip when server tick time exceeds 100ms or individual player latency spikes.

---

27 Active Checks

Package	Checks
Movement	Speed, Flight, Phase (200-tick grace), NoFall, Timer (1.5s window, 2.5x ratio), Velocity, Jesus, Elytra, Vehicle
Combat	Reach, AutoClicker, AttackCooldown, AutoBlock (use-item→attack within 50ms), HitBox (entity bounding box ≥4.5)
Inventory	Dupe, Container (slot bounds + DataValidator NBT validation), CreativeMatch (creative-spawned item validation)
Protocol	BadPackets (NaN/Infinite/pitch bounds), PingSpoof (200-tick grace, lag-adaptive), PacketOrder (attack/swing order + dig state machine), PayloadRate (10/sec custom payloads)
World	Scaffold, FastBreak (per-block tracking, ABORT/START sequences), FastPlace (30ms interval), Nuker (ray-trace LoS + pattern detection)

Every check is configurable per-check: enabled, maxVl, and punishment (kick/ban/alert).

---

Mod-Aware Architecture

BeansAC does not hardcode compatibility. At startup:

1. RegistryScanner iterates all Forge registries (items, blocks, enchantments, mob effects, entities). Caches hashes for subsequent boots.
2. MovementSimulation computes per-player max speed by scanning their active effects and worn enchants at runtime so modded effects automatically expand the envelope.
3. PossibilityMap flags unknown enchants/effects and applies permissive multipliers rather than false-flagging.
4. SandboxManager (optional) spins up headless Forge JVMs when uncertain behavior is detected, testing packets against actual mod code.

---

Data Validation

The DataValidator singleton validates all item NBT entering the server through any path:

• Container clicks (ServerboundContainerClickPacket)
• Creative inventory (ServerboundSetCreativeModeSlotPacket)
• Book editing (ServerboundEditBookPacket — page count, page length, control chars)
• Anvil renaming (ServerboundRenameItemPacket — name length)
• Enchantment registration and level sanity
• NBT depth limits (prevents recursive tag bombs)
• Firework effect count, skull texture size

---

False-Positive Resistance

BeansAC prioritizes false-negative over false-positive. Key mitigations:

• Thread safety — PacketInterceptor.onInboundPacket() and onOutboundPacket() guard with server.isSameThread(). Prevents state corruption from Netty IO threads.
• Server-lag skip — CheckManager.runAll() returns early when server.getAverageTickTime() > 100ms or per-player latency spikes.
• Grace periods — PhaseCheck waits 200 ticks after spawn/teleport. PingSpoofCheck waits 200 ticks. AutoClickerCheck requires 12+ samples.
• RTT compensation — Reach, AttackCooldown, and Velocity checks account for per-player smoothed RTT.
• VL decay — Violation levels decay by 1 every server tick, preventing accumulated false-flag punishments.
• Modded item tolerance — ElytraCheck accepts any non-vanilla item in the chest slot as a potential elytra, not just minecraft:elytra.
• Collision-based block detection — PhaseCheck uses getCollisionShape().isEmpty() instead of a hardcoded whitelist, adapting to any non-solid block from any mod.

---

Performance

• O(1) state history via circular buffer (no array copies)
• Per-player CompensatedWorld using AtomicReferenceArray backends
• CheckManager uses efficient class-based dispatch
• Lightweight per-tick state sync

---

Configuration

TOML-based (config/beansac.toml). Three-phase load: define all values via ForgeConfigSpec.Builder, load file via CommentedFileConfig, then construct immutable config objects. Anti-Xray, sandbox, latency, and webhook sections available.

---

Cancellation Wiring

All checks that call requestCancel() are wired to the mixin layer and actually cancel the packet:

• ReachCheck cancels handleInteract, handleUseItemOn, handlePlayerAction via ReachCheck.validate() return value
• NukerCheck cancels handlePlayerAction via consumeCancel()
• FastBreakCheck cancels handlePlayerAction via consumeCancel()
• ScaffoldCheck cancels handleUseItemOn via consumeCancel()
• FastPlaceCheck cancels handleUseItemOn via consumeCancel()
• AutoBlockCheck cancels handleInteract via consumeCancel()
• HitBoxCheck cancels handleInteract via consumeCancel()
• ContainerCheck cancels handleContainerClick via consumeCancel()
• CreativeMatchCheck cancels handleSetCreativeModeSlot via consumeCancel()
• PacketOrderCheck cancels handlePlayerAction via consumeCancel()
• PayloadRateCheck cancels handleCustomPayload via consumeCancel()

All cancellation paths trigger a resyncBlock() to prevent ghost-block desyncs.

---

Client Brand Detection

Parses the minecraft:brand payload string and detects known clients (forge, fabric, lunar, badlion, wurst, FastMath, cheat keywords). Shown per-player via /beansac debug.

---

Dependencies:

• Minecraft Forge, Java 17
• Top4eat21's topeatLib

---

Commands

Command	Description
/beansac alerts	Toggle live alerts
/beansac vl <player>	Show violation levels
/beansac checks	List all checks with status
/beansac debug <player>	Show client brand + detected features

---

License

12Tae12 Protective License, see here.