Development Environment Setup

Get your development environment ready for authentic retro assembly programming. Choose your system and follow our comprehensive Docker-based setup guide.

Choose Your System

👆

Select a system above to see setup instructions

Commodore 64 Development Setup

Ready to start programming the Commodore 64? This guide will get you up and running in minutes, not hours.

Option 1: Docker Quick Start (Recommended)

The fastest way to start coding. Everything pre-configured and ready to go.

1. Install Docker

macOS/Windows: Download Docker Desktop
Linux: Use your package manager (apt install docker.io or similar)

2. Get the Code198x Environment

docker pull stevehill/code198x:commodore-64

3. Create Your First Project

# Create a project directory
mkdir c64-games
cd c64-games

# Run the C64 development environment
docker run -it -v $(pwd):/workspace stevehill/code198x:commodore-64

4. Test Your Setup

Inside the Docker container, create hello.asm:

; hello.asm - Your first C64 program!
        * = $0801           ; BASIC start address

        ; BASIC header: 10 SYS 2064
        !byte $0c,$08       ; Pointer to next line
        !byte $0a,$00       ; Line number (10)
        !byte $9e           ; SYS token
        !text "2064"        ; Address in ASCII
        !byte $00           ; End of line
        !byte $00,$00       ; End of program

        * = $0810           ; Our code starts here
start:
        lda #$00            ; Black color
        sta $d020           ; Border
        sta $d021           ; Background
        
        lda #$01            ; White color
        jsr $e544           ; Clear screen
        
        rts                 ; Return to BASIC

Build it:

acme -f cbm -o hello.prg hello.asm

You now have hello.prg ready to run on a C64 or emulator!

Option 2: Local Installation

Prefer to install tools directly? Here’s how:

1. Install ACME Assembler

macOS:

brew install acme

Windows:

Download ACME from GitHub
Extract to C:\tools\acme
Add C:\tools\acme to your system PATH

Linux:

# Ubuntu/Debian
sudo apt install acme

# Or build from source
git clone https://github.com/meonwax/acme.git
cd acme/src
make
sudo make install

2. Install VICE Emulator

All Platforms: Download from VICE Homepage

macOS Alternative:

brew install vice

3. Verify Your Setup

Create the same hello.asm from above, then:

# Assemble
acme -f cbm -o hello.prg hello.asm

# Run in VICE
x64sc hello.prg

You should see a black screen - your first C64 program!

Your First Real Program

Let’s make something more interesting - a colorful border effect:

; colors.asm - Cycle border colors
        * = $0801
        
        ; BASIC header (same as before)
        !byte $0c,$08,$0a,$00,$9e
        !text "2064"
        !byte $00,$00,$00

        * = $0810
start:
        ldx #$00            ; Color index
loop:
        stx $d020           ; Set border color
        
        ; Wait a bit
        ldy #$40
delay1: ldx #$00
delay2: dex
        bne delay2
        dey
        bne delay1
        
        ldx $d020           ; Get current color
        inx                 ; Next color
        cpx #$10            ; Wrapped around?
        bne loop
        ldx #$00            ; Reset to black
        jmp loop

Build and run:

acme -f cbm -o colors.prg colors.asm
x64sc colors.prg  # Or drag to your emulator

Watch the border cycle through all 16 C64 colors!

Directory Structure

Organize your projects like this:

c64-games/
├── cosmic-harvester/
│   ├── main.asm
│   ├── sprites.asm
│   ├── Makefile
│   └── build/
├── tools/
│   └── sprites/
└── modules/
    ├── screen.asm
    └── input.asm

Next Steps

You’re ready to start Phase 1! Your environment is set up and you’ve already:

✅ Assembled your first program
✅ Run it on an emulator
✅ Made something visual happen

Next lesson: Setting up the Cosmic Harvester game screen

Troubleshooting

“Command not found” errors

Check your PATH includes the tool locations
Try using full paths to commands

VICE won’t start

On macOS: Allow it in Security & Privacy settings
On Linux: Install SDL libraries if missing

Assembly errors

ACME is case-sensitive
Check for typos in mnemonics (it’s lda, not LDA)
Ensure proper spacing around operators

Quick Reference

ACME Commands:

acme -f cbm -o output.prg input.asm    # Standard C64 PRG
acme -f plain -o output.bin input.asm  # Raw binary
acme -r report.txt input.asm           # Generate report

VICE Keys:

Alt+W - Warp mode (fast forward)
Alt+R - Monitor (debugger)
Alt+S - Settings

Ready to make some games? Let’s go! 🚀

ZX Spectrum Development Setup

Ready to program the ZX Spectrum? This guide will get you creating games for Sir Clive’s rubber-keyed wonder in no time.

Option 1: Docker Quick Start (Recommended)

The fastest way to start coding. Everything pre-configured for Spectrum development.

1. Install Docker

macOS/Windows: Download Docker Desktop
Linux: Use your package manager (apt install docker.io or similar)

2. Get the Code198x Environment

docker pull stevehill/code198x:zx-spectrum

3. Create Your First Project

# Create a project directory
mkdir spectrum-games
cd spectrum-games

# Run the Spectrum development environment
docker run -it -v $(pwd):/workspace stevehill/code198x:zx-spectrum

4. Test Your Setup

Inside the Docker container, create hello.asm:

; hello.asm - Your first Spectrum program!
        org     $8000       ; Start at 32768

start:
        ld      a,0         ; Black ink
        ld      (23693),a   ; Set ink color
        ld      a,7         ; White paper
        ld      (23693+1),a ; Set paper color
        
        call    $0daf       ; Clear screen (ROM routine)
        
        ; Print a message
        ld      de,message  ; Point to message
        ld      bc,msg_end-message ; Length
        call    $203c       ; Print string (ROM routine)
        
        ret                 ; Return to BASIC

message:
        defb    22,10,10    ; AT 10,10
        defm    "HELLO SPECTRUM!"
msg_end:

        ; Create TAP file with BASIC loader
        end start

Build it:

sjasmplus hello.asm --lst --tap=hello.tap

You now have hello.tap ready to load on a Spectrum or emulator!

Option 2: Local Installation

Prefer to install tools directly? Here’s how:

1. Install sjasmplus Assembler

macOS:

brew install sjasmplus

Windows:

Download sjasmplus from GitHub
Extract to C:\tools\sjasmplus
Add to your PATH

Linux:

# Build from source
git clone https://github.com/z00m128/sjasmplus.git
cd sjasmplus
make
sudo make install

2. Install Fuse Emulator

All Platforms: Download from Fuse Homepage

macOS Alternative:

brew install fuse-emulator

3. Verify Your Setup

Create the same hello.asm from above, then:

# Assemble
sjasmplus hello.asm --lst --tap=hello.tap

# Run in Fuse
fuse hello.tap

Press ENTER when you see “Program: hello” to run your code!

Your First Real Program

Let’s create the classic Spectrum color bars effect:

; bars.asm - Classic Spectrum color bars
        org     $8000

start:
        ; Clear screen with black
        ld      a,0
        out     ($fe),a     ; Black border
        call    $0daf       ; Clear screen
        
        ; Draw color bars
        ld      hl,$5800    ; Attribute area
        ld      b,8         ; 8 colors
        ld      c,0         ; Color counter
        
next_bar:
        push    bc
        ld      b,3         ; 3 rows per color
        
next_row:
        push    bc
        ld      b,32        ; 32 columns
        
next_col:
        ld      a,c         ; Get color
        rlca                ; Shift to paper bits
        rlca
        rlca
        or      7           ; White ink
        ld      (hl),a      ; Set attribute
        inc     hl
        djnz    next_col
        
        pop     bc
        djnz    next_row
        
        pop     bc
        inc     c           ; Next color
        djnz    next_bar
        
        ret

        end start

Build and run:

sjasmplus bars.asm --lst --tap=bars.tap
fuse bars.tap

Watch the classic Spectrum color bars fill your screen!

TAP File Creation

sjasmplus can create TAP files automatically with a BASIC loader:

        device zxspectrum48

        org     $6000
        
        ; Your code here
start:
        ; ... game code ...
        ret

        ; This creates a TAP with BASIC loader
        savenex open "game.tap", start
        savenex auto
        savenex close
        
        end start

Directory Structure

Organize your Spectrum projects:

spectrum-games/
├── quantum-shatter/
│   ├── main.asm
│   ├── sprites.asm
│   ├── levels.asm
│   ├── Makefile
│   └── build/
├── tools/
│   └── graphics/
└── modules/
    ├── screen.asm
    ├── keyboard.asm
    └── sound.asm

Next Steps

You’re ready to start Phase 1! Your environment is set up and you’ve:

✅ Assembled your first program
✅ Created a TAP file
✅ Made colorful things happen

Next lesson: Creating the Quantum Shatter game screen

Troubleshooting

“Tape loading error”

Make sure to press ENTER when prompted
Try: LOAD "" (then ENTER)

Colors look wrong

Spectrum uses attribute-based color
Each 8x8 block shares ink/paper colors
This is normal - embrace the limitation!

Assembly errors

sjasmplus is case-insensitive
Check org address (must be >= 23755)
Ensure proper label syntax

Quick Reference

sjasmplus Commands:

sjasmplus source.asm --lst --tap=output.tap    # Create TAP file
sjasmplus source.asm --raw=output.bin          # Raw binary
sjasmplus source.asm --sld=debug.sld           # Debug symbols

Fuse Keys:

F1 - Menu
F2 - Load TAP file
F4 - Save snapshot
F10 - Quit

Ready to experience the joys of attribute clash? Let’s go! 🌈

Amiga Development Setup

Ready to harness the power of the Amiga? This guide will get you creating games for Commodore’s multimedia marvel in no time.

Option 1: Docker Quick Start (Recommended)

The fastest way to start coding. Everything pre-configured for Amiga development.

1. Install Docker

macOS/Windows: Download Docker Desktop
Linux: Use your package manager (apt install docker.io or similar)

2. Get the Code198x Environment

docker pull stevehill/code198x:amiga

3. Create Your First Project

# Create a project directory
mkdir amiga-games
cd amiga-games

# Run the Amiga development environment
docker run -it -v $(pwd):/workspace stevehill/code198x:amiga

4. Test Your Setup

Inside the Docker container, create hello.s:

; hello.s - Your first Amiga program!
        section code,code

start:
        ; Set background color to dark blue
        move.w  #$0024,$dff180      ; COLOR00 = dark blue
        
        ; Simple copper list
        lea     copper(pc),a0
        move.l  a0,$dff080          ; COP1LC
        move.w  #0,$dff088          ; COPJMP1
        
        ; Enable DMA
        move.w  #$8380,$dff096      ; DMACON - enable copper & bitplane DMA
        
        ; Wait for mouse click
.wait:
        btst    #6,$bfe001          ; Left mouse button
        bne.s   .wait
        
        ; Exit
        rts

copper:
        dc.w    $0180,$0000         ; COLOR00 = black
        dc.w    $8001,$fffe         ; Wait for line 128
        dc.w    $0180,$0f00         ; COLOR00 = red
        dc.w    $a001,$fffe         ; Wait for line 160
        dc.w    $0180,$00f0         ; COLOR00 = green
        dc.w    $c001,$fffe         ; Wait for line 192
        dc.w    $0180,$000f         ; COLOR00 = blue
        dc.w    $ffff,$fffe         ; End of copper list

        section data,data_c
        ; Data would go here

        end

Build it:

vasmm68k_mot -Fhunkexe -o hello hello.s

You now have hello ready to add to a bootable ADF!

Option 2: Local Installation

Prefer to install tools directly? Here’s how:

1. Install vasm Assembler

All Platforms:

Download vasm from vasm Homepage
Extract and build:

make CPU=m68k SYNTAX=mot

Copy vasmm68k_mot to your PATH

macOS with Homebrew:

# Install build tools if needed
brew install make

# Build vasm
curl -O http://sun.hasenbraten.de/vasm/release/vasm.tar.gz
tar xzf vasm.tar.gz
cd vasm
make CPU=m68k SYNTAX=mot
sudo cp vasmm68k_mot /usr/local/bin/

2. Install FS-UAE Emulator

All Platforms: Download from FS-UAE Homepage

macOS:

brew install fs-uae

3. Install ADF Tools

macOS/Linux:

# Install amitools for ADF manipulation
pip install amitools

Windows: Download ADF Opus

4. Verify Your Setup

Create the same hello.s from above, then:

# Assemble
vasmm68k_mot -Fhunkexe -o hello hello.s

# Create bootable ADF (using amitools)
xdftool create boot.adf bootable
xdftool boot.adf write hello
xdftool boot.adf boot install boot1x

# Run in FS-UAE
fs-uae boot.adf

You should see colored bars on screen!

Your First Real Program

Let’s create a proper Amiga copper bars effect:

; bars.s - Classic Amiga copper bars
        section code,code

start:
        ; Save system state
        move.l  4.w,a6              ; ExecBase
        lea     gfxname(pc),a1
        moveq   #0,d0
        jsr     -552(a6)            ; OpenLibrary()
        move.l  d0,gfxbase
        beq     .exit
        
        move.l  d0,a6
        move.l  34(a6),oldcopper    ; Save old copper list
        
        ; Take over the system
        jsr     -456(a6)            ; OwnBlitter()
        jsr     -462(a6)            ; WaitBlit()
        
        ; Set our copper list
        lea     copper(pc),a0
        move.l  a0,$dff080          ; COP1LC
        move.w  #0,$dff088          ; COPJMP1
        
        ; Enable DMA
        move.w  #$8380,$dff096      ; DMACON
        
        ; Main loop
.loop:
        ; Wait for vertical blank
        move.l  $dff004,d0
        and.l   #$1ff00,d0
        cmp.l   #300<<8,d0
        bne.s   .loop
        
        ; Animate colors
        lea     colors(pc),a0
        move.w  (a0),d0
        move.w  2(a0),(a0)+
        move.w  2(a0),(a0)+
        move.w  2(a0),(a0)+
        move.w  d0,(a0)
        
        ; Check mouse
        btst    #6,$bfe001
        bne.s   .loop
        
        ; Restore system
        move.l  gfxbase(pc),a6
        move.l  oldcopper(pc),$dff080
        jsr     -462(a6)            ; WaitBlit()
        jsr     -228(a6)            ; DisownBlitter()
        
        move.l  4.w,a6
        move.l  gfxbase(pc),a1
        jsr     -414(a6)            ; CloseLibrary()
        
.exit:  moveq   #0,d0
        rts

copper:
        dc.w    $0180,$0000         ; Background black
        dc.w    $2001,$fffe         ; Wait for line 32
        
        ; Generate copper bars
y       set     32
        rept    20
        dc.w    $0180
colors: dc.w    $0f00               ; Red
        dc.w    y<<8+1,$fffe        ; Wait
        dc.w    $0180,$0000         ; Black
        dc.w    (y+8)<<8+1,$fffe    ; Wait
y       set     y+10
        endr
        
        dc.w    $ffff,$fffe         ; End

gfxname:        dc.b    "graphics.library",0
        even
gfxbase:        dc.l    0
oldcopper:      dc.l    0

        end

Build and create ADF:

vasmm68k_mot -Fhunkexe -o bars bars.s
xdftool create bars.adf bootable
xdftool bars.adf write bars
xdftool bars.adf boot install boot1x

Watch the classic Amiga copper bars!

Creating Bootable ADFs

Our games will be bootable ADFs, not Workbench programs:

# Create empty bootable ADF
xdftool create game.adf bootable

# Add your executable
xdftool game.adf write gameexe

# Install boot block
xdftool game.adf boot install boot1x

# Add additional files
xdftool game.adf write graphics.dat
xdftool game.adf write music.mod

Directory Structure

Organize your Amiga projects:

amiga-games/
├── turbo-horizon/
│   ├── main.s
│   ├── copper.s
│   ├── graphics.s
│   ├── Makefile
│   ├── assets/
│   │   ├── sprites.raw
│   │   └── music.mod
│   └── build/
├── tools/
│   └── iff2raw/
└── modules/
    ├── startup.s
    ├── input.s
    └── blitter.s

Makefile Template

# Amiga game makefile
AS = vasmm68k_mot
ASFLAGS = -Fhunkexe -nosym
TARGET = game
ADF = $(TARGET).adf

SRCS = main.s copper.s graphics.s
OBJS = $(TARGET)

all: $(ADF)

$(OBJS): $(SRCS)
	$(AS) $(ASFLAGS) -o $(OBJS) main.s

$(ADF): $(OBJS)
	xdftool create $(ADF) bootable
	xdftool $(ADF) write $(OBJS)
	xdftool $(ADF) boot install boot1x

clean:
	rm -f $(OBJS) $(ADF)

run: $(ADF)
	fs-uae $(ADF)

Next Steps

You’re ready to start Phase 1! Your environment is set up and you’ve:

✅ Assembled your first Amiga program
✅ Created a bootable ADF
✅ Made copper magic happen

Next lesson: Creating the Turbo Horizon game screen

Troubleshooting

“Guru Meditation” errors

Always save/restore system state
Check address register usage
Ensure proper alignment (.even)

ADF won’t boot

Verify boot block installation
Check executable is first file
Ensure proper hunk format

No graphics visible

Check copper list termination
Verify DMA is enabled
Ensure proper display setup

Quick Reference

vasm Commands:

vasmm68k_mot -Fhunkexe -o output input.s    # Standard executable
vasmm68k_mot -Fbin -o output.bin input.s    # Raw binary
vasmm68k_mot -L listing.txt input.s         # Generate listing

ADF Tools:

xdftool create disk.adf bootable             # Create bootable ADF
xdftool disk.adf write file                  # Add file
xdftool disk.adf list                        # List contents
xdftool disk.adf boot install boot1x         # Install boot block

FS-UAE Keys:

F12 - GUI/Menu
Ctrl+F11 - Grab/Release mouse
F12+Q - Quit
F12+S - Save state

Ready to push the Amiga to its limits? Let’s go! 🌈

NES Development Setup

Ready to code for the NES? This guide will get you creating games for Nintendo’s 8-bit powerhouse in no time.

Option 1: Docker Quick Start (Recommended)

The fastest way to start coding. Everything pre-configured for NES development.

1. Install Docker

macOS/Windows: Download Docker Desktop
Linux: Use your package manager (apt install docker.io or similar)

2. Get the Code198x Environment

docker pull stevehill/code198x:nes

3. Create Your First Project

# Create a project directory
mkdir nes-games
cd nes-games

# Run the NES development environment
docker run -it -v $(pwd):/workspace stevehill/code198x:nes

4. Test Your Setup

Inside the Docker container, create hello.asm:

; hello.asm - Your first NES program!
.segment "HEADER"
    .byte "NES", $1A    ; iNES header identifier
    .byte 2             ; 2x 16KB PRG code
    .byte 1             ; 1x  8KB CHR data
    .byte $01, $00      ; mapper 0, vertical mirroring

.segment "VECTORS"
    .addr nmi_handler
    .addr reset_handler
    .addr 0

.segment "STARTUP"

.segment "CODE"
reset_handler:
    sei                 ; disable interrupts
    cld                 ; disable decimal mode
    ldx #$40
    stx $4017           ; disable APU frame IRQ
    ldx #$FF
    txs                 ; Set up stack
    inx                 ; now X = 0
    stx $2000           ; disable NMI
    stx $2001           ; disable rendering
    stx $4010           ; disable DMC IRQs

    ; First wait for vblank
vblankwait1:
    bit $2002
    bpl vblankwait1

    ; Clear memory
clear_memory:
    lda #$00
    sta $0000, x
    sta $0100, x
    sta $0200, x
    sta $0300, x
    sta $0400, x
    sta $0500, x
    sta $0600, x
    sta $0700, x
    inx
    bne clear_memory

    ; Second wait for vblank
vblankwait2:
    bit $2002
    bpl vblankwait2

    ; Now we're ready!
    lda #%10000000      ; Enable NMI
    sta $2000
    
    lda #%00011110      ; Enable sprites and background
    sta $2001

forever:
    jmp forever

nmi_handler:
    rti

.segment "CHARS"
    ; Include 8KB of CHR-ROM data here
    .res 8192, $00      ; Fill with zeros for now

Build it:

ca65 hello.asm -o hello.o
ld65 -C nes.cfg hello.o -o hello.nes

You now have hello.nes ready to run on an NES emulator!

Option 2: Local Installation

Prefer to install tools directly? Here’s how:

1. Install cc65 Suite

macOS:

brew install cc65

Windows:

Download cc65 from GitHub
Extract to C:\tools\cc65
Add C:\tools\cc65\bin to your PATH

Linux:

# Ubuntu/Debian
sudo apt install cc65

# Or build from source
git clone https://github.com/cc65/cc65.git
cd cc65
make
sudo make install

2. Install FCEUX Emulator

All Platforms: Download from FCEUX Homepage

macOS Alternative:

brew install fceux

3. Create NES Config File

Save as nes.cfg:

MEMORY {
    ZP:     start = $00,    size = $100,  type = rw, file = "";
    OAM:    start = $200,   size = $100,  type = rw, file = "";
    RAM:    start = $300,   size = $500,  type = rw, file = "";
    HDR:    start = $0,     size = $10,   type = ro, file = %O, fill = yes;
    PRG:    start = $8000,  size = $8000, type = ro, file = %O, fill = yes;
    CHR:    start = $0,     size = $2000, type = ro, file = %O, fill = yes;
}

SEGMENTS {
    HEADER:   load = HDR,  type = ro;
    STARTUP:  load = PRG,  type = ro;
    CODE:     load = PRG,  type = ro;
    RODATA:   load = PRG,  type = ro;
    DATA:     load = PRG,  run = RAM, type = rw, define = yes;
    VECTORS:  load = PRG,  type = ro, start = $FFFA;
    CHARS:    load = CHR,  type = ro;
    BSS:      load = RAM,  type = bss, define = yes;
    ZEROPAGE: load = ZP,   type = zp;
    OAM:      load = OAM,  type = bss, define = yes;
}

4. Verify Your Setup

Create the same hello.asm from above, then:

# Assemble
ca65 hello.asm -o hello.o

# Link
ld65 -C nes.cfg hello.o -o hello.nes

# Run in FCEUX
fceux hello.nes

You should see a blue screen - your first NES program!

Your First Real Program

Let’s create a simple sprite display:

; sprite.asm - Display a sprite on screen
.segment "HEADER"
    .byte "NES", $1A
    .byte 2
    .byte 1
    .byte $01, $00

.segment "VECTORS"
    .addr nmi_handler
    .addr reset_handler
    .addr 0

.segment "STARTUP"

.segment "CODE"
reset_handler:
    sei
    cld
    ldx #$40
    stx $4017
    ldx #$FF
    txs
    inx
    stx $2000
    stx $2001
    stx $4010

vblankwait1:
    bit $2002
    bpl vblankwait1

clear_memory:
    lda #$00
    sta $0000, x
    sta $0100, x
    sta $0200, x
    sta $0300, x
    sta $0400, x
    sta $0500, x
    sta $0600, x
    sta $0700, x
    inx
    bne clear_memory

vblankwait2:
    bit $2002
    bpl vblankwait2

    ; Load palette
    lda $2002           ; read PPU status to reset latch
    lda #$3F
    sta $2006           ; write high byte of $3F00
    lda #$00
    sta $2006           ; write low byte of $3F00
    
    ldx #$00
load_palette:
    lda palette_data, x
    sta $2007
    inx
    cpx #$20
    bne load_palette

    ; Set up sprite
    lda #$70            ; Y position
    sta $0200
    lda #$00            ; tile number
    sta $0201
    lda #$00            ; attributes
    sta $0202
    lda #$80            ; X position
    sta $0203

    ; Enable rendering
    lda #%10000000
    sta $2000
    lda #%00011110
    sta $2001

forever:
    jmp forever

nmi_handler:
    ; Copy sprite data
    lda #$00
    sta $2003
    lda #$02
    sta $4014
    rti

palette_data:
    .byte $0F,$31,$32,$33  ; background palette
    .byte $0F,$35,$36,$37
    .byte $0F,$39,$3A,$3B
    .byte $0F,$3D,$3E,$0F
    .byte $0F,$1C,$15,$14  ; sprite palette
    .byte $0F,$02,$38,$3C
    .byte $0F,$30,$37,$1A
    .byte $0F,$0F,$0F,$0F

.segment "CHARS"
    ; Simple smiley face tile
    .byte %00111100
    .byte %01000010
    .byte %10100101
    .byte %10000001
    .byte %10100101
    .byte %10011001
    .byte %01000010
    .byte %00111100
    
    .res 8184, $00      ; Fill rest with zeros

Build and run:

ca65 sprite.asm -o sprite.o
ld65 -C nes.cfg sprite.o -o sprite.nes
fceux sprite.nes

You’ll see a smiley face sprite on screen!

Directory Structure

Organize your NES projects:

nes-games/
├── underground-assault/
│   ├── main.asm
│   ├── graphics.asm
│   ├── levels.asm
│   ├── nes.cfg
│   ├── Makefile
│   └── build/
├── tools/
│   └── chr/
└── modules/
    ├── controller.asm
    ├── ppu.asm
    └── sound.asm

Next Steps

You’re ready to start Phase 1! Your environment is set up and you’ve:

✅ Assembled your first NES program
✅ Created a valid NES ROM
✅ Displayed a sprite on screen

Next lesson: Setting up the Underground Assault game screen

Troubleshooting

“Illegal instruction” errors

NES uses 6502 without decimal mode
Some 65C02 instructions aren’t available
Stick to original 6502 opcodes

Black screen

Check your wait for vblank loops
Ensure PPU is properly initialized
Verify CHR data is included

Sprite not showing

Make sure sprite is in visible area (Y: 0-239)
Check sprite enable bit in $2001
Verify OAM DMA in NMI handler

Quick Reference

ca65/ld65 Commands:

ca65 source.asm -o object.o            # Assemble
ld65 -C nes.cfg object.o -o game.nes   # Link to NES ROM
ca65 -l listing.txt source.asm         # Generate listing

FCEUX Keys:

F5/F7 - Save/Load state
F10 - Reset
Shift+F4 - Toggle FPS display
F1 - Toggle PPU viewer

Ready to create some Nintendo magic? Let’s go! 🎮

Start Learning

Once you've set up your development environment, you're ready to start learning!