BalatroBot (Fork)

[slim marlin]

I've recently started experimenting with Balatro bot development, and besteon/balatrobot was exactly what I was looking for. However, since the project hasn’t seen updates in over a year and there’s limited ongoing support (despite some recent issues and pull requests), I decided to fork it and explore the codebase myself to get it working with the latest versions of Balatro, Lovely, and Steammoded.

During the process, I took notes that gradually evolved into fairly complete documentation. I’ve refactored the code into a proper Python module, cleaned up the Lua, and introduced some structural changes — including breaking changes — all aimed at improving the developer experience. Some highlights include:

• Extensive documentation
• smods docs as a Git submodule
• Lua and Python type annotations
• Formatting, linting, and type checking
• CI for code quality
• Automated releases based on semantic versioning
• Cursor rule support for better LLM usage in the Cursor editor

You can check out the fork here: https://github.com/S1M0N38/balatrobot
And the documentation here: https://s1m0n38.github.io/balatrobot/

If the original authors are interested, I’d be happy to contribute back or help merge it upstream. The Python interface has changed significantly, so it might take some work to reconcile the differences (especially since the GitHub Actions are configured for my personal setup), but I’m open to collaboration.

I'd also really appreciate any feedback or thoughts you might have on the fork.

[drowsy hare]

honestly I love that documentation. it would be nice to have some code examples that could mention and show how we read and parse and act on data returned by the game in different ways too that dont just involve spaghetti function spam

Is it then possible to generate non-predetermined actions? How would that be done and formatted?

[slim marlin]

I'm working on an actual bot rn ... 👀

[drowsy hare]

Yeah I did about 3 months ago want to make my first ML project using balatro but balatrobot didnt have enough good documentation to use it

[slim marlin]

I've vibecoded a simple bot in a Lua file, but it's not easy to scale to a more complex one. Here is the Lua prototype. So I focused a bit to be more knowledgeable about bot mod at first. The API is not complete, though. When I am digging deeper, I see that there is some info that is missing. @drowsy hare

[drowsy hare]

I mean you could in theory run one locally with a custom system prompt or just train one from scratch

[slim marlin]

rn im reworking balatrobot api to a simple version

it will be in v0.2.0

[slim marlin]

im developing v0.2.0 in the dev branch "https://github.com/S1M0N38/balatrobot/tree/dev" . Here is my dev workflow:

1. write test in tests dirs (pure sock connections)
2. implement an action in lua/api.lua
3. use DebugPlus to check for which keys of G I must wait for action completion
4. check that all tests pass.
   and then move to new action implementation. ive implemented so far:

• get_game_state
• go_to_menu
• start_run
• skip_or_select_blind
  the missing action in the api missing are play_cards discard_cards select_booster_action select_shop_action rearrange_hand rearrange_consumables rearrange_jokers use_or_sell_consumables sell_jokers

---

In all of this im using the previous api implementation (the original fork) for reference.

[slim marlin]

yeah I hate the function spam. im trying to have a clean JSON API over UDP in v0.2.0

[drowsy hare]

Would tcp not be better for this case as there is no time limit and missed packets could affect things heavily?

And how do you plan to have the connection setup? Like via a websocket?

[slim marlin]

I will look into that. the only reason I went for UDP is that the original implementation used that and I know is supported by lua socket. When running testing I've never encounter problem regarding corrupted packages but I don't think is too difficult to move from UDP to TCP.

[slim marlin]

wdym? you can checkout https://github.com/S1M0N38/balatrobot/tree/main/tests for and example new Lua API usage (the docs is still outdated). The mod now is pretty simple: 1. you send function call in json format through UDP socket. 2. the action is executed in the game 3. on action completion the game_status is returned (so in the bot logic after sending the request with function call, you should wait for game_status. No websockets).

[drowsy hare]

Yeah, my issue was for example running something over wifi or via port forwarding, if my wifi is not the best some instructions could be missed causing the run to go differently. Since with my approach I will likely be running the training on a different machine with better hardware

since that also lessens the load on the one machine

[drowsy hare]

when game_status is sent back, does it resend the whole game status? Could this be optimized by only sending the changes and keeping 2 copies of the game state to (yet again) lessen the load on my wifi?

it could also allow for easier checking on desyncs (if they do end up occuring)

Additionally, at some point I do want to integrate a simple bot with balatro multiplayer

[drowsy hare]

This also means it would have to send data across the internet

[slim marlin]

I wanna keep as simple as possible so I return the whole game status (btw the game status is not yet finalized. I returning only a couple of info). For the moment I want something simple, somewhat stable and capable to handle one connection at the time.

[drowsy hare]

ah alright

oh btw, regarding the documentation, does uv automatically get the version of python needed for the venv?

[slim marlin]

regarding training, I have in mind a different approach. I've implemented a standard way to log game action and replay them later. My idea is to create a dataset of recorded runs as jsonl file and then train on those files (not training during game execution).

[slim marlin]

yep. from .python-version file

[drowsy hare]

ah yeah i forgot that

[slim marlin]

the installation page of the docs is the only one that is updated.

[drowsy hare]

oh? I was thinking more of a less supervised approach where the ai is simply rewarded for winning blinds with more hands left etc

[drowsy hare]

how would you generate those runs?

since training the AI like that (from my limited understanding) has it assuming your way of playing is (mostly) optimal

since the ai cannot actually make those choices for itself and just trains itself upon pre-generated runs?

[slim marlin]

automatically generated in the runs/ directory (when playing the game manually or when playing by calling api)

[drowsy hare]

In addition, I think this also has it affected by human bias, for example if I REALLY like my gros michel, that means the ai would also really like gros michel too no?

is balatro through steam required?

[slim marlin]

idk im on mac using the script run_lovely_macos.sh

Here is the PR for UDP -> TCP migration https://github.com/S1M0N38/balatrobot/pull/6 . I one-shot it with Claude code and reviewed it with Copilot. Tests all passed. LGTM, but I now have to go and I want to understand a bit instead of blindly merging it.

BalatroBot (Fork)

[slim marlin]

First version of BalatroBot API Protocol : https://s1m0n38.github.io/balatrobot/api-protocol/ . I still need to improve errors.

[slim marlin]

v0.4.0 is out. This is the end of the major part of the BalatroBot re-rewritten.

[shell hollow]

I'm using your bot to make a twitch plays for a caritative event. Dude, your work is so well organized. Love to use your code ❤️ Wp !
Not sure if my project will be used at the end, but if so I will send you a link 🙂

[slim marlin]

cool ! I've create a discord server for this mod if you wanna discuss other ideas https://discord.gg/CZ6zS5DA

[shell hollow]

Ty ! By the way, you linked this thread on the original mod, but we can't reach it if we didn't join balatro server. You should consider changing the link. I try joining the main server, but some devs might not guess that the infinite loading is because we need to join the server X)

[slim marlin]

Imma a bit lost.. what do you mean?

[shell hollow]

https://github.com/besteon/balatrobot/issues/8

I found you through these issues.
But the link lead you to an infinite loading screen (clearly a discord issue) if you are not already on the Balatro Discord server.
You have no error. You NEED to guess that this is the issue. So if you don't understand that, we can't reach the link of your fork
You should at least provide your git or explain that we me join the discord server for the link to work

[slim marlin]

thanks! ive updated the link in the issue comments

[shell hollow]

Nice 🙂

Btw in your doc you talk about the feature of buying deck of cards, will this coming soon ?

[slim marlin]

"buying deck of cards"? could you pin point it?

you mean "buy_and_use_card" and "open_pack" ?

stirby (see github repo) is implementing the main missing action/endpoints. btw I strongly suggest to use the main branch instead of tag release. The releases are pretty old and we gonna start to publish the releases again when BalatroBot is somewhat stable.

[shell hollow]

"open_pack", my bad

I even didn't notice tag release XD I dl the zip like a barbarian ... Just wanted to test if your code worked. The bot_example was a great idea!