Skip to content

README.md

Latest commit

 

History

History
78 lines (58 loc) · 3.45 KB

README.md

File metadata and controls

78 lines (58 loc) · 3.45 KB

Jack Potts

built with Python license MIT version v1.1.0 tests 454 passing platform Windows PRs welcome

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 neural nets, just hand-tuned heuristics backed by combinatorial hand enumeration, Monte Carlo rollouts over future deck draws, and 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.
⚡