Steamodded SMODS: a Lua mod loader for Balatro

A mod loader that borrows the LÖVE model

Balatro is a card game, and Steamodded is the framework that lets other people change it. The project describes itself as a mod loader and injector for Balatro, and it makes a deliberate comparison with the LÖVE framework, which it says it is built using in the same way, with Lua as the implementation language.

That comparison sets expectations better than the description alone. LÖVE is a framework rather than a game, and its value is that it hands you a window, an event loop, drawing primitives and a module system, and lets the community write the parts on top. Steamodded plays the same role for Balatro: it provides the mod loading, injection and APIs, and the interesting work happens in mods written by other people.

The stated design goal is modularity and extensibility, and the README says the project provides a large selection of APIs and other features to facilitate bringing your ideas to life. The audience is therefore two groups at once: players who want to install existing mods, and authors who want to write new ones against a documented API surface.

The repository layout backs up the framework framing. There is a src/ directory, a libs/ directory for bundled dependencies, a localization/ directory, and an assets/ directory, alongside several top level Lua files.

Installing Steamodded is a documentation link, not a command

The installation section of the README is short. Under the heading for how to install Steamodded, it points at the documentation site, docs.smods.dev, and stops there.

That is an unusual README, but it is a sensible division of labour for a project whose install is a multi-step procedure involving injecting into a game rather than a single package manager command. The README does not attempt to restate those steps, so anyone evaluating this project should read the installation instructions on the documentation site before assuming how the framework gets onto a machine.

It also means the repository README is not the place to look for API documentation. The features section says as much directly: documentation for the project is currently incomplete, and a collection of the pages and guides that are available can be found on the documentation site.

For mod authors there is a more specific pointer. Under creating a mod, the README links the guide for your first mod at docs.smods.dev under Guides/Your-First-Mod. Between the installation guide and that first mod guide, the documentation site carries the practical material, and the repository carries the source.

Installing a mod means copying a file or a folder

The mod install procedure is the part of the documentation that is fully described in the README, and it is three steps long.

Navigate to your Mods directory, as the installation instructions tell you, because the location of that directory is defined by the install steps for Steamodded itself. Put the mod into that directory. The README is explicit that a mod can be a single file if only one file is provided, or a whole folder. Launch the game.

There is no manifest to hand edit, no dependency resolution step and no version compatibility field mentioned in this procedure. The single file form is a real convenience for Lua, where a self-contained mod can be one file, and it explains why the framework is worth building on Lua in the first place.

The corollary is that the Mods directory is the whole contract between the framework and a mod. If a mod author wants to ship several files, the folder form handles it, and the framework's job is to load whatever it finds there when the game starts.

What the top level files reveal about the build

The repository root has a small number of files that tell you how the project is put together, and a few of them are more revealing than the README.

config.lua is the framework's configuration, manifest.json is the kind of file that describes a package to a loader, and version.lua and release.lua hold version and release information. The presence of release.lua and version.lua at the top level, separate from the src/ directory, suggests the build and release process reads or writes them, which is a pattern common to projects that script their own packaging.

Two other directories are worth naming. lsp_def/ holds what by its name are definitions for a Lua language server, which would give mod authors editor completion and diagnostics for the framework's APIs rather than for plain Lua. That matters more here than in most projects, because the API surface is large and the prose documentation is incomplete. There is also a tk_debug_window.py, a Python file that sits oddly beside a Lua codebase, which points to a separate debug window tool kept alongside the game framework rather than being part of it.

The .gitattributes file at the root and the assets/ directory are the usual supporting pieces for a project that ships art alongside code.

Release tags that changed numbering scheme

The release history is short and has clearly been through a transition. The most recent tags are 26.1002.0, dated 2026-10-02, and 26.829.0, dated 2026-08-29, both named SMODS in their titles. Before those sits 1.0.0-beta-1814a, dated 2026-06-14.

The older tag follows the familiar shape of a semantic version with a beta marker and a short suffix that looks like a commit identifier. The newer ones do not: they are a two digit year prefix followed by a numeric component and a patch number, so they encode a date-like identity rather than an API version. That is a deliberate choice for a framework that has to be matched to a game build, and it also means an ordinary version comparison tells you very little about breaking changes.

For an author, that has a practical consequence. There is no minor version range to depend on and no compatibility table in the repository, so the coupling between a mod and a framework release is something the mod author has to manage, and the framework's own versioning does not make that easy to express.

The repository is not archived, and the last push was on 2026-10-19, so the project is being worked on rather than parked.

GPL-3.0 and an ecosystem built on voluntary documentation

The licence is the GNU General Public License, and the README states the intent plainly: it ensures the software is free to use, modify and distribute. Anyone shipping a mod built on this framework inherits that framing for the derived work, which is a meaningful constraint on how mods are licensed and distributed. The repository also carries a LICENSE file and a .github/ directory, the usual home for contribution and issue templates.

Contributions are welcome, and the README makes a specific request alongside the invitation: if you are adding new features, providing documentation is highly appreciated. Read together with the admission that documentation is currently incomplete, that sentence explains the state of the project more accurately than the feature list does. The APIs exist, the documentation does not fully describe them, and the project is asking for the second part to catch up.

Support runs through GitHub issues and a Discord server linked from the README. There is no separate commercial or enterprise offering described, and no compatibility matrix between framework releases and game versions in the repository.

So the practical judgement on this project is about documentation depth rather than code quality. The framework removes the hard part, injection, and leaves the reader to reconstruct the API surface from guides, a language server definition and the source.

Editorial conclusion

Use Steamodded if you write or want to run Lua mods for Balatro, since the install path for a mod is a file copy and the framework supplies the APIs a mod author needs, and the repository is not archived with a last push on 2026-10-19. Do not expect a complete API reference before you start, because the README states that documentation for the project is currently incomplete and the guides live on an external documentation site rather than in the repository. Before you commit to it, verify two things: that the documentation page for the specific API you need exists, and that the release tag you install matches the game build you run, since the tags changed scheme from 1.0.0-beta-1814a to date-like 26.1002.0 numbering.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. Steamodded/smods on GitHub