# nesbox/tic-80 architecture

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

- Interactive diagram: https://gitdiagram.com/nesbox/tic-80
- Repository: https://github.com/nesbox/tic-80

## Overview

##### Project type and purpose
- TIC-80 is a cross-platform “fantasy computer” emulator and development environment.
- It bundles a core emulator, multiple scripting language interpreters, built-in editors (code, sprites, maps, sound), a command-line interface, platform abstraction layers (SDL, libretro, bare-metal Pi, Android, N3DS), and a web-based front-end (WASM + JavaScript).

##### File structure analysis
- Top-level directories
– src/ : C source for core emulator (core/, cart.c, script.c), language-binding APIs (src/api/*), studio UI (src/studio/*), system abstractions (src/system/*).
– include/ : public headers (tic80.h, retro_endianness.h, types, config).
– build/ : platform‐specific build artifacts and wrappers (android/, baremetalpi/, linux/, macosx/, webapp/, …).
– cmake/ : CMake modules to configure optional dependencies and target platforms.
– tools/ : helper command-line utilities (bin2txt, prj2cart, wasmp2cart, etc.).
– templates/ : starter projects in various languages for cartridges (C, D, Rust, Zig, Nim, etc.).
– demos/, assets/ : sample cartridges and data.

##### Insights from README
- Supports multiple scripting languages (Lua, JS, Ruby, Python, Squirrel, Wren, Fennel, Janet).
- Cross-platform: desktop (SDL2), console (libretro core), bare-metal Pi, Android, 3DS, web (WebAssembly).
- Build system: CMake driving many optional modules and backends.

a. Main components
1. Core Emulator Engine (C code in src/core, cart.c, script.c)
2. Language Bindings / API Modules (src/api/*)
3. Studio UI (built-in editors under src/studio; code, sprite, map, sfx, music)
4. System Abstraction Layer (src/system/SDL, libretro, baremetalpi, n3ds, android)
5. Web Front-End (build/webapp: WASM-compiled core + JavaScript UI + HTML/CSS)
6. Command-Line & Tools (tool executables under build/tools and tools/)
7. Build System (CMake + platform wrappers under cmake/)
8. Asset & Cartridge Storage (flat files, .tic cartridges, demo assets)

b. Relationships & data flow
- Platform Layer → calls System Abstraction Layer APIs → forwards events (input, graphics, audio) to Core Engine
- Studio UI → uses Core Engine APIs for real-time preview and editing → writes cartridge files
- CLI Tools → call into Core API or manipulate cart files directly → produce binaries or WASM-packs
- Web Front-End → loads WASM module (Core + API modules compiled to WASM) → JavaScript UI wraps built-in editors and runtime loop
- Build System → compiles Core + API + Platform layers into multiple targets (desktop exe, library, WASM, Android APK, etc.)

c. Architectural patterns & design principles
- Modular plugin-style API for each scripting language
- Layered architecture: Core → API → Studio/UI/CLI → Platform
- Abstraction of graphics/audio/input via a small system layer per platform
- Single code-base compiled with CMake into native binaries, shared libraries, or WebAssembly

d. Relevant technologies, frameworks, libraries
- C, C++ (very minimal C++), SDL2, libretro API, WebAssembly (Emscripten), JavaScript, CMake, miniaudio, libpng, GIF, kiss_fft.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core and APIs
    subgraph "Core and API Layer"
        direction TB
        Core["Core Emulator Engine"]:::core
        click Core "https://github.com/nesbox/tic-80/blob/main/src/core/core.c"
        subgraph "Language API Modules"
            direction TB
            Lua["Lua API"]:::api
            click Lua "https://github.com/nesbox/tic-80/blob/main/src/api/lua.c"
            JSAPI["JavaScript API"]:::api
            click JSAPI "https://github.com/nesbox/tic-80/blob/main/src/api/js.c"
            Python["Python API"]:::api
            click Python "https://github.com/nesbox/tic-80/blob/main/src/api/python.c"
            Ruby["Mruby API"]:::api
            click Ruby "https://github.com/nesbox/tic-80/blob/main/src/api/mruby.c"
            Squirrel["Squirrel API"]:::api
            click Squirrel "https://github.com/nesbox/tic-80/blob/main/src/api/squirrel.c"
            Fennel["Fennel API"]:::api
            click Fennel "https://github.com/nesbox/tic-80/blob/main/src/api/fennel.c"
            Janet["Janet API"]:::api
            click Janet "https://github.com/nesbox/tic-80/blob/main/src/api/janet.c"
            Scheme["Scheme API"]:::api
            click Scheme "https://github.com/nesbox/tic-80/blob/main/src/api/scheme.c"
            Wren["Wren API"]:::api
            click Wren "https://github.com/nesbox/tic-80/blob/main/src/api/wren.c"
            WasmAPI["WASM Host API"]:::api
            click WasmAPI "https://github.com/nesbox/tic-80/blob/main/src/api/wasm.c"
        end
    end

    %% UI and Tools
    subgraph "UI & Tools"
        direction TB
        Studio["Studio UI (Editors)"]:::ui
        click Studio "https://github.com/nesbox/tic-80/blob/main/src/studio/studio.c"
        ToolsCLI["CLI Tools"]:::tools
        click ToolsCLI "https://github.com/nesbox/tic-80/blob/main/src/tools.c"
    end

    %% System Abstraction
    subgraph "System Abstraction Layer"
        direction TB
        SDL["SDL2 Backend"]:::platform
        click SDL "https://github.com/nesbox/tic-80/blob/main/src/system/sdl/main.c"
        Libretro["Libretro Core"]:::platform
        click Libretro "https://github.com/nesbox/tic-80/blob/main/src/system/libretro/tic80_libretro.c"
        Pi["Bare-metal Pi"]:::platform
        click Pi "https://github.com/nesbox/tic-80/blob/main/src/system/baremetalpi/main.cpp"
        N3DS["Nintendo 3DS"]:::platform
        click N3DS "https://github.com/nesbox/tic-80/blob/main/src/system/n3ds/main.c"
        Android["Android Backend"]:::platform
        click Android "https://github.com/nesbox/tic-80/blob/main/src/system/sdl/player.c"
    end

    %% Web Front-End
    subgraph "Web Front-End"
        direction TB
        WASM["WASM Module"]:::web
        JSUI["JavaScript UI"]:::web
        Browser["Browser APIs"]:::web
        click WASM "https://github.com/nesbox/tic-80/blob/main/build/webapp/tic80.webmanifest"
        click JSUI "https://github.com/nesbox/tic-80/blob/main/build/webapp/index.html"
        click Browser "https://github.com/nesbox/tic-80/blob/main/build/webapp/serviceworker.js"
    end

    %% Build System and Assets
    subgraph "Build & Assets"
        direction TB
        BuildSys["Build System (CMake)"]:::build
        click BuildSys "https://github.com/nesbox/tic-80/blob/main/CMakeLists.txt"
        Assets["Asset & Cartridge Storage"]:::assets
        click Assets "https://github.com/nesbox/tic-80/tree/main/demos/"
    end

    %% Connections
    Studio -->|"uses APIs"| Core
    ToolsCLI -->|"invokes Core"| Core
    Core <-->|"script execution"| Lua
    Core <-->|"script execution"| JSAPI
    Core <-->|"script execution"| Python
    Core <-->|"script execution"| Ruby
    Core <-->|"script execution"| Squirrel
    Core <-->|"script execution"| Fennel
    Core <-->|"script execution"| Janet
    Core <-->|"script execution"| Scheme
    Core <-->|"script execution"| Wren
    Core <-->|"script execution"| WasmAPI

    Core -->|"render/draw"| SDL
    Core -->|"render/draw"| Libretro
    Core -->|"render/draw"| Pi
    Core -->|"render/draw"| N3DS
    Core -->|"render/draw"| Android

    SDL -->|"SDL2 API calls"| Core
    Libretro -->|"libretro callbacks"| Core
    Pi -->|"hardware interfaces"| Core
    N3DS -->|"3DS APIs"| Core
    Android -->|"JNI/EGL"| Core

    BuildSys -->|"compile Core, APIs, Platforms"| Core
    BuildSys -->|"generate Studio & Tools"| Studio
    BuildSys -->|"package WASM"| WASM

    WASM -->|"Emscripten glue"| Core
    JSUI -->|"UI wrappers"| WASM
    Browser -->|"Canvas/AudioContext"| JSUI

    Assets -->|"load cartridges"| Core
    Assets -->|"provide samples"| Studio

    %% Styles
    classDef core fill:#ffe4b5,stroke:#d2691e,stroke-width:2px
    classDef api fill:#e0ffff,stroke:#20b2aa,stroke-width:2px
    classDef ui fill:#f0fff0,stroke:#228b22,stroke-width:2px
    classDef tools fill:#fafad2,stroke:#bdb76b,stroke-width:2px
    classDef platform fill:#fff0f5,stroke:#c71585,stroke-width:2px
    classDef web fill:#e6e6fa,stroke:#9370db,stroke-width:2px
    classDef build fill:#f5f5f5,stroke:#708090,stroke-width:2px
    classDef assets fill:#ffe4e1,stroke:#cd5c5c,stroke-width:2px
```
