Skip to content

01. Getting started

Jump to bottom
Casimir Eisenach edited this page Jul 17, 2024 · 3 revisions

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

File header

Steamodded will recognize your mod only if the first line in your mod file is EXACTLY --- STEAMODDED HEADER.

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: [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
    • --- LOADER_VERSION_GEQ: 1.1.0 (Requires Steamodded of this version or newer)
    • --- LOADER_VERSION_LEQ: 1.2.0 (Requires Steamodded of this version or older) 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.
Clone this wiki locally