# VICE 3.10 Usage Reference
> Supplemental emulator reference distilled from `C:\Program Files\GTK3VICE-3.10-win64\doc\vice.txt`

This file is a practical subset of the VICE 3.10 manual for AI agents working on Commodore 64 software in this repository.

---

## Preferred C64 Executable

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

Other useful VICE tools installed alongside it:

- `c1541.exe` — disk image tool
- `petcat.exe` — BASIC text/token conversion
- `cartconv.exe` — cartridge conversion
- `vsid.exe` — SID playback

---

## Autostart

Equivalent manual-documented forms:

```text
x64sc mydisk.d64
x64sc -autostart myprog.prg
x64sc -autostart "demo.d64:loader"
```

Useful switches:

| Option | Purpose |
|--------|---------|
| `-autostart-warp` | Enable warp mode during autostart |
| `-autostart-handle-tde` | Temporarily manage True Drive Emulation for autostart |
| `-basicload` | Use BASIC-start load behavior when autostarting from disk |
| `+basicload` | Use `,1` absolute load behavior when autostarting from disk |
| `-autostartprgdiskimage <name>` | Choose the disk image used when autostarting a PRG via disk-copy mode |

Notes:

- For raw `.prg`/P00 files, VICE restores autostart-related settings after load
- If a program must reach the host filesystem, enable virtual device traps

---

## Debug Launch Options

| Option | Meaning |
|--------|---------|
| `-nativemonitor` | Run the monitor in the spawning terminal |
| `-keepmonopen` | Keep the monitor open after continuing execution |
| `-refreshonbreak` | Refresh display when entering monitor and after monitor commands |
| `-monlog` | Log monitor output to a file |
| `-monlogname <name>` | Choose the monitor log filename |
| `-remotemonitor` | Enable the text remote monitor server |
| `-remotemonitoraddress ip4://127.0.0.1:6510` | Bind address for the text monitor server |
| `-binarymonitor` | Enable the binary monitor protocol server |
| `-binarymonitoraddress ip4://127.0.0.1:6502` | Bind address for the binary monitor server |

Recommended debug launch for this repo:

```text
"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak
```

---

## High-Value Debug Commands

| Command | Use |
|---------|-----|
| `r` / `registers` | Show or edit registers |
| `x` / `exit` | Resume execution |
| `q` / `quit` | Quit VICE |
| `step [count]` | Step into |
| `next [count]` | Step over |
| `return` | Run until next `RTS` or `RTI` |
| `until <address>` | Run until a target address |
| `bt` / `backtrace` | Show JSR call chain |
| `goto <address>` | Set PC |
| `m <range>` | Dump memory |
| `i <range>` | View memory as PETSCII |
| `d <range>` | Disassemble |
| `io [address]` | Show I/O register state |
| `break exec $addr` | Execution breakpoint |
| `watch store $addr` | Write watchpoint |
| `trace exec $a $b` | Non-stopping trace |
| `bank` | Show/select banks |
| `device c:` / `8:` | Switch computer or drive memory space |
| `sidefx off` | Avoid side-effect-causing reads while inspecting memory |
| `keybuf "text\x0d"` | Inject keyboard input |
| `playback "file"` | Execute a monitor script file |
| `record "file"` | Record a debug session as commands |

Examples:

```text
break exec $0810
watch store $0001
d $0810 $0840
m $0000 $0002
bt
return
playback "examples/vice-monitor-c64os.txt"
```

Conditional checkpoints support register expressions, raster line `RL`, and cycle `CY`.

Useful conditional examples from the manual style:

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

Checkpoint management:

```text
command 2 "m $0000 $0002"
ignore 2 1
disable 1
enable 1
delete 1
```

Debugging-specific watch targets:

- `$0001` for memory banking writes
- `$0314-$0315` for IRQ vector changes
- `$0318-$0319` for NMI vector changes
- `$0400-$07E7` for screen RAM writes
- `$D800-$DBE7` for color RAM writes

---

## Practical Debug Workflow

1. Launch with `-nativemonitor -keepmonopen -refreshonbreak`
2. Enter `sidefx off`
3. Break at entry with `break exec $0810`
4. Disassemble nearby code with `d`
5. Inspect registers with `r`
6. Use `step` to go into a routine, `next` to stay out of KERNAL internals, and `return` to escape a routine quickly
7. Add watchpoints once the suspicious state is known
8. Use `bt` if execution reached an unexpected location
9. Save a snapshot only for short-lived debugging checkpoints

---

## Snapshots

VICE snapshots:

- save complete emulator state
- can include drive state
- restore memory configuration on load

Important manual warning:

- snapshots are convenient for debugging, but should not be treated as stable long-term storage across VICE versions

---

## Repo-Focused Launch Examples

Build and run the current program:

```text
build.bat
"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp
```

Open with terminal monitor ready for debugging:

```text
"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak
```

Open with monitor logging enabled:

```text
"C:\Program Files\GTK3VICE-3.10-win64\bin\x64sc.exe" -autostart c64os.prg -autostart-warp -nativemonitor -keepmonopen -refreshonbreak -monlog -monlogname vice-monitor.log
```