# C64 Developer Knowledge Base
### Built by 150 Expert Commodore 64 Developers

A comprehensive reference system for AI agents and human developers building applications on the Commodore 64. Synthesized from 11 canonical C64 reference books, with supplemental VICE 3.10 emulator workflow notes for modern testing and debugging.

---

## Source Books

1. *The Anatomy of the Commodore 64*
2. *The Machine Language Book for the Commodore 64*
3. *The Advanced Machine Language Book for the Commodore 64*
4. *Compute's Mapping the Commodore 64*
5. *Compute's VIC-20 & C64 Tool Kit: BASIC*
6. *Compute's VIC-20 & C64 Tool Kit: Kernal*
7. *The Anatomy of the 1541 Disk Drive (Revised Edition)*
8. *The Complete Commodore 64 ROM Disassembly*
9. *Compiler Design and Implementation (64 and 128)*
10. *Compute's SpeedScript*
11. *Invaluable Utilities for the Commodore 64*

---

## File Structure

```
c64-dev-knowledge/
├── README.md               ← This file
├── CLAUDE.md               ← AI agent entry point
├── AGENTS.md               ← Full AI reference document
│
├── skills/                 ← Topic skill files (SKILL.md in each)
│   ├── 6510-assembly/      ← CPU, registers, opcodes, idioms
│   ├── memory-map/         ← Address space, banking, zero page
│   ├── graphics-vic2/      ← VIC-II modes, sprites, raster IRQ
│   ├── sound-sid/          ← SID registers, music, effects
│   ├── disk-io-1541/       ← 1541 DOS, file types, error codes
│   ├── kernal-routines/    ← Kernal jump table, I/O patterns
│   ├── basic-programming/  ← BASIC internals, extending BASIC
│   ├── interrupts/         ← IRQ/NMI handlers, CIA, VIC timing
│   ├── compiler-design/    ← Assembler/compiler construction
│   └── vice-emulator/      ← VICE launch, monitor, autostart, automation
│
├── reference/              ← Quick-lookup tables
│   ├── memory-map-complete.md  ← Full $0000–$FFFF address map
│   ├── 6510-opcodes.md         ← All opcodes with cycles/flags
│   ├── vic-registers.md        ← VIC-II $D000–$D02E register table
│   ├── sid-registers.md        ← SID $D400–$D418 register table
│   ├── cia-registers.md        ← CIA #1 and #2 register tables
│   ├── kernal-jumplist.md      ← All Kernal jump table entries
│   ├── disk-dos-commands.md    ← DOS commands, error codes, disk layout
│   └── vice-usage.md           ← VICE 3.10 emulator and monitor quick reference
│
└── examples/               ← Working code examples
    ├── hello-world.asm     ← Minimal 6510 assembly hello world
    ├── irq-handler.asm     ← Custom raster IRQ installation
    ├── kernal-io.asm       ← File I/O using Kernal routines
    ├── bitmap-demo.asm     ← Hi-res 320×200 bitmap mode
    ├── sprite-demo.bas     ← Sprite animation in BASIC
    ├── sprite-music-demo.bas ← Multicolor sprite + SID music
    ├── sound-demo.bas      ← SID waveforms, ADSR, chords
    ├── disk-access.bas     ← Sequential/relative file I/O
    ├── vice-autostart-c64os.bat ← Launch c64os.prg in x64sc
    ├── vice-debug-c64os.bat ← Launch c64os.prg with VICE native monitor
    ├── vice-monitor-c64os.txt ← VICE monitor playback commands
    └── vice-monitor-c64os-debug.txt ← Repeatable VICE debug session
```

---

## Quick-Start by Topic

| I want to… | Start here |
|-----------|-----------|
| Write 6510 machine code | `skills/6510-assembly/SKILL.md` |
| Understand the memory map | `skills/memory-map/SKILL.md` + `reference/memory-map-complete.md` |
| Program sprites or bitmap graphics | `skills/graphics-vic2/SKILL.md` |
| Make sound or music | `skills/sound-sid/SKILL.md` |
| Read/write disk files | `skills/disk-io-1541/SKILL.md` |
| Use Kernal routines | `skills/kernal-routines/SKILL.md` + `reference/kernal-jumplist.md` |
| Extend or interface with BASIC | `skills/basic-programming/SKILL.md` |
| Write custom IRQ handlers | `skills/interrupts/SKILL.md` |
| Build a compiler or assembler | `skills/compiler-design/SKILL.md` |
| Run or debug software in VICE | `skills/vice-emulator/SKILL.md` + `reference/vice-usage.md` |
| Look up an opcode | `reference/6510-opcodes.md` |
| Look up a chip register | `reference/vic-registers.md`, `sid-registers.md`, `cia-registers.md` |
| Find a Kernal routine | `reference/kernal-jumplist.md` |
| Understand a disk error | `reference/disk-dos-commands.md` |

---

## AI Agent Instructions

See **CLAUDE.md** for the primary agent entry point.
See **AGENTS.md** for the comprehensive reference used by AI to answer C64 development questions.

All skill files follow a consistent structure:
1. Overview
2. Hardware/ROM details with addresses
3. Code patterns and templates
4. Worked examples
5. Common pitfalls

Supplemental emulator material is intentionally kept separate from the canonical platform references so agents can distinguish between C64 hardware facts and modern tooling workflows.

## VICE Debugging

For emulator debugging, start with `skills/vice-emulator/SKILL.md`, then use `reference/vice-usage.md` as the command quick reference.

The most useful repo examples are:

- `examples/vice-debug-c64os.bat` for launching `c64os.prg` in `x64sc` with native monitor, keep-open, and refresh-on-break enabled
- `examples/vice-monitor-c64os-debug.txt` for a repeatable monitor session with breakpoints, watchpoints, stepping hints, and keyboard-buffer injection

---

## C64 Hardware at a Glance

| Component | Details |
|-----------|---------|
| CPU | MOS 6510 @ 1.02MHz (PAL) / 0.985MHz (NTSC) |
| RAM | 64 KB (with banking) |
| ROM | 20 KB (BASIC 8KB + Kernal 8KB + Char 4KB) |
| Video | MOS 6569 VIC-II (PAL) / 6567 (NTSC) |
| Sound | MOS 6581/8580 SID — 3 voices, 4 waveforms, filter |
| I/O | MOS 6526 CIA × 2 (keyboard, joystick, serial, timer) |
| Storage | Commodore 1541 (170KB, 35 tracks, GCR encoding) |
| Display | 40×25 text / 320×200 hi-res / 160×200 multicolor |
| Sprites | 8 hardware sprites (24×21 pixels each) |
| Colors | 16 fixed colors |