# xpost2000/legends-jrpg architecture

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

- Interactive diagram: https://gitdiagram.com/xpost2000/legends-jrpg
- Repository: https://github.com/xpost2000/legends-jrpg

## Overview

##### Project Type & Purpose
- This is a full-featured game engine and game, specifically a tactical JRPG reminiscent of late SNES titles.
- The engine handles software rendering (with custom SIMD optimizations), multithreaded job scheduling, audio (with SDL2_mixer and SoLoud), and custom systems for scripting, editing, and file packaging.
- The README emphasizes features like the entirely self-made engine, custom scripting language (lisp based), a variety of development tools (level and world map editors), and custom resource formats.

##### File Structure
- Top-Level Directories:
- "src": Contains all the engine/game source code, subdivided into modules for graphics, audio, UI, battle, cutscenes, script, input, and file serialization.
- "areas", "scenes", "shops", "worldmaps", "dlg", "res": These directories hold game-specific data files, level definitions, dialogues, UI assets, and media art. They are loaded at runtime through the game’s virtual file system.
- "bigfilemaker": Tools for building the custom bigfile archive used by the virtual filesystem.
- "dependencies": Contains third-party libraries (SDL2, stb) and also assets related to SDL2 linking under various platforms.
- "media": Contains code samples and additional documentation; useful for understanding how subsystems (like input, jobs, serialization) are constructed.
- Build scripts & Makefile:
- The Makefile indicates targets for running the game (release and debug), packaging the distribution with “run-tree”, and specialized web builds (using emscripten) and Windows builds. This suggests a modular build process with clearly differentiated build targets.

##### Main Components
a. Core Engine Subsystems:
- Game Loop & Main Module (src/main.c, src/game.c, etc.)
- Multithreaded Job System: Represent the custom job queue (note references in README regarding SIMD and multithreading).
b. Rendering System:
- SDL2 & Platform Abstraction: Note the usage of SDL2 in "dependencies" and specialized audio modules (src/audio_sdl2_mixer.c, src/audio_soloud.c).
c. Audio Subsystem:
- SDL2_Mixer module and SoLoud variant – indicating the abstraction layer over audio.
d. UI & Input Handling:
- Several UI modules (pause_menu_ui.c, options_menu_ui.c, inventory and equipment UI) and input mapping (src/input.c, src/input_mapper.c).
e. Scripting Engine & Custom Formats:
- Custom scripting language and dialogue system (src/dialogue_script_parse.c, src/game_script.c, etc.) along with serialization and binary file packing (bigfilemaker, custom save system with delta compression).
f. Development Tools / Editors:
- Level Editor (src/editor.c) and World Map Editor (src/world_editor.c). It’s important to indicate that these tools output custom binary files which are also read by the game.
g. Data/Resource Management:
- Virtual Filesystem using bigfile archives, areas, scenes, and resource files stored in res/, dlg/, shops/, and worldmaps directories.

##### Relationships and Interactions
- How the core game loop orchestrates the various subsystems – graphics, audio, UI, and scripting.
- Data flow from resource directories through the custom file loader (bigfilemaker output) to runtime engine components.
- Relationship between the editors and the runtime engine (editors create files that are subsequently loaded by the game).

##### Architectural Patterns & Design Principles
- Layered architecture: hardware/platform abstraction layer (SDL2, dependencies), core engine (game loop, memory management), and domain-specific modules (combat, UI, scripting).
- Separation between development tools vs. runtime engine components.
- The use of components like memory arenas and a job system hints at an architecture designed for high performance with a fixed memory footprint.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Runtime Engine Subgraph
    subgraph "Runtime Engine"
        CoreGameEngine["Core Game Engine"]:::runtime
        MemoryManagement["Memory Management"]:::runtime
        JobSystem["Multithreaded Job System"]:::runtime
        Rendering["Rendering System"]:::runtime
        Audio["Audio System"]:::runtime
        UI["UI & Input Handling"]:::runtime
        Scripting["Scripting & Serialization"]:::runtime
    end

    %% Platform Abstraction Subgraph
    subgraph "Platform Abstraction"
        SDL2_Platform["Platform Abstraction (SDL2)"]:::dependency
    end

    %% Development Tools Subgraph
    subgraph "Development Tools"
        Editors["Level & World Map Editors"]:::tools
        BigfilePacker["Bigfile Archive Tools"]:::tools
    end

    %% Resource Management Subgraph
    subgraph "Resource Management"
        VirtualFS["Virtual Filesystem / Resource Manager"]:::resource
    end

    %% Relationships in Runtime Engine
    CoreGameEngine -->|"orchestrates"| MemoryManagement
    CoreGameEngine -->|"orchestrates"| JobSystem
    CoreGameEngine -->|"orchestrates"| Rendering
    CoreGameEngine -->|"orchestrates"| Audio
    CoreGameEngine -->|"orchestrates"| UI
    CoreGameEngine -->|"orchestrates"| Scripting

    %% Platform Abstraction supports UI, Rendering, and Audio
    SDL2_Platform -->|"supports"| Rendering
    SDL2_Platform -->|"supports"| Audio
    SDL2_Platform -->|"supports"| UI

    %% Development Tools output assets to Resource Management
    Editors -->|"outputs"| VirtualFS
    BigfilePacker -->|"packages"| VirtualFS

    %% Resource supplies assets to the Core Engine
    VirtualFS -->|"supplies"| CoreGameEngine

    %% Click Events for Core Engine components
    click CoreGameEngine "https://github.com/xpost2000/legends-jrpg/blob/master/src/main.c"
    click CoreGameEngine "https://github.com/xpost2000/legends-jrpg/blob/master/src/game.c"

    %% Click Events for Memory Management
    click MemoryManagement "https://github.com/xpost2000/legends-jrpg/blob/master/src/memory_arena.c"
    click MemoryManagement "https://github.com/xpost2000/legends-jrpg/blob/master/src/memory_arena_def.c"

    %% Click Event for Multithreaded Job System
    click JobSystem "https://github.com/xpost2000/legends-jrpg/blob/master/src/thread_pool.c"

    %% Click Events for Rendering System
    click Rendering "https://github.com/xpost2000/legends-jrpg/blob/master/src/software_framebuffer.c"
    click Rendering "https://github.com/xpost2000/legends-jrpg/blob/master/src/graphics.c"
    click Rendering "https://github.com/xpost2000/legends-jrpg/blob/master/src/opengl_renderer.c"
    click Rendering "https://github.com/xpost2000/legends-jrpg/blob/master/src/opengl_renderer_def.c"

    %% Click Event for Platform Abstraction (SDL2)
    click SDL2_Platform "https://github.com/xpost2000/legends-jrpg/tree/master/dependencies/x86-64/include/SDL2"

    %% Click Events for Audio System
    click Audio "https://github.com/xpost2000/legends-jrpg/blob/master/src/audio_sdl2_mixer.c"
    click Audio "https://github.com/xpost2000/legends-jrpg/blob/master/src/audio_soloud.c"

    %% Click Events for UI & Input Handling
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/input.c"
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/input_mapper.c"
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/pause_menu_ui.c"
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/options_menu_ui.c"
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/save_menu_ui.c"
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/battle_ui.c"
    click UI "https://github.com/xpost2000/legends-jrpg/blob/master/src/common_ui.c"

    %% Click Events for Scripting & Serialization
    click Scripting "https://github.com/xpost2000/legends-jrpg/blob/master/src/dialogue_script_parse.c"
    click Scripting "https://github.com/xpost2000/legends-jrpg/blob/master/src/game_script.c"
    click Scripting "https://github.com/xpost2000/legends-jrpg/blob/master/src/game_script_def.c"
    click Scripting "https://github.com/xpost2000/legends-jrpg/blob/master/src/lisp_read.c"
    click Scripting "https://github.com/xpost2000/legends-jrpg/blob/master/src/serializer.c"
    click Scripting "https://github.com/xpost2000/legends-jrpg/blob/master/src/serializer_def.c"

    %% Click Events for Development Tools
    click Editors "https://github.com/xpost2000/legends-jrpg/blob/master/src/editor.c"
    click Editors "https://github.com/xpost2000/legends-jrpg/blob/master/src/world_editor.c"
    click BigfilePacker "https://github.com/xpost2000/legends-jrpg/blob/master/bigfilemaker/bigfile_packer.c"
    click BigfilePacker "https://github.com/xpost2000/legends-jrpg/blob/master/bigfilemaker/bigfile_unpacker.c"

    %% Click Events for Resource Management directories
    click VirtualFS "https://github.com/xpost2000/legends-jrpg/tree/master/areas"
    click VirtualFS "https://github.com/xpost2000/legends-jrpg/tree/master/scenes"
    click VirtualFS "https://github.com/xpost2000/legends-jrpg/tree/master/shops"
    click VirtualFS "https://github.com/xpost2000/legends-jrpg/tree/master/worldmaps"
    click VirtualFS "https://github.com/xpost2000/legends-jrpg/tree/master/dlg"
    click VirtualFS "https://github.com/xpost2000/legends-jrpg/tree/master/res"

    %% Styles
    classDef runtime fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef tools fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef dependency fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef resource fill:#FADBD8,stroke:#E74C3C,stroke-width:2px;
```
