BeansAC

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.