Copperline

Copperline is a cycle-driven Commodore Amiga emulator (OCS, ECS, and AGA) written in Rust. The emulator advances the CPU (68000 through 68060), Agnus, Denise, Paula, CIAs, floppy subsystem, and chip bus on a unified colour-clock timeline. Bus arbitration occurs per colour clock, with Copper and blitter DMA scheduled according to hardware slot sequences.

The project home is copperline.dev; the source code is hosted on GitHub.

Documentation overview¶

• Getting started -- Installation, building from source, and first boot.

• Configuration reference -- The copperline.toml reference for machine profiles, memory, storage, expansion boards, and input.

• The window, status bar, and menus -- Window controls, status bar, keyboard shortcuts, and gamepad mapping.

• WHDLoad support -- Direct launching and library management for WHDLoad packages.

• Direct executable launching (--run) -- Booting straight into cross-compiled Amiga executables.

• Physical floppy drives (FluxBridge) -- Using physical floppy drives through a Greaseweazle.

• Physical host disks -- Giving the machine a real disk or storage card of the host’s.

• Roland MT-32 emulation -- Built-in Roland MT-32 emulation and front panel.

• Coppersynth (General MIDI synthesizer) -- Built-in General MIDI SoundFont synthesizer.

• Hayes modem emulation -- Hayes-compatible AT modem emulation over TCP.

• Importing UAE configurations -- Converting WinUAE, Amiberry, and FS-UAE configurations.

• WinUAE state import -- Importing supported WinUAE save states and profiling resumed frames.

• Rollback netplay -- Rollback netplay for two to four players across desktop instances or browsers.

• Headless and scripted execution -- Scripted, non-interactive execution for automated testing and CI.

• Browser build and WebAssembly integration -- WebAssembly build and web integration details.

• Libretro / RetroArch -- The libretro core for RetroArch and other libretro frontends.

• Standalone game player (Player kit) -- Bundling standalone player packages for specific games.

• Writing Zorro board plugins -- Writing data-driven and WebAssembly Zorro II/III expansion board plugins.

• Custom chip registers -- One reference page per custom chip register (in the HTML manual and the debugger’s help, not the PDF).

• The Debug workspace, Debugger console, Headless debugger environment reference, and Remote GDB debugging -- The Debug workspace, the debugger console, the headless debugger, and the GDB remote stub.

• Reverse debugging, Waveform export (VCD logic analyzer), and Per-frame profiling -- Reverse execution, VCD chipset waveform export, and per-frame profiling and guest code coverage.

• Visual Studio Code and Bartman with Copperline -- VS Code setup, source debugging, and illustrated CPU/DMA and graphics profiling using the installable Bartman fork.

• Control protocol (CCP) -- JSON-RPC control protocol (copperline-ctl) for automation, with an MCP server mode for coding agents.

• Debug Adapter Protocol (IDE debugging) -- DAP launch, attach, stepping, and debug-information reference.

• A/B divergence finder -- A/B divergence finder: two builds or two configs in lockstep, narrowed to the first differing frame and instruction.

• Debugging workflows -- Worked debugging workflows that combine these tools.

• Architecture overview -- Source layout, frame loop, and host boundary.

• The timing model, Chipset modules, The video pipeline, Audio sink service (src/audio/), and CPU integration -- The timing model and the chipset, video, audio, and CPU implementations.

• Peripherals and expansion, Toccata and the AD1848 model, The MHI decoder board: mailbox register protocol, copperhf.device: register protocol and boot ROM, The zz9k crypto board: ZZ9000 SDK v2 protocol subset, Picasso II/II+ and CL-GD5426/5428 model, and Graffity [Zorro II]/[Zorro III] model -- Expansion hardware models and board protocols.

• Netplay architecture and Save states (savestate.rs) -- Netplay architecture and the save-state format.

• In-repo reference documents -- The in-repository reference documents behind the timing models.

Core design principles¶

1. Hardware-accurate modelling. Behaviour is implemented according to chip specifications rather than application-specific hacks or game title detection.

2. Determinism. Given the same configuration, media, clock seed, and timed inputs, the core produces the same results in headless and interactive runs. Live host services, such as networking and physical drives, have separate replay limits.