Copperline - An Amiga emulator in Rust

// get started

Download and run

Copperline includes AROS, an open-source Kickstart replacement, so it boots without a ROM of your own. Bring your own disk images; some software needs an original Kickstart ROM. Check compatibility.

Download for macOS

For Apple Silicon and Intel Macs. Open the DMG and copy Copperline.app to Applications.

The app is ad-hoc signed rather than notarized, so macOS may block the first launch. Allow it in System Settings → Privacy & Security → Open Anyway.

Install with Homebrew

brew tap CopperlineHQ/copperline https://github.com/CopperlineHQ/Copperline
brew install copperline

Download for Linux

AppImage for x86-64. Make it executable, then launch it:

chmod +x Copperline-1.0.0-rc.1-x86_64.AppImage
./Copperline-1.0.0-rc.1-x86_64.AppImage

A Vulkan driver is required. See the Linux setup guide.

Install Copperline
Pick the download for your system, or open the browser version.
Choose your Amiga
The launcher starts with an A500 running AROS. Choose another machine or your own Kickstart ROM, then start it. Configuration guide.
Load your software
On the desktop, drag a disk image onto the window or insert one from the status bar. WHDLoad archives can be launched directly.

Upgrading from 0.21? Every netplay peer needs the same release, RetroArch save states need recreating after updating the core, and high-density floppy images are now refused. Read the upgrade notes.

All release downloads Install the RetroArch core Full installation guide

Build from source or try the development branch

Building from source needs Rust 1.95 or newer and the dependencies for your platform.

git clone https://github.com/CopperlineHQ/Copperline.git
cd Copperline
cargo build --release
./target/release/copperline

With the Homebrew tap installed, brew install --HEAD copperline builds the latest development version.

// features

Play, explore and build

Amiga hardware, modelled in detail

OCS, ECS and AGA machines with 68000 to 68060 CPUs, Zorro expansion boards, hard disks and CD drives.

Hardware and configuration

Play together online

Rollback netplay for two players on desktops or in browsers, or up to four on desktops through the four-player adapter, with up to eight spectators. The host sends the machine setup, ROMs and supported media, so the other players need no local copies.

Set up netplay

Run it in RetroArch

A libretro core for A500, A1200 and CD32 software, with WHDLoad, playlists, save states, four local controller ports and RetroArch netplay.

Install the core

Step backwards through a bug

Inspect registers and memory beside the Amiga display. Rewind execution to find the instruction that changed a value.

See the Debug workspace

See where each bus cycle goes

The Frame Analyzer shows which part of the machine used the chip bus in each cycle of a frame.

Explore frame analysis

Automate your Amiga

Script inputs, capture frames and replay sessions for regression tests. Debug Amiga source code from VS Code.

Scripting and development

// in action

Demos and Workbench

Spaceballs' State of the Art demo running in Copperline — **State of the Art.** Spaceballs' OCS demo.

Workbench 3.1. An A1200 booting from an IDE disk.

Desire's HAMazing demo showing a robot and toy monkey under a swinging lamp — **HAMazing.** Desire's lighting effects in HAM6.

More screenshots

Copperline displaying a colourful image in AGA HAM8 mode — **AGA HAM8.** A picture in HAM8, which can show 262,144 colours at once.

Desire's Inside demo showing an Amiga 500 motherboard in pixel art — **Inside.** Desire's pixel-art Amiga motherboard.

// debugger

Keep the machine in view

The Debug workspace puts registers, disassembly and memory beside the Amiga display. Resize the panes, edit values and follow addresses between inspectors.

State of the Art beside CPU registers, disassembly and memory in Copperline 0.20.0 — **CPU workspace.** The Amiga display beside editable registers, disassembly and memory.

Step backwards

Reverse stepping replays earlier execution from snapshots. Find the last change to a memory address, or run backwards to a breakpoint.

Reverse debugging

Switch between Play and Debug

Press Cmd+B on macOS or Alt+B on Linux and Windows. The inspectors keep their state while you play.

Workspace controls and inspectors

// frame analyzer

Understand the timing

See whether the CPU, the Copper, the blitter or another DMA channel owns each bus cycle across a video frame. Inspect a single scanline, find where the CPU waited for the bus, or overlay bus activity on the picture to match timing to what is on screen.

Copperline's Frame Analyzer showing chip-bus ownership beside the Amiga display — Read the Frame Analyzer guide

// development

Make a bug repeatable

Schedule inputs and captures from the command line, record a session to a .clscript file, or drive a running machine through the JSON-RPC control protocol.

Headless run: press Space at 4 s and take a screenshot at 12 s of emulated time

copperline --factory --model A500 --insert-disk-after 0 df0 game.adf \
  --noaudio --press-after 4 SPACE --screenshot-after 12 shot.png

A run repeats exactly when the configuration, media, clock seeds and inputs are the same. Live host files, networks and physical devices can make runs differ. Determinism and the host boundary.

Scripting guide Control protocol Debug with VS Code

// compatibility · 1.0.0-rc.1

Compatibility and limitations

Games, demos and Workbench run on OCS, ECS and AGA machines, but not everything works yet. Compatibility depends on the software and the configuration, and accuracy improves with each release.

ROMs and software: AROS is included, so you can start straight away. Some games and Workbench installations need an original Kickstart ROM. ROM and setup guide.
Netplay: Two to four desktops, or two browsers, running the same Copperline build can play together, with up to eight spectators of the same kind. Players three and four need the four-player adapter. A desktop cannot connect to a browser, and mixing operating systems or browser engines has not been verified yet. Netplay requirements.
Experimental JIT: The optional JIT for 68020 and later CPUs changes CPU timing and is off by default. Leave it off when accurate instruction timing matters. CPU settings.
Physical floppy drives: Real drives work through a Greaseweazle controller and FluxBridge; other flux controllers are not supported. A save state cannot rewind a physical disk. Supported hardware and limitations.
Disk formats: Floppy images must be double-density Amiga disks. High-density (1.76 MB) Amiga images and sector-based PC/CrossDOS images are not supported. Supported image formats.
Keyboard layouts: Host keys map to Amiga keys by physical position, not by the host's keyboard layout, and there is no layout setting yet.

CPU behaviour is checked against the SingleStepTests 68000 corpus and WinUAE's cputest sets, chipset behaviour against vAmigaTS and Copperline's own probe disks, and timing against measurements on real Amigas. The documentation has the details.

Found a problem? Check the existing issues or report it with the version, the machine configuration and the steps to reproduce it. An input recording helps.

// questions

A few things to know

Do I need a Kickstart ROM?

No. Copperline boots its included AROS ROM straight away. Some software needs an original Kickstart ROM; if you have one, select it in the launcher. Read the setup guide.

How does Copperline compare with other Amiga emulators?

WinUAE, FS-UAE and vAmiga have many years of compatibility work behind them, and Copperline is much younger. It concentrates on reverse debugging, chip-bus analysis, scripting and repeatable tests. The browser build and netplay also make it easy to try a configuration or play together.

Is the macOS build notarized?

Not yet. The downloads are ad-hoc signed, so macOS asks you to approve the first launch in Privacy & Security. Installing with Homebrew builds Copperline from source on your Mac instead, so there is nothing to approve.

How was Copperline developed?

I work from hardware documentation, real Amigas and test disks. AI coding assistants help with implementation, tests and debugging, and changes are checked with hardware tests and regression runs.

Where does the name come from?

The Copper is the Amiga's display coprocessor. It runs alongside the CPU and writes chipset registers in step with the video beam, which is how raster effects such as colour bars are drawn. Copperline is named after it.

// Andrew Hutchings · LinuxJedi

Built with real Amigas on the workbench

I wanted an Amiga emulator I could automate from the command line and use to track down difficult bugs. The first milestone was getting DiagROM to display its menu.

I also repair, collect and design hardware for real Amigas. Those machines are my reference when the emulator's behaviour needs checking.

More about my work

Join in

Chat on Discord about configurations, demos and Amiga hardware.

Report an issue or contribute a fix on GitHub.

See community projects built with Copperline.

Support Copperline

Support helps cover development hardware, testing equipment and code-signing costs. Join Patreon, or give through GitHub Sponsors, Ko-fi or PayPal.

Thank you to patrons Lee Hobson, Sphair and Karlos_Fandango, and contributors Bernie Innocenti, Lee Hobson, jbl007, Simon Dick, Nicolas Ramz, Ben Letchford, Volker Schwaberow and Matt Harlum.