# balatro-multiplayer/balatromultiplayer architecture

> Architecture diagram of the GitHub repository balatro-multiplayer/balatromultiplayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/balatro-multiplayer/balatromultiplayer
- Repository: https://github.com/balatro-multiplayer/balatromultiplayer

## Overview

##### Project Type and Purpose
- The README clearly states that this is a "Balatro Multiplayer Mod" built by virtualized and TGMM, indicating that it extends or alters gameplay by incorporating multiplayer features.
- The project is a mod (or extension) rather than a full standalone application, and it is “work-in-progress” (WIP). Being a mod, it integrates deeply with the game's core, while adding new functionality (multiplayer, custom gamemodes, UI components).

##### Analyzing the File Structure
- Top-Level Directories:
- .github – Contains GitHub-specific configuration (FUNDING, etc.).
- assets – Likely images or resources for different resolutions.
- compatibility – Contains Lua scripts to handle compatibility with other mods (e.g., AntePreview.lua, CodexArcanum.lua). These are plug-in scripts that make sure the mod plays well with other game modifications.
- gamemodes – Houses core and additional gamemode definitions (like attrition, etc.) with a file (_gamemodes.lua) that might act like an initializer.
- localization – Includes translation files in various languages.
- lovely – Contains multiple .toml files which likely serve as configuration or definitions for various aspects of the mod (cards, challenges, game settings, HUD, etc.). This folder modularizes game aspects into separate, configurable files.
- misc – Utility and management Lua scripts.
- networking – Contains scripts for network actions and socket communications, crucial for the multiplayer aspect.
- objects – Organizes game entities into subfolders (blinds, challenges, consumables, editions, jokers, stickers) with individual Lua scripts. This is where most game-specific logic regarding interactive elements is implemented.
- rulesets – Defines the rulesets available, suggesting a pluggable system for game rules.
- ui – Encompasses all the user interface components such as game menu, lobby, HUD, and main menu among others.
- Core Files:
- config.lua and core.lua are likely the configuration and entry point of logic for the mod.
- Multiplayer.json may offer metadata for multiplayer configuration.

##### Main Components of the System
a. Core Logic
- Entry Point: config.lua, core.lua
- Responsible for mod initialization, settings, and overall game mode management.
b. Gamemodes Module
- gamemodes folder: Contains definitions and behaviors of various game modes.
c. Object Management
- objects folder: Manages game entities from jokers, challenges, stickers, etc.
d. Networking Module
- networking folder: Handles real-time data communication (action_handlers.lua, socket.lua) essential for multiplayer support.
e. Compatibility Layer
- compatibility folder: Ensures interoperability with other mods through targeted Lua scripts.
f. Configuration & Behavior Customization
- lovely folder (.toml files): Likely provides declarative configuration for cards, challenges, deck selection, HUD design, and game rules.
g. Localization
- localization folder: Contains translations to support multiple languages.
h. User Interface (UI)
- ui folder: Contains menus and in-game HUD that make the mod interactive for the players.
i. Miscellaneous Utilities
- misc folder: Contains scripts for utility functions and mod management (e.g., mod_hash check, disable_restart).

##### Instructing the Principal Software Engineer
- Clear labels on each component so that the function (e.g., “Core Logic”, “Networking Layer”) is immediately understandable.
- Communication between modules – for instance, show that the UI receives updates from the core, while the networking module serves as the bidirectional channel for multiplayer data.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Game System"
        Core["Mod Core"] 
        Gamemodes["Gamemodes Engine"]
        Objects["Object System"]
        Misc["Misc Utilities"]
    end

    subgraph "Communication & Integration"
        Networking["Networking Layer"]
        Compatibility["Compatibility Modules"]
    end

    subgraph "Presentation & Configuration"
        UI["UI Components"]
        Lovely["Lovely Config & Behavior"]
        Localization["Localization"]
        Assets["Assets (Resources)"]
    end

    %% Relationships - Core System Flow
    Lovely -->|"configures"| Core
    Core -->|"initializes"| Gamemodes
    Core -->|"manages"| Objects
    Misc -->|"helpers"| Core

    %% Communication arrows
    Core -->|"sends"| Networking
    Networking -->|"receives"| Core
    Networking -->|"updates"| UI

    Compatibility -->|"integrates"| Core
    Compatibility -->|"integrates"| Objects

    %% Presentation arrows
    Localization -->|"localizes"| UI
    Assets -->|"resources"| UI
    Assets -->|"resources"| Objects
    Core -->|"updates"| UI

    %% Click Events
    click Core "https://github.com/balatro-multiplayer/balatromultiplayer/blob/main/config.lua"
    click Core "https://github.com/balatro-multiplayer/balatromultiplayer/blob/main/core.lua"
    click Gamemodes "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/gamemodes/"
    click Objects "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/objects/"
    click Networking "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/networking/"
    click Compatibility "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/compatibility/"
    click Lovely "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/lovely/"
    click Localization "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/localization/"
    click UI "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/ui/"
    click Misc "https://github.com/balatro-multiplayer/balatromultiplayer/tree/main/misc/"

    %% Styles
    class Core coreStyle
    class Gamemodes gamemodesStyle
    class Objects objectsStyle
    class Networking networkingStyle
    class Compatibility compatibilityStyle
    class UI uiStyle
    class Lovely lovelyStyle
    class Localization localizationStyle
    class Assets assetsStyle
    class Misc miscStyle

    classDef coreStyle fill:#FDEBD0,stroke:#333,stroke-width:2px;
    classDef gamemodesStyle fill:#D6EAF8,stroke:#333,stroke-width:2px;
    classDef objectsStyle fill:#D5F5E3,stroke:#333,stroke-width:2px;
    classDef networkingStyle fill:#FADBD8,stroke:#333,stroke-width:2px,shape:hexagon;
    classDef compatibilityStyle fill:#E8DAEF,stroke:#333,stroke-width:2px;
    classDef uiStyle fill:#FCF3CF,stroke:#333,stroke-width:2px;
    classDef lovelyStyle fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef localizationStyle fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef assetsStyle fill:#E8F8F5,stroke:#333,stroke-width:2px;
    classDef miscStyle fill:#D7BDE2,stroke:#333,stroke-width:2px;
```
