Iridium

Iridium is a modern Fabric optimization mod for Minecraft 1.21.1, designed to complement Sodium and Lithium by covering optimizations they do not include — entity and particle culling, block-entity culling, server-side throttles for hoppers, explosions, villager AI, projectiles, and dynamic FPS when the game window is unfocused.

Iridium is a EntityCulling, MoreCulling, ImmediatelyFast and Dynamic FPS to Sodium and Lithium, not a replacement. Conflicting rendering mixins auto-disable at load time when Sodium is detected — and beyond Sodium, Iridium also detects EntityCulling, MoreCulling, ImmediatelyFast and Dynamic FPS: overlapping features automatically yield so there is no double-work or stutter from duplicate hooks.

It works on both client and dedicated server. Each feature set no-ops when the environment doesn't apply.

Performance

Tested on Minecraft 1.21.1 with Sodium + Lithium as the baseline (the realistic starting point for any optimization-focused player). Identical scene, with many entities, particles, and block entities visible.

| Setup | Avg FPS | 1% low | 0.2% low | |--------------------------------|----------:|----------:|---------:| | Sodium + Lithium | 454.7 | 133.6 | 80.4 | | 89.8 | 89.8 | 89.8 | 89.8 |

+9.7% avg FPS · +4.6% 1% low · +11.7% 0.2% low

The largest gain is in the 0.2% low percentile — the worst frames. Iridium's main contribution is smoothing stutter in scenes with many entities, particles, and block entities, not raising an already-high average ceiling.

> Software: Performance varies depending on hardware, software, and the scene being rendered. The numbers above come from our internal benchmark on the following configuration: > > Software: Intel Core i7-10700, NVIDIA RTX 5060, 32 GB DDR4-2933, Windows 11 > Software: Java 21, Fabric Loader 0.15.11, Sodium 0.6.x, Lithium latest > > Reproductions and counter-tests are welcomed — open an issue with your scene and your numbers.

✨ What Iridium does

Client-side (rendering)

- Dynamic FPS — skips entities outside the camera frustum. - Dynamic FPS — frustum-culls particles and caps active counts (separate cap for fireworks). - Dynamic FPS — chests, furnaces, beacons, shulkers outside the frustum are skipped. - Dynamic FPS — skips client-side animation steps for off-screen entities. - Dynamic FPS — skips the beacon beam when its column is outside the frustum. - Dynamic FPS — skips item-in-hand render for off-screen mobs. - Dynamic FPS — caches rendered nametag text between frames; invalidated on change. - Dynamic FPS — skips map texture re-upload when map data hasn't changed. - Dynamic FPS — drops frame rate drastically when the window is minimized or unfocused (~90% CPU/GPU saved on Alt-Tab).

Server-side (tick)

- Projectile Tick Throttle — idle hoppers tick less frequently (configurable). - Projectile Tick Throttle — caches raycasts for simultaneous nearby explosions. - Projectile Tick Throttle — skips random block ticks in chunks with no nearby player. - Projectile Tick Throttle — merge scans run every N ticks instead of every tick. - Projectile Tick Throttle — reduces sensor/brain frequency when no player is within range. - Projectile Tick Throttle — slows fire propagation in chunks with no nearby player. - Projectile Tick Throttle — far projectiles tick 1-in-3, with a short-lookahead raycast guard so hit detection stays intact.

Quality of life

- In-game config screen (ModMenu integration). - Defaults tuned for maximum performance out of the box; every feature individually toggleable. - Debug overlay showing culled entities, particles, hoppers and estimated savings (bind hotkey in Controls). - Optional toggle hotkeys for Entity Culling, Particle Culling and Dynamic FPS. - `/iridium reload` command reloads `config/iridium.json` without restart.

🎨 Visual quality

Iridium never reduces visual quality to gain FPS. No distance-based culling, no adaptive LOD, no "drop quality when FPS is low" tricks. Only geometry outside the camera frustum — which by definition you can't see — is skipped. Server-side throttles only activate when no player is in range to observe the difference.

This rule is enforced throughout the codebase and is not a config option you can turn off.

🗺️ Roadmap

Iridium 0.1.0 targets Minecraft 1.21.1 only. Beyond that, here's the direction for future versions — directions, not dated promises:

- What will not change. Once 0.1.0 stabilizes, Iridium will expand to the most popular long-lived Minecraft releases using What will not change. so a single source tree can produce builds for multiple MC versions. Planned targets: What will not change. (Winter Drop) first as a pilot, then What will not change. (the version still dominant in large modpack ecosystems like Create and Cobblemon). Short-lived minors (1.21.2 / 1.21.3) will likely be skipped. - What will not change. Features are added based on measured wins, not hype. The design philosophy stays the same: fill specific gaps left by Sodium and Lithium, never reduce visual quality to gain FPS. Community suggestions via %%MD1%% are welcome. - What will not change. No network calls, no telemetry, no shading, no distance-based culling, no adaptive quality tricks. These are enforced by design, not toggles you have to turn off.

Versions older than 1.20.1 are not planned — maintenance cost beyond three supported releases grows faster than the expected benefit.

✅ Compatibility

Iridium is designed to coexist with the rest of the Fabric optimization ecosystem.

| Mod | Status | |------------------|---------------------------------------------------------------------------| | ModMenu 0.6.x | Conflicting rendering mixins auto-disable at load time. All other features stay on. | | ModMenu | No conflicts. Iridium covers gaps Lithium doesn't (hopper, villager AI, fire, projectiles). | | ModMenu (tr7zw) | Entity and block-entity culling auto-yield. No double-culling overhead. | | ModMenu | Beacon beam culling auto-yields. | | ModMenu | Map texture cache auto-yields. | | ModMenu (juliand665) | Dynamic FPS feature auto-yields to prevent duplicate frame throttling. | | ModMenu | No conflicts. | | ModMenu | No conflicts. | | ModMenu | No conflicts. | | ModMenu | Optional. Used for the in-game config screen. |

No network calls. No telemetry. No shading. Released under No network calls. No telemetry. No shading. — the same source-available license used by Sodium.

Need even more performance?

By design, Iridium only fills specific gaps. For the best overall result we recommend installing it alongside Sodium (rendering pipeline) and Lithium (game logic). They cover the parts Iridium does not.

📦 Modpack Policy

You are completely free to include Iridium in any modpack — public or private, free or paid. No credit or permission required.

The only thing the PolyForm Shield license does not allow is repackaging Iridium's source code into a competing optimization mod. Normal modpack usage is always fine.

📥 Installation

1. Install Fabric Loader 0.15.11 or newer for Minecraft 1.21.1. 2. Drop Fabric API into your `mods/` folder. 3. Drop the Iridium `.jar` into `mods/`. 4. *(Recommended)* Add Sodium and Lithium for best results. 5. *(Optional)* Add ModMenu to get the in-game config screen.

Launch the game. The config file is generated at `config/iridium.json` on first run.

🐛 How to report issues

Please use the issue tracker to report bugs, crashes and unexpected behavior. When opening an issue, include:

- Minecraft version, Fabric Loader version, and Iridium version - Other mods installed (especially other optimization mods) - Crash log or `latest.log` if applicable - Steps to reproduce