Potassium

Potassium

A conservative, client-side performance mod for Minecraft that trims optional rendering work and gives you honest, real frame-time diagnostics — without touching your video settings, your world, or your shaders.

Potassium does not promise a magic FPS number. It reduces work the game doesn't strictly need (hidden entities, distant/overflowing particles, redundant occlusion checks) and reports what actually happened, so you can measure the difference yourself.

Requirements

• Minecraft 26.3
• Fabric Loader 0.19.3 or newer
• Java 25 or newer
• Client-side only (does nothing on a dedicated server)

The two Fabric API modules it uses (fabric-command-api-v2 and fabric-api-base) are bundled inside the jar, so you do not need the full Fabric API — Fabric Loader is enough. Sodium is optional; if present, Potassium's options appear in Sodium's config screen.

What it does

Conservative entity & block-entity culling

Skips rendering entities that are occluded by terrain, using bounded raycasts and cached visibility results. It is deliberately cautious:

• Only a limited set of vanilla mob types are occlusion-culled; other entities are left alone.
• Chest block entities (chests, trapped chests, ender chests) are culled; other block entities are untouched.
• Caches are bounded LRU maps and are invalidated when the camera, models, or terrain change.
• When in doubt it under-culls rather than risk hiding something you can see. Finite sampling can't prove every tiny gap is blocked, so it errs toward showing entities.

If Iris or EntityCulling is installed, Potassium's occlusion culling disables itself to avoid conflicting with them.

Optional particle budgets & distance culling

• A soft particle cap (a budget, not a hard wall) to keep particle-heavy scenes from overwhelming the frame.
• Optional distance-based particle culling.
• Both are configurable and can be turned off.

Hardware-informed profiles

On first run Potassium detects your GPU and system and suggests a starting profile. This is a heuristic, not a measured FPS guarantee. Five profiles are available:

• Compatibility — culling off, minimal changes
• Balanced
• Performance
• Maximum Performance
• Custom — your own settings

You can accept the suggestion, pick a profile yourself, or go fully custom. Automatic profile selection can be disabled.

Optional adaptive workload management (off by default)

When enabled, Potassium watches your frame times and gently adjusts optional work — the particle budget, the occlusion raycast budget, and the recheck interval — to help hold your target FPS. It never changes resolution, render distance, simulation distance, shaders, or world simulation. It only ever reduces optional effects, and it suspends itself in menus, while paused, or when the window is unfocused.

Unfocused-window throttle

Optionally caps the frame rate while the game window is in the background to save CPU/GPU and power.

FPS counter & diagnostics

• A simple, color-coded FPS counter (top-left), hidden with F1/F3.
• An optional detailed HUD (right-aligned) with frame timing and cache/particle stats.
• /potassium stats — prints a full diagnostic snapshot in chat.
• /potassium stats reset — zeroes the counters and frame history.

Diagnostics are real measurements, not estimates dressed up as facts:

• Rolling frame-time window with average FPS, worst frame, and spike count.
• True 1% and 0.1% low FPS (computed from the slowest frames; shown as n/a until enough frames are sampled).
• JVM process CPU usage, allocation rate, and garbage-collection counts/time.

Where a number can't be measured honestly, it says so: GPU utilization is reported as n/a, GC collector time is labeled as collector time (not pause time), and cache memory is labeled as a JVM-layout estimate.

What it will never do

• Change your resolution, render distance, or simulation distance
• Silently change shader settings
• Alter world simulation or gameplay
• Disable important rendering
• Call a quality reduction a "free" optimization

Configuration

Settings live in config/potassium.json and are also exposed through Sodium's options screen when Sodium is installed. Every feature can be toggled, and budgets/limits are clamped to safe ranges. A corrupt or unreadable config falls back to conservative Compatibility defaults rather than crashing.

Honest limitations

• Occlusion culling uses finite sampling, so it under-culls rather than risk popping visible entities.
• With Iris or EntityCulling present, Potassium's occlusion culling steps aside.
• GPU utilization is not measurable from the JVM and is shown as n/a.
• No benchmarked speedup is claimed yet. Controlled, repeatable benchmarks are still in progress; any performance gain depends on your hardware, world, and settings. Use /potassium stats to measure on your own machine.

License & author

MIT licensed. Author: Doveblond.