C64-dev/AGENTS.md

AGENTS.md — Commodore 64 Developer Knowledge Base

Assembled by a collective of 150 expert Commodore 64 developers. This file is the primary reference for AI agents assisting with Commodore 64 application development. Core C64 platform knowledge is sourced from canonical reference books (see Sources below). Supplemental modern emulator workflow guidance is included for VICE 3.10 from C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt.

---

How to Use This Knowledge Base

This repository contains structured skills and reference material for developing software on the Commodore 64. Each subdirectory under skills/ is a self-contained topic skill. When answering a C64 development question, consult the most relevant skill first, then cross-reference the reference/ files.

Skill Index

Directory	Topic	When to Use
skills/6510-assembly/	6510 CPU, opcodes, addressing modes, registers	Writing or debugging assembly/ML programs
skills/memory-map/	Complete C64 memory layout, zero page, banking	Memory management, PEEK/POKE, ML placement
skills/graphics-vic2/	VIC-II chip, sprites, character modes, color	All graphics programming
skills/sound-sid/	SID 6581, ADSR, waveforms, filters	Music and sound effects
skills/disk-io-1541/	1541 DOS, file types, direct access	Disk operations, file I/O
skills/kernal-routines/	OS jump table, screen/serial/tape I/O	Using built-in OS calls from ML
skills/basic-programming/	BASIC 2.0 interpreter, extending BASIC, tokens	BASIC programs, BASIC extensions
skills/interrupts/	IRQ, NMI, CIA timers, raster interrupts	Interrupt-driven code, timing
skills/compiler-design/	Compiler & assembler construction for C64/128	Writing compilers, assemblers, parsers
skills/vice-emulator/	VICE emulator, autostart, monitor, snapshots, automation	Running, testing, and debugging C64 software in VICE

Reference Files

File	Contents
reference/memory-map-complete.md	All C64 memory locations with descriptions
reference/6510-opcodes.md	Full 6510 opcode table
reference/kernal-jumplist.md	All Kernal jump table addresses and parameters
reference/vic-registers.md	VIC-II chip register map
reference/sid-registers.md	SID chip register map
reference/cia-registers.md	CIA 6526 register map
reference/disk-dos-commands.md	1541 DOS command reference
reference/vice-usage.md	VICE 3.10 emulator, monitor, autostart, and automation reference

Example Programs

File	Description
examples/hello-world.asm	Minimal 6510 assembly hello world
examples/sprite-demo.bas	BASIC sprite programming demo
examples/sound-demo.bas	SID chip sound demo in BASIC
examples/disk-access.bas	Sequential and relative file access
examples/irq-handler.asm	Custom IRQ handler skeleton
examples/kernal-io.asm	Using Kernal routines for I/O
examples/vice-autostart-c64os.bat	Launch c64os.prg directly in x64sc
examples/vice-monitor-c64os.txt	VICE monitor playback script for debugging c64os.prg
examples/vice-debug-c64os.bat	Launch c64os.prg with VICE native monitor and debug-friendly options
examples/vice-monitor-c64os-debug.txt	Repeatable VICE debugging session with breakpoints, watchpoints, and keyboard injection

---

System Overview

The Commodore 64 (1982) features:

• CPU: MOS 6510 (6502-compatible, 1 MHz NTSC / ~0.985 MHz PAL)
• RAM: 64KB (not all simultaneously accessible)
• ROM: 20KB total — 8KB BASIC ($A000–$BFFF), 8KB Kernal ($E000–$FFFF), 4KB Character ROM ($D000 when banked in)
• Graphics: VIC-II (MOS 6567 NTSC / 6569 PAL) at $D000–$D3FF
• Sound: SID MOS 6581 at $D400–$D7FF
• I/O: Two CIA 6526 chips at $DC00–$DCFF (CIA #1) and $DD00–$DDFF (CIA #2)
• Screen: 40×25 text, 320×200 bitmap, 160×200 multicolor
• Colors: 16 colors
• Sprites: 8 hardware sprites (24×21 pixels each)

---

Memory Architecture Quick Reference

$0000–$00FF  Zero Page      — CPU registers, BASIC/Kernal variables (fast access)
$0100–$01FF  Stack          — 6510 hardware stack
$0200–$03FF  Pages 2–3      — OS/BASIC working storage, vectors
$0400–$07FF  Screen RAM     — Default video matrix (40×25 = 1000 bytes)
$0800–$9FFF  BASIC RAM      — BASIC program area (default: $0801–$9FFF)
$A000–$BFFF  BASIC ROM      — Microsoft BASIC 2.0 (or RAM when banked out)
$C000–$CFFF  Free RAM       — ML programs, data (4KB always RAM)
$D000–$D3FF  VIC-II         — Graphics chip registers (I/O mode)
$D400–$D7FF  SID            — Sound chip registers (I/O mode)
$D800–$DBFF  Color RAM      — Screen color data (nybble wide, 1000 bytes)
$DC00–$DCFF  CIA #1         — Keyboard, joystick, IRQ timer
$DD00–$DDFF  CIA #2         — Serial bus, NMI timer, VIC-II bank select
$E000–$FFFF  Kernal ROM     — Operating system (or RAM when banked out)

Memory bank control — Location $0001 (6510 I/O port):

Bits 2-0:  000 = RAM everywhere
           101 = BASIC+Kernal ROM, I/O (default)
           110 = Kernal ROM + I/O, BASIC=RAM
           111 = All ROM + I/O (normal)

---

Critical Zero-Page Locations

Address	Dec	Name	Description
$0000	0	R6510	6510 I/O direction register
$0001	1	M6510	6510 I/O port (memory bank/tape)
$0002	2	—	Unused (free for user)
$0003-$0004	3-4	ADRAY1	Float→fixed vector
$0005-$0006	5-6	ADRAY2	Fixed→float vector
$0007	7	CHARAC	Search character
$0014-$0015	20-21	—	Integer value
$002B-$002C	43-44	TXTTAB	Start of BASIC program
$002D-$002E	45-46	VARTAB	Start of variable area
$0030-$0031	48-49	FRETOP	Top of string storage
$0037-$0038	55-56	MEMSIZ	Pointer to end of BASIC RAM
$0039-$003A	57-58	CURLIN	Current BASIC line number
$003E-$003F	62-63	OLDLIN	Previous BASIC line number
$0052-$0053	82-83	OLDTXT	Previous BASIC text pointer
$007A-$007B	122-123	FNPNT	Floating point accumulator
$00AC-$00AD	172-173	STRNG1	Start of string 1
$00C1	193	SAL	Save start address (low)
$00C2	194	SAH	Save start address (high)
$00AE-$00AF	174-175	FRESPC	String utility pointer
$00FB-$00FE	251-254	—	Free zero-page (user)

---

Kernal Jump Table Quick Reference

All Kernal routines are called via JSR to their jump table address ($FFxx). The jump table is always available regardless of ROM banking mode.

Address	Name	Function
$FF81	CINT	Initialize screen editor
$FF84	IOINIT	Initialize I/O devices
$FF87	RAMTAS	Test/initialize RAM
$FF8A	RESTOR	Restore default I/O vectors
$FF8D	VECTOR	Read/set RAM vectors
$FF90	SETMSG	Control OS messages
$FF93	SECOND	Send secondary address after LISTEN
$FF96	TKSA	Send secondary address after TALK
$FF99	MEMTOP	Read/set top of memory
$FF9C	MEMBOT	Read/set bottom of memory
$FF9F	SCNKEY	Scan keyboard
$FFA2	SETTMO	Set serial bus timeout
$FFA5	ACPTR	Input byte from serial bus
$FFA8	CIOUT	Output byte to serial bus
$FFAB	UNTLK	Send UNTALK to serial bus
$FFAE	UNLSN	Send UNLISTEN to serial bus
$FFB1	LISTEN	Command device to LISTEN
$FFB4	TALK	Command device to TALK
$FFB7	READST	Read I/O status word
$FFBA	SETLFS	Set logical/device/command
$FFBD	SETNAM	Set filename
$FFC0	OPEN	Open logical file
$FFC3	CLOSE	Close logical file
$FFC6	CHKIN	Open channel for input
$FFC9	CHKOUT	Open channel for output
$FFCC	CLRCH	Close input/output channels
$FFCF	BASIN	Input character from channel
$FFD2	BSOUT	Output character to channel
$FFD5	LOAD	Load from device
$FFD8	SAVE	Save to device
$FFDB	SETTIM	Set real-time clock
$FFDE	RDTIM	Read real-time clock
$FFE1	STOP	Test STOP key
$FFE4	GETIN	Get character from queue
$FFE7	CLALL	Close all files
$FFEA	UDTIM	Increment real-time clock
$FFED	SCREEN	Return screen dimensions
$FFF0	PLOT	Read/set cursor position
$FFF3	IOBASE	Return base address of I/O

---

Source Books

This knowledge base was compiled from these canonical references:

1. The Anatomy of the Commodore 64 — Angerhausen, Becker, Englisch, Gerits (Abacus/Data Becker)
2. The Machine Language Book for the Commodore 64 — Lothar Englisch (Abacus)
3. The Advanced Machine Language Book for the Commodore 64 — (Abacus)
4. COMPUTE!‘s Mapping the Commodore 64 — Sheldon Leemon (COMPUTE! Publications)
5. COMPUTE!‘s VIC-20 and Commodore 64 Tool Kit: BASIC — Dan Heeb (COMPUTE!)
6. COMPUTE!‘s VIC-20 and Commodore 64 Tool Kit: Kernal — (COMPUTE!)
7. The Anatomy of the 1541 Disk Drive (Revised Edition) — (Abacus)
8. The Complete Commodore 64 ROM Disassembly — P.G. & K.B. (Melbourne House)
9. Compiler Design and Implementation (64 and 128) — (Abacus)
10. COMPUTE!‘s SpeedScript — (COMPUTE!) — word processor source & techniques
11. Invaluable Utilities for the Commodore 64 — (various)

Supplemental Emulator Source

1. VICE 3.10 Manual — C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt

• Use for emulator operation, autostart behavior, monitor commands, snapshots, and automation interfaces

---

Agent Workflow

When an AI agent receives a C64 development question:

1. Identify the domain using the Skill Index table above
2. Load the relevant SKILL.md from the appropriate skills/ subdirectory
3. Cross-reference reference/ files for specific register values, addresses, or opcodes
4. Check examples/ for working code patterns
5. If the task involves running or debugging software in an emulator, load skills/vice-emulator/SKILL.md and reference/vice-usage.md
6. Apply the 150-expert consensus: prefer documented Kernal routines over custom implementations; use zero-page for speed; always consider memory banking when accessing $D000–$DFFF

---

VICE Debug Workflow

When debugging a C64 program in VICE, agents should prefer this flow:

1. Launch x64sc rather than the older x64
2. Prefer -nativemonitor -keepmonopen -refreshonbreak for interactive debugging
3. Start the monitor session with sidefx off
4. Break at the machine-code entry point or suspicious routine
5. Use step, next, return, and backtrace intentionally rather than single-stepping blindly
6. Use watchpoints for critical C64 state such as $0001, $0314/$0315, screen RAM, color RAM, and I/O registers
7. Use monitor playback files from examples/ to make debug sessions repeatable
8. Use snapshots for short-lived checkpoints only, not archival state

For this repository specifically:

• examples/vice-debug-c64os.bat launches c64os.prg with monitor-friendly options
• examples/vice-monitor-c64os-debug.txt sets up a practical debug session for startup, banking, and command input

---

Common Development Patterns

Running ML from BASIC

10 FOR I=49152 TO 49162 : READ D : POKE I,D : NEXT
20 SYS 49152
30 DATA 169,0,141,32,208,169,15,141,33,208,96

Protecting ML from BASIC

POKE 56,192 : CLR  ' Sets BASIC top to $C000 (49152)

Reading the Kernal status after I/O

JSR $FFB7  ; READST — status in Accumulator
BNE error  ; any non-zero means error

Setting up a custom IRQ

SEI                 ; disable interrupts
LDA #<my_irq       ; low byte of handler
STA $0314
LDA #>my_irq       ; high byte
STA $0315
CLI                 ; enable interrupts