You are viewing a potentially older version of this package. View all versions.
Thunderstore-lovely-0.10.0 icon

lovely

Lovely is a runtime lua injector for LÖVE 2d

By Thunderstore
https://github.com/ethangreen-dev/lovely-injector
Date uploaded a month ago
Version 0.10.0
Download link Thunderstore-lovely-0.10.0.zip
Downloads 12471
Dependency string Thunderstore-lovely-0.10.0

README

Lovely is a runtime lua injector for LÖVE 2d

Lovely is a lua injector which embeds code into a LÖVE 2d game at runtime. Unlike executable patchers, mods can be installed, updated, and removed over and over again without requiring a partial or total game reinstallation. This is accomplished through in-process lua API detouring and an easy to use (and distribute) patch system.

Manual Installation

Windows + Proton / Wine

  1. Download the latest release for Windows. This will be lovely-x86_64-pc-windows-msvc.zip.
  2. Open the .zip archive, copy winmm.dll into the game directory. You can navigate to the game's directory by right-clicking the game in Steam, hovering "Manage", and selecting "Browse local files". If you are upgrading from an older version of Lovely, delete the old version.dll from the game directory.
  3. Put one or more mods into the mod directory (NOT the same as the game directory). You may need to create the Mods folder yourself, or launch Balatro with lovely installed once to create it automatically. If you are modding Balatro, this should be
  1. Only Steam Deck / Proton / Wine Set your game's launch options in Steam to WINEDLLOVERRIDES="winmm=n,b" %command%.
  2. Run the game through Steam.

Mac

  1. Download the latest release for Mac. If you have an M-series CPU (M1, M2, etc.) then this will be lovely-aarch64-apple-darwin.tar.gz. If you have an Intel CPU then it will be lovely-x86_64-apple-darwin.tar.gz
  2. Open the .zip archive, copy liblovely.dylib and run_lovely_macos.sh into the game directory. You can navigate to the game's directory by right-clicking the game in Steam, hovering "Manage", and selecting "Browse local files".
  3. Put one or more mods into the Mac mod directory (NOT the same as the game directory). This should be /Users/$USER/Library/Application Support/Balatro/Mods where $USER is your username (if you are modding Balatro).
    If you can't find this folder, try pressing Shift-Command-. (period) to show hidden files in Finder.
  4. Run the game by either dragging and dropping run_lovely_macos.sh onto Terminal.app in Applications > Utilities and then pressing enter, or by executing sh run_lovely_macos.sh in the terminal within the game directory.

Note: You cannot run your game through Steam on Mac due to a bug within the Steam client. You must run it with the run_lovely_macos.sh script.

Important: Mods with Lovely patch files (lovely.toml or in lovely/*.toml) must be installed into their own folder (or zip file) within the mod directory. No exceptions!

Linux Native

  1. Install love using your distribution's package manager. This is sudo pacman -S love on SteamOS and Arch-based distros, and sudo apt install love on Ubuntu & Debian-based ones.
  2. Download the latest release for Linux. This will be x86_64-unknown-linux-gnu.tar.gz.
  3. Open the .tar.gz archive, copy liblovely.so and run_lovely_linux.sh into the game directory. You can navigate to the game's directory by right-clicking the game in Steam, hovering "Manage", and selecting "Browse local files".
  4. Put one or more mods into the mod directory (NOT the same as the game directory). If you are modding Balatro, this should be ~/.local/share/love/Mods.
  5. Run the game by executing ./run_lovely_linux.sh in the terminal within the game directory (you can copy this file into the directory of choice).

Patches

Note that the patch format is unstable and prone to change until Lovely is out of early development.

Patch files define where and how code injection occurs within the game process. A good (complex) example of this can be found in the Steamodded repo here.

[manifest]
version = "1.0.0"
priority = 0

# Define a var substitution rule. This searches for lines that contain {{lovely:var_name}}
# (var_name from this example, it can really be anything) and replaces each match with the
# provided value.
# This example would transform print('{{lovely:var_name}}') to print('Hello world!').
#
# USEFUL: For when you want to reduce the complexity of repetitive injections, eg. embedding
# release version numbers in multiple locations.
[vars]
var_name = "Hello world!"

# Inject one or more lines of code before, after, or at (replacing) a line which matches
# the provided pattern.
#
# USEFUL: For when you need to add / modify a small amount of code to setup initialization
# routines, etc.
[[patches]]
[patches.pattern]
target = "game.lua"
pattern = "self.SPEEDFACTOR = 1"
position = "after"
payload = '''
initSteamodded()
print('{{lovely:var_name}}')
'''
match_indent = true
times = 1 # Optional, when omitted all instances of the pattern will be replaced. Otherwise the first <times> instances will be replaced. 

# Inject one or more lines of code before, after, at, or interwoven into one or more
# Regex capture groups.
# - I recommend you to use a Regex playground like https://regexr.com to build
#   your patterns.
# - Regex is NOT EFFICIENT. Please use the pattern patch unless absolutely necessary.
# - This patch has capture group support.
# - This patch does NOT trim whitespace from each line. Take that into account when
#   designing your pattern.
#
# USEFUL: For when the pattern patch is not expressive enough to describe how the
# payload should be injected.
[patches.regex]
target = "tag.lua"
pattern = "(?<indent>[\t ]*)if (?<cond>_context.type == 'eval' then)"
position = 'at'
line_prepend = '$indent'
payload = '''
local obj = SMODS.Tags[self.key]
local res
if obj and obj.apply and type(obj.apply) == 'function' then
    res = obj.apply(self, _context)
end
if res then
    return res
elseif $cond
'''
times = 1

# Append or prepend the contents of one or more files onto the target.
#
# USEFUL: For when you *only* care about getting your code into the game, nothing else.
# This does NOT inject it as a new module.
[[patches]]
[patches.copy]
target = "main.lua"
position = "append"
sources = [
    "core/core.lua",
    "core/deck.lua",
    "core/joker.lua",
    "core/sprite.lua",
    "debug/debug.lua",
    "loader/loader.lua",
]
payload = "-- I'm extra code that isn't worth an extra file"

# Inject a new module into the game *before* a target file it loaded.
# USEFUL: For when you want to silo your code into a separate require-able module OR inject a "global" dependency before game / mod code begins execution.
[[patches]]
[patches.module]
source = "nativefs.lua"
before = "main.lua"
name = "nativefs"

TL;DR - Patch variants

  • Use pattern patches to surgically embed code at specific locations within the target. Supports * (matches 0 or more occurrences of any character) and ? (matches exactly one occurrence of any character) wildcards.
  • Use regex patches only when the pattern patch does not fulfill your needs. This is basically the pattern patch but with a backing regex query engine, capture groups and all.
  • Use copy patches when you need to copy a large amount of position-independent code into the target.
  • Use module patches to inject a lua module into the game's runtime. Note that this currently only supports single file modules, but this should be changing soon.

Patch files

Patch files are loaded from mod directories inside of the mod folder (MOD_DIR). Lovely will load any patch files present within MOD_DIR/ModName/lovely/ or load a single patch from MOD_DIR/ModName/lovely.toml. If multiple patches are loaded they will be injected into the game in the order by order of their priority.

Paths defined within the patch are rooted by the mod's directory. For example, core/deck.lua resolves to MOD_DIR/ModName/core/deck.lua.

Patch targets

Each patch definition has one or more patch targets. These targets are typically the relative paths of source files when dumped from the game with a tool like 7zip. For example, one can target a top-level file like main.lua, or one in a subdirectory like engine/event.lua.

For certain games/libraries, files are loaded differently. Targets (or more specifically buffer names) can be arbitrarily anything.

Lovely itself uses the format of =[lovely <patchname> "<relative path to mod>"] for buffers loaded via module patch.

Patch debugging

Lovely dumps patched lua source files to MOD_DIR/lovely/dump. Logs are likewise written to MOD_DIR/lovely/log.

Not yet implemented

  • manifest.version

CHANGELOG

v0.10.0

The lovely Windows binary has been renamed to winmm.dll!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Install guide

OS Download
Windows lovely-x86_64-pc-windows-msvc.zip
Mac (Arm) lovely-aarch64-apple-darwin.tar.gz
Mac (x86) lovely-x86_64-apple-darwin.tar.gz
Linux lovely-x86_64-unknown-linux-gnu.tar.gz

What's Changed

New Contributors

Full Changelog: https://github.com/ethangreen-dev/lovely-injector/compare/v0.9.0...v0.10.0

v0.9.0

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

Install guide

OS Download
Windows lovely-x86_64-pc-windows-msvc.zip
Mac (Arm) lovely-aarch64-apple-darwin.tar.gz
Mac (x86) lovely-x86_64-apple-darwin.tar.gz
Linux lovely-x86_64-unknown-linux-gnu.tar.gz

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.

[!IMPORTANT] BREAKING CHANGES:

  • Module patches with load_now = true that fail to load or execute now properly propagate errors instead of failing silently.
  • On Linux native, the mod directory has changed from ~/.config/<game>/Mods to ~/.local/share/<game>/Mods to follow XDG standards. You'll need to move your mods to the new location.

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

[!IMPORTANT] Most mods WILL NOT WORK AS ZIPS until modloaders have added support. NO EXCEPTIONS!

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:

[[patch]]
[patch.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:

[[patch]]
[patch.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

New Contributors

Full Changelog: https://github.com/ethangreen-dev/lovely-injector/compare/v0.8.0...v0.9.0

v0.7.1

What's Changed

Full Changelog: https://github.com/ethangreen-dev/lovely-injector/compare/v0.7.0...v0.7.1

v0.7.0

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.

[!IMPORTANT] Patching other mods can cause problems if done incorrectly - problems that can be impossible to debug even with a complete dump. Be careful with this tool, communicate your intent with other devs as needed, document what you've done, and remember to have fun!

#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

New Contributors

Full Changelog: https://github.com/ethangreen-dev/lovely-injector/compare/v0.6.0...v0.7.0

v0.6.0

What's Changed

New Contributors

Full Changelog: https://github.com/ethangreen-dev/lovely-injector/compare/v0.4.0...v0.6.0

v0.4.0

What's Changed

New Contributors

Full Changelog: https://github.com/ethangreen-dev/lovely-injector/compare/v0.3.1...v0.4.0

v0.3.1

  • [9f1c346] Implement native print override This fixes missed output from Lua print calls

  • [436fcc7] Implement lua module injection. This allows modules to be injected and require-ed. Initially implemented for nativefs.

  • [436fcc7] Add Lovely metadata injection. This makes it possible for a Lua caller to query information about the Lovely environment.

  • [7ceeace] Add LOVELY_INTEGRITY global const to patched source files. This has been implemented to enable runtime integrity checking for Ankh.

  • [ffeb76f] Fix missing target name check in PatternPatch.

About

Contact Us Privacy Policy Thunderstore Wiki

Developers

API Docs GitHub Repo Package Format Docs Markdown Preview Manifest Validator

Thunderstore 2024