How tfdsoft/famidash works
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.