# stephane-d/sgdk architecture

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

- Interactive diagram: https://gitdiagram.com/stephane-d/sgdk
- Repository: https://github.com/stephane-d/sgdk

## Overview

##### Project type and purpose
- SGDK is a **software development kit** (SDK) in C (with some assembly) for writing Sega Mega Drive/Genesis games.
- It comprises three main “layers”:
– The **SGDK core library** (headers in `inc/`, sources in `src/`)
– A suite of **resource‐compilation and auxiliary tools** (Java- and C/C++-based tools under `tools/` and their Windows binaries in `bin/`)
– **Sample projects** and a **VSCode project template** to demonstrate usage.

##### File structure
- `inc/` + `src/` → the C/assembly code that implements the SGDK API (graphics, sound, VDP, input, multitasking, memory, etc.).
- `tools/` → source code for the custom tools (e.g. `rescomp`, `apj`, `lz4w`, `convsym`, `sjasm`, `xgmtool`, etc.).
- `bin/` → prebuilt tool binaries/jars for Windows (Java `.jar`, `.exe`).
- `lib/` → static libraries (`libmd.a`, `libgcc.a`) used at link time.
- `project/template/` → a minimal starter project; user copies this to begin a new game.
- `sample/` → dozens of example projects illustrating “basics”, “advanced” features, demos, audio tools, multitasking, etc.
- Build scripts & config (`makefile.gen`, `common.mk`, `CMakeLists.txt`, batch files) glue together compilation.

##### README for additional insights
- SGDK uses the **m68k-elf GCC** toolchain (targeting the 68000 CPU in the Mega Drive) plus **Java** for resource tools.
- Resources (images, maps, sprites, sounds) are processed by **rescomp** and other tools to generate C data arrays.
- The final ROM is produced by linking SGDK library code + user code + generated resource code + `libgcc.a`.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Environment
    subgraph "Developer Environment"
        IDE["VSCode + Genesis-Code"]:::ext
        JAVA["Java Runtime"]:::ext
        GCC["m68k-elf GCC Toolchain"]:::ext
    end

    %% Resource Pipeline Tools
    subgraph "Resource Pipeline Tools"
        BIN1["rescomp.jar"]:::tools
        BIN2["lz4w.jar"]:::tools
        BIN3["apj.jar"]:::tools
        BIN4["convsym.exe"]:::tools
        BIN5["sjasm.exe"]:::tools
        BIN6["xgmtool.exe"]:::tools
        BIN7["xgm2tool.jar"]:::tools
        SRC1["tools/rescomp/"]:::tools
        SRC2["tools/lz4w/"]:::tools
        SRC3["tools/apj/"]:::tools
        SRC4["tools/convsym/"]:::tools
        SRC5["tools/sjasm/"]:::tools
        SRC6["tools/xgmtool/"]:::tools
        SRC7["tools/xgm2tool/"]:::tools
    end

    %% SGDK Core Library
    subgraph "SGDK Core Library"
        HEADERS["inc/ (headers)"]:::core
        SOURCES["src/ (sources)"]:::core
        LIBS["libmd.a, libgcc.a, libmd_debug.a"]:::core
    end

    %% Build System
    subgraph "Build System & Config"
        S1["makefile.gen"]:::ext
        S2["common.mk"]:::ext
        S3["CMakeLists.txt"]:::ext
        S4["build_lib.bat"]:::ext
        S5["build_adv.bat"]:::ext
        S6["build_samples.bat"]:::ext
        LDS["md.ld"]:::ext
    end

    %% User Project
    subgraph "User Project"
        TEMPLATE["project/template/"]:::user
        SAMPLES["sample/"]:::user
        ASSETS["assets (res/ directories)"]:::user
    end

    %% Build Process
    subgraph "Build Process"
        RESC["Resource Conversion"]:::ext
        COMP["Compilation"]:::ext
        LINK["Linking"]:::ext
        ROM["rom.bin"]:::user
    end

    %% Output & Deployment
    subgraph "Output & Deployment"
        OUTD["out/debug/"]:::user
        OUTR["out/release/"]:::user
        EMU["Emulator / Flash Cart"]:::ext
    end

    %% Flows
    ASSETS -->|convert resources| BIN1
    BIN1 & BIN2 & BIN3 & BIN4 & BIN5 & BIN6 & BIN7 --> RESC
    RESC --> COMP
    HEADERS & SOURCES --> COMP
    TEMPLATE --> COMP
    SAMPLES --> COMP
    COMP --> LINK
    LIBS --> LINK
    LDS --> LINK
    LINK --> ROM
    ROM --> OUTD
    ROM --> OUTR
    OUTD --> EMU
    OUTR --> EMU
    IDE & JAVA & GCC & S1 & S2 & S3 & S4 & S5 & S6 --> COMP

    %% Click Events
    click HEADERS "https://github.com/stephane-d/sgdk/tree/master/inc/"
    click SOURCES "https://github.com/stephane-d/sgdk/tree/master/src/"
    click libmd "https://github.com/stephane-d/sgdk/blob/master/lib/libmd.a"
    click libgcc "https://github.com/stephane-d/sgdk/blob/master/lib/libgcc.a"
    click libmd_debug "https://github.com/stephane-d/sgdk/blob/master/lib/libmd_debug.a"
    click BIN1 "https://github.com/stephane-d/sgdk/blob/master/bin/rescomp.jar"
    click BIN2 "https://github.com/stephane-d/sgdk/blob/master/bin/lz4w.jar"
    click BIN3 "https://github.com/stephane-d/sgdk/blob/master/bin/apj.jar"
    click BIN4 "https://github.com/stephane-d/sgdk/blob/master/bin/convsym.exe"
    click BIN5 "https://github.com/stephane-d/sgdk/blob/master/bin/sjasm.exe"
    click BIN6 "https://github.com/stephane-d/sgdk/blob/master/bin/xgmtool.exe"
    click BIN7 "https://github.com/stephane-d/sgdk/blob/master/bin/xgm2tool.jar"
    click SRC1 "https://github.com/stephane-d/sgdk/tree/master/tools/rescomp/"
    click SRC2 "https://github.com/stephane-d/sgdk/tree/master/tools/lz4w/"
    click SRC3 "https://github.com/stephane-d/sgdk/tree/master/tools/apj/"
    click SRC4 "https://github.com/stephane-d/sgdk/tree/master/tools/convsym/"
    click SRC5 "https://github.com/stephane-d/sgdk/tree/master/tools/sjasm/"
    click SRC6 "https://github.com/stephane-d/sgdk/tree/master/tools/xgmtool/"
    click SRC7 "https://github.com/stephane-d/sgdk/tree/master/tools/xgm2tool/"
    click S1 "https://github.com/stephane-d/sgdk/blob/master/makefile.gen"
    click S2 "https://github.com/stephane-d/sgdk/blob/master/common.mk"
    click S3 "https://github.com/stephane-d/sgdk/blob/master/CMakeLists.txt"
    click S4 "https://github.com/stephane-d/sgdk/blob/master/build_lib.bat"
    click S5 "https://github.com/stephane-d/sgdk/blob/master/build_adv.bat"
    click S6 "https://github.com/stephane-d/sgdk/blob/master/build_samples.bat"
    click TEMPLATE "https://github.com/stephane-d/sgdk/tree/master/project/template/"
    click SAMPLES "https://github.com/stephane-d/sgdk/tree/master/sample/"
    click OUTD "https://github.com/stephane-d/sgdk/tree/master/out/debug/"
    click OUTR "https://github.com/stephane-d/sgdk/tree/master/out/release/"

    %% Styles
    classDef core fill:#cfe2f3,stroke:#0b5394;color:#0b5394
    classDef tools fill:#fce5cd,stroke:#e69138;color:#e69138
    classDef user fill:#d9ead3,stroke:#6aa84f;color:#6aa84f
    classDef ext fill:#eeeeee,stroke:#999999;color:#666666
    class HEADERS,SOURCES,LIBS core
    class BIN1,BIN2,BIN3,BIN4,BIN5,BIN6,BIN7,SRC1,SRC2,SRC3,SRC4,SRC5,SRC6,SRC7 tools
    class TEMPLATE,SAMPLES,ASSETS,ROM,OUTD,OUTR user
    class IDE,JAVA,GCC,S1,S2,S3,S4,S5,S6,LDS,RESC,COMP,LINK,EMU ext
```
