How steamodded/smods works
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