# steamodded/smods architecture

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

- Interactive diagram: https://gitdiagram.com/steamodded/smods
- Repository: https://github.com/steamodded/smods

## Overview

##### Project type and purpose
- Steamodded is an open-source modding framework (a “plugin manager”/“injector”) for the game Balatro.
- It is pure Lua, structured to load and wire together “core” engine code, third-party mods, built-in libraries (JSON, HTTP, native filesystem), localization, assets, and type definitions (LSP).

##### File structure
- Top–level:
- config.lua, version.lua, manifest.json – global configuration and metadata
- src/ – core runtime modules (loader, core, index, overrides, game_object, ui, utils, logging, crash_handler, compat)
- libs/ – bundled third-party libraries (HTTPS via LuaJIT–curl, JSON, nativefs)
- lovely/ – a collection of TOML-driven feature modules (“lovely” enhancements)
- localization/ – language data per locale
- lsp_def/ – type definitions and helper stubs for editor integration
- assets/ – static resources (images at 1×, 2×; sounds)
- .github/, LICENSE, README.md – CI, license, docs

##### README for additional insights
- Purpose: “mod loader and injector,” modularity/extensibility, Lua-based API.

##### Main components and interactions
a. Mod Loader Core
- src/index.lua: entry point
- src/loader.lua: finds and loads mods from the Mods directory
- src/overrides.lua: hooks into game functions to inject mod behavior
- src/core.lua: central event-dispatch and lifecycle management
b. Built-in Libraries
- libs/json, libs/https, libs/nativefs – utility APIs exposed to mods
c. “Lovely” Modules
- lovely/*.toml – feature definitions interpreted at runtime by loader
d. Localization
- localization/*.lua – loaded based on user locale, fed into core/UI modules
e. Asset Manager
- assets/ – static assets served via nativefs API to mods and UI
f. LSP Definitions
g. External Systems
- Balatro game engine – exports host API to Steamodded via Lua
- External HTTP endpoints (via smods-https.lua)

##### Architectural patterns and design principles
- Plugin Architecture: core defines events/hooks; mods subscribe/override
- Modular design: separation of loader, core, utilities, features, assets, localization
- Data-driven configuration: TOML files under lovely/
- Dependency injection: libs are passed into mod context

##### Step-by-step creation advice
– Override Hooks (src/overrides.lua) → Game Engine
– UI Module (src/ui.lua) → Game Engine’s render API
– Bundled Libraries (json, https, nativefs)
– Localization service
– Asset service
5. “Lovely Modules” feeding configuration into Core at startup.
6. “Game Engine” as the ultimate host, receiving hooks and API calls.
- Core/runtime: solid rectangles
- Libraries: rounded rectangles

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Filesystem"
        style Filesystem fill:none,stroke:none
        Mods["Disk/Mods Folder"]:::extensions
        Lovely["Lovely Modules (TOML)"]:::extensions
        Localization["Localization Data"]:::extensions
        Assets["Static Assets"]:::extensions
        LibsGroup["Bundled Libraries"]:::libs
    end

    Mods --> Loader
    Lovely --> Loader
    LibsGroup --> JSONLib
    LibsGroup --> HTTPSLib
    LibsGroup --> NativeFS
    Localization --> Core
    Assets --> Core

    Loader["Loader<br/>(src/loader.lua)"]:::runtime
    click Loader "https://github.com/steamodded/smods/blob/main/src/loader.lua"

    Loader --> Core

    Core["Core/Event Bus<br/>(src/core.lua)"]:::runtime
    click Core "https://github.com/steamodded/smods/blob/main/src/core.lua"

    Core --> Overrides
    Core --> UI
    Core --> GameObject
    Core --> CrashHandler
    Core --> Logging
    Core --> Utils
    Core --> Compat

    Overrides["Override Hooks<br/>(src/overrides.lua)"]:::runtime
    click Overrides "https://github.com/steamodded/smods/blob/main/src/overrides.lua"
    Overrides --> GameEngine

    UI["UI Integration Module<br/>(src/ui.lua)"]:::runtime
    click UI "https://github.com/steamodded/smods/blob/main/src/ui.lua"
    UI --> GameEngine

    GameObject["Game-Object API Surface<br/>(src/game_object.lua)"]:::runtime
    click GameObject "https://github.com/steamodded/smods/blob/main/src/game_object.lua"

    CrashHandler["Crash Handling Service<br/>(src/crash_handler.lua)"]:::runtime
    click CrashHandler "https://github.com/steamodded/smods/blob/main/src/crash_handler.lua"

    Logging["Logging Utility<br/>(src/logging.lua)"]:::runtime
    click Logging "https://github.com/steamodded/smods/blob/main/src/logging.lua"

    Utils["General Utilities<br/>(src/utils.lua)"]:::runtime
    click Utils "https://github.com/steamodded/smods/blob/main/src/utils.lua"

    Compat["Compatibility Layer (v0.9.8)<br/>(src/compat_0_9_8.lua)"]:::runtime
    click Compat "https://github.com/steamodded/smods/blob/main/src/compat_0_9_8.lua"

    JSONLib["JSON Library"]:::libs
    click JSONLib "https://github.com/steamodded/smods/blob/main/libs/json/json.lua"
    click JSONLib "https://github.com/steamodded/smods/blob/main/libs/json/init.lua"

    HTTPSLib["HTTPS Library"]:::libs
    click HTTPSLib "https://github.com/steamodded/smods/blob/main/libs/https/smods-https.lua"
    click HTTPSLib "https://github.com/steamodded/smods/blob/main/libs/https/luajit-curl.lua"
    HTTPSLib --> ExternalHTTP

    NativeFS["Native Filesystem Library"]:::libs
    click NativeFS "https://github.com/steamodded/smods/blob/main/libs/nativefs/init.lua"
    click NativeFS "https://github.com/steamodded/smods/blob/main/libs/nativefs/nativefs.lua"

    ExternalHTTP["External HTTP Endpoints"]:::external
    GameEngine["Balatro Game Engine"]:::external

    Core --> GameEngine

    subgraph "IDE Support"
        LSP["LSP Type Definitions"]:::ide
        click LSP "https://github.com/steamodded/smods/tree/main/lsp_def/"
    end

    classDef runtime fill:#EFEFEF,stroke:#333,stroke-width:1px
    classDef extensions fill:#F9F4BC,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef libs fill:#D0E6A5,stroke:#333,stroke-width:1px,rx:5,ry:5
    classDef external fill:#CCCCCC,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef ide fill:#F2D1E5,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
