Balatro RL

A reinforcement learning agent that plays Balatro using a custom mod and Python training environment.

Overview

This project combines a Balatro mod (RLBridge) with a Python reinforcement learning environment to train an AI agent to play Balatro. The mod extracts game state information and executes actions from the RL agent via a dual-pipe communication system.

Features

• Game State Extraction: Reads hand cards, chips, available hands/discards, and other game state data
• Action Execution: AI can play hands, discard cards, select hands
• Dual-pipe Communication: Request/response system using named pipes for real-time communication
• Replay System: Automatically saves winning games with top 10 highest chip score
• Custom Reward Function: Rewards efficient play, complex hands, and winning rounds
• Automated Training: Runs automatically start new games after wins/losses

Installation

Prerequisites

• Balatro (Steam version)
• Lovely Injector for mod injection
• Python 3.8+ with dependencies (requirements.txt)

Setup

1. Install Lovely Injector following their instructions
2. Install Python dependencies: pip install -r requirements.txt
3. Launch Balatro with Lovely Injector enabled (more details in lovely-injector docs)
4. Run the Python training script: python -m ai.train_balatro

Architecture

• RLBridge Mod: Lua mod using Lovely's patching system to hook into game state
• Named Pipes: Dual-pipe system (/tmp/balatro_request, /tmp/balatro_response) for communication.
• Python Environment: Custom Gym environment for RL training
• Replay System: JSON-based storage of winning game sequences

Future Work

• Explore training parallelization (possibly via Docker/multiple instances)

---

Development Notes (Personal)

Symlink for development (Arch Linux with Proton):

ln -s ~/dev/balatro-rl/RLBridge /mnt/gamerlinuxssd/SteamLibrary/steamapps/compatdata/2379780/pfx/drive_c/users/steamuser/AppData/Roaming/Balatro/Mods/RLBridge