# 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 12. **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 ```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 ```basic POKE 56,192 : CLR ' Sets BASIC top to $C000 (49152) ``` ### Reading the Kernal status after I/O ```asm JSR $FFB7 ; READST — status in Accumulator BNE error ; any non-zero means error ``` ### Setting up a custom IRQ ```asm SEI ; disable interrupts LDA #my_irq ; high byte STA $0315 CLI ; enable interrupts ```