01. Getting started

Getting started

Installing Lovely

Steamodded is built on Lovely, a runtime Lua injector for LÖVE2D games. Please follow the installation instructions for your operating system here.

Installing Steamodded

If you previously installed Steamodded without Lovely, you must first remove that installation by verifying your game files on Steam: Library > Balatro > Properties > Installed Files > Verify integrity of game files.

Direct download

1. Head to the Release page and select the latest release.
2. Within the Assets header, choose Source code (zip). a. To install the 1.0.0 Alpha, use this download instead.
3. Extract the downloaded zip file.
4. In your file explorer, navigate to Balatro's save directory: Windows: %AppData%/Balatro; Mac: ~/Library/Application Support/Balatro; Linux (WINE/Proton): ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro.
5. Create a directory named Mods inside the save directory if it doesn't already exist, and navigate to it.
6. Move the interior Steamodded-1.x.x folder from the download into Mods. Make sure that you don't have two Steamodded folders inside each other: your file structure should not look like this (Balatro/Mods/Steamodded-1.x.x/Steamodded-1.x.x/core/core.lua), but like this (Balatro/Mods/Steamodded-1.x.x/core/core.lua).
7. To update to a new version, delete the Steamodded-1.x.x directory in Mods and repeat steps 1-6.

Using the command line (requires Git)

1. Navigate to Balatro's save directory: Windows: cd %AppData%/Balatro; Mac: cd ~/Library/Application Support/Balatro; Linux (WINE/Proton): cd ~/.local/share/Steam/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro
2. Create the Mods directory if it doesn't already exist, and nagivate to it: mkdir Mods && cd Mods
3. Clone the repository: git clone https://github.com/Steamopollys/Steamodded.git && cd Steamodded
4. Access a specific release 1.x.x: git fetch --all && git checkout tags/1.x.x -b 1.x.x && git checkout 1.x.x
5. If you want to test upcoming features in the beta phase, you can do so by using the main branch instead: git checkout main. To update to the latest commit, run git pull.

About anti-virus issues

Lovely is commonly flagged by anti-virus software because it works similarly to a Trojan, i.e. it injects itself into a process and modifies it. It is however not a Trojan or malware of any other kind. You need not take anyone's word for this - Lovely is open source, so you can check the source code and even build the injector yourself if you want. To get Lovely running properly, you may need to whitelist it from your anti-virus software.

Using Windows Defender

• In Windows Security, navigate to Virus & threat protection > Manage settings.
• Disable Real-time protection. This will stop Defender from trying to delete version.dll while you're moving it.
• Scroll down to Add or remove exclusions and confirm if prompted.
• Navigate to the game's directory by right-clicking the game in Steam, hovering "Manage", and selecting "Browse local files". Copy the file path of this directory.
• Add an exclusion for this directory.
• Real-time protection will re-enable itself automatically, but the exclusion is needed indefinitely because Lovely is run each time you launch Balatro.

Creating your first mod

Metadata

The (new) standard way to specify your mod's metadata is in a separate JSON file in your mod folder, as per the following specification:

// Mods/your_mod/your_mod.json
{
	"id": "your_mod", // [required] ! Must be unique
	"name": "Your Mod", // [required]
	"author": ["You", "Someone else"], // [required]
	"description": "A description of your mod.", // [required] ! To use more advanced typesetting, specify your description as a localization entry at G.localization.descriptions.Mod[id]
	"prefix": "prefix", // [required] ! Must be unique. This prefix is added to the keys of all objects your mod registers. UNLIKE LEGACY HEADERS, THERE IS NO DEFAULT VALUE.
	"main_file": "main.lua", // [required] ! This is the entry point of your mod. The specified file (including .lua extension) will be executed when your mod is loaded.
	"priority": -20, // [default: 0] ! Mods are loaded in order from lowest to highest priority value.
	"badge_colour": "FF230A", // [default: 666665] ! Background colour for your mod badge. Must be a valid hex color with 6 or 8 digits (RRGGBB or RRGGBBAA)
	"badge_text_colour": "ABC123", // [default: FFFFFF] ! Text colour for your mod badge.
	"display_name": "YM", // [default: <name>] ! Displayed text on your mod badge.
	"version": "1.0.0", // ! Must follow the format of semantic versioning
	"dependencies": [
		{
			"id": "Steamodded",
			"min_version": "1.0.0~BETA"
		}, 
		{
			"id": "Galdur",
			"min_version": "1.1.2",
			"max_version": "2.0.0" // exclude an incompatible major version
		}
	], // ! All mods in the list must be installed and loaded, else this mod will not load.
	"conflicts": [
		{
			"id": "Talisman",
			"min_version": "1.1.0", // this version change broke compatibility with your mod
			"max_version": "2.0.0~" // compatibility was restored in a major version change
		}
	], // ! No mods in the list may be installed, else this mod will not load.
	"provides": [
		"SomeAPIMod"
	], // ! Use this if your mod is able to stand in for a different mod and fulfill dependencies on it. This allows the usage of a different ID so both mods can coexist.
	"dump_loc": false // !! Not for use in distributions. Writes all localization changes made on startup to a file, for conversion from a legacy system.
}

Template for copying:

{
	"id": "",
	"name": "",
	"display_name": "",
	"author": [""],
	"description": "",
	"prefix": "",
	"main_file": "",
	"priority": 0,
	"badge_colour": "",
	"badge_text_colour": "",
	"version": "",
	"dependencies": [
		{
			"id": "Steamodded",
			"min_version": "1.0.0~ALPHA-1030e"
		}
	],
}

File header

Using the legacy file header system is still supported, though switching to metadata files is encouraged. Steamodded will recognize your mod in this system only if the first line in your mod file is EXACTLY --- STEAMODDED HEADER. If you are transitioning away from using this method, make sure to remove the header to prevent Steamodded from trying to load your mod twice.

Your mod can also contain the following lines. These lines describe information about your mod and how Steamodded should load it.

• Required:
  • --- MOD_NAME: Example Mod
  • --- MOD_ID: ExampleMod (Must be unique and without spaces)
  • --- MOD_AUTHOR: [You, AnotherDev, AnotherOtherDev] (Brackets are required)
  • --- MOD_DESCRIPTION: A description of your mod. (No line breaks, text is wrapped automatically.)
• Optional:
  • --- PRIORITY: -100 (Negative values go first, positive values go last)
  • --- BADGE_COLOR: 123456 or --- BADGE_COLOUR: ABCDEF
  • --- DISPLAY_NAME: Example (Shown on mod badges instead of your mod's name)
  • --- DEPENDENCIES: [Steamodded>=1.0.0~BETA, Mod1, Mod2>=1.0.0, Mod3<=1.7.5, Mod4>=1.0.0<=2.0]
  • --- CONFLICTS: [Mod5, Mod6<=0.9.9, Mod7>=0.6.2, Mod8<=1.0>=0.3.7]
  • --- PREFIX: example (Must be unique. Defaults to the first 4 letters, lowercase, of your mod's ID.)
  • --- VERSION: 1.0.0 These lines can be specified in any order.

Useful resources

• Often, something you want to do has already been implemented in the base game. Familiarizing yourself with the game's code is an important step to learn Balatro modding. To get Balatro's source code, extract the game's executable file with 7-zip. For Mac, find Balatro.love inside Balatro.app and rename it to Balatro.zip, then extract Balatro.zip.
• It can also be useful to look at code from other mod creators. The best place to find them is in the official Balatro Discord.