Hello! Just wanted to take this moment to thank everyone in this amazing community for their ingenuity and creativity and wonderful drive. It's really rare for a game to persist for as long as Balatro and I'm so proud that I have been able to be a part of it for the past (almost) two years.

I can't even begin to explain how thankful I am to have the incredible @WilsontheWolf and @cg-223. They have taken care of so much work between now and v0.8.0 and I am so lucky to have them as maintainers. They deserve so much appreciation for keeping up the pressure and making this release happen.

And remember to thank the hardworking people that make the mods, they keep this community alive.

You are obligated to try these mods out: (and legally obligated to try out every mod you see elsewhere, too)

Entropy, Tangents, Matador, LobotomyCorp, Amulet, Hatchet, Gros Balatro, Stocking Stuffer, MrBones, Insignia, MyDreamJournal, Balatro Plus, Arrow, TooManyJokers, Multiverse, 45DegreeRotatedBeatblock, Basslatro, Joyous Spring, Incognito, Galdur, Hyperfixation, Hot Potato, UltraViolet, Qualatro, Corrupted Nether, Fusion Jokers, Fortlatro, 1 in 10000 Chance for Withered Foxy Jumpscare Every Second, BeatblockPlus, Beattools, Scruffy Plays Pikmen, Lovely Mobile Maker Revo's Vault Dilatro, Aikoyori's Shenanigans

Install guide

Mobile Mods!!!!

@WilsontheWolf has created https://lmm.shorty.systems, it lets you mod Balatro on mobile with lovely by porting the Steam version of the game. Try it out. The official Balatro Discord has a longstanding rule against the discussion of modding non-desktop platforms. Be aware of this before asking for support.

Contributors

Big thanks to the following contributors:

• @cg223 for multiple targets support, copy patch payloads, nested folder loading, and runtime API additions
• @WilsontheWolf for the runtime API (reload_patches, variable store), load_now error handling, Linux directory fix, and luaL_loadbuffer hook, and lots more
• @kasimeka for fixing the --vanilla segfault on Unix and adding Nix support
• @SpomJ for improving Linux installation documentation
• @hliuson for release workflow improvements

Notable Changes

Zip mods

TL;DR: Mods can now be distributed as zip files.

Lovely can now load mods packaged as zips. Packaging is simple, just drop your mod files into the archive into either the top-level or into a folder, both are valid.

mod.zip
  lovely.toml
  ...

works the same as

mod.zip
  mod/
    lovely.toml
    ...

Recursive patch loading

TL;DR: Patch files are loaded recursively, clean your lovely dirs.

Patch files inside the lovely/ directory are loaded recursively from subdirectories.

For example:

tangents/
    lovely/
      questionable_feature.toml
      features/
        real_feature.toml
        content.toml
      tweaks/
        balanced.toml

Multiple targets per patch

TL;DR: Pattern, regex, and copy patches can target multiple files.

Patch away with reckless abandon:

[[patches]]
[patches.pattern]
target = ["main.lua", "game.lua", "init.lua"]
pattern = "old_code"
payload = "new_code"

Copy patch payloads

TL;DR: Copy patch payload field

Copy patches now have an optional payload field that lets you inject code without the fuss of a separate file:

[[patches]]
[patches.copy]
target = "main.lua"
position = "append"
payload = """
-- Inline code here
print("Injected!")
"""

Runtime API additions

TL;DR: New Lua APIs for runtime patch manipulation.

The lovely module now exposes several new functions for runtime control:

• lovely.reload_patches() - Reload all patches from disk without restarting. This does not reapply patches, you need a restart for that.
• lovely.apply_patches(buffer_name, buffer_content) - Apply patches to arbitrary buffers at runtime. You can patch shaders with this! And whatever you want, really.
• lovely.set_var(key, value) - Store a var in the store.
• lovely.get_var(key) - Retrieve a var from the store.
• lovely.remove_var(key) - Remove and return a var from the store.

Example usage:

-- Store configuration
lovely.set_var("is_tangents_questionable", "true")

-- Retrieve it later
if lovely.get_var("is_tangents_questionable") == "true" then
	panic!("What?")
end

-- Apply patches to a dynamically loaded buffer
local patched = lovely.apply_patches("buffer_name", buffer)

-- Force a patch reload (not a restart)
lovely.reload_patches()

Module patches now apply Lovely patches

TL;DR: You can patch injected modules.

Injected modules can now be patch targets! =[lovely modname "filename"]

Bug Fixes

• Fixed hardcoded game names in Linux launch scripts (run_lovely_linux.sh)
• Fixed segfault when running with --vanilla flag on Unix
• Fixed double-panic behavior on Windows
• Fixed panic when obtaining extension from extensionless files
• Fixed incorrect mod directory on Linux (#325)

What's Changed

• Update release.yml by @hliuson in #265
• fix(unix): prevent segfault when run with --vanilla by @kasimeka in #263
• feat: add nix package and devshell by @kasimeka in #278
• feat: check preload for if lovely was loaded by @WilsontheWolf in #283
• Runtime: Implement native Lua modules v2 by @WilsontheWolf in #285
• feat: reload on lovely module by @WilsontheWolf in #286
• Allow patching lovely modules by @WilsontheWolf in #293
• Add name fields to patches by @cg-223 in #298
• Support nested folders inside Mods/foo/lovely by @cg-223 in #290
• Add Lua-sided apply_patches function by @cg-223 in #300
• feat: lua variable store by @WilsontheWolf in #299
• Allow multiple targets on a patch by @cg-223 in #297
• feat: win hook luaL_loadbuffer by @WilsontheWolf in #305
• feat: lua table helper by @WilsontheWolf in #306
• feat: log path in lua module by @WilsontheWolf in #303
• Check needs_patching before calling apply_patches from Lua by @cg-223 in https://github.com/ethangreen-dev/lovel...

Install guide

New Contributors

• @lmaple0 made their first contribution in #132
• @astroLazybones made their first contribution in #171
• @kasimeka made their first contribution in #186
• @bconlon1 made their first contribution in #154
• @IzawGithub made their first contribution in #157
• @Githubguy132010 made their first contribution in #200
• @myuujiku made their first contribution in #188

Notable Changes

• #187 Fixed broken cross-mod patch targeting on Mac.
• #218 Fixed panic caused by attempting to obtain the extension of a file without one.
• #188 The mod directory can now be set with the environment variable LOVELY_MOD_DIR.
• #228 Modules injected via module patches are now always available if load_now is false or otherwise not set. The before field is now optional as it is not used when load_now is false or not set.
• #228 Modules (including lovely) are now always accessible, even in different threads or when the game is restarted with love.event.restart (unless load_now is true).

Other Notes

• Gamepass support is unfortunately blocked by my limited availability, but work shall continue soon. I've written up a quick and dirty todo list here: #160 (comment)
• Mobile support is quickly improving thanks to the hard work of @WilsontheWolf and his liblovely project. This aims to make lovely's core codebase available for use in native contexts like within LuaJIT or Love2d. iOS (jailbroken) and mobile-maker support has experimental implementations, so we're hopeful that this is the silver bullet we need.
• A million downloads!
• ... And a lot more boring stuff that you can read about below.

What's Changed

• feat: allow a local copy of version.dll to be used on non-windows systems by @WilsontheWolf in #126
• fix: prevent edge-case panics on Wine by @ethangreen-dev in #127
• Update build.rs for users whose system disk is not C by @lmaple0 in #132
• fix: bad log prints due to weird stack positioning by @ethangreen-dev in #144
• fixed typo by @astroLazybones in #171
• fix(ci/macos): lock ziglang to the last v0.13 release by @kasimeka in #186
• feat(ci): add linux build by @kasimeka in #184
• Register log_dir variable after mod-dir argument is specified. by @bconlon1 in #154
• Use Dobby for mac by @english5040 in #187
• Remove once_cell dependency. by @IzawGithub in #157
• switch Dobby submodule import to https protocol by @kasimeka in #194
• Update README.md by @Githubguy132010 in #200
• fix Dobby build in linux CI by @kasimeka in #196
• Platform defined dynamic symbol resolution by @ethangreen-dev in #198
• Fix lovely-unix and style by @english5040 in #222
• fix: wrong lua symbols by @WilsontheWolf in #226
• fix: init lovely per state by @WilsontheWolf in #227
• feat: load modules asap by @WilsontheWolf in #228
• C-related cleanup by @english5040 in #224
• feat: make mod dir configurable via LOVELY_MOD_DIR env var by @myuujiku in #188
• Fix bad types in lovely-win by @ethangreen-dev in #234

Full Changelog: v0.7.1...v0.8.0

Install guide

What's Changed

• fix: sort patches initially by order, then by prio by @ethangreen-dev in #123
• fix: revert build toolchain to 1.77.2 by @ethangreen-dev in #124

Full Changelog: v0.7.0...v0.7.1

Install guide

Contributors

A huge thanks goes out to the following contributors:

• @flakywanderer for improving log messages with patch metadata.
• @WilsontheWolf for fixing the logging of panics on Unix targets.
• @drgrib for improving the Steam Deck install guide.
• @vgskye for completing much of the work on the Lovely Linux target.
• @asquared31415 for updating the Linux PR.
• @Rick1029 for writing a guide on running Lovely and Love2D games natively on Linux.

Notable Changes

#103 Expanded patch targets

TL;DR: You can specify more patch targets.

Patches can now target other mods and even love2d itself. Since non-Balatro buffer names can be complex you should use --dump-all and the corresponding .txt file in dump/ to determine the name of your target.

#114 Strict patch application ordering

TL;DR: Pattern and regex order inconsistencies have been fixed.

Lovely patches have a strict order in which they are applied: module → copy → pattern → regex, however this was not the case in v0.6.0. This version (and all the ones preceding it) merged the pattern and regex patches together such that they were applied in the same step in the order that they were defined within the patch file. This has been resolved by separating and applying these patches sequentially.

#103 Improved debugging via --dump-all

TL;DR: Use --dump-all to dump everything.

Every encountered buffer can be dumped, not just the ones that have been patched. Alongside each is a text file which contains the internal name of the buffer - use this name in the target field of patches.

#121 Hacky patch directory interpolation

TL;DR: Use {{lovely_hack::patch_dir}} in your payloads to access the patch's mod directory.

This variable will be replaced with the parent directory of the patch (either ../lovely.toml or ../../lovely/patch.toml, for example. It's a hacky and temporary solution that WILL be replaced at some point in the future, but it'll work fine for now.

#66 + #102 Linux support

TL;DR: Native Linux support but you must build it yourself (for now).

Follow the guide written by @Rick1029: https://github.com/Rick1029/lovely-injector/

What's Changed

• Include patch file origin paths in patch logging messages by @flakywanderer in #89
• feat: add {{lovely:mod_dir}} interpolation by @ethangreen-dev in #95
• fix: replace flawed tolstring impl with tostring lua call by @ethangreen-dev in #96
• updated version of #66 by @asquared31415 in #102
• Add extended patch target support by @ethangreen-dev in #103
• Add a proper window title, fix --disable-mods arg (Windows) by @ethangreen-dev in #104
• feat: log panics in unix by @WilsontheWolf in #112
• Add strict patch file ordering to fix edge-case panics on Unix platforms by @ethangreen-dev in #113
• Add strict patch application order to pattern and regex patches by @ethangreen-dev in #114
• Update README.md path for Steam Deck by @drgrib in #93
• Fix bad file ordering on Windows + Unix by @ethangreen-dev in #117
• chore: bump crate versions to 0.7.0 by @ethangreen-dev in #119
• fix: bad workflow caused by lovely-mac name change by @ethangreen-dev in #120
• fix: change patch dir interp to be backwards compat by @ethangreen-dev in #121

New Contributors

• @asquared31415 made their first contribution in #102
• @drgrib made their first contribution in #93

Full Changelog: v0.6.0...v0.7.0

Install guide

Bye-bye, beta

What's Changed

• Implement shared "Lovely runtime" to reduce code duplication across win and mac targets by @ethangreen-dev in #6
• Complex Regex patching and patch optimization via ropey by @ethangreen-dev in #7
• Cleanup previously dumped buffers at startup, remove @ prefix from file names by @ethangreen-dev in #11
• Add check and panic message when old dwmapi.dll binary is found within the game directory by @ethangreen-dev in #12
• Add --disable-console argument by @ethangreen-dev in #13
• Fix bad pattern text insert due to Rope byte API use mixup by @ethangreen-dev in #14
• Increment version to 0.5.0-beta2 by @ethangreen-dev in #15
• Fix build failure caused by libudis86-sys and retour on Linux native hosts by @ethangreen-dev in #16
• Fix hard crash when printing nil value, change mod path for mac systems by @tetraminus in #18
• Improved toml errors by @WilsontheWolf in #22
• Implement log file writing and apply general logging improvements by @ethangreen-dev in #25
• Fix #20 and #24 by @english5040 in #28
• Update README with Mac install guide, various other adjustments to content + formatting by @ethangreen-dev in #29
• Implement Github Action release workflow by @ethangreen-dev in #31
• Fix invalid archive file type in README install guide by @ethangreen-dev in #33
• make v0.5.0-beta3 release, ga fix for master branch trigger by @ethangreen-dev in #34
• fix ga workflow trigger by removing branch check by @ethangreen-dev in #35
• Clarify Steam Deck / Proton / Wine install instructions by @ethangreen-dev in #36
• feat: unhardcoded game directory by @WilsontheWolf in #27
• Implement mod disable / enable via .lovelyignore files by @ethangreen-dev in #37
• Remove erroneous dbg! statement sadge by @ethangreen-dev in #30
• Revert pattern patch overwrite deprecation warning by @ethangreen-dev in #39
• Update core version to v0.5.0-beta4 by @ethangreen-dev in #40
• Mac: use the name of the enclosing .app for the mod directory by @english5040 in #41
• update core version to v0.5.0-beta4 by @ethangreen-dev in #42
• Improve install instructions, again by @english5040 in #43
• Fix incorrect delta calculation by @english5040 in #45
• Pass through args to run_lovely.sh by @english5040 in #46
• Fix bad windows download link in release workflow by @ethangreen-dev in #49
• Update to v0.5.0-beta6 by @ethangreen-dev in #50
• Refactor, resolve some issues by @english5040 in #51
• Fix unconditional removal of last byte #53 by @dadahsueh in #54
• Update to v0.5.0-beta7 by @ethangreen-dev in #56
• fix: build failure caused by isize, itertools deps by @ethangreen-dev in #57
• Implement better patches by @flakywanderer in #68
• Allow patching games running on LOVE2D 12, or otherwise using luaL_loadbufferx by @tetraminus in #70
• Load modules lazily through package.preload by @flakywanderer in #74
• Add MIT license by @ethangreen-dev in #75
• fix: module source names by @WilsontheWolf in #76
• Fix edgecase panic caused by chunk names containing bad utf8 by @ethangreen-dev in #78
• Fix reverse output of Lua log messages by @ethangreen-dev in #80
• Update to v0.6.0 by @ethangreen-dev in #87

New Contributors

• @WilsontheWolf made their first contribution in #22
• @english5040 made their first contribution in #28
• @dadahsueh made their first contribution in #54
• @flakywanderer made their first contribution in #68

Full Changelog: v0.4.0...v0.6.0

Install guide

What's Changed

• Refactor, resolve some issues by @english5040 in #51
• Fix unconditional removal of last byte #53 by @dadahsueh in #54
• Update to v0.5.0-beta7 by @ethangreen-dev in #56
• fix: build failure caused by isize, itertools deps by @ethangreen-dev in #57
• Implement better patches by @flakywanderer in #68
• Allow patching games running on LOVE2D 12, or otherwise using luaL_loadbufferx by @tetraminus in #70
• Load modules lazily through package.preload by @flakywanderer in #74
• Add MIT license by @ethangreen-dev in #75

New Contributors

• @dadahsueh made their first contribution in #54
• @flakywanderer made their first contribution in #68

Full Changelog: v0.5.0-beta6...v0.5.0-beta7

Install guide

What's Changed

• Improve install instructions, again by @english5040 in #43
• Fix incorrect delta calculation by @english5040 in #45
• Pass through args to run_lovely.sh by @english5040 in #46
• Fix bad windows download link in release workflow by @ethangreen-dev in #49

Full Changelog: v0.5.0-beta5...v0.5.0-beta6

Install guide

What's Changed

• Mac: use the name of the enclosing .app for the mod directory by @english5040 in #41

Full Changelog: v0.5.0-beta4...v0.5.0-beta5

Install guide

What's Changed

• Clarify Steam Deck / Proton / Wine install instructions by @ethangreen-dev in #36
• feat: unhardcoded game directory by @WilsontheWolf in #27
• Implement mod disable / enable via .lovelyignore files by @ethangreen-dev in #37
• Remove erroneous dbg! statement sadge by @ethangreen-dev in #30
• Revert pattern patch overwrite deprecation warning by @ethangreen-dev in #39

Full Changelog: v0.5.0-beta3...v0.5.0-beta4

Install guide

What's Changed

• Fix build failure caused by libudis86-sys and retour on Linux native hosts by @ethangreen-dev in #16
• Fix hard crash when printing nil value, change mod path for mac systems by @tetraminus in #18
• Improved toml errors by @WilsontheWolf in #22
• Implement log file writing and apply general logging improvements by @ethangreen-dev in #25
• Fix #20 and #24 by @english5040 in #28
• Update README with Mac install guide, various other adjustments to content + formatting by @ethangreen-dev in #29
• Implement Github Action release workflow by @ethangreen-dev in #31
• Fix invalid archive file type in README install guide by @ethangreen-dev in #33

New Contributors

• @WilsontheWolf made their first contribution in #22
• @english5040 made their first contribution in #28

Full Changelog: v0.5.0-beta2...v0.5.0-beta3