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:

.minecraft/potassium/shader-cache

• 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.