# tfdsoft/famidash architecture

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

- Interactive diagram: https://gitdiagram.com/tfdsoft/famidash
- Repository: https://github.com/tfdsoft/famidash

## Overview

##### Project type and purpose
- This is an NES “demake” (retro re-creation) of Geometry Dash called Famidash. It is a game project, primarily written in 6502 assembly (cc65 toolchain), with separate asset pipelines for graphics, levels, and music. The end result is a single MMC3-mapped NES ROM.
- The README confirms it’s a game build: nightly builds, level and music contribution, and a heavy emphasis on assembly code, assets, and build scripts.

##### File structure
- Top-level folders:
- SAUCE: core game source code in .c/.h/.s for game logic, state machines, sprite routines, physics, etc.
- LIB: assembly libraries (crt0, mapper support, zero page, etc.) and includes.
- LEVELS: level definitions in Tiled (.tmx/.csv), Python/BAT/SH scripts to export/convert into .s assets.
- GRAPHICS: .chr banks, Aseprite sources, templates, scripts for compiling to CHR files.
- MUSIC: FamiStudio modules (.fms/.dnm), exports (.s, .dmc), intermediate text/PCM, and scripts for conversion.
- NSF: builds a .nsf version (NES sound format) for music.
- CONFIG: mapper configuration files.
- BUILD SCRIPTS: Makefile, .bat/.sh scripts, Python utilities, GitHub Actions workflows.
- Build configuration: cc65 (ca65, ld65), winmake or make, Python/Node scripts for asset conversion, custom tools (NESsc, famistudio_ca65).

##### README for additional insights
- Dependencies: cc65 toolchain, Python, FamiStudio, Tiled, Windows shell or Bash for scripts.

##### Main components
a. Asset Pipelines
- Level Pipeline: Tiled (.tmx/.csv) → export_levels.py/.sh → .s level data → assembled object
- Graphics Pipeline: Aseprite/CHR templates → conversion scripts (parallax.py, exporters) → .chr banks → graphics object
- Music Pipeline: FamiStudio modules → export.py/.bat → DMC samples, music_*.s, sfx.s → assembled object
b. Code Compilation
- SAUCE source (C/ASM) + LIB (crt0, mapper, neslib) → ca65 → object files
c. Linking & Packaging
- ld65 + mapper.cfg → NES ROM (famidash.nes) → optional .zip
d. CI/CD
- GitHub Actions workflow triggers build, creates nightly artifacts
e. External Tools & Services
- cc65 toolchain (ca65, ld65, cc65)
- Python, Bash/Batch
- FamiStudio, Tiled
- GitHub Actions (CI)

##### Relationships and interactions
- Asset pipelines feed their output (.s, .dmc) into the assembler stage in parallel.
- SAUCE/LIB source compile into objects.
- Linker takes all object files + mapper configuration to produce final ROM.
- CI workflow orchestrates build scripts and publishes artifacts.
- Developers interact via GitHub (PRs), commit to branches, trigger CI.

##### Architectural patterns and design principles
- Monolithic binary with clear separation of concerns: code logic vs. data assets.
- Pipeline pattern for asset conversion; build-time data generation.
- Configuration-driven mapper and build flags.

- Clear labels on each block (e.g., “Level Exporter,” “ca65 Assembler,” “MMC3 Mapper”).
- Arrowheads showing data flow (e.g., .tmx → export_levels.py → level_data.s → ca65).
- Notes on tool versions or config files (e.g., mmc3.cfg, build_flags.h).

##### Final advice
- Be exhaustive: represent each conversion script as its own block if it’s critical to understanding the pipeline.
- Essential files (Makefile, GitHub workflow) to show how the build is orchestrated.
- Avoid over-generalization: distinguish between level, graphics, and music pipelines even though all converge in the assembler.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Raw Assets"
        LevelTMX[".tmx/.csv"]:::raw
        Aseprite[".aseprite / famidash.bmp"]:::raw
        MusicFMS[".fms / .dnm"]:::raw
    end

    subgraph "Asset Pipelines"
        subgraph "Level Pipeline"
            ExportLevels["export_levels.py / .sh / .bat"]:::tool
            LevelDataS["all_level_data.s / all_level_table.s"]:::compiled
        end
        subgraph "Graphics Pipeline"
            Parallax["parallax.py"]:::tool
            CHR[".chr Banks"]:::compiled
        end
        subgraph "Music Pipeline"
            ExportMusic["export.py / .bat"]:::tool
            MusicAssets["music_*.s / sfx.s / music_bank*.dmc"]:::compiled
        end
    end

    subgraph "Source Code"
        CodeC["famidash.c / *.h"]:::source
        Crt0["crt0.s / mapper.s / neslib.s / famistudio_ca65.s / lz.s / zeropage.inc"]:::source
    end

    subgraph "Compilation"
        subgraph "Assembling"
            Assembler["ca65 Assembler"]:::compileTool
            Objects["Object Files"]:::artifact
        end
        subgraph "Linking"
            Linker["ld65 + mapper.cfg"]:::compileTool
            ROM["famidash.nes"]:::output
        end
    end

    subgraph "NSF Build"
        NSFAssembler["NSF ca65 + nsfmapper.s"]:::compileTool
        NSFROM["famidash.nsf"]:::output
    end

    subgraph "CI/CD"
        Workflow[".github/workflows/main.yml"]:::ci
        CacheAction[".github/actions/cache_cc65/action.yaml"]:::ci
        Scripts["Makefile / build.bat / clean.bat / 1build.bat / 2export levels and build.bat / 3export music-levels-build.bat"]:::ci
        Artifacts["Nightly ZIP Artifacts"]:::output
    end

    %% Raw to Pipelines
    LevelTMX --> ExportLevels --> LevelDataS --> Assembler
    Aseprite --> Parallax --> CHR --> Assembler
    MusicFMS --> ExportMusic --> MusicAssets --> Assembler

    %% Source to Assembler
    CodeC --> Assembler
    Crt0 --> Assembler

    %% Assembling to Linking
    Assembler --> Objects --> Linker --> ROM

    %% Music to NSF
    MusicAssets --> NSFAssembler --> NSFROM

    %% CI/CD orchestration
    Workflow --> Scripts
    Scripts --> ExportLevels
    Scripts --> Parallax
    Scripts --> ExportMusic
    Scripts --> Assembler
    Scripts --> Linker
    Workflow --> Artifacts

    %% Click Events
    click LevelTMX "https://github.com/tfdsoft/famidash/tree/main/LEVELS/LEVEL DATA"
    click ExportLevels "https://github.com/tfdsoft/famidash/blob/main/LEVELS/export_levels.py"
    click Parallax "https://github.com/tfdsoft/famidash/blob/main/GRAPHICS/Old/parallax.py"
    click ExportMusic "https://github.com/tfdsoft/famidash/blob/main/MUSIC/export.py"
    click CodeC "https://github.com/tfdsoft/famidash/blob/main/SAUCE/famidash.c"
    click Crt0 "https://github.com/tfdsoft/famidash/blob/main/LIB/asm/crt0.s"
    click Linker "https://github.com/tfdsoft/famidash/blob/main/CONFIG/mmc3.cfg"
    click NSFAssembler "https://github.com/tfdsoft/famidash/blob/main/NSF/crt0.s"
    click Workflow "https://github.com/tfdsoft/famidash/blob/main/.github/workflows/main.yml"
    click CacheAction "https://github.com/tfdsoft/famidash/blob/main/.github/actions/cache_cc65/action.yaml"
    click Scripts "https://github.com/tfdsoft/famidash/tree/main/Makefile"

    %% Styles
    classDef raw fill:#b3e6b3,stroke:#333;
    classDef tool fill:#b3d1ff,stroke:#333;
    classDef compileTool fill:#ffcc99,stroke:#333;
    classDef compiled fill:#e6e6e6,stroke:#333;
    classDef source fill:#ffe6e6,stroke:#333;
    classDef output fill:#d9b3ff,stroke:#333;
    classDef ci fill:#cccccc,stroke:#333;
    classDef artifact fill:#f2f2f2,stroke:#333;
```
