Potassium

Potassium is a lightweight Fabric optimisation mod focused on improving Minecraft's client-side rendering, UI responsiveness, shader compatibility, and frame pacing without replacing the renderer or changing gameplay.

Instead of rewriting large systems, Potassium targets small but frequent rendering costs: HUD updates, text layout, map rendering, particles, entity animation, shader/cache safety, and platform-aware rendering paths.

It is designed to work alongside popular optimisation mods such as Sodium, Lithium, FerriteCore, Entity Culling, C2ME, ModernFix, and Iris.

Features

HUD Render State Throttle

Reduces redundant HUD processing when player state has not changed.

• Health, hunger, display health, status effects, and tick state are checked before rebuilding HUD render state.
• Prevents unnecessary UI recalculation while preserving vanilla gameplay feedback.
• Includes safeguards to avoid GUI flashing or stale UI state.

Entity Animation LOD

Adds distance-based cosmetic animation reduction for living entities.

• Distant mobs reduce walk-animation updates beyond normal viewing range.
• Movement, AI, hitboxes, combat, damage, and server behaviour are unaffected.
• Only cosmetic animation work is reduced.

Particle Optimisations

Improves particle-heavy scenes while protecting gameplay-critical feedback.

• Particle update throttling is conservative and density-aware.
• Critical particles such as block breaking, redstone, portal, potion/status, vibration, sculk, and interaction feedback stay protected.
• Helps stabilize frame pacing during explosions, campfires, effects, and busy scenes.

Text And Layout Caching

Caches repeated UI text measurements and layout work.

• Reduces repeated font width calculations.
• Helps menus, chat, scoreboards, overlays, and Mod Menu screens feel smoother.
• Cache sizes are bounded to avoid long-session memory growth.

Map Rendering Safety And Throttling

Optimises map render-state updates while preserving correctness.

• Reduces redundant map texture/state refreshes.
• Keeps item-frame maps safe by avoiding throttling before map textures are initialized.
• Fixes crashes related to filled maps in item frames.

Shader Compatibility Fixes

Improves compatibility with Iris shader packs and large render modpacks.

• Fixed rare cases where players, mobs, item frames, held items, or maps could render black.
• Disabled unsafe entity packed-light caching to preserve vanilla and Iris lighting correctness.
• Adds Iris safety gates so Potassium avoids interfering with shader framebuffer, sampler, and program state.
• Tested against shader-heavy scenarios including Complementary and Solas-style setups.

Dedicated Potassium Shader Cache Folder

Adds a dedicated Potassium cache location:

• Stores bounded shader environment metadata for safer future shader warm-up and cache validation.
• Keeps Potassium cache data separate from Iris' own shader cache.
• Includes automatic pruning so cache data does not grow indefinitely.
• Does not currently claim full GPU program-binary reuse; this is safe groundwork for future shader-cache improvements.

Super Resolution UI

Adds in-game super-resolution configuration through Mod Menu.

• Provides selectable upscaling modes and status information.
• Shows whether each backend is available, fallback-only, or unavailable.
• Includes descriptions for Potassium Spatial, FSR-style paths, SGSR-style paths, DLSS, and XeSS.
• Frame generation defaults to disabled for safety.

Important: full native DLSS, XeSS, and FSR3 frame generation are not fully delivered yet. Unsupported native paths remain fallback-safe instead of crashing or pretending to work.

Platform-Aware Rendering Support

Potassium includes platform-aware checks for safer optimisation decisions.

• Apple Silicon safeguards disable fragile framebuffer upscaling paths that can affect water, transparency, or first-person item depth.
• OpenGL/Vulkan backend detection groundwork is included for newer Minecraft versions.
• Experimental 26.2-pre-2 support is conservative while Minecraft's Vulkan path settles.

Performance Philosophy

Potassium focuses on micro-optimisations that add up:

• Reduce redundant UI processing.
• Lower repeated text/layout work.
• Keep particle-heavy scenes smoother.
• Avoid unsafe render shortcuts that break visuals.
• Prefer compatibility and vanilla correctness over risky FPS gains.

The goal is smoother frame pacing and lower CPU/GPU overhead without changing world generation, AI, combat, redstone, or server logic.

Compatibility

Potassium is designed to work alongside major Fabric optimisation and rendering mods.

Requirements

Minecraft 1.21.11

• Fabric Loader 0.18.4+
• Fabric API compatible with Minecraft 1.21.11
• Java 21+

Minecraft 26.1-26.1.2

• Fabric Loader 0.18.4+
• Fabric API compatible with Minecraft 26.1.x
• Java 25+

Minecraft 26.2-pre-4 Experimental

• Fabric Loader 0.19.2+
• Fabric API 0.150.1+26.2
• Java 25+

EXPECT BUGS

Reporting Issues

Please use the issue tracker linked at the top of the page to report bugs, crashes, and other issues. Include a description of the issue, Minecraft version, mod version, log files, and any other information if possible.