Lithium: a Minecraft performance mod you can install on one side only

One codebase, two loaders, and no need to install on both sides

The first property worth understanding is the one-sided installation. The readme says the mod works on both the client and the server and does not require the mod to be installed on both sides. That sentence is what separates this from most performance work on a game server, where a server-side change only helps if the players also install something, and where asking players to install something is the point at which adoption stops. Here an operator can add it to a server and see the benefit without touching a single client. The second property is the promise itself, stated as no change to game mechanics or visuals, and the article that follows the introduction is about the mechanism rather than about marketing. The third is the loader story. Two mod loaders are supported, and the repository shows how that is achieved: there is a shared module holding the code, a second module whose name suggests reusable pieces, and a separate module for each loader. So this is not one project with a second fork maintained alongside it. It is one implementation with two entry points, and a single release whose name carries the game version and the mod version and whose description states it covers both loaders. That is the difference between a project that supports two loaders and a project that supports two loaders twice. The distribution is equally ordinary: two well-known mod repositories, a launcher, or a jar dropped into the mods folder. One small thing to know if you clone it: the default branch is a development branch rather than a release branch, and the readme does not explain the branch layout.

The no-mechanics guarantee is kept by switching optimisations off, not by fixing them

A performance mod that promises not to change behaviour is making a claim it has to enforce, and the enforcement mechanism here is the most interesting thing in the readme. The mod is described as a collection of vastly different optimisations, and the key property is that very few of them depend on each other. That independence is what makes the rest work. If a user reports that some other mod breaks, the resolution is not to remove Lithium, it is to identify the one optimisation responsible and switch it off, and the readme says exactly that. The list of individual switches is documented in a separate summary file rather than only inside the configuration file itself, so you can look up the name of the thing you need to disable instead of reading a configuration file line by line. Then there is the policy for defaults, and it is the part that makes the no-mechanics promise credible. An optimisation is disabled by default if there is a major unresolved issue with it. That is a deliberate, conservative default: a known-broken optimisation ships dark rather than shipping on and being disabled by each user individually, which is the pattern that lets a performance mod drift into changing behaviour over time. The consequence for a user is that the out-of-the-box configuration is the stable set, an empty configuration file means the defaults rather than nothing, and if you have a problem the expected response is to find the switch.

Three mixin configuration files, because the two loaders need different ones

The top-level file list contains three configuration summaries with almost identical names, one for the mod in general and one for each of the two loaders, and that is a small detail that explains a lot about how this project is organised. The optimisations are applied by mixing into the game's own classes, and a mixin configuration is what decides which mixins apply and under which conditions. Two loaders that differ in how they load and transform classes cannot share one configuration file, so the same set of optimisations is described three times, and each list is accompanied by a human readable summary in markdown. For a user that means the switch you need to flip for a conflict is documented in a document you can read rather than in a file you have to decode, and the loader-specific file is the one that applies to your setup. The practice of shipping a markdown summary alongside each configuration file is worth copying, because the alternative is a user reporting a bug rather than disabling a feature, and the two have very different costs. One caveat to hold on to. Everything here is documentation of the current version, and the summaries are per loader and per version, so when you upgrade to a release built for a new game version the set of optimisations will have changed and the file you consulted last time is not the file you have now.

Three of the readme's links point somewhere other than this repository

This is a small finding that will cost you five minutes if you do not know it in advance, and it is worth knowing because the links look authoritative. The contributors link in the support section points at a repository with a different name, the one for a single loader, rather than at this repository's contributor graph. The community invitation is hosted on a personal domain belonging to the project's former maintainer, so the entire community entry point for the project lives on infrastructure that the current maintainer does not control. And the build status badge for the bleeding-edge section, along with the link to the workflow itself, points at the same single-loader repository. That last one matters most in practice, because the section that tells you how to get unstable builds is describing builds produced by a different repository than the one you are reading. None of this is a criticism. The projects are siblings under the same organisation, the single-loader repository is where the automated builds naturally live, and a personal domain hosting a community link is a common outcome of a project changing hands. But a reader who follows the bleeding-edge link and lands in a different repository with a different branch layout deserves to have been warned, and nobody can infer it from the readme. If you are evaluating this project, follow each link and note which repository it actually goes to.

Bleeding-edge builds, and a support policy stated in advance

The unstable build section is short and unusually well handled, and the reason it reads well is that it sets expectations before anything goes wrong. There is a badge, a description of what produces the builds, and the mechanism: an automated workflow that runs on every push to the repository, which means what you download reflects the latest snapshot of development rather than a tagged release. Then the warning, in plain terms. The builds will often include unfinished code that has not been extensively tested, and that code may introduce incomplete features, bugs and crashes. The readme says directly that you should not use them unless you know what you are doing and are comfortable with debugging software, and then it says something almost no project says: if you report an issue using these builds, we will expect that this is the case. That is a support boundary declared in advance rather than discovered when a ticket arrives. It tells a user on a stable build that a bug report will be taken seriously, and it tells a user on an unstable build that the report will be read as a debugging request rather than as a regression. The build status badge is the one pointed at the sibling repository described in the previous section, so if you are following the instruction, read that section first. For anyone running a public server, the practical reading is simple: stable releases only, unless you have a reason and the patience to debug.

One named developer, a sponsorship page, and a version line still in the zero range

The support section states the maintenance situation in one sentence, and it is the most useful sentence in the document for an evaluator. The project is actively developed by one named person, and has been since the previous maintainer stepped down from active development in 2020. Both names appear in a table with their roles, the current one as developer with a sponsorship link and the previous one as former developer. That is a bus factor of one, stated plainly, with a person attached to it rather than a corporate team, and a sponsorship link rather than a budget. It is a completely normal and honest situation for a long-lived volunteer project, and it is also the single most important fact for anyone considering depending on it. The version record gives the rest of the picture. The three most recent releases are all for the same game version and are two weeks apart at most, with the newest on the same day as the last push, so the release cadence is fast and the work is current. The mod's own version is in the zero two six range, which after a project that has been running since at least 2020 tells you the author has not felt the need to declare a one point zero, and for a mod that follows the game rather than versioning its own API that is a defensible choice. Each release name encodes both the game version and the mod version, which is the single most useful thing about the naming scheme: you can tell from the file name whether it matches the game you are running, without opening anything.

Gradle, four modules, a source bundle in the build output, and a checked-in IDE directory

The build section is short because the build is conventional, and two details in it are more interesting than the rest. The build uses Gradle and a single command produces the artefacts, which land in one directory. That directory contains the production binaries and, alongside them, their source bundles. For a project under a copyleft library licence, shipping a source bundle with the binary is a deliberate and sensible practice, because it means someone who needs to modify it can start from the matching source rather than from whatever is in version control on release day. The other detail is the wrapper: a script is committed that downloads the correct Gradle version for the project, and the readme tells you to substitute the system command with the wrapper script, giving the Windows form and the macOS and Linux form separately. That is standard practice and it is worth following, because a project that builds against a specific Gradle version should not depend on what a contributor happens to have installed.

The three commands the readme names, in the forms it gives them:

gradle build
./gradlew
./gradlew.bat

Two things about the repository layout to be aware of. An editor directory is committed at the top level, which is convenient for one editor and a nuisance for everyone else, and the build files are written in the Kotlin dialect rather than the Groovy one, so an older version of your build tooling will not read them. Neither is a problem for a user installing a released build; both are things a contributor meets on day one.

The alternatives, the licence, and what to verify first

The other ways to make a game server perform better are better hardware and a different server implementation, and both of those leave your clients completely untouched. That is the honest comparison, and it frames what Lithium is and is not. Hardware is the reliable option and it costs money proportionally. A different server implementation can help and it is a much larger change than installing a mod. Lithium is the option that costs nothing, requires no client action, and is reversible, which is why it is worth trying first even though its gains are bounded by how much of your frame time the game's own logic was actually costing you. On a single-player machine the comparison does not apply at all, because there is no server, and the only question is whether your machine is the bottleneck. The licence is the GNU LGPL at version three, with the text in a file at the top of the repository, and the copyleft scope of that licence applies to modifications of the mod rather than to the game or to a server running it, which is the usual and uncontroversial arrangement for this kind of add-on. If you intend to fork it, the source bundle in the build output is the starting point. What to verify first, in order. Install it on the server alone and measure, because that is the whole pitch and it costs you one file. Leave the configuration empty and only touch it when something breaks, since the defaults are the curated set. Read the mixin configuration summary for your loader before you need it, so you know which switch you would flip. And check the file name against your game version, because a mismatched build is the most common reason a mod like this appears to do nothing.

Editorial conclusion

Lithium is close to a free win for a server operator, because it works on the server alone and does not ask your players to install anything, which is the constraint that stops most server-side improvements from being adopted. Adopt it on a server, leave the default configuration alone, and change nothing until a mod conflict appears. Do not adopt it if you need a guaranteed identical experience for every client, because a client who has not installed it is running different code from a client who has, and the readme's compatibility claim is that it is compatible with most other mods rather than all of them. Three things to check as you go. The optimisation that a conflict is caused by, since the mixin configuration summaries list them individually and the fix is to disable one switch rather than the whole mod. Whether the version you are offered matches the game version you are running, because the release names encode both. And who is maintaining it, because one named developer has been doing so since 2020, which is a fact the readme states plainly and which you should weigh against how much you depend on it.

Frequently asked questions

Official sources

1. CaffeineMC/lithium on GitHub
2. Issues
3. License: LGPL-3.0
4. README
5. Releases