How ojuliomiguel/snes_pangolin works
What this project is (type + purpose)
This is a SNES homebrew ROM project written primarily in 65c816 assembly, built via a Makefile into a .sfc ROM image, and run in an emulator (Mesen/Snes9x). The purpose appears to be a “hello world / hello screen” style ROM (“Hello Julio” GIF) with supporting assets (font, palette/tiles).
• Build toolchain produces a ROM binary from source + assets + linker configuration.
• Runtime environment is the SNES hardware model (emulator/console), executing ROM code and reading embedded assets.
How the repository structure maps to architecture
From the file tree:
Source (ROM program)
• src/hello.asm – likely the main program entry, initialization, and rendering loop.
• src/test_minimal.asm – a minimal/test ROM program (sanity check).
• src/hdr.inc – SNES ROM header/constants/macros included by ASM sources.
• src/minimal.cfg, src/snes.cfg – linker/memory mapping configs (very important in SNES dev; they define banks, vectors, ROM layout).
Assets (data packed into ROM)
• assets/font.bin – raw font tile data.
• assets/cup_16x8_4bpp.bin – 4bpp graphics tile data.
• assets/cup_16x8_palette.cgram – palette data formatted for SNES CGRAM.
Build & dev workflow
• Makefile – orchestrates assembling/linking, generating final .sfc, copying to root.
• scripts/run_emulator.sh – runs the produced ROM in an emulator.
• scripts/watch.sh – file-watching rebuild loop.
• .vscode/* – VS Code task wiring to the Make targets.
• font.py – an asset pipeline tool (likely converts source font to SNES tile format).
Meta
• README.md – workflow and emulator discovery.
• .github/*, .memory/* – not runtime-critical, but explain contributor/dev context.
Developer / IDE
• VS Code Tasks call Make targets.
Build Orchestrator
• Makefile (targets: build/run/watch/clean).
Asset Pipeline
• font.py produces assets/font.bin (or regenerates it).
• Prebuilt binaries in assets/ are inputs to ROM link stage.
Assembler + Linker (implicit from cfg usage)
• Even if not visible in tree, the presence of .cfg strongly implies something like ca65/ld65 or a similar assembler/linker pair.
• Inputs: src/*.asm, src/hdr.inc, assets/*, src/*.cfg
• Output: build/hello.sfc and hello.sfc (copied to root).
Emulator Runner
• scripts/run_emulator.sh selects Mesen/Snes9x and launches ROM.
ROM image (hello.sfc)
• Contains: code + vectors/header + embedded asset data + memory map as defined by snes.cfg.
SNES CPU (65c816)
• Executes init, main loop, and routines (rendering, DMA transfers, etc.).
PPU / Video
• Reads VRAM/CGRAM/OAM state set up by the program.
• Displays tiles/sprites from assets.
Memory regions
• ROM banks (mapped by cfg)
• RAM (WRAM)
• VRAM/CGRAM (graphics/palette)
External runtime host
• Emulator (Mesen/Snes9x) or real hardware via EverDrive.
• VS Code Task / CLI → Makefile
• Makefile → (Assembler + Linker)
• src/hello.asm, src/test_minimal.asm → Assembler
• src/snes.cfg / src/minimal.cfg → Linker (memory map/layout constraints)
• Linker → outputs build/hello.sfc
• build/hello.sfc → copied to hello.sfc (root)
• scripts/run_emulator.sh consumes hello.sfc (or build output) → launches Emulator
Runtime flow
• Emulator/Console loads ROM
• CPU executes code from ROM → writes to PPU registers / VRAM / CGRAM
• PPU reads VRAM/CGRAM → produces video frame output
• Optional: CPU reads controller input (not shown in repo but often present; include only if code confirms)
Architectural patterns/design principles implied here
• Separation of concerns:
• src/ = program logic + platform headers
• assets/ = binary data inputs
• scripts/ = dev tooling
• *.cfg = explicit memory/ROM layout configuration
• “Embedded firmware” style build
• Reproducible build workflow
• Make targets + watch + run are an integrated dev loop.
• Actors: Developer, Emulator, (optional) Real SNES via EverDrive
• System: “Pangolin SNES ROM”
• External dependency: Emulator binaries
• Explicitly show artifacts (.asm, .inc, .cfg, .bin, .cgram, .sfc)
• Transformation steps (assemble, link, package, run)
• CPU, ROM, WRAM, PPU (VRAM/CGRAM), frame output
Concrete labeling guidance (use the repo names verbatim)
• src/hello.asm (Main ROM program)
• src/hdr.inc (Header / constants / macros)
• src/snes.cfg (SNES memory map)
• assets/font.bin (Font tiles)
• assets/*4bpp.bin (Graphics tiles)
• assets/*.cgram (Palette)
• font.py (Asset generator)
• Makefile (Build orchestration)
• scripts/run_emulator.sh (Emulator launcher)
• Output: build/hello.sfc + hello.sfc
• “Emulator (Mesen/Snes9x)”
• “SNES CPU (65c816)”
• “ROM (hello.sfc)”
• “WRAM”
• “PPU”
• “VRAM”
• “CGRAM”
• “Video Output (framebuffer/window)”
Build-time lane:
Developer/VSCode → Makefile → (Assembler) ← src/*.asm + hdr.inc → (Linker w/ snes.cfg/minimal.cfg + assets/*.bin/*.cgram) → build/hello.sfc → run_emulator.sh → Emulator
Runtime lane:
Emulator loads hello.sfc → CPU executes → writes VRAM/CGRAM → PPU renders → Video output
That separation captures the essential architecture of this repo while staying maximally faithful to what’s actually present.