CaveFlow

A client-side Fabric mod. Every air block underground has a direction the air wants to go. CaveFlow computes that direction via a BFS flood-fill from sky openings and renders dust particles that drift along the result.

What it does

• Airflow simulation — BFS seeds from every sky-exposed opening, propagates flow vectors through the cave network, runs on background threads so it doesn't spike frame time.
• Dust particles — spawn from underground air cells and travel along the computed vectors. Biome-aware: standard caves, lush caves, and sculk/deep dark each get a distinct particle variant.
• Explored vs. unexplored density — cells you've been near get a lower density multiplier. Returning to a known cave feels quieter; virgin caves feel more alive.
• Settled dust — in dead-end pockets where airflow stalls, particles slow down and sit low.
• Depth and Y-level scaling — flow builds up deeper underground.
• Disk cache — computed flow is saved per world/server and reloaded on reconnect so it doesn't recompute every session.
• Debug overlay — /caveflow debug or the config toggle renders 3D flow arrows in-world.

How to use

Just load a world. No commands needed — flow computation starts when chunks load and particles appear automatically underground.

• /caveflow debug — toggle the 3D flow arrow overlay.
• ModMenu → CaveFlow → ⚙ for the config screen.

Configuration

Four tabs in the config screen:

• General — master toggle.
• Airflow — particle density, flow speed, detection range, explored/unexplored multipliers, depth and Y-level scaling.
• Effects — visual variants. Some options here aren't implemented yet (heat shimmer, cold-air particles, drafts, tunnel currents) — they're in the menu but don't do anything.
• Advanced — background threads, BFS budget per tick, queue size, min/max cave depth, FPS throttle and pause thresholds, disk cache path, eviction interval, fast-move threshold, debug overlay radius and stride.

Requirements

Minecraft	Loader	Fabric API	YACL
1.21.11	Fabric 0.19.2+	any 1.21.x build	3.8.2+

Optional: ModMenu — adds the config-screen button.

Client-side only. Does not need to be on the server.

Notes

• Performance defaults are tuned for a mid-range CPU (~0.5 ms/tick BFS). Drop BFS Budget and Background Threads in the config if needed.
• The fast-move threshold pauses distant BFS work above a set speed — useful with elytra so computation isn't wasted on terrain flying past.
• Automatic FPS protection — BFS work throttles automatically when frame rate drops. Below the throttle threshold (default 60 FPS) the budget scales down linearly; below the pause threshold (default 30 FPS) the BFS pauses entirely and a chat message is shown. Both thresholds are configurable. When the game window loses focus BFS pauses silently — no message is sent.