Contributing to BalatroBot

Welcome to BalatroBot! We're excited that you're interested in contributing to this Python framework and Lua mod for creating automated bots to play Balatro.

BalatroBot uses a dual-architecture approach with a Python framework that communicates with a Lua mod running inside Balatro via TCP sockets. This allows for real-time bot automation and game state analysis.

Project Status & Priorities

We track all development work using the BalatroBot GitHub Project. This is the best place to see current priorities, ongoing work, and opportunities for contribution.

Getting Started

Prerequisites

Before contributing, ensure you have:

Balatro: Version 1.0.1o-FULL
SMODS (Steamodded): Version 1.0.0-beta-0711a or newer
Python: 3.13+ (managed via uv)
uv: Python package manager (Installation Guide)
OS: macOS, Linux. Windows is not currently supported
DebugPlus (optional): useful for Lua API development and debugging

Development Environment Setup

Fork and Clone

git clone https://github.com/YOUR_USERNAME/balatrobot.git
cd balatrobot

Install Dependencies
```
make install-dev
```
Start Balatro with Mods
```
./balatro.sh -p 12346
```
Verify Balatro is Running
```
# Check if Balatro is running
./balatro.sh --status

# Monitor startup logs
tail -n 100 logs/balatro_12346.log
```
Look for these success indicators:
- "BalatrobotAPI initialized"
- "BalatroBot loaded - version X.X.X"
- "TCP socket created on port 12346"

How to Contribute

Types of Contributions Welcome

Bug Fixes: Issues tracked in our GitHub project
Feature Development: New bot strategies, API enhancements
Performance Improvements: Optimization of TCP communication or game interaction
Documentation: Improvements to guides, API documentation, or examples
Testing: Additional test coverage, edge case handling

Contribution Workflow

Check Issues First (Highly Encouraged)
- Browse the BalatroBot GitHub Project
- Comment on issues you'd like to work on
- Create new issues for bugs or feature requests

Fork & Branch

git checkout -b feature/your-feature-name

Make Changes
- Follow our code style guidelines (see below)
- Add tests for new functionality
- Update documentation as needed
Create Pull Request
- Important: Enable "Allow edits from maintainers" when creating your PR
- Link to related issues
- Provide clear description of changes
- Include tests for new functionality

Commit Messages

We highly encourage following Conventional Commits format:

feat(api): add new game state detection
fix(tcp): resolve connection timeout issues
docs(readme): update setup instructions
test(api): add shop booster validation tests

Development & Testing

Makefile Commands

BalatroBot includes a comprehensive Makefile that provides a convenient interface for all development tasks. Use make help to see all available commands:

# Show all available commands with descriptions
make help

Installation & Setup

make install        # Install package dependencies
make install-dev    # Install with development dependencies

Code Quality & Formatting

make lint           # Run ruff linter (check only)
make lint-fix       # Run ruff linter with auto-fixes
make format         # Run ruff formatter and stylua
make format-md      # Run markdown formatter
make typecheck      # Run type checker
make quality        # Run all code quality checks
make dev            # Quick development check (format + lint + typecheck, no tests)

Testing Requirements

Testing with Makefile

make test           # Run tests with single instance (auto-starts if needed)
make test-parallel  # Run tests on 4 instances (auto-starts if needed)
make test-teardown  # Kill all Balatro instances

# Complete workflow including tests
make all            # Run format + lint + typecheck + test

The testing system automatically handles Balatro instance management:

make test: Runs tests with a single instance, auto-starting if needed
make test-parallel: Runs tests on 4 instances for ~4x speedup, auto-starting if needed
make test-teardown: Cleans up all instances when done

Both test commands keep instances running after completion for faster subsequent runs.

Manual Setup for Advanced Testing:

# Check/manage Balatro instances
./balatro.sh --status                   # Show running instances
./balatro.sh --kill                     # Kill all instances

# Start instances manually
./balatro.sh -p 12346 -p 12347          # Two instances
./balatro.sh --headless --fast -p 12346 -p 12347 -p 12348 -p 12349  # Full setup

# Manual parallel testing
pytest -n 4 --port 12346 --port 12347 --port 12348 --port 12349 tests/lua/

Performance Modes:

--headless: No graphics, ideal for servers
--fast: 10x speed, disabled effects, optimal for testing

Documentation

make docs-serve     # Serve documentation locally
make docs-build     # Build documentation
make docs-clean     # Clean built documentation

Build & Maintenance

make build          # Build package for distribution
make clean          # Clean build artifacts and caches

Technical Guidelines

Python Development

Style: Follow modern Python 3.13+ patterns
Type Hints: Use pipe operator for unions (str | int | None)
Type Aliases: Use type statement
Docstrings: Google-style without type information (types in annotations)
Generics: Modern syntax (class Container[T]:)

Lua Development

Focus Area: Primary development is on src/lua/api.lua
Communication: TCP protocol on port 12346
Debugging: Use DebugPlus mod for enhanced debugging capabilities

Environment Variables

Configure BalatroBot behavior with these environment variables:

BALATROBOT_HEADLESS=1: Disable graphics for server environments
BALATROBOT_FAST=1: Enable 10x speed with disabled effects for testing
BALATROBOT_PORT: TCP communication port (default: "12346")

Communication & Community

Preferred Channels

GitHub Issues: Primary communication for bugs, features, and project coordination
Discord: Join us at the Balatro Discord for real-time discussions

Happy contributing!