# Switching from Classic VICE to ViceSharp

A side-by-side reference for users who already drive classic VICE (`x64sc`, `c1541`, etc.) and want to try ViceSharp as a drop-in alternative. For the broader install / first-run story, start at [USER-GUIDE.md](USER-GUIDE.md).

## 1. Binary mapping

| Classic VICE | ViceSharp launcher | Status |
|--------------|--------------------|--------|
| `x64` | `x64` (binary-name dispatch) | Supported via the launcher library; maps to the cycle-exact C64 host (ViceSharp does not maintain a separate "fast" variant). No `x64.exe` ships yet. |
| `x64sc` | `x64sc` (console shell) | Supported via the console shell: `ViceSharp.Console` parses its arguments as binary name `x64sc`. Identical topology to `x64`; both go through the same cycle-exact path. No `x64sc.exe` ships yet. |
| `c1541` | `c1541` (binary-name dispatch) | Supported as a standalone 1541 disk-tool topology (single drive, optional D64 mount) in the launcher library. No `c1541.exe` ships yet. |
| `x128` | `x128.exe` | Not yet. Throws `NotSupportedException`. C128 is iteration 3. |
| `xvic` | `xvic.exe` | Not yet. VIC-20 is iteration 2. |
| `xpet` | `xpet.exe` | Not yet. PET is iteration 4. |
| `xplus4` | `xplus4.exe` | Not yet. Plus/4 / C16 is iteration 5. |
| `xcbm2` / `xcbm5x0` | same names | Not yet. CBM-II is post-MVP. |
| `vsid` | `vsid.exe` | Not yet. SID-only player is post-MVP. |
| `petcat` | `petcat.exe` | Not yet. BASIC tokeniser is post-MVP. |
| `cartconv` | `cartconv.exe` | Not yet. Cart converter is post-MVP. |

`ViceSharp.Launcher` is a class library: no VICE-named executables are built today. Binary-name dispatch is implemented in [ViceTopologyBuilder.cs](../src/ViceSharp.Launcher/ViceTopologyBuilder.cs) and consumed by `ViceSharp.Console` (which hardcodes the binary name `x64sc`); unsupported binary names deliberately throw with a message listing the supported set so you find out fast rather than silently doing the wrong thing. Until named binaries ship, invoke the flags below through `dotnet run --project src/ViceSharp.Console --`.

## 2. Flag mapping

The launcher's flag parser is [ViceArgsParser.cs](../src/ViceSharp.Launcher/ViceArgsParser.cs). The table below is exhaustive for the parser; unlisted classic VICE flags are collected into `ViceArgs.Unknown` and silently ignored (matching VICE's own lenient handling).

### Supported

| Classic VICE flag | ViceSharp launcher | Notes |
|-------------------|--------------------|-------|
| `-8 <path>` | `-8 <path>` | Attach D64 to drive 8. |
| `-9 <path>` | `-9 <path>` | Attach D64 to drive 9. |
| `-cart <path>` | `-cart <path>` | Attach standard 8K / 16K raw or CRT cartridge image. Live memory-map wiring is implemented for standard cartridges; see section 3 for remaining mapper limits. |
| `+truedrive` | `+truedrive` | Enable true-drive emulation; drive YAML peripheral gets `fidelity: TrueDevice`. |
| `-truedrive` | `-truedrive` | Disable true-drive emulation. |
| `-config <path>` (closest analogue) | `--machine-yaml <path>` / `-m <path>` | Explicit machine topology YAML. ViceSharp uses YAML topologies instead of a flat `vicerc`. |
| (n/a in classic) | `--cycles <N>` | Host-cycle budget. Classic VICE runs until you quit; ViceSharp's console host needs a budget for deterministic batch runs. |
| `-autostart <path>` | `-autostart <path>` | Autostart a PRG. Parsed and consumed by the console entry point (FR-CFG-005 AC8). |
| `x64sc ... testcase.prg` (positional) | `program.prg` (positional) | Any bare `*.prg` argument is treated as an autostart PRG, matching the classic testbench invocation style. |
| `-debugcart` | `-debugcart` / `+debugcart` | Debug cartridge ($D7FF exit signaling for regression harnesses, per VICE `debugcart.c`). `-debugcart` enables, `+debugcart` disables; consumed by the console entry point. |
| `-limitcycles <N>` | `--limitcycles <N>` / `-limitcycles <N>` | Bounded execution cycle limit (testbench); overrides the run's cycle budget in the console entry point. |
| `-verbose` / `-v` | `-v` / `--verbose` | Same intent. |
| `-help` / `-?` | `--help` / `-h` / `-?` | Same intent. |

### Partial / bounded

| Classic VICE flag | ViceSharp behaviour |
|-------------------|---------------------|
| `-cart <path>` | Standard raw/CRT images load, normalise to 8K / 16K ROML+ROMH banks, and drive the C64 memory map through `GAME` / `EXROM`. Broader mapper families and cart-converter workflows are post-MVP. |
| `-autostart <path>` | PRG autostart is parsed and dispatched by the console entry point; disk-image autostart (`LOAD"*",8,1: RUN` injection from a D64) is not wired, so for disks use `-8 <disk.d64>` plus a topology where the drive image is mounted at boot. |

### Not yet (collected as unknown)

Each of these is currently in the launcher's `Unknown` bucket; the run still proceeds but the flag has no effect. They are all candidate work items for the launcher.

| Classic VICE flag | Status |
|-------------------|--------|
| `-warp` | Launcher flag not yet wired. The capability exists: the Avalonia desktop UI has a Warp toggle (Alt+W), a speed-cycle button, and a live limiter slider; warp runs uncapped and discards live sound, same semantics as VICE `-warp`. |
| `-sound` / `-soundoutput` | Launcher flag not yet wired. A default WinMM audio backend is connected on Windows desktop (the Avalonia app enables it at startup; `VICESHARP_AUDIO=0` disables it); library consumers pass an `IAudioBackend` to `Sid6581(IBus, IAudioBackend?)`. |
| `-fullscreen` | Not yet. The Avalonia/host-control core exists, but the launcher path does not start an always-on display shell. |
| `-model <name>` (`c64c`, `c64pal`, etc.) | Launcher flag not yet wired. The model profiles exist: `C64MachineProfiles` defines C64, C64C, SX-64, C64GS, and Japanese boards in PAL and NTSC variants, exercised by the 322-case `X64ScVariantLockstepTests` gate. Only the flag wiring is missing. |
| `-ntsc` / `-pal` | Launcher flag not yet wired. NTSC and PAL profiles exist; see `-model`. |
| `-tape <path>` | Not yet via the launcher. TAP support exists at the device layer, but launcher attach plus spin-up/record timing remain under `RUNTIME-TAPE-002`. |
| `-monitor` (built-in machine-language monitor) | Not yet via the launcher. The gRPC monitor/control surface is built under `BACKFILL-HOSTUI-001`; wiring this flag belongs with `CLI-LAUNCHER-001`. |
| `-keymap`, `-joydev`, `-userportdevice`, `-cartrev`, etc. | Not yet. |

If a flag you depend on is in this list, please file an issue (see [USER-GUIDE.md, Where to file regressions](USER-GUIDE.md#where-to-file-regressions)) so it gets prioritised against real demand.

## 3. Behaviour caveats

### Topology is YAML, not a flat config

Classic VICE puts everything in one command line (or one `vicerc`). ViceSharp prefers an explicit YAML topology because the substrate is multi-system from the start: each drive, cartridge-CPU, or user-port-CPU is its own clocked machine on a shared `IInterSystemBus`. The launcher synthesises a YAML on the fly for the common `-8` / `-9` / `+truedrive` cases, but for anything beyond that, write the YAML directly.

The canonical sample is [docs/samples/c64-plus-1541.multisystem.yaml](samples/c64-plus-1541.multisystem.yaml); see [USER-GUIDE.md section 5](USER-GUIDE.md#5-machine-yaml-topologies) for the schema.

Recommendation:
- VICE muscle memory: the `x64sc -8 disk.d64 +truedrive` form is what the launcher library parses and dispatches; until named binaries ship, drive topologies go through `--machine-yaml` on the console shell.
- Multi-drive / multi-machine: write a YAML and pass `--machine-yaml`.

### No always-on UI / GUI host

The launcher invokes the console host. It does not start an Avalonia screen, built-in monitor window, or default sound output. The host UI/control core exists behind gRPC and the in-process Avalonia host boundary, but the launcher remains a batch-mode emulator until `CLI-LAUNCHER-001` wires those surfaces into process-level flags. `--cycles N` is the way you bound a run.

### True-drive emulation defaults

In ViceSharp, the canonical sample sets `fidelity: TrueDevice` explicitly. If you omit `fidelity:`, you get `Buffered` (sector-stream fast path), which is much faster but never runs the drive's 6502. Classic VICE's "TrueDrive 8" resource maps to `+truedrive` on the launcher, which in turn sets `fidelity: TrueDevice` on every drive peripheral the launcher emits.

## 4. Performance and accuracy

ViceSharp targets cycle-exact parity with native VICE on the C64 host path. The current gate:

- **100,000-cycle lockstep** against native VICE on the BASIC `READY.` boot path (`LockstepValidationTests`). Trace-by-trace identical CPU state.
- **Drive CPU lockstep accessors** (`vice_drivecpu_get_*`) expose VICE's per-unit drive 6502 register file from .NET. The `LockstepDriveValidationTests` gate verifies `Drive%uTrueEmulation` toggles cleanly and the drive CPU advances under TDE.
- **BenchmarkDotNet harness** is checked in under [tests/ViceSharp.Benchmarks/](../tests/ViceSharp.Benchmarks/) for the CPU / VIC / SID / CIA hot paths; native VICE comparison numbers are deferred (`PERF-BENCHMARK-001`).

What this means in practice:
- For boot sequences, KERNAL traps, and any code that lives inside the lockstep gate, ViceSharp's CPU output is identical to VICE cycle-for-cycle.
- For VIC-II pixel-level behaviour, visible sprite composition, sprite priority/collision coverage, display-mode pixel routing including invalid ECM priority/collision, managed continuous side-border behavior, VIC-II register readback masks/collision latch writes, and managed matrix idle/fill fetch behavior are implemented, but native display-mode/register/matrix checkpoints, sprite fetch depth, and FLI/AFLI timing remain under `BACKFILL-VIDEO-001`. Demo code that depends on deep raster effects can still diverge from VICE.
- For SID, hard sync, ring modulation, combined waveforms, ADSR behaviour, digi output, and dual-SID coverage are wired and exercised in the focused suite. Further analog 8580/filter deepening is post-MVP unless final lockstep exposes a concrete regression.

## 5. Bug compatibility

Classic VICE faithfully reproduces several Commodore-era hardware bugs that real demos and games rely on. ViceSharp's current status:

| Bug | Status |
|-----|--------|
| 6510 illegal opcodes | Reproduced. Lockstep gate covers them. |
| 6510 jump-vector page-cross bug (`JMP ($xxFF)`) | Reproduced. |
| VIC-II "bad line" cycle stealing | Reproduced at the CIA / CPU contention level; managed matrix idle/fill behavior is covered, while native matrix checkpoints and FLI/AFLI effects remain under `BACKFILL-VIDEO-001`. |
| VIC-II sprite-DMA timing | Bounded. Sprite fetch is wired and side-border visibility is managed, but non-PAL per-model fetch tables and native multiplexing checkpoints remain. |
| SID ADSR bug | Reproduced in the focused Phase 1 SID suite; further analog deepening is post-MVP. |
| SID combined waveforms | Reproduced for the Phase 1 SID suite; further analog deepening is post-MVP. |
| 1541 GCR bit-stream timing | Byte-level GCR playback implemented under true drive: `GcrCodec` plus `C1541DriveMechanismDevice` raise byte-ready through VIA2 at per-speed-zone intervals (32/30/28/26 cycles). The sector-stream fast path remains the default fidelity; sub-byte bit-cell effects (weak bits, killer tracks) are not modeled. |

If a specific demo / game depends on a deferred bug, file a regression with the SID dump or D64; that helps prioritise the relevant slice.

## 6. Where to file regressions

File issues at [github.com/sharpninja/vice-sharp/issues](https://github.com/sharpninja/vice-sharp/issues). See [USER-GUIDE.md, Where to file regressions](USER-GUIDE.md#where-to-file-regressions) for what to include.

When opening a parity issue, include both the classic VICE invocation you are coming from and the ViceSharp invocation that should have matched, plus a minimal repro (D64 / CRT / TAP / SID dump).