z80gfx Homebrew Computer

START Quick Start Guide

Get up and running in under 3 minutes. This section walks you through running your first program, and understanding the basic workflow for writing software.

Step 1: Run Something

# Built-in Hello World
z80emu

# Built-in demo with graphics + sound
z80emu_gui

# Run the Snake game
z80emu_gui snake.bin

# Run Nascom BASIC (real-world ROM)
z80emu_gui ROM_32K.HEX

# Self-test suite (21 CPU tests)
z80emu --test

# Interactive debugger
z80emu -d snake.binCopy

Step 2: Understand the Workflow

START Hello World Tutorial

Here's the simplest possible program that prints text. This works on both the console and GUI builds:

; hello.asm - Prints "Hello!" via the ACIA data port
; Assemble to hello.bin, run with: z80emu_gui hello.bin

    ORG  $0000

    LD   SP, $FFFF       ; Initialize stack pointer
    LD   HL, message     ; Point HL to our string
print_loop:
    LD   A, (HL)         ; Load next character
    OR   A               ; Test for null terminator
    JR   Z, done         ; If zero, we're done
    OUT  ($81), A        ; Output character via ACIA
    INC  HL              ; Advance to next character
    JR   print_loop      ; Loop

done:
    HALT                 ; Stop the CPU

message:
    DB   "Hello from z80gfx!", 13, 10, 0Copy

31 FF FF     ; LD SP, $FFFF
21 0D 00     ; LD HL, $000D  (address of message)
7E           ; LD A, (HL)
B7           ; OR A
28 05        ; JR Z, +5
D3 81        ; OUT ($81), A
23           ; INC HL
18 F7        ; JR -9  (back to LD A,(HL))
76           ; HALT
48 65 6C ... ; "Hello from z80gfx!\r\n\0"

Hello World with Graphics (GUI only)

This version clears the screen, draws a pattern to VRAM, beeps, and sets the border colour:

; graphical_hello.asm - Graphics + Sound + Terminal demo

    ORG  $0000
    LD   SP, $FFFF

    ; Print to terminal
    LD   HL, message
    CALL print_str

    ; Clear VRAM
    LD   HL, $C000        ; VRAM base
    LD   DE, $1800        ; 6144 bytes
clr:
    LD   (HL), 0
    INC  HL
    DEC  DE
    LD   A, D
    OR   E
    JR   NZ, clr

    ; Draw a horizontal line at row 96 (center of screen)
    LD   HL, $C000 + (96 * 32)   ; = $CC00
    LD   B, 32                    ; 32 bytes = full row width
line:
    LD   (HL), $FF
    INC  HL
    DJNZ line

    ; Play a 440 Hz beep
    LD   A, $B8
    OUT  ($40), A         ; Freq low byte (440 & $FF)
    LD   A, $81
    OUT  ($41), A         ; Freq high ($01) + gate ON ($80)

    ; Short delay
    LD   BC, $FFFF
delay:
    DEC  BC
    LD   A, B
    OR   C
    JR   NZ, delay

    ; Silence beeper
    LD   A, $01
    OUT  ($41), A         ; Gate OFF

    ; Set border to dark blue
    LD   A, 4
    OUT  ($42), A

    HALT

print_str:
    LD   A, (HL)
    OR   A
    RET  Z
    OUT  ($81), A
    INC  HL
    JR   print_str

message:
    DB   27, "[2J"        ; ANSI: clear screen
    DB   27, "[H"         ; ANSI: cursor home
    DB   "z80gfx says hello!", 13, 10, 0Copy

1 System Overview

The z80gfx is a homebrew 8-bit computer built around the Zilog Z80 CPU, implemented as a software emulator. It comes in two flavours that share the same CPU core (z80.h) and disassembler (z80disasm.h).

Console Build: z80emu Console

The original single-file build with no external dependencies. Compiles from main.cpp alone. Provides:

• Text-only I/O through stdin/stdout
• Full interactive debugger (breakpoints, stepping, disassembly, memory/register inspection)
• 21-test CPU self-test suite (--test)
• Built-in Hello World and uppercase echo ROMs
• Intel HEX and raw binary file loading
• Cross-platform: Windows (MSVC/MinGW), Linux, macOS

GUI Build: z80emu_gui GUI

The raylib-based graphical build. Compiled from main_gui.cpp, links raylib (auto-fetched by CMake). Adds:

• 256×192 monochrome framebuffer panel (VRAM at $C000)
• 80×25 ANSI terminal panel with escape sequence support
• Square-wave beeper with 15-bit frequency control
• Border colour control (16-colour palette)
• F1 soft-reset
• Window size: 1312 × 932 pixels

2 Memory Map

The z80gfx has a flat 64 KB address space with no bank switching or MMU. All memory is freely readable and writable. The following layout is used by convention in the GUI build:

VRAM Layout Detail

The framebuffer occupies $C000-$F7FF (6,144 bytes). It represents a 256×192 monochrome bitmap in row-major order. Each byte represents 8 horizontal pixels, with the MSB being the leftmost pixel.

Address of pixel (x, y):
  byte_addr = $C000 + (y * 32) + (x / 8)
  bit_mask  = $80 >> (x % 8)

To set pixel:    mem[byte_addr] |=  bit_mask     ; turn ON
To clear pixel:  mem[byte_addr] &= ~bit_mask     ; turn OFF
To flip pixel:   mem[byte_addr] ^=  bit_mask     ; toggle

Byte layout:
  Bit:    7   6   5   4   3   2   1   0
  Pixel: [0] [1] [2] [3] [4] [5] [6] [7]
         MSB (leftmost)           LSB (rightmost)

Row stride: 32 bytes
Total: 192 rows × 32 bytes = 6,144 bytesCopy

The renderer uses palette[15] (white) for set bits and palette[0] (black) for clear bits. There is no attribute memory or colour-per-tile system in the current video mode.

Tile Coordinates

For tile-based games using 8×8 pixel tiles, the framebuffer forms a 32×24 tile grid. The address calculation is very efficient:

; Convert tile (tx, ty) to VRAM address
; H = ty + $C0        (high byte = VRAM page + tile row)
; L = tx              (low byte = tile column)
; This gives the first byte of the 8-row tile.
; Each subsequent row is +32 bytes.

; Example: draw solid tile at (10, 5)
    LD   A, 5
    ADD  A, $C0        ; H = $C5
    LD   H, A
    LD   L, 10         ; L = $0A  ->  HL = $C50A
    LD   B, 8          ; 8 rows
    LD   DE, 32        ; row stride
    LD   A, $FF        ; solid fill pattern
.loop:
    LD   (HL), A
    ADD  HL, DE
    DJNZ .loopCopy

3 I/O Port Reference

I/O ports are accessed with the Z80 IN and OUT instructions. The emulator matches on the low byte of the port address only (port & $FF). Both builds share keyboard and ACIA ports; the GUI build adds video and sound.

Complete Port Map

Simple I/O Ports ($00–$01)

Port $00 (Read) — Keyboard Status

Returns $FF if at least one keypress is waiting, $00 if empty. Non-blocking.

; Poll-wait for a keypress
wait_key:
    IN   A, ($00)        ; read keyboard status
    OR   A               ; test if zero
    JR   Z, wait_key     ; loop until key available
    IN   A, ($01)        ; read the key
    ; A now holds the ASCII codeCopy

Port $01 (Read) — Character Input

Returns the next character from the keyboard queue. Console build: blocks until a key is available. GUI build: returns 0 if empty (non-blocking).

Port $01 (Write) — Character Output

Sends a character to the display. Console: stdout. GUI: the on-screen ANSI terminal panel.

    LD   A, 'H'          ; ASCII $48
    OUT  ($01), A         ; print 'H'
    LD   A, 'i'           ; ASCII $69
    OUT  ($01), A         ; print 'i'Copy

6850 ACIA Ports ($80–$81)

The ACIA provides a serial-port-style interface compatible with the Motorola 6850, as used in Grant Searle's designs. Functionally equivalent to the simple ports, but adds a status register for polled I/O — making it compatible with existing Z80 software like Nascom BASIC.

Port $80 (Read) — ACIA Status Register

; Standard ACIA polling pattern (used by BASIC ROMs)
acia_rx_wait:
    IN   A, ($80)        ; read ACIA status
    AND  $01             ; test RDRF bit
    JR   Z, acia_rx_wait ; loop until character ready
    IN   A, ($81)        ; read the character
    RET

acia_tx:                 ; Output character in A
    PUSH AF
.wait:
    IN   A, ($80)        ; check TDRE (always ready here)
    AND  $02
    JR   Z, .wait
    POP  AF
    OUT  ($81), A        ; transmit
    RETCopy

Beeper Ports ($40–$41) GUI

The beeper generates a square wave. Frequency is a 15-bit unsigned integer in Hz (direct 1:1 mapping). Bit 7 of port $41 is the on/off gate.

Port $40 (Write) — Frequency Low Byte

Sets bits 0–7 of the frequency register. High byte is preserved from the last $41 write.

Port $41 (Write) — Frequency High Byte + Gate

; Play 440 Hz (concert A) then silence
    LD   A, $B8           ; 440 & $FF = $B8
    OUT  ($40), A         ; freq low byte
    LD   A, $81           ; (440 >> 8) | $80 = $01 | $80 = $81
    OUT  ($41), A         ; freq high + gate ON
    ; ... delay ...
    LD   A, $01           ; freq hi $01, gate OFF (bit 7 clear)
    OUT  ($41), A         ; silenceCopy

Musical Note Frequency Table

Video Ports ($42–$43) GUI

Port $42 (Write) — Border Colour

Sets the border colour surrounding the framebuffer. Accepts palette index 0–15.

    LD   A, 4             ; dark blue
    OUT  ($42), ACopy

Port $43 (Write) — Video Mode (Reserved)

Reserved for future colour modes. Currently a no-op. Only mode 0 (256×192 mono) exists.

Colour Palette

16 CGA-style colours used for border and terminal text:

4 Video System (VRAM) GUI

Common VRAM Operations

Clear Screen

clear_screen:
    LD   HL, $C000       ; VRAM start
    LD   DE, $1800       ; 6144 bytes to clear
.loop:
    LD   (HL), 0         ; zero = all pixels off
    INC  HL
    DEC  DE
    LD   A, D
    OR   E               ; test DE == 0
    JR   NZ, .loop
    RETCopy

Draw 8×8 Solid Tile

; Input: B = tile_x (0-31), C = tile_y (0-23), A = pattern byte
draw_tile:
    PUSH AF
    LD   A, C
    ADD  A, $C0          ; H = tile_y + VRAM page base
    LD   H, A
    LD   L, B            ; L = tile_x
    LD   DE, 32          ; row stride
    POP  AF
    LD   B, 8            ; 8 rows per tile
.loop:
    LD   (HL), A         ; write pattern to row
    ADD  HL, DE          ; advance to next pixel row
    DJNZ .loop
    RETCopy

Draw Custom 8×8 Sprite from Data

; Input: B = tile_x, C = tile_y, IX = pattern data (8 bytes)
draw_sprite:
    LD   A, C
    ADD  A, $C0
    LD   H, A
    LD   L, B
    LD   DE, 32
    LD   B, 8
.loop:
    LD   A, (IX+0)       ; load pattern row
    LD   (HL), A         ; write to VRAM
    INC  IX
    ADD  HL, DE          ; next pixel row
    DJNZ .loop
    RET

; Sprite data examples:
spr_heart:  DB $00,$66,$FF,$FF,$FF,$7E,$3C,$18
spr_arrow:  DB $10,$30,$7F,$FF,$7F,$30,$10,$00
spr_ball:   DB $18,$3C,$7E,$7E,$7E,$7E,$3C,$18Copy

Set Individual Pixel

; Input: B = x (0-255), C = y (0-191)
set_pixel:
    LD   H, 0
    LD   L, C            ; HL = y
    ADD  HL, HL          ; *2
    ADD  HL, HL          ; *4
    ADD  HL, HL          ; *8
    ADD  HL, HL          ; *16
    ADD  HL, HL          ; *32 (y * 32)
    LD   A, B
    SRL  A
    SRL  A
    SRL  A               ; A = x / 8
    LD   E, A
    LD   D, 0
    ADD  HL, DE          ; + byte column
    LD   DE, $C000
    ADD  HL, DE          ; + VRAM base
    ; Build bit mask
    LD   A, B
    AND  $07             ; x mod 8
    LD   B, A
    LD   A, $80          ; leftmost bit
    JR   Z, .apply
.shift:
    SRL  A               ; shift mask right
    DJNZ .shift
.apply:
    OR   (HL)            ; merge with existing
    LD   (HL), A
    RETCopy

Scroll Screen Up by 1 Tile Row

scroll_up_tile:
    LD   HL, $C100       ; source = tile row 1
    LD   DE, $C000       ; dest = tile row 0
    LD   BC, $1700       ; 23 tile rows * 256 bytes
    LDIR                 ; block copy
    ; Clear bottom tile row
    LD   HL, $F700
    LD   B, 0            ; 256 bytes
.clr:
    LD   (HL), 0
    INC  HL
    DJNZ .clr
    RETCopy

Draw Horizontal Line

; Draw a full-width horizontal line at pixel row Y
; Input: C = y (0-191)
draw_hline:
    LD   H, 0
    LD   L, C
    ADD  HL, HL
    ADD  HL, HL
    ADD  HL, HL
    ADD  HL, HL
    ADD  HL, HL          ; HL = y * 32
    LD   DE, $C000
    ADD  HL, DE          ; HL = VRAM addr of row start
    LD   B, 32
    LD   A, $FF
.loop:
    LD   (HL), A
    INC  HL
    DJNZ .loop
    RETCopy

5 Terminal System (ANSI) GUI

The GUI build includes an 80×25 character terminal panel below the framebuffer. Characters written to port $01 or $81 appear on this terminal. It supports a subset of ANSI/VT100 escape sequences.

Control Characters

ANSI Escape Sequences

Format: ESC [ params command where params are semicolon-separated numbers.

; Terminal control examples
esc_clear:    DB  $1B, "[2J", $1B, "[H", 0      ; clear screen + cursor home
esc_red:      DB  $1B, "[31m", 0                  ; red foreground
esc_green:    DB  $1B, "[32m", 0                  ; green foreground
esc_bright:   DB  $1B, "[92m", 0                  ; bright green
esc_reset:    DB  $1B, "[0m", 0                   ; reset to default
esc_pos:      DB  $1B, "[5;10H", 0                ; cursor to row 5, col 10Copy

6 Sound System (Beeper) GUI

Single-channel square wave generator. 50% duty cycle, 22,050 Hz sample rate, 15-bit frequency control (0–32,767 Hz). The audio callback runs on a separate thread; frequency and gate values are atomic.

Programming Pattern

; Play a note
;   1. Write freq low byte to port $40
;   2. Write freq high | $80 to port $41 (gate ON)
;   3. Delay for desired duration
;   4. Write freq high (without $80) to port $41 (gate OFF)

; Play frequency in DE (Hz) for B duration units
play_tone:
    LD   A, E
    OUT  ($40), A         ; freq low
    LD   A, D
    AND  $7F
    OR   $80              ; set gate bit
    OUT  ($41), A         ; freq high + ON
.wait:
    PUSH BC
    LD   BC, $2000        ; inner delay
.inner:
    DEC  BC
    LD   A, B
    OR   C
    JR   NZ, .inner
    POP  BC
    DJNZ .wait
    ; Silence
    LD   A, D
    AND  $7F              ; gate OFF
    OUT  ($41), A
    RETCopy

Sound Effect Examples

; Short beep (440 Hz, ~20ms)
beep:
    LD   A, $B8
    OUT  ($40), A
    LD   A, $81
    OUT  ($41), A
    LD   C, 16
.outer:
    LD   B, 0
.inner:
    DJNZ .inner
    DEC  C
    JR   NZ, .outer
    LD   A, $01
    OUT  ($41), A          ; silence
    RET

; Rising tone (power-up sound)
rising:
    LD   DE, $0100         ; start at 256 Hz
    LD   C, 30
.step:
    LD   A, E
    OUT  ($40), A
    LD   A, D
    OR   $80
    OUT  ($41), A
    LD   B, 0
.dly:
    DJNZ .dly
    INC  DE
    INC  DE
    INC  DE                ; raise pitch
    DEC  C
    JR   NZ, .step
    LD   A, 0
    OUT  ($41), A
    RETCopy

7 Keyboard Input

Three Input Methods

; Method 1: Simple port polling (both builds)
wait_key:
    IN   A, ($00)         ; keyboard status
    OR   A
    JR   Z, wait_key      ; loop until ready
    IN   A, ($01)         ; read key
    RET

; Method 2: ACIA status polling (compatible with BASIC ROMs)
acia_read:
    IN   A, ($80)         ; ACIA status
    AND  $01              ; test RDRF
    JR   Z, acia_read
    IN   A, ($81)         ; read character
    RET

; Method 3: Non-blocking check (good for game loops)
check_key:
    IN   A, ($00)
    OR   A
    RET  Z                ; Z flag set = no key available
    IN   A, ($01)         ; A = key, Z clear
    RETCopy

Key Codes

*ESC is reserved by raylib for window close and is not passed to Z80 programs.

Interrupt-Driven Input

The emulator triggers interrupts cooperatively when keys are pending and IFF1 is set (~every 1,024 instructions in GUI). Use IM 1 for the simplest setup:

    ORG  $0000
    LD   SP, $FFFF
    IM   1                ; interrupts jump to $0038
    EI                    ; enable interrupts
    JP   main

    ORG  $0038            ; IM 1 vector
isr:
    PUSH AF
    IN   A, ($81)         ; read the key
    LD   ($2000), A       ; store it
    LD   A, 1
    LD   ($2001), A       ; set flag
    POP  AF
    EI
    RETI

main:
    LD   A, ($2001)       ; check flag
    OR   A
    JR   Z, main
    XOR  A
    LD   ($2001), A       ; clear flag
    LD   A, ($2000)       ; process key
    OUT  ($81), A         ; echo it
    JR   mainCopy

8 Z80 CPU Reference

Registers

Main Registers:           Shadow (Alternate) Set:
  16-bit  Hi   Lo          (swapped with EX AF,AF' and EXX)
  ------  ---  ---         AF'  BC'  DE'  HL'
  AF      A    F (flags)
  BC      B    C         Index Registers:
  DE      D    E           IX   (16-bit, displacement addressing)
  HL      H    L           IY   (16-bit, displacement addressing)

  SP   Stack Pointer     Special:
  PC   Program Counter     I    Interrupt Vector (high byte for IM 2)
                           R    Refresh Counter (7-bit + preserved bit 7)Copy

A (Accumulator) is the primary register for arithmetic and I/O. HL is the primary memory pointer. BC is commonly used as a counter (B for DJNZ loops, BC for LDIR/LDDR). DE is commonly a destination pointer. F holds the CPU flags (see Flag Register).

Addressing Modes

9 Instruction Set Summary

Complete instruction set as implemented in the emulator. r = B/C/D/E/H/L/A, rr = BC/DE/HL/SP, cc = condition code.

Load & Exchange

Arithmetic

Logic & Bit Manipulation

Rotate & Shift

Jump, Call & Return

Condition Codes

I/O & Block Operations

10 Flag Register

Bit:  7    6    5    4    3    2    1    0
Flag: S    Z    -    H    -    P/V  N    C

Hex masks:
  S   = $80   Sign flag (bit 7 of result)
  Z   = $40   Zero flag (result == 0)
  H   = $10   Half-Carry (carry from bit 3 to bit 4)
  P/V = $04   Parity (even 1-bits) or Overflow (signed)
  N   = $02   Subtract flag (set by SUB/SBC/CP/DEC/NEG)
  C   = $01   Carry flag (unsigned overflow / borrow)Copy

Flag Effects by Instruction Group

* = affected by result, V = overflow, P = parity, 0 = cleared, 1 = set, — = unchanged

11 Interrupt System

Interrupt Modes

Emulator Timing

• Console: checks every ~10,000 instructions if a key is pending
• GUI: checks every ~1,024 instructions during each frame
• Only triggered when IFF1 is set (interrupts enabled via EI)
• Keyboard input is the only interrupt source (no timer)

DI / EI / HALT Behaviour

• DI — Disables maskable interrupts (IFF1 = IFF2 = 0)
• EI — Enables interrupts. Takes effect after the next instruction.
• HALT — Stops CPU. Only an interrupt (if enabled) or reset resumes it.
• RETI/RETN — Copies IFF2 to IFF1, pops PC. Always use EI before RETI in your ISR.

12 Debugger Reference Console

Launch with: z80emu -d [rom.bin [addr]]

; Example debugger session:
z80emu> r
AF=0042 BC=0000 DE=0000 HL=000D SP=FFFF PC=0003
IX=0000 IY=0000 I=00 R=03 IM=0 IFF1=0 IFF2=0
Flags: S=0 Z=1 H=0 P=0 N=0 C=0
0003: 7E             LD A,(HL)

z80emu> b 0008        ; set breakpoint at $0008
z80emu> c             ; continue to breakpoint
z80emu> m C000 20     ; dump first 32 bytes of VRAM
z80emu> l             ; disassemble from current PCCopy

13 File Loading

Intel HEX Format (.hex)

Files with .hex extension are auto-detected and parsed. Each line: :LLAAAATT[DD...]CC

Raw Binary Format

All other files are loaded as raw binary blobs, copied directly into memory at the specified address.

z80emu rom.bin            # load at $0000
z80emu rom.bin 100        # load at $0100
z80emu -d rom.bin 100     # debug with load at $0100
z80emu_gui snake.bin      # GUI, load at $0000
z80emu ROM_32K.HEX        # Intel HEX auto-detectedCopy

Creating ROM Files

Options for creating binary ROMs:

• Z80 cross-assembler: z80asm, zmac, Pasmo, TASM, NASM-z80
• Python scripts: see tools/make_snake.py and tools/make_pong.py for a mini assembler approach
• Manual hex editing: hand-assemble opcodes and save as binary

14 Programming Techniques

Program Template

; Minimal z80gfx GUI program
    ORG  $0000
    LD   SP, $FFFF        ; ALWAYS init stack first
    LD   A, 4
    OUT  ($42), A         ; border = dark blue

    CALL clear_screen

    ; === Your code here ===

    HALT                  ; stop CPU

clear_screen:
    LD   HL, $C000
    LD   DE, $1800
.loop:
    LD   (HL), 0
    INC  HL
    DEC  DE
    LD   A, D
    OR   E
    JR   NZ, .loop
    RETCopy

Delay Loops

; Short (~8ms)              ; Medium (~250ms)
short_delay:                medium_delay:
    LD   B, 0                   LD   BC, $6000
.loop:                     .loop:
    DJNZ .loop                  DEC  BC
    RET                         LD   A, B
                                OR   C
; Long (~1 second)              JR   NZ, .loop
long_delay:                     RET
    LD   D, 4
.outer:
    LD   BC, $FFFF
.inner:
    DEC  BC
    LD   A, B
    OR   C
    JR   NZ, .inner
    DEC  D
    JR   NZ, .outer
    RETCopy

Testing 16-bit Zero (Common Pattern)

; The Z80 does NOT set flags on DEC rr (16-bit decrement).
; To test if DE or BC reached zero:

    DEC  DE               ; decrement 16-bit pair
    LD   A, D             ; copy high byte to A
    OR   E                ; OR with low byte
    JR   NZ, loop         ; Z flag set only if both bytes are 0

; This works for BC too:
    DEC  BC
    LD   A, B
    OR   C
    JR   NZ, loopCopy

Random Number Generator

; LCG: rand = 5*rand + 1 (mod 256)
; Full-period per Hull-Dobell theorem
; Output: A = pseudo-random byte
rand_byte:
    LD   A, (rand_seed)
    LD   B, A             ; save copy
    ADD  A, A             ; *2
    ADD  A, A             ; *4
    ADD  A, B             ; *5
    ADD  A, 1             ; +1
    LD   (rand_seed), A
    RET

; Restrict to range 0..N-1 (N must be power of 2):
    CALL rand_byte
    AND  N-1              ; e.g. AND $1F for 0-31Copy

String Printing

; Print null-terminated string via ACIA
; Input: HL = string address
print_str:
    LD   A, (HL)
    OR   A                ; test for null
    RET  Z                ; return when done
    OUT  ($81), A         ; output character
    INC  HL
    JR   print_str

; Print A register as 2-digit hex
print_hex:
    PUSH AF
    SRL  A
    SRL  A
    SRL  A
    SRL  A                ; high nibble
    CALL print_nibble
    POP  AF
    AND  $0F              ; low nibble
print_nibble:
    CP   10
    JR   C, .digit
    ADD  A, 'A' - 10
    JR   .out
.digit:
    ADD  A, '0'
.out:
    OUT  ($81), A
    RETCopy

Game Loop Architecture

game_init:
    LD   SP, $FFFF
    LD   A, 4
    OUT  ($42), A         ; border colour
    CALL clear_screen
    CALL draw_playfield
    CALL init_game_state

game_loop:
    CALL delay            ; frame timing
    CALL read_input       ; poll keyboard (non-blocking)
    CALL update_logic     ; move objects, check collisions
    CALL draw_frame       ; update VRAM
    JP   game_loop

; Non-blocking input for game loops:
read_input:
    IN   A, ($80)         ; ACIA status
    AND  $01              ; test RDRF
    RET  Z                ; no key = return
    IN   A, ($81)         ; read key
    ; CP 'w' / CP 'a' / CP 's' / CP 'd' etc.
    RETCopy

15 Game Example: Snake GUI

734 bytes. Demonstrates tile graphics, keyboard input, collision detection, sound, circular buffers, and RNG. Run: z80emu_gui snake.bin

RAM Variable Map

Key Design Decisions

; Direction encoding: UP=0, RIGHT=1, DOWN=2, LEFT=3
; Reverse detection: (current XOR new) == 2 means opposite
;   UP(0) XOR DOWN(2)    = 2  -> reject
;   LEFT(3) XOR RIGHT(1) = 2  -> reject
;   All other combos != 2     -> accept

; Page-aligned circular buffer trick:
;   Buffer at $2300 means H is always $23.
;   L register wraps naturally at 256.
;   head_idx and tail_idx are just L values.
;   Advancing by 2 bytes (one segment) = INC L; INC L.Copy

16 Game Example: Pong GUI

512 bytes. Pixel-level rendering, physics, AI opponent, wall/paddle collision, beeper sound. Run: z80emu_gui pong.bin

Pixel-to-VRAM Address Calculation

; Convert (byte_column, pixel_row) to VRAM address
; Used for drawing vertical sprites (ball, paddles)
    LD   H, 0
    LD   L, y             ; HL = pixel row
    ADD  HL, HL           ; *2
    ADD  HL, HL           ; *4
    ADD  HL, HL           ; *8
    ADD  HL, HL           ; *16
    ADD  HL, HL           ; *32  (y * bytes_per_row)
    LD   E, xb            ; byte column
    LD   D, 0
    ADD  HL, DE           ; + column offset
    LD   DE, $C000
    ADD  HL, DE           ; + VRAM base
    ; Draw vertical column:
    LD   B, height
    LD   DE, 32           ; row stride
.loop:
    LD   (HL), A          ; A = $FF (draw) or $00 (erase)
    ADD  HL, DE
    DJNZ .loopCopy

17 Quick Reference Card

MEMORY MAP
$0000-$1FFF  ROM (8K)        $C000-$F7FF  VRAM (6K, 256x192 mono)
$2000-$BFFF  RAM (40K)       $F800-$FFFF  Stack (2K, grows down)

I/O PORTS
$00 R  Key status ($FF/00)   $40 W  Beeper freq lo
$01 RW Char I/O              $41 W  Beeper freq hi + gate (bit 7)
$80 R  ACIA status           $42 W  Border colour (0-15)
$81 RW ACIA data             $43 W  Video mode (reserved)

VRAM ADDRESSING
Base: $C000  End: $F7FF  Row stride: 32 bytes
Pixel (x,y):  addr = $C000 + y*32 + x/8    mask = $80 >> (x%8)
Tile (tx,ty): H = ty + $C0, L = tx          8 rows, stride 32

BEEPER
Sound ON:   OUT ($40), freq_lo    OUT ($41), (freq_hi & $7F) | $80
Sound OFF:  OUT ($41), freq_hi & $7F

ESSENTIAL PATTERNS
Init:          LD SP, $FFFF       Test DE==0:   LD A,D / OR E / JR NZ
Loop N times:  LD B,N / DJNZ      Print char:   LD A,ch / OUT ($81),A
Poll key:      IN A,($80) / AND 1 Block copy:   LDIR (HL->DE, BC bytes)
Read key:      IN A,($81)         Set pixel:    OR (HL) / LD (HL),A

REGISTERS
Main:    AF(acc+flags) BC DE HL SP PC    Shadow: AF' BC' DE' HL'
Index:   IX IY  (displacement: IX+d, IY+d, d = -128..+127)
Special: I(interrupt vector) R(refresh)   Flags: S Z H P/V N C

COLOURS
 0 Black       4 Dk Blue      8  Dk Grey     12 Br Blue
 1 Dk Red      5 Dk Magenta   9  Br Red      13 Br Magenta
 2 Dk Green    6 Dk Cyan      10 Br Green    14 Br Cyan
 3 Brown       7 Lt Grey      11 Yellow      15 White

COMMAND LINE
Console:  z80emu [-d] [rom.bin [addr]]  |  --test  |  --echo
GUI:      z80emu_gui [rom.bin [addr]]     (F1 = reset)
Debugger: s=step c=continue r=regs l=list m=memory b=break q=quit