Where's my Brain (WMB)

# WHERE'S MY BRAIN (WMB) A lightweight, loader-agnostic Minecraft 1.20.1 optimization mod focused on smarter mob AI scheduling, distance-aware throttling, and adaptive auto-tuning. Keep gameplay feel near players while cutting wasted CPU on far-away or idle mobs. Works on both Forge and Fabric via Architectury. (https://img.shields.io/badge/Join-Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/QM5beZpkYT) --- ## Features - Async Entity Tracking - Off-thread per-player entity visibility/tracking decisions to reduce main thread work. - Global or per-dimension thread pools with adaptive backpressure (queue-aware scheduling). - Respects `asyncTracker.updateInterval`, `cacheDuration`, and `maxTrackingDistance`. - Integrates with AutoTuner to adjust scheduling under load. - Timeouts and graceful fallbacks keep the main thread safe. - Regional/Chunk-based TPS Manager (R‑TPS) - Divides each dimension into square regions (default: `regionalTPS.regionSize = 4` chunks per side) and continuously measures load per region. - Tracks per-region metrics: average AI time (ms), average memory (MB), player presence, redstone updates, BE/scheduled tick counts, and activity recency. - Applies scalable tick multipliers per region using named levels (e.g., `normal=1`, `warning=2`, `critical=4`). - Hysteresis (`regionalTPS.hysteresisPct`, default 0.15) prevents flip‑flops when load hovers near thresholds. - Static overrides let you pin specific regions to a level. - Safety: global TPS is computed over a sliding window and emergency triggers are gated by warm‑up and cooldown to avoid false alarms. - Gating integrates with chunk random/scheduled ticks to cut work in stressed regions while remaining invisible near players. - Distance-based AI Bucketing (DAB) - Dynamically throttles AI ticks based on each mob’s nearest-player distance. - Per-dimension and per-entity overrides. - Hysteresis deadband to prevent thrashing near thresholds. - Sensible exemptions (leashed, named, owned/tamed, persistent, and configurable boss exemptions). - Proximity Snapshot Service - Centralizes nearest-player computations to a periodic snapshot, reducing redundant work. - Mob-side cache reduced to 2 ticks for responsive DAB updates with minimal overhead. - Pathfinding Optimizations - Minimum per-mob path recalculation interval and grouping window. - Optional experimental path sharing. - Caching with TTL to avoid repeated path solves. - Auto-Tuning (PID) - Targets a desired average tick time (ms) and gently adjusts pathfinding recalc interval. - PID controller (kp/ki/kd) with integral clamping and step-limits for smooth convergence. - Transparently falls back to a simple step controller if PID gains are zero. - Optional AI Culling (Conservative) - Skip AI processing for far, idle, and unengaged mobs behind multiple safety gates. - Optional Visibility Culling (Conservative) - Skip AI for mobs far outside any player’s chunk range, with the same safety gates. - Metrics and Command - Lightweight internal counters for `/wmb stats`. - See DAB thresholds, proximity settings, pathfinding parameters, and tuner state. --- ## How It Works - DAB continuously places each mob into a distance bucket (near/mid/far/distant) relative to the nearest player and assigns a tick interval multiplier per bucket. - Async Entity Tracking computes per-player tracked entity sets off-thread and applies updates post-tick; intervals adapt via tuner and backpressure. - The proximity service snapshots player positions every N ticks (configurable) to amortize distance queries. - Pathfinding and AI recalculations are rate-limited with per-mob minimum intervals and optional grouping. - The Auto Tuner reads average tick time over a window and adjusts `pathfinding.minRecalcInterval` to steer the server towards `tuning.targetTickMs`. - Culling and visibility features add optional, conservative gates to skip AI when it’s safe to do so. --- ## Diagrams ### Async Entity Tracking: Flow ``` ├─ PreTick │ ├─ shouldSchedulePlayer?(interval + tuner + backpressure) │ ├─ Snapshot(Player) │ ├─ CollectEntitySnapshots (AABB around player) │ └─ Submit Task → Executor │ └─ │ ├─ Filter by distance ≤ maxTrackingDistance (2D) │ ├─ Diff with current tracked set → {toAdd, toRemove} │ └─ Enqueue TrackingResult └─ PostTick ├─ Drain completed results (batched) ├─ Apply adds/removes to tracking sets ├─ Update metrics (durations, queue size, counts) └─ Periodic maintenance (cleanup/disconnects) ``` ### Threading Model: Global vs Per-Dimension Pools ``` Option A: Global Pool ↑ tasks from all dimensions Option B: Per-Dimension Pools ↑ OW tasks