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.

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

[Server Tick]
  ├─ PreTick
  │   ├─ shouldSchedulePlayer?(interval + tuner + backpressure)
  │   ├─ Snapshot(Player)
  │   ├─ CollectEntitySnapshots (AABB around player)
  │   └─ Submit Task → Executor
  │        └─ [Off-thread]
  │            ├─ 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

  [AsyncTracker Executor (N threads)]
      ↑ tasks from all dimensions

Option B: Per-Dimension Pools

  [Overworld Executor (M)]   [Nether Executor (M)]   [End Executor (M)]
       ↑ OW tasks                  ↑ Nether tasks          ↑ End tasks

Backpressure: bounded queues + CallerRunsPolicy; scheduling slows when queues grow.

Auto‑Tuner: Control Loop

tickNanos → EMA → window(avg)
            │
            ▼
      Controller (PID or Simple)
            │
     ┌───────┴─────────────────────────────┐
     │                                     │
pathfinding.minRecalcInterval += step   trackerIntervalAddend = clamp(-step)
     │                                     │
cooldown ticks prevent rapid toggling      additive scheduling shift for tracker

DAB Bucketing and Hysteresis

distance (blocks) → 0 ── d0 ── d1 ── d2 ──▶
bucket             NEAR    MID    FAR  DISTANT
multiplier         x1      x2     x4   x8   (defaults; configurable)

hysteresisBlocks (±h) creates a deadband around d0/d1/d2 to reduce bucket flipping.

Regional TPS: Decision Pipeline

[Server Tick]
  ├─ PreTick
  │   ├─ Global TPS sample ← steady after 5+ samples; clamped [0..20]; warm‑up (≥200 ticks) before emergency checks
  │   └─ Update player→region mapping
  ├─ PostTick (per region)
  │   ├─ Accumulate AI nanos, BE & scheduled ticks, redstone updates, memory, players
  │   ├─ Windowed averages (regionalTPS.windowTicks)
  │   ├─ Decide target level using thresholds + hysteresis
  │   ├─ Smoothly adjust region multiplier toward target (±1 per tick)
  │   └─ Apply gating hooks (e.g., chunk random/scheduled ticks)
  └─ Global
      ├─ Emergency trigger if: warm‑up passed ∧ samples≥20 ∧ TPS<15 with cooldown
      └─ Periodic logging & eviction of stale regions

Heatmap: Client Flow & Interactions

/wmb heatmap [radius] → server builds window around player
                        ↓
                 send Heatmap to client
                        ↓
                HeatmapScreen (press H to reopen last)
                        ↓
   Interactions:
   - Mouse wheel: zoom
   - Right‑drag: pan
   - Left‑click on header: toggle Mode (AI ms, Mem MB, Players, Priority)
   - Click LOD: toggle merged vs per‑region view
   - Hover: tooltips (merged + region details)
   - Sidebar: detailed panel (emergency, target multiplier, good/bad streaks, etc.)
   - Global TPS shown in header

Installation

Minecraft: 1.20.1
Loaders: Fabric or Forge (Architectury)
Drop the mod jar into your mods/ folder.
Start the game once to generate the wmb.toml config with inline comments.

Config location by loader:

Fabric: .minecraft/config/wmb.toml
Forge: <instance>/config/wmb.toml

Commands

/wmb regions here
- Prints the current region’s coordinates, level, and summary.
/wmb regions top [n]
- Lists the top N heaviest regions by average AI ms.
/wmb heatmap [radius]
- Generates a heatmap around your position (default radius 8 regions) and sends it to your client.
/wmb reload
- Reloads wmb.toml from disk and applies runtime values.
/wmb metrics on|off
- Toggle internal metrics collection used by stats commands.
/wmb tuning on|off
- Enable/disable the AutoTuner at runtime.
/wmb preset <vanilla|balanced|aggressive>
- Apply a runtime preset of conservative to stronger optimizations. Use /wmb reload to revert to file values.
/wmb stats
- Shows DAB thresholds & multipliers, proximity snapshot interval, async spawn/tracker thread settings, pathfinding and tuner parameters, and metrics (if enabled).
/wmb trackerstats
- Prints tracker status and queue/task metrics.
/wmb debug entity
- Inspect the nearest mob’s effective DAB interval near the player.
/wmb debug chunk
- Summarize average DAB interval for mobs in your current chunk.

Keybinds

Heatmap: H (default)
- Opens the last received heatmap on the client. If you haven’t requested one yet, use /wmb heatmap first.
/wmb profile start|stop
- Lightweight profiler for AI step timing; prints a summary when stopped.
/wmb stresstest start <entity> [count] [radius] [duration] [pathEvery] [waypoints]
- Spawns a controlled scenario for stress testing. Use status, report, and stop to manage.

Configuration Reference

All options are documented inline in the generated wmb.toml. Below is a structured overview.

Distance-based AI Bucketing (DAB)

dab.enabled (bool)
- Turn distance-aware AI throttling on/off globally.
dab.d0, dab.d1, dab.d2 (double, blocks)
- Distance thresholds separating near/mid/far/distant buckets.
dab.multipliers.near|mid|far|distant (int)
- AI tick interval per bucket. 1 means every tick (no throttle), higher means less frequent AI updates.
dab.hysteresisBlocks (double, blocks)
- Deadband around the thresholds to avoid rapid bucket flipping near the boundary.
dab.perEntity["namespace:id"]
- Per-entity overrides and exemptions.
- Keys: exempt (bool), highPriority (bool), near, mid, far, distant (ints).
- If exempt or highPriority is true, DAB is disabled for that entity type.
dab.perDimension["namespace:dimension"]
- Per-dimension overrides for d0/d1/d2 and nested multipliers.near|mid|far|distant.

Notes:

Some high-importance entities (e.g., bosses) can be exempted from DAB by default in code or via per-entity overrides.
Leashed, named, owned/tamed, and persistent entities are not throttled.

Proximity

proximity.updateIntervalTicks (int)
- How often player positions are snapshotted. Larger = less CPU, slower DAB responsiveness. Typical: 3–10.

Pathfinding

pathfinding.enabled (bool)
- Enable optimizations around path recalculations and caching.
pathfinding.minRecalcInterval (int, ticks)
- Minimum ticks between recalculations per mob. This is the actuator adjusted by the tuner.
pathfinding.groupWindowTicks (int, ticks)
- Group/stagger recalcs within a small window to spread CPU spikes.
pathfinding.cacheTtlTicks (int, ticks)
- Keep solved paths for this long before expiring.
pathfinding.experimentalShareEnabled (bool)
- Experimental: allow similar mobs to share path results.
pathfinding.shareTtlTicks (int, ticks)
- TTL for shared path entries if sharing is enabled.

Auto Tuning

tuning.enabled (bool)
- Enable closed-loop tuning of pathfinding.minRecalcInterval towards a target tick duration.
tuning.targetTickMs (double, ms)
- Desired average tick duration (50.0 ms = 20 TPS).
tuning.windowTicks (int)
- Number of ticks per averaging window.
tuning.cooldownTicks (int)
- Minimum ticks between successive adjustments.
tuning.minRecalcMin / tuning.minRecalcMax (int)
- Clamp the actuator (min recalc interval) within this range.
tuning.kp, tuning.ki, tuning.kd (double)
- PID gains. If all are zero, the tuner falls back to a simple, step-based controller.
tuning.maxStepPerWindow (int)
- Maximum absolute change to the actuator per window.
tuning.integralMaxAbs (double)
- Absolute clamp for integral term to avoid windup.

Checks

checks.suffocationInterval (int, ticks)
- Tuning of vanilla suffocation checks. Higher = less CPU, slightly slower detection.

Async Spawn

asyncSpawn.enabled (bool)
- Enable off-thread spawn preparation work.
asyncSpawn.threadPoolSize (int)
- Worker threads to use for async spawn tasks. Recommended: 1–4.

Async Entity Tracker

asyncTracker.enabled (bool)
- Enable asynchronous per-player entity tracking.
asyncTracker.threadPoolSize (int)
- Worker threads for the global tracker executor when perDimensionPools = false.
asyncTracker.updateInterval (int, ticks)
- Minimum ticks between recalculations per player before cache reuse.
asyncTracker.cacheDuration (int, ticks)
- How long to reuse the last visibility result before forcing a recalculation.
asyncTracker.perDimensionPools (bool)
- If true, use one executor per dimension to isolate load.
asyncTracker.threadPoolSizePerDim (int)
- Core threads for each per-dimension executor when perDimensionPools = true.
asyncTracker.maxTrackingDistance (double, blocks)
- Maximum 2D horizontal distance from the player for an entity to be considered tracked.

Culling (Optional)

culling.enabled (bool)
- Conservative AI skipping for far, idle mobs with multiple safety gates.
culling.minDistance (double, blocks)
- Only consider mobs at least this far from the nearest player.
culling.requireNoTarget / requireNoPath / requireLowMotion (bool)
- Safety gates to ensure we skip AI only for idle, unengaged mobs.
culling.lowMotionSpeed (double, blocks/tick)
- Threshold used by requireLowMotion.
culling.allowEveryNTicks (int, ticks)
- Even when eligible, allow full AI every N ticks to avoid starvation.
culling.exemptNamed|Leashed|Owned|Persistent (bool)
- Protective exemptions to never skip important mobs.

Visibility (Optional)

visibility.enabled (bool)
- Apply similar skipping rules to mobs far outside any player’s chunk range.
visibility.playerChunkRange (int, chunks)
- Chebyshev chunk distance around players considered "active". Outside this range, mobs may be skipped subject to gates.
visibility.requireNoTarget / requireNoPath / requireLowMotion (bool)
- Same safety gates as culling.
visibility.lowMotionSpeed (double, blocks/tick)
- Threshold used by requireLowMotion.
visibility.allowEveryNTicks (int, ticks)
- Even when eligible, allow full AI every N ticks to avoid starvation.
visibility.exemptNamed|Leashed|Owned|Persistent (bool)
- Protective exemptions to never skip important mobs.

Regional TPS

regionalTPS.enabled (bool)
- Master switch for the chunk‑based TPS system.
regionalTPS.regionSize (int, chunks)
- Side length of a square region in chunks. Default: 4.
regionalTPS.windowTicks (int, ticks)
- Averaging window for per‑region metrics and decisions.
regionalTPS.thresholds.maxTickMs (double, ms)
- Soft ceiling for average AI time in a region before increasing level.
regionalTPS.thresholds.maxEntities (int)
- Heuristic cap for entity counts within the region window.
regionalTPS.thresholds.maxBlockEntities (int)
- Heuristic cap for block entities within the region window.
regionalTPS.hysteresisPct (double, 0.0–0.45)
- Percentage deadband applied around thresholds to prevent rapid level flip‑flopping. Default: 0.15 (15%).
regionalTPS.scaling.levels.<name> (int)
- Map of named levels to tick multipliers, e.g., normal=1, warning=2, critical=4.
regionalTPS.staticRegions["dim:rx,rz"] = "levelName"
- Pin specific regions (by dimension and region coords) to a chosen level.

Config Versioning and Auto‑Merge

The config file includes configVersion. As of v1.2‑SNAPSHOT, the schema version is 5.
On load, WMB auto‑merges any missing keys with safe defaults and bumps configVersion forward.
Existing user values are preserved. Keys are not removed automatically.
The generated wmb.toml includes inline comments for every option.

Tuning Guide

Start with tuning.enabled = false. Observe baseline with /wmb stats.
Set a realistic tuning.targetTickMs for your hardware and modpack. 50.0 ms is 20 TPS; aim slightly below your typical average load.
Begin with a simple controller: kp > 0, ki = 0, kd = 0. Suggested: kp = 0.25.
If you see steady-state error, gently introduce ki (e.g., 0.01–0.05).
If you overshoot or oscillate, add kd (e.g., 0.05–0.2).
Keep maxStepPerWindow small (1–2) for smoothness. Clamp integral via integralMaxAbs.
Always bound the actuator with minRecalcMin/minRecalcMax.
Tracker integration: the tuner also adjusts tracker scheduling additively; leave asyncTracker.updateInterval moderate and let the tuner smooth load.

Compatibility

Designed to be conservative and safe around gameplay-critical AI.
Bosses, named, leashed, owned/tamed, and persistent mobs are protected by default.
Should be broadly compatible; experimental features (like path sharing) are opt-in.

FAQ

Does DAB change combat behavior near the player?
- No. The near bucket usually uses a multiplier of 1, keeping AI behavior responsive up close.
Does async tracking cause entity pop‑in or desync?
- No. Tracking sets are computed off‑thread but applied safely on the main thread each tick. Timeouts fall back gracefully.
What if my server has multiple heavy dimensions?
- Enable asyncTracker.perDimensionPools to isolate tracker load by dimension and size threadPoolSizePerDim accordingly.
Will auto-tuning fight my manual settings?
- The tuner only adjusts pathfinding.minRecalcInterval. Everything else remains exactly as configured.
What if I don’t want any culling?
- Both culling systems are disabled by default. They’re strictly opt-in and conservative.
Is this a magic TPS booster?
- No. It’s a set of intelligent trade-offs to save CPU in situations where it doesn’t affect gameplay feel.

Changelog

1.2 (2025-09-04)

New — Regional/Chunk-based TPS Manager (R‑TPS)
- Per‑region load tracking (avg AI ms, memory MB, players, redstone updates, BE/scheduled ticks, activity).
- Named scaling levels (e.g., normal=1, warning=2, critical=4) applied as tick multipliers per region.
- Hysteresis via regionalTPS.hysteresisPct (default 0.15) to stabilize level transitions.
- Static region overrides to pin hotspots to specific levels.
- Integrates with chunk random/scheduled tick gating; invisible near players.
New — Heatmap UI for Regional TPS
- Request with /wmb heatmap [radius]; reopen last heatmap with the H key.
- Mouse wheel zoom; right‑click drag to pan; live window requests while panning/zooming.
- Modes: AI ms, Mem MB, Players, Priority; LOD toggle (merged vs per‑region tiles).
- Tooltips and a detailed side panel (emergency state, target multiplier, consecutive good/bad ticks, histories).
- Global TPS display in the header.
Improvements — Global TPS measurement and safety
- Lazy‑init tick timing; compute TPS only after 5+ samples; clamp to [0..20].
- Gate emergency triggers until warm‑up (≥200 ticks) and require ≥20 samples; add cooldown to avoid log spam.
Improvements — Regional decisions and sampling
- Applied hysteresis to regional scaling decisions; introduced levelIndex to track transitions.
- Normalized Y sampling for region gating to level.getMinBuildHeight() + 1.
Networking & Client
- Updated heatmap/detail serialization to include memory, player counts, priority, global TPS, target multiplier, and histories.
- Client can refresh the existing screen (setHeatmap) without reopening; remembers last heatmap for the H key.
Fixes
- Heatmap tooltip compile error fixed by initializing local variables.
- Eliminated false global TPS emergencies at startup or sporadic spikes; reduced warning spam.
Config
- Config schema bumped to 5; added regionalTPS.* keys including hysteresisPct.
- Defaults and inline comments updated in wmb.toml.
Migration Notes
- Existing configs auto‑merge new keys and bump configVersion safely. Review regionalTPS.thresholds and regionalTPS.scaling.levels for your pack.

License

See LICENSE.txt in the repository.

Where's my Brain (WMB)