lovely

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

• %AppData%/Balatro/Mods on Windows
• 0 on Steam Deck (~/ will be called Home if you are moving files in the GUI file manager)
• Flatpak version of Steam: ~/.var/app/com.valvesoftware.Steam/.steam/steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods

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.

1. 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  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