MultiplayerAPI

Multiplayer API for Balatro

Multiplayer API (mod id MultiplayerAPI, global MPAPI) is a Steamodded library mod that gives other Balatro mods online multiplayer. It handles the account and server connection, lobbies, matchmaking, actions between players, chat, replays and moderation. The mods built on it only describe their own game rules.

It is part of the Balatro Multiplayer Platform:

Repository — Mod id — What it is

BalatroMultiplayerAPI — MultiplayerAPI — This library

BalatroMultiplayerPvP — MultiplayerPvP — Head-to-head PvP gamemodes

BalatroMultiplayerSpeedrunning — MultiplayerSPDRN — Speedrun gamemodes

BalatroMultiplayerServer — n/a — The server: Nakama runtime, website and admin tools

MPAPI on its own adds an account button and the multiplayer menu. You need at least one gamemode mod (PvP or Speedrun) to actually play.

Installation

Launchers

Launchers are the easiest ways to get modded Balatro running quickly. We have two main launchers we support:

R2 Mod Man

We recommend downloading the mod with r2mm if you intend to play it casually. You can download r2mm here: https://r2modman.com/

BET

Otherwise you can use own custom closed source launcher called BET, which is intended to be a successor of BMM. You can download BET here: https://new.balatromp.com/download

Manual

Requirements:

• Steamodded (>= 1.0.0~BETA-1814a)
• Lovely Injector (>= 0.10)
• Balatro running through Steam (the API signs in with your Steam account)

Steps:

1. Install Steamodded and Lovely.
2. Download the latest release of this mod from the Releases page.
3. Extract it into its own folder in your Balatro Mods directory. Make sure the folder is not nested inside a second folder of the same name.
4. Install at least one gamemode mod (PvP or Speedrunning) the same way.
5. Launch the game through Steam.

Configuration

Join a Community server

By default the game plays on the Official server. To play on a Community server, get its address from the person who runs it. Then:

1. Close Balatro.
2. Open config.lua in MPAPI's folder in Mods, and add the server keys inside the braces:

   return {
   	['chat_enabled'] = false,
   	['use_custom_server'] = true,
   	['server_host'] = '127.0.0.1', -- the server's address
   	['server_port'] = 7350,
   	['server_secure'] = false,
   }

1. If config/MultiplayerAPI.jkr exists in the Balatro save folder, delete it (it can hold older settings).
2. Start Balatro through Steam. The game logs in with Device login, so it still needs the Steam client for your Steam id. The Lovely log shows Login: Device (server is not Official).

On a Community server your account and rating are separate from the Official server. Ranked does not need the launcher there, and you may queue with any mods. Player names on a Community server are not proven: anyone can use any name.

Each key falls back to the Official server's value when it is unset. The game reads the server_* keys only when use_custom_server = true:

Key — Official server value

server_host — nakama.balatromp.com

server_port — 443

server_secure — true (TLS)

nakama_server_key — defaultkey

web_url — https://new.balatromp.com (match-log and report links)

On Windows, write 127.0.0.1 rather than localhost. Windows tries IPv6 first, and the connection then stalls for about 20 seconds before it falls back to IPv4.

To go back to the Official server, remove the use_custom_server line from config.lua, delete config/MultiplayerAPI.jkr again, and restart Balatro. You can leave the server_* keys: the game ignores them. A new MPAPI version replaces config.lua, so you then add the keys again.

To run a Community server yourself, see "Run a Community server" in the BalatroMultiplayerServer README.

Mod code

Options passed to MPAPI.connect{ host, port, secure, server_key, web_url } take precedence over the config.

Using MPAPI from a mod

Declare the dependency in your mod's JSON:

"dependencies": ["Steamodded (>=1.0.0~BETA-1814a)", "Lovely (>=0.10)", "MultiplayerAPI"]

The best reference is the gamemode mods. BalatroMultiplayerSpeedrunning's core.lua shows a complete registration.

Startup: MPAPI.onloaded

Do your registration inside MPAPI.on_loaded(fn). MPAPI runs these callbacks once Steam is available and the connection has started. While a callback runs, MPAPI sets SMODS.current_mod back to the mod that registered it. That way the action types and gamemodes you create there belong to your mod, which matters for lobby routing (see below).

Pages and registering your mod

Each screen is an MPAPI.Page. The page that is showing replaces the main menu. Register your mod's menu and lobby screens as pages, then register the mod with their keys:

MPAPI.on_loaded(function()
	MPAPI.Page({
		key = 'mymod_main_menu',     -- used verbatim; no Steamodded prefix is added
		category = 'mod_menu',       -- 'mod_menu' | 'lobby_menu' | 'game_select' | ...
		build = function(self) return MyMod.build_menu() end,
	})
	MPAPI.Page({ key = 'mymod_lobby', category = 'lobby_menu', build = function(se