# emmachase/riko4 architecture

> Architecture diagram of the GitHub repository emmachase/riko4, 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/emmachase/riko4
- Repository: https://github.com/emmachase/riko4

## Overview

Based on your file tree and README, Riko4 is a fantasy computer and game engine with a dual-layer architecture. Essentially, you have a core engine written in C/C++ (found under the “src” directory) that handles low-level functionality like audio, graphics (GPU, shader management), file system operations, networking, and more. On top of that, you have a rich scripting layer (mostly Lua) located throughout the “scripts” directory. This layer provides everything from bootstrapping (boot.lua) to a variety of interactive demos, games, and even a built-in shell (scripts/usr) that mimics an operating system environment. In addition, assets and data (like shaders in the “data” folder) are also parts of the system that the engine consumes at runtime.

##### Main Components
- Core Engine (C++):
- Represented by the “src” folder that includes several modules:
- Core: Handles events, Lua machine integration, process management, and shader management.
- Engine: Contains submodules for audio, file system (fs), GPU image processing, networking, polygons handling, timer functions, and userdata management.
- Scripting Layer (Lua):
- Found in the “scripts” folder and its subdirectories:
- Boot and initialization scripts.
- Game demos and interactive applications (located in “scripts/home/demos” and “scripts/home/games”) that showcase various features of the engine.
- User-facing shell and utilities (under “scripts/usr”) offering command-line functionality and editors.
- Reusable libraries (in “scripts/lib”) that extend capabilities of the engine such as bitmap manipulation, UI components, and event mediation.
- Data/Assets:
- The “data” directory, especially the shaders (common.frag, common.vert), which are utilized by the engine’s shader subsystem.
- Build and Dependency Management:
- CMake configuration files (CMakeLists.txt, CMakePresets.json) and vcpkg configuration (vcpkg.json and vcpkg-overlay) illustrate the external libraries (such as SDL and sdl-gpu) that are integral to the project.

##### Component Interactions
- A layered relationship where the C++ Core Engine forms the bottom layer that interacts directly with hardware or system APIs. The engine exposes APIs (for graphics, audio, input, etc.) that the Lua scripting environment can invoke.
- That the Lua layer sits on top, using an embedded Lua interpreter (as instantiated by luaMachine.cpp in the “src/core” folder) to execute scripts, drive game demos, expose shell commands, and manage user interactions.
- That assets (e.g., shaders, game resources) flow from the “data” folder into the engine at runtime.

##### Architectural Patterns and Design Principles
- Separation of concerns between the engine (system-level operations) and the scripting layer (high-level logic, demos, user interface).
- That the project follows a modular design: core engine modules are clearly separated (e.g., “audio”, “gpu”, “net”) and the scripting libraries are bundled in dedicated folders.
- Mention integration through language binding (C++ to Lua) that illustrates an interpreter or bridge design pattern.
- Plugin/extensibility design observed in “scripts/lib” which can be enhanced or extended with additional Lua modules.

##### Relevant Technologies
- C/C++ as the implementation language (with files in “src”).
- Lua for scripting the high-level behaviors (scripts, demos, shell commands).
- CMake for build automation, with integration to vcpkg to manage third-party libraries such as SDL and specialized ports (e.g., sdl-gpu).
- Use of shader technology (GLSL) as indicated by “common.frag” and “common.vert” for graphical rendering.

##### Being Detailed
- Don’t hesitate to break down the “Core Engine” into its submodules (e.g., events, graphics, audio, network) and similarly detail the various Lua script groupings such as demos, games, and user tools.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Engine Layer
    subgraph "Core Engine (C++)"
        CF["Core Functionality"]:::core
        EM["Engine Modules"]:::core
        subgraph "Lua Integration"
            LMCPP["luaMachine.cpp"]:::core
            LMH["luaMachine.h"]:::core
        end
        MH["Misc Helpers"]:::core
        RS["Resources"]:::core
        UE["Util & Error Handling"]:::core
    end

    %% Lua Scripting Environment Layer
    subgraph "Lua Scripting Environment"
        BS["Boot Scripts"]:::lua
        D["Game Demos"]:::lua
        G["Game Games"]:::lua
        US["User Shell Utilities"]:::lua
        RL["Reusable Lua Libraries"]:::lua
    end

    %% Asset/Data Layer
    subgraph "Asset/Data Layer"
        SH["Shaders & Assets"]:::asset
    end

    %% Build and Dependency Management Layer
    subgraph "Build & Dependency Management"
        CMake["CMakeLists.txt"]:::build
        CMPreset["CMakePresets.json"]:::build
        VCPKG["vcpkg.json"]:::build
        VCPKGO["vcpkg-overlay"]:::build
    end

    %% Relationships between Lua Scripting and Core Engine
    BS -->|"initialize"| CF
    D  -->|"callsAPI"| CF
    G  -->|"callsAPI"| CF
    US -->|"executes"| CF
    RL -->|"extendsAPI"| CF

    %% Core Engine asset loading
    CF -->|"loads_assets"| SH

    %% Build system feeding into Core Engine modules
    CMake -->|"build_config"| CF
    CMPreset -->|"build_config"| CF
    VCPKG -->|"dependencies"| EM
    VCPKGO -->|"dependencies"| EM

    %% Class definitions for styling
    classDef core fill:#f9e6e6,stroke:#b30000,stroke-width:2px;
    classDef lua fill:#e6f7ff,stroke:#005073,stroke-width:2px;
    classDef asset fill:#e6ffe6,stroke:#228b22,stroke-width:2px;
    classDef build fill:#fffbe6,stroke:#e6b800,stroke-width:2px;

    %% Click Events for Core Engine components
    click CF "https://github.com/emmachase/riko4/tree/master/src/core"
    click EM "https://github.com/emmachase/riko4/tree/master/src/engine"
    click LMCPP "https://github.com/emmachase/riko4/blob/master/src/core/luaMachine.cpp"
    click LMH "https://github.com/emmachase/riko4/blob/master/src/core/luaMachine.h"
    click MH "https://github.com/emmachase/riko4/tree/master/src/misc"
    click RS "https://github.com/emmachase/riko4/tree/master/src/resources"
    click UE "https://github.com/emmachase/riko4/tree/master/src/util"

    %% Click Events for Scripting Layer components
    click BS "https://github.com/emmachase/riko4/blob/master/scripts/boot.lua"
    click D "https://github.com/emmachase/riko4/tree/master/scripts/home/demos"
    click G "https://github.com/emmachase/riko4/tree/master/scripts/home/games"
    click US "https://github.com/emmachase/riko4/tree/master/scripts/usr"
    click RL "https://github.com/emmachase/riko4/tree/master/scripts/lib"

    %% Click Event for Asset/Data Layer
    click SH "https://github.com/emmachase/riko4/tree/master/data/shaders"

    %% Click Events for Build & Dependency Management components
    click CMake "https://github.com/emmachase/riko4/blob/master/CMakeLists.txt"
    click CMPreset "https://github.com/emmachase/riko4/blob/master/CMakePresets.json"
    click VCPKG "https://github.com/emmachase/riko4/blob/master/vcpkg.json"
    click VCPKGO "https://github.com/emmachase/riko4/tree/master/vcpkg-overlay"
```
