Lithium: Minecraft game logic optimization

What Lithium optimizes

Lithium focuses on the server side of the game: the logic that runs every tick (20 times per second). These aren't graphical changes, so Lithium doesn't affect FPS directly. Instead, it improves TPS (ticks per second) and gets rid of lag spikes.

Mob AI and pathfinding

Vanilla Minecraft works out mob movement paths with an algorithm that searches the surrounding blocks. Lithium rewrites this system so it's faster and uses less memory. The effect is most noticeable in worlds with lots of mobs: farms, spawner farms, villages full of villagers.

Entity physics

Collisions between entities (mobs, items, arrows) require checking the position of every object in a given chunk. Lithium uses optimized data structures for these calculations, which cuts collision-check time by several dozen percent.

Block ticking

Every block in loaded chunks can need an update each tick: plants grow, water flows, redstone sends signals. Lithium optimizes the tick event queue and skips needless checks on blocks that don't need updating.

Chunk generation

Lithium speeds up generating new terrain by optimizing noise generation and structure placement. Exploring new land feels smoother.

Collision shapes

Minecraft stores block collision shapes (VoxelShapes) in a way that causes a lot of memory allocation. Lithium caches these shapes and reduces pressure on the garbage collector, which cuts down on lag spikes.

How Lithium works under the hood

Lithium doesn't change game mechanics: everything works exactly as it does in vanilla. The mod swaps inefficient algorithms and data structures for faster equivalents. Examples:

• Entity list in a chunk: vanilla uses an ArrayList, Lithium replaces it with a spatial structure with O(1) lookup
• Pathfinding: vanilla recalculates the path from scratch every tick, Lithium caches the results and only recalculates when the surroundings change
• Block state lookups: vanilla searches the state map linearly, Lithium indexes them in O(1)

The key point: none of these changes affect gameplay. A villager still reaches its bed, water still flows the same way, crops grow at the same rate. Lithium changes how the game calculates these things, not what it calculates.

Installation

Lithium is a Fabric mod. Installing it takes literally a minute:

1. Make sure you have the Fabric Loader installed (guide)
2. Download Lithium from Modrinth and pick the version for your MC version
3. Put the lithium-fabric-X.X.X.jar file in .minecraft/mods/
4. Launch the game with the Fabric profile

Lithium doesn't need Fabric API: it works on its own. There are no settings to configure. Drop the file in and forget about it.

Lithium also exists in a NeoForge version called Lithium (NeoForge); look for it on Modrinth.

Real performance gains

How much Lithium helps depends on what you do in the game. A few scenarios:

20 TPS means the game runs at full speed. Below 16 TPS the game starts to stutter: mobs teleport, redstone lags behind, blocks break with a delay. Lithium keeps TPS closer to 20 in situations that would normally cause drops.

Lithium + Sodium: the full set

Lithium and Sodium optimize different layers of the game and are designed to work together:

• Sodium - rendering (GPU): 2-5x more FPS, a rewritten chunk renderer
• Lithium - logic (CPU): higher TPS, fewer lag spikes, better physics
• Moonrise - chunks: Paper's chunk system, compatible with Lithium and FerriteCore (it replaces Starlight, whose repository has been archived)
• FerriteCore - memory: 40-50% less RAM usage
• ModernFix - general: fixes memory leaks, faster loading

Sodium, Lithium, FerriteCore and ModernFix are the absolute baseline for any Fabric installation, and on a server it's worth adding Moonrise. The combined performance gain is bigger than the sum of the individual mods, because they remove bottlenecks at different levels.

Lithium on servers

Lithium is especially valuable on multiplayer servers. A server doesn't render graphics (so it doesn't need Sodium), but it has to calculate the game logic for all players at once. Lithium reduces the server's CPU load, which means a stable 20 TPS even with 30+ players online.

On Fabric servers, install Lithium like any other server mod: put the .jar file in the server's mods/ folder. Players don't need Lithium installed on their side (it's a server-side mod), but they can have it on the client to optimize singleplayer.

Server alternative: Paper/Purpur servers (forks of Spigot) have many of Lithium's optimizations built in. If you use Paper, the gain from Lithium will be smaller.

Frequently asked questions

Does Lithium change game mechanics?

No. Lithium is designed so the game behaves exactly like vanilla. If something works differently with Lithium, that's a bug and should be reported on the project's GitHub.

Does Lithium work with OptiFine?

Lithium doesn't conflict with OptiFine (through OptiFabric), because it doesn't modify the renderer. But Sodium + Lithium is the better choice, because Sodium gives higher FPS than OptiFine.

Does Lithium require Fabric API?

No. Lithium works without Fabric API. But if you have other Fabric mods, you probably need Fabric API anyway.

Does Lithium work on Forge/NeoForge?

The official version of Lithium is for Fabric. There are NeoForge ports (search for "Lithium" on Modrinth with the NeoForge filter). On old Forge, the equivalent is Radium.

Can I use Lithium together with Sodium?

Yes, they are designed to work together. Sodium optimizes the GPU (rendering), Lithium optimizes the CPU (logic). Together they give the best results.