🌸 Poppy Compiler

Smart multi-system assembly compiler for retro gaming projects

🎉 v2.0.0 Released

Poppy v2.0.0 is now available with Pansy.Core integration, reverse converters, and bank switching! Download the release →

🎯 Overview

Poppy is a production-ready multi-system assembly compiler targeting classic gaming platforms:

Platform	CPU	Status
NES	MOS 6502	✅ Compile-validated
SNES	WDC 65816	✅ Compile-validated
Game Boy	Sharp SM83	✅ Compile-validated
Atari 2600	MOS 6507	✅ Compile-validated
Atari Lynx	WDC 65C02	✅ Compile-validated
Genesis	Motorola 68000	✅ Compile-validated
GBA	ARM7TDMI	✅ Compile-validated
WonderSwan	NEC V30MZ	✅ Compile-validated
Master System	Zilog Z80	✅ Compile-validated
TurboGrafx-16	HuC6280	✅ Compile-validated

The compiler supports real-world game development with comprehensive tooling, including a VS Code extension with IntelliSense, formatting, and build integration.

✨ Features

Implemented ✅

Core Compiler Features:

📝 Clean, lowercase assembly syntax
🔢 $ prefix for hexadecimal values (e.g., $40df)
🏷️ Labels, local labels, and anonymous labels
📍 .org directive for address setting
📊 Data directives (.byte, .word, .long, .fill, .ds)
🔀 All 6502 addressing modes
📈 Automatic zero-page optimization
🖥️ Command-line interface

File System & Organization:

📦 .include directive for file inclusion
📂 .incbin directive for binary data inclusion
🧩 .asset / .asset_manifest directives for binary/JSON/CHR reinsertion
🔄 Preprocessor with include path resolution
🗂️ Multi-file project support

Target Systems:

🎮 Full NES/Famicom support (6502)
🎨 Full SNES/Super Famicom support (65816)
🕹️ Full Game Boy/Color support (SM83)
🏛️ Multiple memory mapping modes (LoROM, HiROM, ExHiROM)
📋 All iNES mapper configurations

Label System:

🏷️ Global labels
📌 Local labels with @ prefix and scoping
➕ Anonymous forward labels (+, ++, etc.)
➖ Anonymous backward labels (-, --, etc.)

Directives & Features:

🎯 Target directives (.nes, .snes, .gb)
🗺️ Memory mapping (.lorom, .hirom, .exhirom)
🔧 Mapper selection (.mapper)
📐 Alignment directives (.align, .pad)
✅ Compile-time assertions (.assert)
⚠️ Error and warning directives (.error, .warning)
💬 Multi-line comments (/* */)

SNES ROM Generation:

🎨 SNES header at correct ROM offset ($7fc0 LoROM, $ffc0 HiROM)
📋 11 SNES header directives (.snes_name, .snes_map_mode, etc.)
🗺️ LoROM, HiROM, and ExHiROM support
✅ Automatic checksum calculation
🔢 ROM speed, type, and region configuration

Game Boy ROM Generation:

🕹️ Game Boy header at $0100-$014f
📋 7 GB header directives (.gb_title, .gb_mbc, .gb_cgb, etc.)
🎮 MBC support (MBC1, MBC3, MBC5, etc.)
🌈 CGB (Color Game Boy) mode flags
✅ Automatic Nintendo logo and checksums
🔋 RAM size and battery configuration

NES ROM Generation:

🎮 iNES 1.0 and iNES 2.0 header generation
📋 12 iNES header directives (.ines_prg, .ines_chr, .ines_mapper, etc.)
🗺️ Support for mappers 0-4095, submappers 0-15
🔋 Battery backup, trainer, mirroring configuration
🌍 NTSC/PAL timing selection

Macro System:

🔧 Macro definitions with parameters (.macro/.endmacro)
🎯 Macro parameter substitution and default values
🏷️ Local labels within macros
🔁 Nested macro invocations

Conditional Assembly:

❓ Conditional compilation (.if/.else/.endif)
🔍 Symbol existence checks (.ifdef/.ifndef)
🔢 Expression-based conditionals (.ifeq, .ifne, .ifgt, etc.)

Code Generation:

🔁 Repeat blocks (.rept/.endr) for code generation
🔢 Enumeration blocks (.enum/.ende) for sequential constants
📊 Listing file generation with symbol tables

Metadata & Verification:

🌼 Automatic Pansy metadata generation (symbols, CDL, cross-refs)
🔄 Roundtrip verification against original ROM (byte-for-byte)
📦 Peony project support (peony.json from Nexen game packs)
🎯 --pansy, --no-pansy, --no-verify CLI flags

Developer Tools:

🎨 VS Code Extension
- Syntax highlighting for all platforms
- IntelliSense with opcode documentation
- Code formatting with column alignment
- 40+ code snippets
- Build task integration
- Go-to-definition and hover info
📊 Comprehensive error messages with context
🧮 Advanced expression evaluation
📋 Multiple output formats (ROM, symbols, listings, memory maps)

Format Export:

🔄 PASM-to-ASAR exporter (.asm output)
🔄 PASM-to-CA65 exporter (.s output with .→@ local label conversion)
🔄 PASM-to-XKAS exporter (;→// comment conversion)
🏭 ExporterFactory for extensible format registration
📝 Automatic directive translation via reverse mapping tables

🚀 Quick Start

Installation

From GitHub Releases

Download the latest release from GitHub Releases.

From Source

# Clone the repository
git clone https://github.com/TheAnsarya/poppy.git
cd poppy

# Build the compiler
cd src
dotnet build -c Release

# The compiler will be at: src/Poppy.CLI/bin/Release/net10.0/poppy.exe

VS Code Extension

Install the "Poppy Assembly" extension from the Visual Studio Code Marketplace for the best development experience.

Usage

# Basic assembly
poppy game.pasm                     # Output: game.bin

# Specify output file
poppy -o rom.nes game.pasm          # Output: rom.nes

# Generate debug symbols
poppy -s game.nl game.pasm          # Creates FCEUX .nl symbol file
poppy -s game.mlb game.pasm         # Creates Mesen .mlb symbol file
poppy -s game.sym game.pasm         # Creates generic .sym symbol file

# Generate listing file
poppy -l game.lst game.pasm         # Creates symbol table listing

# Verbose output
poppy -V game.pasm                  # Shows compilation progress

# Target different architectures
poppy -t 6502 game.pasm             # NES (default)
poppy -t 65816 game.pasm            # SNES
poppy -t sm83 game.pasm             # Game Boy

# Pansy metadata & roundtrip verification
poppy game.pasm -o game.nes         # Auto-generates game.pansy
poppy game.pasm --no-pansy          # Disable Pansy generation
poppy game.pasm --no-verify         # Disable roundtrip verification
poppy game.pasm --pansy out.pansy   # Custom Pansy output path

# Export to other assembler formats
poppy export game.pasm --to asar    # Export to ASAR format (.asm)
poppy export game.pasm --to ca65    # Export to CA65 format (.s)
poppy export game.pasm --to xkas    # Export to XKAS format (.asm)
poppy export src/ --to asar         # Export entire project directory

# Genesis asset-manifest workflow (conversion + inclusion)
poppy --platform genesis src/main.pasm -o build/game.bin

Example Assembly (NES/6502)

; Example NES ROM with iNES 2.0 header
.nes
.ines_prg 2        ; 32KB PRG ROM
.ines_chr 1        ; 8KB CHR ROM
.ines_mapper 0     ; NROM mapper
.ines_mirroring 1  ; vertical mirroring

; Constants
PPU_CTRL = $2000
PPU_MASK = $2001
PPU_STATUS = $2002

; Reset vector
.org $8000

reset:
    sei
    cld
    ldx #$ff
    txs

    lda #$00
    sta PPU_CTRL
    sta PPU_MASK

@wait_vblank1:
    bit PPU_STATUS
    bpl @wait_vblank1

@wait_vblank2:
    bit PPU_STATUS
    bpl @wait_vblank2

main_loop:
    jmp main_loop

; NMI handler
nmi:
    rti

; IRQ handler  
irq:
    rti

; Interrupt vectors
.org $fffa
.word nmi        ; NMI vector
.word reset      ; Reset vector
.word irq        ; IRQ/BRK vector

Advanced Features

Local Labels

subroutine1:
@local_loop:     ; local to subroutine1
    dex
    bne @local_loop
    rts

subroutine2:
@local_loop:     ; different local scope
    dey
    bne @local_loop
    rts

Anonymous Labels

; Forward references (+)
lda #$00
beq +            ; jump to next +
lda #$01
+:
sta $2000

; Backward references (-)
-:
lda ($00),y
sta $2007
iny
bne -            ; jump to previous -

File Inclusion

.include "constants.inc"
.include "macros.inc"

; Binary data inclusion
.org $a000
.incbin "graphics.chr"

Compile-Time Assertions

.assert * < $8000, "Code exceeds PRG ROM bank"
.error "Not implemented yet"
.warning "TODO: Optimize this section"

Examples

Check out the example projects in the examples/ directory:

nes-hello-world - Minimal NES ROM with screen initialization
snes-hello-world - SNES ROM with native mode setup
gb-hello-world - Game Boy ROM displaying "HELLO" text

📖 Documentation

User Guides

Document	Description
User Manual	Complete usage guide with examples
Channel F Development Guide	Channel F/F8 project layout, syntax, and coding patterns
SNES Development Guide	Comprehensive SNES/65816 guide
Game Boy Development Guide	Complete GB/GBC guide with SM83
Atari Lynx Guide	Atari Lynx/65C02 assembly guide
System Syntax Reference	Per-system `.target`, CLI platform commands, and baseline syntax
Build from Project	Nexen → Peony → Poppy pipeline
Project File Format	`.poppy` project configuration
Syntax Specification	Assembly language syntax guide

Migration Guides

Document	Description
Migrating from ASAR	ASAR → Poppy for SNES
Migrating from ca65	ca65/cc65 → Poppy for NES/SNES
Migrating from xkas	xkas → Poppy for SNES
Migrating from RGBDS	RGBDS → Poppy for Game Boy
Migrating from WLA-DX	WLA-DX → Poppy for Z80/6502/65816
Migrating from DASM	DASM → Poppy for Atari 2600
Migrating from ASM68K	ASM68K → Poppy for Genesis
Migrating from devkitARM	devkitARM/GAS → Poppy for GBA

Technical Reference

Document	Description
Architecture	Compiler design and structure
Benchmarks	BenchmarkDotNet suite and ARM special-emission benchmark workflows
PASM File Format	Poppy Assembly `.pasm` file format specification
CDL/DIZ Workflow	Poppy ↔ Peony roundtrip workflow with CDL/DIZ files
File Formats	ROM and patch format reference
Resources	External links and research
Release Notes v1.0.0	Complete v1.0.0 release summary

Planning Documents

Document	Description
Roadmap	Development roadmap and milestones (v1.0 complete!)
v1.x Roadmap	Plans for v1.1-v1.3 (project system, assets, advanced features)
v2.0 Roadmap	Platform expansion (GBA, Genesis, SPC700, LSP, WASM)
v1.0.0 Release Report	Complete v1.0.0 release summary
All Plans	Architecture plans, encoding specs, issue analysis

Internal Documentation

Document	Description
Chat Logs	AI conversation archives
Session Logs	Work session summaries

🎮 Target Projects

Priority compilation targets:

Dragon Warrior 1 (NES) - Simple NES game
Final Fantasy Mystic Quest (SNES) - Simple SNES game
Dragon Warrior 4 (NES) - Complex NES game
Dragon Quest 3 Remake (SNES) - Complex SNES project

📐 Syntax Highlights

Hexadecimal Notation

lda #$40        ; immediate value
sta $2000       ; absolute address
lda $10,x       ; zero page indexed

Labels and References

start:
lda #$01
jsr subroutine
jmp start

subroutine:
inc $10
rts

Include Directives

.include "constants.inc"
.include "macros.inc"

; Asset with convertor (planned)
.asset "graphics.png" png2chr

🏗️ Project Status

Current Version: v2.0.0 (Released 2026)

Completed:

✅ Full NES support (6502, iNES 2.0)
✅ Full SNES support (65816, LoROM/HiROM/ExHiROM)
✅ Full Game Boy support (SM83, MBC1/3/5, CGB modes)
✅ Full Atari 2600 support (6507)
✅ Full Atari Lynx support (65C02)
✅ Complete macro system with parameters
✅ Conditional assembly (.if, .ifdef, .ifndef)
✅ Include system (.include, .incbin)
✅ Debug symbol export (.sym, .nl, .mlb)
✅ Reverse converters (PASM → ASAR/CA65/XKAS)
✅ VS Code extension (published to marketplace)
✅ Comprehensive documentation (21 guides, 5,800+ lines)
✅ Example projects for all platforms
✅ Pansy.Core integration for metadata export
✅ Bank switching support
✅ 3,185 tests passing

Planned:

Language Server Protocol (LSP)
Web-based compiler (WASM)
Plugin system

See v1.x Roadmap and v2.0 Roadmap for details.

📋 Coding Standards

This project follows strict formatting guidelines:

Indentation: TABS only (never spaces)
Brace Style: K&R (opening brace on same line)
Hexadecimal: Always lowercase with $ prefix
Assembly: Lowercase opcodes (lda, sta, jsr)
Encoding: UTF-8 with BOM
Line Endings: CRLF

See .github/copilot-instructions.md for complete guidelines.

🌷 Integrated Pipeline

Poppy is the build stage of the Flower Toolchain — an integrated pipeline for playing, debugging, disassembling, editing, and rebuilding retro games:

Stage	Tool	Poppy Role
1. Play & Debug	Nexen	—
2. Disassemble	Peony	—
3. Edit & Document	Editor + Pansy UI	—
4. Build	Poppy	Compile `.pasm` → ROM, generate Pansy metadata
5. Verify	Game Garden	Roundtrip byte-identical rebuild

See the Integrated Pipeline Master Plan for architecture details.

🤝 Related Projects

Nexen - Multi-system emulator & debugger
🌼 Pansy - Universal disassembly metadata format
🌺 Peony - Multi-system disassembler
🌱 Game Garden - Games disassembly & recompilation
GameInfo - ROM hacking toolkit
BPS-Patch - Binary patching system

📜 License

See the LICENSE file for details (Unlicense)

🔗 References

Inspired by and learning from:

ASAR - SNES patching assembler
XKAS - SNES assembler
Ophis - 6502 assembler
ca65 - Part of cc65 suite

🌸 Poppy - Making retro game development bloom

Name		Name	Last commit message	Last commit date
Latest commit History 365 Commits
.github		.github
.vscode		.vscode
configs		configs
docs		docs
examples		examples
includes		includes
project-base		project-base
src		src
templates		templates
vscode-extension		vscode-extension
~docs		~docs
~manual-testing		~manual-testing
~plans		~plans
.editorconfig		.editorconfig
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.markdownlintignore		.markdownlintignore
LICENSE		LICENSE
README.md		README.md
RELEASE-NOTES-1.0.0.md		RELEASE-NOTES-1.0.0.md
new-project.sh		new-project.sh
package.json		package.json
update-system-directives.ps1		update-system-directives.ps1
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

🌸 Poppy Compiler

🎉 v2.0.0 Released

🎯 Overview

✨ Features

Implemented ✅

🚀 Quick Start

Installation

From GitHub Releases

From Source

VS Code Extension

Usage

Example Assembly (NES/6502)

Advanced Features

Local Labels

Anonymous Labels

File Inclusion

Compile-Time Assertions

Examples

📖 Documentation

User Guides

Migration Guides

Technical Reference

Planning Documents

Internal Documentation

🎮 Target Projects

📐 Syntax Highlights

Hexadecimal Notation

Labels and References

Include Directives

🏗️ Project Status

📋 Coding Standards

🌷 Integrated Pipeline

🤝 Related Projects

📜 License

🔗 References

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages