C64-dev/skills/vice-emulator/SKILL.md

---

name: vice-emulator description: > Use this skill when you need to run, autostart, debug, snapshot, or automate Commodore 64 programs in the VICE emulator. Covers x64sc, command-line autostart, warp mode, true drive emulation handling, the built-in monitor, remote and binary monitor servers, and snapshot caveats. Source: VICE 3.10 manual (C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt).

VICE Emulator Workflow for the Commodore 64

This skill is primarily about debugging programs with VICE, not just launching them.

When to Use This Skill

Use this skill when you need to:

• Launch a .prg, .d64, .g64, .tap, or cartridge image in VICE
• Choose the correct C64 emulator executable
• Autostart software for test runs
• Open the VICE monitor and set breakpoints or watchpoints
• Save or restore snapshots during debugging
• Automate VICE from an agent via the remote or binary monitor

If the user asks to “debug the assembly,” “trace startup,” “find where banking breaks,” or “step through a PRG,” this is the first skill to load.

---

Preferred C64 Emulator

For C64 work, prefer:

• x64sc — accurate C64 emulator with cycle-based and pixel-accurate VIC-II emulation

The VICE manual notes that:

• x64 was the older fast emulator
• x64sc is the accurate emulator and the default choice for serious debugging

Useful companion tools in the VICE package:

• c1541 — disk image tool
• petcat — BASIC tokenization/detokenization tool
• cartconv — cartridge image conversion
• vsid — SID player

---

Command-Line Autostart

The VICE manual documents two equivalent ways to autostart:

x64sc mydisk.d64
x64sc -autostart myprog.prg

You can also select a named file inside an image:

x64sc "demo.d64:loader"
x64sc -autostart "demo.d64:loader"

Helpful options for agent workflows:

-autostart-warp
-autostart-handle-tde
-basicload
+basicload

Notes from the manual:

• -autostart-warp temporarily enables warp mode during autostart
• -autostart-handle-tde lets VICE temporarily manage True Drive Emulation during autostart
• For raw .prg/P00 files, VICE loads the file and then restores the previous autostart settings
• If the started program must access the host filesystem, enable virtual device traps

---

Native, Remote, and Binary Monitor

VICE supports three monitor-related workflows that are useful for agents:

Native Monitor

-nativemonitor
+nativemonitor

When enabled, the monitor runs in the spawning terminal instead of only inside the emulator UI.

Remote Monitor

-remotemonitor
-remotemonitoraddress ip4://127.0.0.1:6510

This enables the text-based remote monitor server.

Binary Monitor

-binarymonitor
-binarymonitoraddress ip4://127.0.0.1:6502

This enables the binary monitor protocol used by automation tools and external debuggers.

Recommended Debug Launch

For agent-driven debugging, prefer launching VICE with:

x64sc -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak

Useful companion options from the manual:

-monlog
-monlogname vice-monitor.log

These make the monitor visible in the terminal, keep it open after continuing, refresh screen state on breaks, and optionally log monitor output.

---

Core Debugging Commands

These monitor commands are the most useful for day-to-day program debugging:

Command	Meaning
x / exit	Leave the monitor and resume execution
q / quit	Exit VICE
r / registers	Show or modify registers
reset [type]	Reset the machine or drive
goto <address>	Set the program counter
next [count]	Step over instructions
step [count]	Step into instructions
return	Run until the next RTS or RTI
until <address>	Run until an address is reached, then break
bt / backtrace	Show the JSR call chain
m <range>	Show memory
i <range>	Show memory as PETSCII
d <range>	Disassemble
io [address]	Inspect I/O registers or a chip block
break exec $addr	Break on execution
watch store $addr	Break when an address is written
trace exec $addr1 $addr2	Trace execution without stopping
bank	Show/select banks
device c: / 8:	Switch computer vs drive address space
sidefx off	Prevent monitor reads from causing hardware side effects
keybuf "text\x0d"	Feed characters into the keyboard buffer
playback "file"	Execute commands from a monitor script
record "file"	Record monitor commands for replay

Examples:

break exec $0810
watch store $0001
d $0810 $0840
m $0000 $0002
bt
return

Conditional checkpoints are supported. The manual documents register-based conditions and raster-aware conditions such as RL and CY.

---

Breakpoints, Watchpoints, and Tracepoints

VICE supports several complementary debugging styles:

1. Breakpoints

Use when you care about where execution reaches:

break exec $0810
until $0930

2. Watchpoints

Use when you care about what wrote or read a memory location:

watch store $0001
watch load $dc0d

For C64 debugging, watchpoints are especially useful for:

• $0001 — memory banking changes
• $0314/$0315 — IRQ vector changes
• $d020/$d021 — border/background color debugging
• $0400-$07e7 — screen RAM writes
• $d800-$dbe7 — color RAM writes

3. Tracepoints

Use when you need a non-stopping execution log:

trace exec $0810 $08ff

4. Conditional Checkpoints

The VICE manual supports conditions using registers, arithmetic, boolean operators, raster line RL, cycle CY, and bank-qualified memory references.

Examples:

break exec $0810 if A == $00
break load 0 $ffff if @cpu:(pc - $1) == $37

5. Checkpoint Automation

The monitor can attach commands to checkpoints:

command 2 "m $0000 $0002"
ignore 2 1
disable 1
enable 1

This is useful when you want an automatic memory dump the first time a watchpoint hits.

---

Stepping Strategy

Use these commands intentionally:

• step for stepping into a subroutine
• next for stepping over a subroutine
• return for stepping out of the current subroutine
• until <address> to run quickly to a known target
• backtrace to recover the call chain after a break

Recommended sequence for a new bug:

1. Break at the program entry or suspicious routine
2. d the nearby code
3. r to inspect registers
4. step or next depending on whether you need to enter subroutines
5. backtrace if you need to know how execution reached the current point
6. Add watchpoints once you identify suspicious state

---

Safe Inspection Rules

The monitor manual explicitly documents side-effectful reads.

For C64 work:

• start with sidefx off
• use device c: for the main machine and device 8: when debugging a true-emulated drive CPU
• use bank if you need to inspect the CPU-visible versus I/O-visible memory view
• use io $d000, io $d400, io $dc00, or io $dd00 when you want chip-level register context

---

Monitor Script Files

VICE can execute a command file from inside the monitor, and can also record command sequences:

playback "examples/vice-monitor-c64os.txt"
record "my-session.txt"

This is the easiest way for an agent to set up a repeatable debug session.

In this repository, prefer:

• examples/vice-monitor-c64os.txt for startup and banking inspection
• examples/vice-monitor-c64os-debug.txt for a fuller debugging session with labels, checkpoints, and keyboard injection

---

Debugging Recipes

Debugging PRG Startup

1. Launch with -nativemonitor -keepmonopen -refreshonbreak
2. break exec $0810
3. d $0801 $0840
4. step through startup or next over known KERNAL calls

Debugging Banking Problems

1. watch store $0001
2. Add command <n> "m $0000 $0002" to dump the port state when it hits
3. Use bank and io to inspect what memory view is active

Debugging Command Input

1. Break at your parser or input loop
2. Use keybuf "help\x0d" to push test input into the keyboard buffer
3. Use i on the input buffer to inspect PETSCII text

Debugging IRQ/Vector Corruption

1. watch store $0314 $0315
2. watch store $0318 $0319
3. Use bt and d when the watchpoint hits
4. If needed, inspect chip state with io $dc00 and io $d000

---

Snapshots

VICE snapshots save the complete emulator state, including memory configuration and optionally attached drives.

Use snapshots for:

• fast retry points during debugging
• preserving an emulator state mid-session
• short-lived reproduction cases

Do not use snapshots for:

• permanent archival storage
• cross-version compatibility guarantees

The VICE manual explicitly warns that snapshot compatibility is not reliable across versions.

---

Recommended Repo Workflow

For this repository:

1. Build the program with build.bat
2. Launch c64os.prg with x64sc -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak
3. Run playback "examples/vice-monitor-c64os-debug.txt" for an immediate debug setup
4. Use watch store $0001 to confirm banking writes
5. Use step, next, return, and backtrace to narrow the failing routine
6. Use snapshots for quick iteration, not long-term storage

---

Common Pitfalls

1. x64sc is the preferred accurate emulator; do not default to the older x64
2. Autostart behavior changes depending on PRG vs image file
3. True Drive Emulation can affect autostart speed and compatibility
4. Monitor reads can have side effects unless you disable them with sidefx off
5. Stepping without choosing between step, next, and return can waste a lot of time in KERNAL code
6. Forgetting device 8: vs device c: can make you debug the wrong CPU when true drive emulation is involved
7. Snapshots are convenient, but the manual warns against treating them as stable long-term artifacts