BalatroCoop

A 2-player LAN co-op mod for Balatro.

Both players play through the same run together. Blind scores are combined, progression is synchronized, and both players share the shop.

Current version: 0.2.2 Alpha

This is an early release, so bugs and desyncs may still happen.

Installation

Thunderstore

If you're using the Thunderstore Mod Manager / r2modman, install BalatroCoop normally and let the manager install its dependencies.

BalatroCoop requires:

• Steamodded
• Lovely

Manual installation

Install the dependencies first:

• Steamodded
• Lovely

Then:

1. Download BalatroCoop.

2. Extract the ZIP.

3. Open File Explorer.

4. Click the address bar and paste:

   %AppData%\Balatro\Mods

5. Copy the entire BalatroCoop folder into the Mods folder.

The final path should look like:

%AppData%\Balatro\Mods\BalatroCoop\main.lua

Do not copy only main.lua, and make sure you don't end up with:

BalatroCoop\BalatroCoop\main.lua

How to play

Both players need BalatroCoop installed.

1. Open CO-OP / LAN.
2. One player clicks Create Room.
3. Send the displayed LAN IP to the other player.
4. The second player enters that address into Host IP or IP:port and clicks Join Room.
5. Both players choose their decks and click Ready.
6. The host clicks Start Together.

For two game instances on the same PC, use:

127.0.0.1

BalatroCoop uses TCP port:

22122

If Windows Firewall asks for permission, allow Balatro on your Private network.

Remote connections through a TCP tunnel

The Join field accepts a LAN or public IPv4 address. To use a tunnel with a different external port, enter IP:port, for example 203.0.113.10:14908 (example address only). Without a port, the mod uses 22122.

The host creates the room normally and configures their tunnel to forward TCP traffic to 127.0.0.1:22122 on the host PC. Give the guest the tunnel's public IPv4 and external port. The displayed Your LAN IP is still the local address; the mod cannot discover your tunnel endpoint automatically.

Both players must use the same BalatroCoop version. This does not add matchmaking, a hosted relay or reconnection. Actual remote connectivity depends on the tunnel service and network configuration.

Features

• 2-player LAN co-op
• Combined blind scoring
• Separate decks for both players
• Shared shop
• Synced blind selection and skips
• Synced round progression
• Shared purchase and reroll state
• Remote player Jokers and consumables
• Other player's played-card animations
• LAN IP detection
• Environment and connection diagnostics

Compatibility

Currently focused on:

• Windows 10/11
• Steam Balatro
• 2-player LAN
• Steamodded
• Lovely

Recent Steamodded and Lovely versions are allowed even if they have not all been individually tested.

Large gameplay-changing mods are not officially tested yet. For the most reliable experience, try BalatroCoop with only Steamodded and Lovely first.

Current limitations

This is an Alpha release.

Currently there is:

• no reconnect after disconnecting
• no matchmaking
• no dedicated server
• no official macOS/Linux support yet
• limited compatibility testing with other large mods

Do not expose TCP port 22122 directly to the public internet.

Bug reports

If something breaks, please include:

• BalatroCoop version
• Balatro version
• Steamodded version
• Lovely version
• whether you were Host or Guest
• what happened before the problem
• screenshot, video, or crash log if available

Changelog

0.2.2 — remote address input, 2026-10-13

• Accept LAN/public IPv4 addresses with an optional TCP port for externally configured tunnels. Default connections still use 22122; hosting still binds 0.0.0.0:22122.
• Allow colon entry and retain the selected port through asynchronous connection completion.
• Publish Thunderstore only; no gameplay or wire protocol changes.

0.2.1 — alpha packaging update, 2026-10-12

• Publish the explicit Steamodded/Lovely Thunderstore requirements and updated player README under version 0.2.1.
• Keep the opponent information popup fix and MAVU author credit. No gameplay or protocol changes.

0.2.0 — distribution alpha candidate, 2026-10-11

• Fix a missing local text-row helper that crashed the opponent information popup after module splitting; cover waiting/empty/populated inventories, pagination and popup cleanup.

• Show one detected physical LAN/default-route IPv4 on the room home and host pages; ambiguous addresses have an explicit chooser. Keep the Join field empty with an Enter host LAN IP placeholder.

• Copy IP copies the displayed local address. Host binding remains 0.0.0.0:22122 and the network protocol is unchanged.

• Corrected Vortex 1.0.1 / Thunderstore manager status to pending clean-profile QA.

• Replace exact-pair approval with minimum supported versions, Supported ranges, recorded Verified combinations and an explicit known-incompatible list. Future versions are Unverified and allowed; compatible installed frameworks are not downgraded.

• Fixed Steam Browse fallback and added independent manifest/x64/library validation.

• Recognize Lovely 0.10.0 winmm.dll by hash; verified old DLL migration with external backup, rollback and unknown-injector protection.

• Added installer policy/filesystem tests; kept real Windows and Steam Balatro acceptance separate. No gameplay changes.

• Use protected loading of the LuaSocket built into LÖVE; missing networking leaves solo available.

• Add environment diagnostics, first-entry check, LAN IP/Copy IP and categorized nonblocking connection errors.

• Bump handshake to BCOOP_2 and require matching Mod version before room actions. Gameplay transactions/barriers remain unchanged.

• Add one-source platform packaging, pinned official dependency downloads, NSIS Windows installer, upgrade backup and reversible uninstall.

• Add player README, development docs, release provenance, tag-triggered draft releases and honest QA gates.

• Windows/Steam clean installation, manager deployment and gameplay acceptance are NOT RUN. Manager flows are PENDING_CLEAN_PROFILE_QA; this is not a certified public release.

0.1.2 — 2026-10-03

• Set co-op blind scaling to 2 + the number of Plasma decks, replacing native per-player scaling to prevent double multiplication. Solo runs keep native scaling.
• Render shop Next Round readiness as geometric checkmarks attached to native UI layout, without depending on Unicode font coverage. Readiness and cancellation retain the existing server protocol.
• Protocol remains BCOOP_1; both players should update and start a new run.

0.1.1 — 2026-10-03

• Restore three graphics.print calls incorrectly changed into debug logging during refactoring: remote cursor label and ready-marker shadow/text.
• Add rendering-path regression tests for blind/shop cursors, ready markers and expired cursor packets; add a static check against corrupted graphics namespaces.
• Protocol remains BCOOP_1. No gameplay changes.

0.1.0 — 2026-10-03

Behavior-preserving refactor based on the uploaded V12.16 prototype.

• Replaced the 4,275-line entry script with a dependency-ordered module loader.
• Consolidated four server message layers and four client message layers into explicit dispatcher registrations.
• Consolidated three Game draw layers, two update layers, two shop install/update layers, and three room cleanup layers.
• Removed the overridden, unreachable pre-native shop renderer. Kept the active native renderer, localization and viewport conversion.
• Separated room, game, market and UI state; moved captured callback references to their own hook namespace.
• Version comes from the mod manifest. Bumped the protocol to BCOOP_1 to prevent mixed old/new clients.
• Added authenticated snapshot queries, passive revisioned snapshot receipt and debug logging.
• Preserved transaction IDs, epoch/revision checks, applied-ID payment guard, pack acceptance, deferred vouchers and native-event/animation barriers.
• Added reproducible baseline traces, protocol tests, syntax/structure checks, documentation and conservative license notice.

No new gameplay, blind multiplier adjustment, reconnect, automatic resync, or server-side hand simulation was added.