16KB

Ham Suçlama Geçmiş

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 the manual installed as C:\Program Files\GTK3VICE-3.10-win64\doc\vice.pdf (copy kept at reference/vice.pdf).

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
`skills/powerc/`	Power C compiler on the C64	Writing, compiling, linking, and running C programs (reference/POWERc.d81)

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
`reference/vice.pdf`	VICE 3.10 manual as shipped with the emulator
`reference/POWERc.d81`	Power C compiler, libraries, and headers (copy before writing to it)
`reference/Power_C_Instruction_Manual.pdf`	Power C Instruction Manual (Spinnaker, 1986)

Example Programs

File	Description
`examples/hello-world.asm`	Minimal 6510 assembly hello world
`examples/bitmap-demo.asm`	Hi-res 320×200 bitmap mode: draws a diagonal line, key returns to text mode
`examples/sprite-demo.bas`	BASIC sprite programming demo
`examples/sprite-music-demo.bas`	Multicolor sprite moving to a SID bass line
`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/moonlander.c`	Lunar Lander game in C (cc65), joystick control
`examples/moonlander.prg`	Built `moonlander.c` binary
`examples/moonlander-build.bat`	Build `moonlander.c` with `cl65`; `-run` also launches it
`examples/run.bat`	Rebuild if needed, then autostart `moonlander.prg` in VICE
`examples/linked-list-test.c`	`malloc`-backed linked list tests plus a heap capacity probe (cc65)
`examples/linked-list-test.prg`	Built `linked-list-test.c` binary
`examples/linked-list-test-build.bat`	Build `linked-list-test.c` with `cl65`; `-run` also launches it
`examples/powerc-hello.c`	Minimal Power C program; ASCII source converted to PETSCII for the disk
`examples/powerc-hello.d81`	Power C work disk with `hello.c` compiled, linked, and ready to run
`examples/powerc-work.d81`	Writable working copy of the Power C system disk
`examples/powerc-build.bat`	Run a Power C Shell command sequence on a work disk via `-keybuf`
`examples/powerc-ced.bat`	Boot the Power C system disk and enter the `ced` editor
`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:

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

Supplemental Emulator Source

VICE 3.10 Manual — C:\Program Files\GTK3VICE-3.10-win64\doc\vice.pdf (copy: reference/vice.pdf)

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

Agent Workflow

When an AI agent receives a C64 development question:

Identify the domain using the Skill Index table above
Load the relevant SKILL.md from the appropriate skills/ subdirectory
Cross-reference reference/ files for specific register values, addresses, or opcodes
Check examples/ for working code patterns
If the task involves running or debugging software in an emulator, load skills/vice-emulator/SKILL.md and reference/vice-usage.md
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

Development Conventions

Write machine addresses in hexadecimal with a $ prefix (for example, $D000 and $FFD2). Include decimal equivalents when an address is used with BASIC PEEK or POKE (for example, $D000 = 53248).
Check memory banking before accessing $A000–$FFFF; the CPU may see ROM, RAM, I/O, or character ROM depending on the 6510 port at $0001.
Prefer Kernal routines for standard I/O and use zero page for variables that benefit from faster access. Keep BASIC's memory ceiling below machine code that BASIC might otherwise overwrite.
State whether timing-sensitive code assumes PAL or NTSC, especially for raster timing and sound frequencies.

Hardware Limits to Check

Resource	Limit or behavior
Default BASIC program area	`$0801–$9FFF` (38,911 addressable bytes; usable free space is lower)
6510 hardware stack	`$0100–$01FF` (256 bytes)
Default screen matrix	`$0400–$07E7` (1,000 visible character cells)
Color RAM	`$D800–$DBE7` (1,000 visible 4-bit color cells when I/O is mapped in)
VIC-II address space	One 16KB bank at a time, selected by CIA #2 at `$DD00`, bits 0–1
Sprite data	64 bytes per block; at most 256 block positions in a 16KB VIC bank
SID reads	`$D400–$D418` are write-only; `$D419–$D41C` provide paddle, oscillator 3, and envelope 3 readings
Character ROM	CPU-readable at `$D000–$DFFF` only under the appropriate `$0001` banking configuration

Development Tools

VICE is the emulator used by the examples in this repository. Common modern assemblers include KickAssembler, ACME, ca65, and 64tass; CBM .prg Studio is a Windows IDE, C64 debugger provides visual debugging with VICE integration, and Exomizer and Pucrunch are executable crunchers. Period tools include SUPERMON, Mikro Assembler, PAL, and Simon's BASIC.

VICE Debug Workflow

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

Launch x64sc rather than the older x64
Prefer -nativemonitor -keepmonopen -refreshonbreak for interactive debugging
Start the monitor session with sidefx off
Break at the machine-code entry point or suspicious routine
Use step, next, return, and backtrace intentionally rather than single-stepping blindly
Use watchpoints for critical C64 state such as $0001, $0314/$0315, screen RAM, color RAM, and I/O registers
Use monitor playback files from examples/ to make debug sessions repeatable
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

Assembly program skeleton

        *=$C000             ; assemble at $C000 (49152)
START   JSR $FF81           ; CINT: initialize the screen editor
        ; program code goes here
        RTS                 ; return to BASIC when entered with SYS 49152

16KB Ham Suçlama Geçmiş