Skip to content

ui.md

Latest commit

 

History

History
767 lines (663 loc) · 41.9 KB

ui.md

File metadata and controls

767 lines (663 loc) · 41.9 KB
Raw

The window, status bar, and menus

Copperline opens a single window: the emulated display presented at a TV-like 4:3 aspect ratio, above a status bar with the machine's controls. The window scales continuously when resized.

Keyboard shortcuts

The app shortcut modifier is Cmd on macOS and Alt on Linux/Windows.

macOS Linux/Windows Action
Cmd+Q Alt+Q Quit
Cmd+E Alt+E Open / close the menu (also the status bar's hamburger button); releases a captured mouse
Cmd+S Alt+S Save a screenshot (copperline-screenshot-<YYYYMMDDHHmmSS>.png in the working directory; the on-screen confirmation overlay is not part of the saved image)
Cmd+R Alt+R Start / stop a video-with-audio recording (below)
Cmd+Shift+R Alt+Shift+R Start / stop an input recording (below)
Cmd+Shift+S Alt+Shift+S Save a state (copperline-state-<YYYYMMDDHHmmSS>.clstate in the working directory)
Cmd+Shift+L Alt+Shift+L Load a save state from a file dialog
Cmd+1..Cmd+9, Cmd+0 Alt+1..Alt+9, Alt+0 Quick-save to numbered slot 1-10
Cmd+Shift+1..Cmd+Shift+0 Alt+Shift+1..Alt+Shift+0 Quick-load from that slot
Cmd+D Alt+D Swap to the next disk in a drive's configured playlist
Cmd+G Alt+G Capture / release the host mouse (clicking the display also captures)
Cmd+B Alt+B Open the debugger window
Cmd+K Alt+K Open the debugger console
Cmd+J Alt+J Toggle joystick input mode: gamepad / keyboard (also the status-bar icon)
Cmd+M Alt+M Toggle the 1084-style monitor bezel around the picture ([display] bezel sets the start-up value)
Cmd+Shift+A Alt+Shift+A Cycle the audio output: Default, each host device, then Disabled (also Audio Settings > Audio Output)
Cmd+A Alt+A Cycle Paula's audio filter: auto, on, off (also Audio Settings > Audio Filter)
Cmd+Shift++ / Cmd+Shift+- Alt+Shift++ / Alt+Shift+- Raise / lower the parallel-port sampler input gain (only when a sampler is attached; also Parallel Port > Sampler Gain)
Cmd+Shift+> / Cmd+Shift+< Alt+Shift+> / Alt+Shift+< Raise / lower the host mouse sensitivity (also the launcher's Input tab)
Cmd+F Alt+F Toggle fullscreen on / off
Cmd+Shift+F Alt+Shift+F Show / hide the status bar
Cmd+P Alt+P Toggle the performance overlay ([display] perf_overlay sets the start-up value)
Cmd+W Alt+W Toggle Warp Speed (turbo) on / off
Cmd+Shift+W Alt+Shift+W Cycle the Warp Speed limit: 2x, 4x, 8x, 16x, Max
Cmd+Z Alt+Z Rewind the machine one step (needs [emulation] rewind or Emulation Settings > Rewind)
Esc Esc Close an open menu, tool window, or overlay panel; otherwise passed through to the Amiga
Ctrl+Amiga+Amiga Ctrl+Amiga+Amiga Keyboard reset (warm reboot)

Host modifiers that are passed through to the emulated keyboard map onto the Amiga keyboard: Alt becomes Amiga Alt, Cmd/Super becomes the left/right Amiga keys, and left Ctrl becomes Amiga Ctrl, so Ctrl+Amiga+Amiga is typed naturally. The Amiga keyboard has no right Ctrl, so host right Ctrl also acts as the right Amiga key -- handy on PC/laptop keyboards that lack a right Super/Win key.

All other keys are sent to the emulated machine through the real path: a bit-timed keyboard-MCU model clocks each transition into CIA-A's serial register over the emulated KCLK/KDAT lines, with the real handshake, power-up stream, and recovery protocol -- so even software that talks to the keyboard hardware directly behaves. Ctrl+Amiga+Amiga runs the authentic reset protocol (reset warning, then KCLK held low), so the reboot lands a fraction of a second after the chord, as on real hardware.

Status bar

The status bar (44 pixels below the display) holds, left to right (it can be hidden entirely with Cmd+Shift+F / Alt+Shift+F or Video Settings > Status Bar):

  • LED block. PWR and FDD always; a green HDD activity LED on machines with a hard-disk controller (Gayle or A4000 IDE, or any SCSI adapter) or a host-folder filesystem mount ([[filesys]]), lit while either is accessed; a blue CD activity LED on CDTV/CD32 that lights while the drive reads data or plays CD audio (on a machine whose CD drive is a SCSI CD-ROM unit, the LED shows CD-DA playback; its data reads ride the HDD LED with the rest of the SCSI bus). A small digital counter shows the current floppy track. The PWR LED is lit whenever the machine is powered, driven by the guest's /LED line the way it drives the LED on an A500 rev 6 or later board: full brightness while the line is engaged (Paula's analogue filter on), dimmed -- not extinguished -- once the software releases it. It follows the pin itself, so the Audio Filter menu override changes what you hear, never the LED.
  • Per-drive floppy controls. Every connected drive gets a disk button (marked with the drive number) that opens a file dialog -- multi-select several images to queue a swap playlist for that drive -- plus a swap button that cycles to the next queued disk and an eject button. Swap and eject grey out when there is nothing to swap to or eject. With three or four drives the clusters stack two-up. A bay driving a physical floppy drive keeps its numbered disk button, so you can see the drive is there, but loading, swapping and ejecting do nothing for it -- the disk is in a real drive, and changing it is done by hand (see ).
  • CD controls on machines with a CD drive (CDTV, CD32, or a SCSI CD-ROM unit): a CD button that loads (or swaps) a CD image (.cue/.iso/.chd) with the proper media-change notification, and a CD eject button. These do not appear on machines without a CD drive.
  • Joystick toggle (just left of the volume control): a gamepad or keyboard icon showing which source drives the joystick port. Click it to flip between gamepad-only and keyboard joystick emulation; see .
  • Volume slider: drag, or scroll the mouse wheel over it for 5% steps.
  • Hamburger menu button: opens the pop-up menu (below).
  • Camera button: saves a screenshot (same as Cmd+S on macOS or Alt+S on Linux/Windows).
  • Pause / power / reboot buttons. Pause freezes emulation while staying powered; power cold-boots (clears RAM) or powers off back to the test screen; reboot is a warm reset.

Performance overlay

Cmd+P (macOS) / Alt+P, Video Settings > Performance, or [display] perf_overlay = true shows a live emulation-performance readout in the top-right corner of the display, one line per data point at the menu's font size (it follows Menu Size), refreshed twice a second:

Line Meaning
50.0 fps Emulated video frames retired per host second: 50 (PAL) or 60 (NTSC) when the machine holds real time, lower when the host cannot keep up, far higher under Warp Speed
x1.00 Speed factor: emulated seconds advanced per host second (the effective multiplier under Warp Speed)
emu 3.2 ms Host milliseconds of emulation work per emulated frame, pacing sleeps excluded
host 16% Share of host wall time spent emulating. In real-time mode this is the share of the frame budget (20.0 ms PAL, 16.7 ms NTSC) used per frame
audio 148 ms Live audio output lead -- the cushion that absorbs host scheduling hiccups (steady state is about 150 ms)
xrun 0 Audio underrun frames per second: the audible symptom of the host falling behind
slip 0 Times the pacer fell hopelessly behind real time (over ~100 ms, e.g. a host stall) and dropped emulated time instead of chasing it, since the last guest reset

Copperline never skips frames to keep pace: when the host cannot sustain real time the machine slows down (fps and the speed factor fall below nominal while host sits near 100%), and only a stall beyond the pacer's catch-up limit drops emulated time, counted by slip. Under Warp Speed the presentation shows one frame per burst, but every emulated frame is still computed.

Like the transient message overlay, the readout is painted into the presentation only: screenshots, frame dumps, and recordings never include it. While a video recording is running the block steps below the REC badge. COPPERLINE_PERF_OVERLAY=1|0 overrides the config for a single run, and --perf-overlay shows it from the command line; the launcher's Perf overlay row (A/V & Emu, Video) makes it stick. The same counters are exported through the control protocol's status reply for headless runs (see ).

Drag and drop

Disk images can be dropped anywhere on the emulator window:

  • Floppy images (ADF/ADZ/DMS/IPF/SCP, gzip or zip packed): with one connected drive the disk is inserted immediately. With several, a drive chooser opens over the display -- click a drive, press its number (1-4), or press Esc to cancel. Dropping several floppies at once queues them all as the target drive's swap playlist, exactly like a multi-selection in the disk dialog.
  • CD images (.cue/.iso/.chd) mount in the machine's CD drive (CDTV, CD32, or a SCSI CD-ROM unit), with the media-change notification.
  • Hard disk images and Kickstart ROMs cannot be swapped at runtime; a notice points at the machine-configuration screen, which also refuses drops while it is open.

The chooser opens after the drop rather than offering per-drive drop targets because the windowing layer reports file drops without a cursor position. For the same reason drops are unavailable under native Wayland (X11/XWayland works).

Menu, tool windows, and overlay panels

:alt: The pop-up menu with a category open
:width: 75%

The menu, with a category open beside it.

The hamburger button at the right of the status bar opens the menu, as does Cmd+E / Alt+E. It grows upward from the status bar and dims the picture behind it, so what it covers stays readable without competing for attention. The dimming is a window effect: it never appears in a screenshot, a frame dump, or a recording.

The top level holds the tools, then a category per area of the machine, then the ROM, the shortcut reference and About... last. A category is marked > and opens a list of its own beside it; a setting with more than two values opens a further list of those values with the one in force ticked, and a setting that is simply on or off is ticked in place. Categories with nothing to offer -- the serial and parallel ports on a machine with nothing on them -- are not shown at all.

Point at a category and it opens; point at one of its rows and that row is where the keyboard is. The cursor keys walk the same path -- up and down within a list, right into a category, left back out -- and Return picks the row under the cursor. Esc steps back one level, and closes the menu from the top.

Picking a row that opens something else -- a window, a panel, a file dialog -- closes the menu behind it. Changing a setting leaves the menu up with the new value marked, so a run of changes costs one open rather than one each. Opening the menu also releases a captured mouse.

Menu Size under Video Settings draws the whole menu at 1x or 2x. The start-up size is [display] menu_scale, --menu-scale, or Menu size on the launcher's A/V & Emu page (Video category).

Tool windows are separate native windows so the emulated display remains visible; the debugger and frame analyzer can be open at the same time. Overlay panels are drawn over the display. While either kind is open, key presses and display clicks stay in the UI instead of reaching the Amiga; Esc closes the focused tool window or overlay.

Tools

  • Machine Configuration...: opens the configuration screen (below) to reconfigure the machine and relaunch it. The same screen opens automatically on a no-machine start.
  • Frame Analyzer...: pauses the machine and opens a separate diagnostic window with two tabs: which chip-bus owner had each Agnus colour clock across the captured frame, including overscan and blanking, and a memory heat map of what last touched each part of the address space; see .
  • Debugger... (also Cmd+B / Alt+B): pauses the machine and opens the tabbed debugger in a tool window; see .
  • Console... (also Cmd+K / Alt+K): a GDB-flavoured debugger command line in its own tool window; see .

Audio Settings

  • Audio Output (also Cmd+Shift+A / Alt+Shift+A): the system default, any host output device, or Disabled (sound off entirely, equivalent to --noaudio). The device switches live without a restart.
  • Audio Filter (also Cmd+A / Alt+A): Paula's analogue low-pass filter -- Auto (guest-driven, the default), Enabled, or Disabled. The forced settings apply regardless of what the software asks; auto restores hardware behaviour. The PWR LED keeps following the guest's /LED line whatever is forced here.

Video Settings

  • Menu Size: 1x or 2x, described above.
  • Pixel Aspect: the 4:3 CRT pixel aspect (the default; PAL lo-res pixels slightly wider than tall, as a real TV shows them) or square pixels (a 320x256 screen is an exact 640x512, handy for pixel-exact comparison with square-pixel emulators). The window and its backing texture resize with the mode. The start-up mode comes from [display] pixel_aspect (see Configuration).
  • Scaling: how that canvas is drawn into the window -- Smooth (the default: fit to the window preserving aspect ratio, interpolated) or Integer (the largest whole-number multiple of the canvas that fits, centred in black borders and point-sampled, so every canvas pixel is the same square block of host pixels). The fit is taken in whole canvas pixels, so every step exists on high-DPI and fractional-scale displays alike. Integer scaling applies to RTG board modes too, at multiples of their own native resolution, and gives way to the smooth fit when the window cannot hold even a 1:1 copy rather than cropping the picture. The window never resizes when it changes, and a video recording carries on underneath. The start-up mode is [display] scaling, which also notes which pixel-aspect pairing is fully pixel-exact (see Configuration).
  • CRT Shader: the GPU tube-emulation pass over the picture -- Disabled, Scanlines (the line structure of a 15 kHz set), Mask (an RGB phosphor shadow mask), CRT (1084) (both, plus a bowed tube face and a corner vignette), and Custom when the config named a shader of your own, which is re-read from disk each time it is chosen. The change is session-only: the start-up preset, the strength knob, and how to write a custom shader are [display] shader and shader_strength (see Configuration). The pass is a window effect only -- screenshots, frame dumps and recordings are never shader-processed -- and it steps aside for the frames it cannot sensibly draw: while the menu or any panel is open, under RTG, and in programmable multisync scan modes.
  • Screen Tint: the monochrome-monitor tint over the picture -- Colour (full colour), Black & white, Green and Amber (the two classic monochrome phosphors), and Sepia -- the same looks as the web frontend's Screen selector. Session-only, like the shader; the start-up tint is [display] tint (see Configuration). A window effect only: captures stay untinted, the menu and the status bar keep their colours, and RTG scanout is never tinted.
  • Fullscreen (also Cmd+F / Alt+F): borderless fullscreen on the window's current monitor. The picture keeps its aspect and letterboxes as needed, exactly as when resizing the window.
  • Status Bar (also Cmd+Shift+F / Alt+Shift+F): show or hide the status bar. Handy alongside fullscreen for a clean, chrome-free picture.
  • Performance (also Cmd+P / Alt+P): show or hide the performance overlay. Session-only; the start-up value is [display] perf_overlay (see Configuration).

Input Settings

  • Port 1 Device / Port 2 Device: hot-plug the controller in a game port -- Mouse, Joystick, CD32 pad, Analogue, or None; see .
  • Joystick Input (also Cmd+J / Alt+J, or the status-bar icon): Gamepad-only or Keyboard joystick emulation.
  • Autofire: the autofire rate (off, 3, 5, 8, 12, 16 Hz), which pulses a held fire button on live gamepad and keyboard input. Scripted input is never gated; see the [input] section of Configuration.
  • Calibrate Gamepad...: the guided calibration flow, described below.
  • Input Mapping...: edits which host keys drive the controller controls, for both keyboard mappings; see .

Serial Port and Parallel Port

Shown only when something is on the port.

  • MIDI In / MIDI Out (serial port in MIDI mode): Paula's serial bridge onto the host's MIDI sources and destinations; see the [serial] section of Configuration.
  • Sampler Input / Sampler Gain (parallel-port sampler attached): the sampler's host capture device, and its input gain, which the Increase and Decrease rows step (also Cmd/Alt+Shift +/-). Both change live. See the [parallel] section of Configuration.

Emulation Settings

  • Floppy Speed: the emulated drive speed -- 100% (real speed), 200%, 400%, 800%, or turbo (disk DMA transfers complete almost instantly). Changes apply to the live machine immediately. The start-up value comes from [floppy] speed; see Configuration for what each level preserves and the compatibility trade-off.
  • Rewind (the hotkey is Cmd+Z / Alt+Z): records rewind history. While it is on, the emulator keeps a ring of whole-machine snapshots and the hotkey steps the machine back through them -- the whole machine, not just the picture: CPU, chips, RAM and all. One press goes back one capture interval (half a second of emulated time by default). Turning it off releases the snapshots, which is where the memory goes; the budget and interval are [emulation] rewind_budget_mb and rewind_interval_frames, and rewind = true starts recording at launch (see Configuration). It shares its substrate with the debugger's reverse controls, so the same determinism caveats apply -- see .

Warp Settings

  • Warp Speed (also Cmd+W / Alt+W): runs the emulator unpaced for fast-forward. Toggling back re-anchors real-time pacing cleanly.
  • Warp Limit (also Cmd+Shift+W / Alt+Shift+W): how fast warp runs. Because the window presents with vsync, emulating one frame per presented frame would cap warp at the host monitor's refresh rate (about 1.2x for 50 Hz PAL on a 60 Hz display). The limit sets an output frame skip -- 2x, 4x, 8x, 16x, or Max -- so warp retires that many emulated frames per presented frame, making the effective speed roughly the limit times the refresh rate (host CPU permitting). Max runs flat out and still presents at vsync. The default is set by [emulation] warp_speed (see Configuration).

Recording

  • Record Video (also Cmd+R / Alt+R): starts a video-with-audio recording; the same row (or shortcut again) stops it. See below.
  • Record Input (also Cmd+Shift+R / Alt+Shift+R): records every input event that reaches the emulated machine; stopping writes a script file that --script replays deterministically. See below.

Save State

  • Quick Save and Quick Load each list all ten numbered slots, naming when the slot was written or showing it as empty, so an overwrite is visible before it is chosen. No dialog, and no file to name. The hotkeys reach the same slots -- Cmd/Alt+<digit> saves and Cmd/Alt+Shift+<digit> loads, with 0 as the tenth. See below.
  • Save State... (also Cmd+Shift+S / Alt+Shift+S) and Load State... (also Cmd+Shift+L / Alt+Shift+L): snapshot the whole emulated machine to a file of your choosing, or restore one and continue from exactly that point. See below.

And last

  • Load Kickstart ROM...: fit a different boot ROM. Pick a 512 KiB Kickstart, then optionally a second file for the extended ROM (512 KiB at $E00000 or 256 KiB at $F00000; Cancel to skip and remove any fitted extended ROM). The machine then cold-resets, as if the chip had been swapped and the power cycled.
  • Keyboard Shortcuts...: the shortcut reference.
  • About...: app version plus a summary of the emulated machine, and credits including Copperline's contributors and Patreon sponsors (see CREDITS.md). Builds made from an untagged git commit append the short commit ID to the version shown in the window title and About panel.
:alt: The keyboard shortcuts window
:width: 75%

The Keyboard Shortcuts window.

(machine-configuration-screen)=

Machine configuration screen

Starting Copperline with no machine specified -- no ./copperline.toml, no --config, no ROM or override, and not a headless run -- opens the configuration screen instead of booting. It is also available any time from the menu's Machine Configuration... item, seeded with the running machine's settings.

:alt: The machine configuration screen
:width: 75%

The configuration screen: the machine selector across the top, category tabs
down the left, settings on the right, and the action bar along the bottom. Here
an A1200 is selected on the Memory tab; Zorro III RAM is greyed with the reason
"needs 32-bit CPU" (the A1200's 68EC020 has a 24-bit bus).

The layout is:

  • Machine selector (top). Pick a machine -- A1000, A500 (OCS), A500, A500+, A600, A1200, A3000, A4000, CDTV, or CD32. With no profile chosen the A500 is highlighted, since that is the machine the defaults describe. Selecting a machine applies that profile's defaults (chipset, CPU, RAM, gate array, RTC) to every tab; settings that no longer apply (an IDE image on a machine with no IDE port, a CD image on a machine with no CD drive) are dropped so they cannot block a launch.
  • Category tabs (left sidebar). System (chipset and Agnus/Denise overrides, video standard, RTC, identify board, RTG card), CPU (model, FPU, clock, caches, and the experimental not-cycle-exact JIT mode -- see [cpu] jit in ), Memory (chip/fast/slow/motherboard/Zorro III RAM), ROM (Kickstart and extended ROM), Floppy (drive count and speed, then each wired drive as a greyed DFn: heading with its indented disk image and write-protect; drives that are not enabled are hidden rather than greyed. Each drive also carries a Physical drive tick box that hands the bay to a physical floppy drive: its media row then names the interface -- or None with nothing plugged in -- and a Configure button opens that drive's own page, headed with the installed library and its version, for the serial port, drive select, density, read mode, bridge speed and auto-cache, greying whatever the chosen interface does not honour. See ), Storage (IDE master/slave, the SCSI controller -- A2091, A4091, or the A3000's onboard SCSI -- and its boot ROM and units; a row of buttons at the top links to three sub-pages: CD (image, insert delay, CD32 NVRAM); Host Mounts, for host directories served live as AmigaDOS volumes (up to four mounts, each with a boot priority and a read-write/read-only Access field -- the config file itself takes up to eight [[filesys]] mounts, of which the launcher edits the first four); and Boot Priority, which sets each hard-disk drive's synthesized-RDB boot priority (see below). Each sub-page has a < Back button in that top row that returns to Storage), Input (the controller device in each game port and the joystick input source), I/O Ports (the serial, parallel, and Ethernet ports under Serial: / Parallel: / Ethernet: headings, with each port's options indented beneath it: serial mode and MIDI endpoints; the parallel device -- None, Printer, or Sampler -- with, for the printer, its capture output file, or for the sampler, its host audio input and input gain; and the A2065 Ethernet and HostSocket bsdsocket.library boards, each -- None, Isolated, Loopback, NAT, or Bridged; Bridged adds a host-adapter row. NAT and Bridged show a warning because host-clocked traffic makes input recordings and save-state replays non-reproducible while it flows), Zorro (extra autoconfig boards by metadata file, with a config panel for a WASM plugin board's declared options), and A/V & Emu, split by a row of category buttons at the top into Audio (output device, channel mode, stereo separation, filter, floppy sounds and volume), Video (start fullscreen, status bar, monitor bezel, perf overlay, menu size, overscan, pixel aspect, scaling, deinterlace, screen tint, phosphor, CRT shader and shader strength), and Emulation (power-on, realtime priority, pacing, warp speed) -- opening on Audio, and switched freely between the three.
  • Settings rows (right pane). [<]/[>] step through a value, On/Off buttons flip a toggle, and the Browse and Clear buttons set or remove a file path through a native file dialog. On the Storage tab, once an IDE or SCSI drive has an image a small editable box appears next to Browse: click it and type to set the volume name for a directory mount (left blank, a directory mount inherits the host directory's name; the box has no effect on a raw HDF). A setting that does not apply to the chosen machine is greyed and shows why in place of its control -- "needs 32-bit CPU" for Zorro III RAM and the RTG card, "needs 68020+" for the FPU, "needs A600/A1200/A4000" for IDE.
  • Boot Priority sub-page (from Storage). One row per hard-disk drive, under Drive / Priority / Status columns, setting the de_BootPri written into the partition Copperline synthesizes in front of a bare hardfile (it has no effect on an image carrying its own RDB). In the Priority column [<]/[>] nudge the value by one and the value box is also a text field -- click it and type any priority (-128..127), then Enter. The Status column's Bootable box is ticked by default; clearing it greys that row's priority and writes the -128 "disabled" sentinel, so the volume mounts but never boots. A drive with no image, or a CD image, is greyed ("No drive" / "CD-ROM"), with no stepper to reach for. A SCSI unit appears only once it carries a disk, so the page lists what the machine can actually boot from. Drives you add here with no priority of their own cascade so they do not tie: the first is 0 (just under DF0:'s 5), and each later one drops below the floppies -- -35, -40, -45. A drive already carrying a priority in the config keeps it, and one that just names a device with no bootpri stays at 0. See for how the priority ranks against Kickstart's DF0: boot node at 5.
  • Action bar (bottom). Load... and Save... read and write a .toml config through a file dialog (Save writes a minimal file, only the settings that differ from the chosen profile's defaults, so it reads like the example configs). Defaults resets to the selected profile. Run validates the configuration and boots it; if anything is wrong -- an unusable RAM size, a missing disk image, a ROM file that cannot be read, an option the chosen machine cannot use -- the reason is shown on the status line and you stay on the screen to fix it.
:alt: The Boot Priority sub-page of the Storage tab
:width: 75%

The Boot Priority sub-page: an A1200 whose IDE master boots at priority 0, its
slave with the Bootable box cleared (showing the -128 that stores), and one
SCSI unit of a fitted A2091 carrying a disk of its own. A greyed **Info:**
label heads a note on the valid priority range.

Saved files use the same schema as a hand-written copperline.toml (see ), so the screen and the config file are interchangeable: configure a machine and save it, or load an existing config to tweak it. Run builds the machine in place, so the configuration screen and a direct --config launch produce an identical machine.

Recording video

Cmd+R on macOS or Alt+R on Linux/Windows (or the menu's "Record Video") starts capturing the emulated display and sound to copperline-video-<YYYYMMDDHHmmSS>.avi in the working directory; pressing it again stops and finalizes the file. A red REC badge sits in the display's top-right corner while a recording runs -- like the screenshot overlay, the badge, status bar, and menus are never part of the captured video.

The file is an AVI with lossless ZMBV video (the DOSBox capture codec: zlib-compressed keyframes plus frame deltas, which keeps typical Amiga output to a few MB per minute) and uncompressed 16-bit stereo PCM audio at 44.1 kHz. It plays directly in VLC, mpv, and anything else built on ffmpeg; for other players, transcode with ffmpeg -i copperline-video-<ts>.avi out.mp4.

Frames and audio are captured on the emulated timeline, not the host clock: the recording stays in sync even when the host stutters, and a capture made under Warp Speed plays back at normal speed. The audio track is tapped before the status bar's volume slider, so recordings keep full level regardless of the live output volume. Pausing (or powering off) suspends the capture; recording resumes when emulation continues.

Recording input

Cmd+Shift+R on macOS or Alt+Shift+R on Linux/Windows (or the menu's "Record Input") starts logging every input event that reaches the emulated machine -- key presses with their hold times, mouse buttons and motion, joystick / CD32-pad controls, analogue pot positions, and floppy inserts, on whichever port carries each device -- each stamped with its emulated time. Pressing it again stops the recording and writes copperline-input-<YYYYMMDDHHmmSS>.clscript in the working directory: a plain text file of scripted-input directives that copperline --script FILE replays exactly, because the core is deterministic and the events re-fire at the same emulated timestamps.

This is the direct way to turn "I can reproduce it by hand" into a regression: play the sequence once while recording, then keep the script (optionally together with a save state to skip the lead-in) as a deterministic, shareable reproduction. The format and the headless --record-input variant are described in .

(save-states)=

Save states

Cmd+Shift+S on macOS or Alt+Shift+S on Linux/Windows (or the menu's "Save State") writes a snapshot of the whole emulated machine to copperline-state-<YYYYMMDDHHmmSS>.clstate in the working directory: CPU, chip/slow/fast RAM, ROM, the full chipset and CIA state, floppy images (including unsaved in-memory changes), expansion boards, and CD/NVRAM state. Cmd+Shift+L / Alt+Shift+L (or "Load State...") restores one; the machine continues from exactly the saved point, byte-for-byte -- the core is deterministic, so a resumed run is indistinguishable from one that was never interrupted.

States are taken at emulated-frame boundaries and are versioned: a file from an older, incompatible build is refused with a clear message rather than producing a corrupt machine.

A state is self-contained: it carries its own RAM, ROM, and chipset, so loading one always restores the machine it was taken on -- even if you launched Copperline with a different config. When the loaded machine differs from the running one -- a different model, chipset, video standard, RAM size, or even a different Kickstart of the same machine (the ROM is fingerprinted) -- the load reconfigures to match the state and tells you so (the load message names the restored machine, e.g. "reconfigured to A1200 / 68EC020 / AGA / PAL"); your current config is not silently mixed in. Two caveats:

  • Hard-drive images (HDF files) are referenced by path, not embedded. The state reopens the same file on load, so guest writes made to the hard drive after the snapshot are still visible after restoring -- treat a state as a CPU/chipset snapshot, not a disk backup. In-memory volumes (directory-as-HDD) and floppy images are embedded whole.
  • CD images are likewise reopened by path; keep the cue/bin (or CHD) where it was.

Quick-save slots

Naming a file is the wrong interaction for the "before this jump" save you take twenty times an hour, so there are ten numbered slots as well. Cmd/Alt+<digit> saves to that slot and Cmd/Alt+Shift+<digit> loads it, with 0 as the tenth. The menu's Quick Save and Quick Load lists reach the same ten, each row naming when that slot was written or showing it as empty.

A quick save overwrites its slot without asking -- that is the point of it -- and loading a slot that has never been written reports "Slot N is empty" rather than failing. Slots are ordinary .clstate files, identical in format to a named save, kept per user rather than per working directory so they are reachable however Copperline was launched:

Host Location
Linux/BSD $XDG_CONFIG_HOME/copperline/states/, else ~/.config/copperline/states/
macOS ~/.config/copperline/states/
Windows %APPDATA%\copperline\states\

Because they are per user and not per machine, a slot may hold a state from a different Amiga than the one running. That is safe: as above, the state carries its own machine and the load reconfigures to match it and says so.

The headless flags --save-state-after SECS PATH and --load-state PATH script the same feature for debugging workflows: snapshot a long-running program just before the scene under investigation once, then iterate from the state in seconds instead of re-emulating minutes. The file format and what exactly is (and is not) captured are specified in the internals chapter.

Controller ports

An Amiga has two game ports, and either accepts any controller. Copperline models that: each port carries a device -- mouse, joystick, cd32 pad, analogue paddles, or none -- set with [input] port1/port2 in the config (or --port1/--port2, or the launcher's Input tab). The default is the stock wiring, a mouse in port 1 and a joystick in port 2 (a CD32 pad on the CD32 profile). The runtime menu's Port 1 Device / Port 2 Device items hot-plug a different device live, exactly like swapping the physical plug: the old device's lines release, and the port's quadrature counters hold.

The host mouse drives the (lowest-numbered) port with a mouse plugged in and feeds its JOYxDAT counters. Click the display (or press Cmd+G on macOS or Alt+G on Linux/Windows) to capture the host mouse; the same shortcut releases it. The click that takes the capture is a window action and is not passed to the Amiga, so the first click that reaches the guest is the first one aimed at it -- otherwise a single click on a gadget arrives as two, close enough together to read as a double click.

While an overlay panel is open, host cursor motion is not fed to the emulated mouse. Tool windows likewise keep the debugger or analyzer interaction separate from Amiga mouse input. A panel or tool window opened while the mouse was captured borrows the cursor and hands the capture back when the last of them closes, so a visit to the debugger does not leave the machine uncaptured -- which matters most in fullscreen, where there is no desktop to reach for. An explicit Cmd/Alt+G release settles it the other way: the capture stays off.

Uncaptured, host cursor motion over the display still drives the emulated mouse, and [input] mouse_sensitivity scales it the same way it scales captured motion. At the default setting the factor is 1.0 and the pointer tracks the host cursor one-for-one.

[input] mouse_capture (--mouse-capture, the launcher's Input tab) changes when the grab is taken: auto grabs whenever the window has the focus and on entering fullscreen, so no host cursor is ever loose over the display, and manual grabs only on the shortcut, leaving display clicks to go straight to the Amiga. See Mouse capture.

A USB gamepad drives the emulated digital joystick on whichever port one is plugged into: directions through JOYxDAT, fire through /FIRx, and a second button through POTxY/POTGOR. A cd32 device speaks the CD32 serial button protocol instead, including the red/blue/green/yellow and transport buttons, on either port. An analogue device presents pot resistances on the POTxX/POTxY pins; no live host device maps to it yet -- drive it with --pot-after scripting or the control protocol's input.analogue.

Copperline can also emulate the joystick from the host keyboard. There are two explicit input modes, and the active one is always shown by the gamepad / keyboard icon in the status bar (next to the volume control), so a "my keys aren't working" surprise can be spotted and fixed at a glance:

  • gamepad (the default): use only a calibrated gamepad; every keyboard key passes through to the Amiga. With no pad connected there is no joystick input. This is the no-surprise mode for interactive AmigaOS setup.
  • keyboard: use the keyboard-joystick mapping so the joystick port works without a controller.

With joysticks (or pads) in both ports -- a two-player setup -- the gamepad and the cursor-key mapping drive one port each, and the mode picks which source gets the lower-numbered port. Whenever no physical pad is present, a second keyboard mapping on the numeric keypad stands in for it, so two players can share one keyboard.

With mice in both ports, the host mouse drives the lower-numbered one and the cursor-key mapping drives the second as an emulated mouse (in keyboard mode; in gamepad mode the second mouse is undriven and the keyboard passes through). The same applies whenever the keyboard-routed port carries a mouse: the mapping's keys become the pointer.

Click the status-bar icon to flip between them; the menu's Joystick Input item and Cmd+J on macOS / Alt+J on Linux and Windows do the same. Set the starting mode with [input] joystick in the config (or --joystick MODE, or the launcher's Input tab).

The primary keyboard mapping is FS-UAE-compatible: cursor keys for directions, and Right Ctrl, Right Alt or Left Ctrl for fire, with Left Alt as the second button (the left-hand fire keys pair naturally with the right-hand arrows, and compact keyboards often lack the right-side modifiers). For CD32 pad buttons, C is red/fire, X is blue, D is green, S is yellow, Return is play/pause, Z is rewind, and A is forward. On a mouse port the same keys drive the pointer: cursor keys move it, the fire keys are the left button, X or Left Alt the right, and D the middle. The second (numpad) mapping is 8/2/4/6 for directions, 0 for fire, . for the second button, and numpad Enter for play. While a mapping owns its keys, they are not sent to the Amiga keyboard.

Those are the defaults; every binding is editable from the menu's Input Mapping... item (see ). A held fire button can also be turned into a pulse train with the Autofire item or [input] autofire_hz.

Gamepad calibration

Pads are read through raw gilrs events with no controller database, so each controller is calibrated once: push each control when prompted. This records raw axis/button codes and directions, which makes any pad work regardless of database coverage and handles inverted or odd axis layouts automatically.

:alt: The gamepad calibration window
:width: 75%

The calibration window mid-flow. Skip covers pads without the CD32 extras.

Run it either from the menu ("Calibrate Gamepad...") -- which ends with a live test of the finished bindings and a Save button that makes them live immediately -- or from the terminal with copperline --calibrate-gamepad. The steps are the four directions, fire (CD32 red), button 2 (CD32 blue), and the optional CD32 green/yellow/play/rewind/forward buttons; every step waits for the pad to return to neutral before sampling, so a held control cannot bleed into the next binding.

Calibrations are saved per controller UUID in ~/.config/copperline/gamepads.toml ($XDG_CONFIG_HOME respected; %APPDATA%\copperline\ on Windows).

Input mapping

The keyboard also stands in for a controller, on two independent mappings so one keyboard can drive a two-player setup (see ). The menu's Input Mapping... item edits both.

:alt: The input mapping window
:width: 75%

Editing the first keyboard mapping, with the Fire row armed for capture.

Pick the mapping with the Controller 1 / Controller 2 tabs, then Set on a row and press the key to bind (Escape cancels that row without closing the panel). Clear unbinds a control entirely, Defaults restores the built-in layouts, and Save writes the map and applies it to the running machine. Closing the window discards the edits.

A control may hold several keys, and they OR together: fire ships bound to Right Ctrl, Right Alt, Left Ctrl and C, so compact keyboards without the right-hand modifiers still work, and releasing one alias while another is held keeps the button down. Binding a key removes it from wherever it was before -- including from the other mapping -- so the two controllers can never end up fighting over one key.

Saved maps live next to the gamepad calibrations, in ~/.config/copperline/keymap.toml (same per-platform locations as above). Deleting the file restores the defaults.