Jack Potts

Rule-based bot that plays Balatro autonomously via the balatrobot mod's JSON-RPC API. A priority-ordered rule engine evaluates every game state and the first rule that fires wins — no ML, no tree search, just hand-tuned heuristics backed by a full simulation of Balatro's scoring pipeline.

Live stats dashboard: jackpotts.drlat.dev

Documentation

Page	What's inside
Installation	Prerequisites, the fork rationale, .env.local setup
Usage	Running single games, the supervisor, CLI flags, logs
Architecture	Rule engine, decision flow, module map
Scoring	Joker pipeline, card/enhancement/edition handling, The Idol mod patch
Dashboard	JackPotts ingest pipeline, payload shape, batch lifecycle
Testing	Unit tests, integration harness, writing new tests
Release notes	Changelog

Quickstart

git clone https://github.com/DrLatBC/JackPotts.git
cd JackPotts
pip install -e ".[dev,runtime]"

Create .env.local in the repo root:

BALATRO_EXE=G:\SteamLibrary\steamapps\common\Balatro\Balatro.exe
LOVELY_DLL=G:\SteamLibrary\steamapps\common\Balatro\version.dll

Run a single game:

uvx balatrobot serve --port 12346          # terminal 1
balatro-bot --port 12346 --start           # terminal 2

Run 4 parallel instances with health monitoring:

python -m balatro_bot.supervisor --instances 4

See Installation and Usage for full details.

How it works

balatrobot API  -->  bot.py (game loop)
                       |
                     engine.py (priority-ordered rules)
                       |
              +--------+---------+
              |                  |
        domain/policy/     domain/scoring/
        (what to do)       (how much is it worth)
              |                  |
        joker_effects/     strategy.py
        (score simulation) (build affinity)

Every candidate hand is run through the full scoring simulation — joker effects, enhancements, editions, seals, retriggers, boss blind modifiers — before the bot picks one. Scoring accuracy against the game's actual chip totals sits at 99.89%.

See Architecture for the full breakdown.

Contributing

PRs welcome. The integration harness (docs/testing.md) makes it easy to reproduce scoring mismatches against a live Balatro instance — please include a failing test case with bug reports where feasible.