AMSpiriT Lite — Quick Reference

AMSpiriT Lite is a Linux/Windows Amstrad CPC emulator based on the AMSpiriT core by David MANUEL.

Control Keys

Key	Action
`F1`	Open this help in the browser
`F2`	Save a PNG screenshot in the current directory
`F4`	Quick-save snapshot to current slot
`Shift`+`F4`	Quick-load snapshot from current slot
`F6`	Debugger: step back (timelapse rewind, when paused and available)
`F7`	Debugger: pause if running; step (BASIC statement or Z80 instruction) if paused
`F8`	Debugger: step over (Z80 `CALL`/`CALL cc` or BASIC `GOSUB`; else a plain step)
`F9`	Debugger: resume (only while paused)
`Shift`+`F9`	Toggle turbo mode (full speed, audio muted)
`F10`	Hard reset (cold boot)
`Shift`+`F10`	Soft reset (warm restart)
`F11` (SDL only)	Cycle monitor preset (colour CTM644, green GT65, TV, ASIC variants)
`Shift`+`F11`	Cycle screen types (colour, green monitor, ASIC variants)
`Ctrl`+`F11` (SDL only)	Toggle FPS overlay
`Ctrl`+`Shift`+`F11` (SDL only)	Cycle CRTC debug visualisation modes
`F12`	Toggle fullscreen / windowed
`Shift`+`F12`	Toggle display: visible CPC screen ↔ full CRTC frame
`Pause`	Pause / Resume emulation
`→` (when paused)	Step one frame forward
`←` / `→` (when paused, timelapse on)	Navigate rewind history one frame at a time
`Alt`+`F4`	Close window (handled by the window manager)
`Ctrl`+`1` to `Ctrl`+`0`	CPC numpad 1–0 (for laptops without a numeric keypad)
Mouse wheel (up/down)	Adjust volume (±10% per scroll)
Mouse middle click	Toggle mute / unmute

Note: F6-F9 mirror the web page's step-by-step debugger (--web-server). BASIC vs Z80 stepping is auto-detected from whether a BASIC program is currently running — there is no tab to select, unlike the web page.

Loading Files

Drag and drop a file onto the emulator window to load it. The Qt frontend also has a File menu to open a file dialog.

Tip: hold Ctrl while dropping a file to perform a hard reset before loading — useful for starting a disk image in a clean machine state.

Format	Description
`.dsk`	Standard disk image
`.hfe` / `.ipf`	High-fidelity disk image (CAPS)
`.cdt` / `.wav`	Tape (CDT or WAV audio)
`.sna`	Snapshot (saved state)
`.cpr`	CPC Plus / GX4000 cartridge — automatically switches to CPC 6128+ model and CRTC type 3

Snapshot Slots

AMSpiriT Lite maintains 4 quick-save slots (1–4) per game. Slots are stored alongside the ROM/disk image and persist across sessions.

Action	Key / Button
Quick-save to current slot	`F4`
Quick-load from current slot	`Shift`+`F4`
Cycle to next slot (while paused)	Gamepad Start / + button
Cycle to previous slot (while paused)	Gamepad Select / − button
Save to slot (while running)	Gamepad Start / + button
Load from slot (while running)	Gamepad Select / − button

In the Qt frontend, snapshot slots are also accessible from the Emulation → Snapshots menu and from the web debug interface.

Timelapse / Rewind

The optional timelapse feature records a rolling buffer of CPC state snapshots in RAM as the emulator runs. When paused, you can step backwards and forwards through the recorded history — useful for debugging, finding the right moment to screenshot, or just rewinding a bad move in a game.

Enable timelapse at startup with --enable-timelapse. In the Qt frontend, use the Emulation → Timelapse menu to enable it and adjust settings.

Key / Action	Description
`←` (when paused)	Step one frame backward in the timelapse history
`→` (when paused)	Step one frame forward (toward present), or step one normal frame if fully caught up
D-pad ← (gamepad, when paused)	Step backward in timelapse
D-pad → (gamepad, when paused)	Step forward in timelapse / resume if at head

The status bar / title shows < N / M while rewound (N frames ahead of oldest, M total stored).

Memory: each snapshot is approximately 130 KB (CPC 6128). The default buffer holds 100 frames (~13 MB); adjust with --timelapse-slots N.

Turbo Mode

Turbo mode disables 50 Hz pacing and mutes audio, letting the emulator run at the host CPU's full speed. Useful for skipping long tape loads or intros.

Press Shift+F9 to toggle turbo on or off at any time.
When launched with --turbo together with --autotype or -A, turbo stops automatically once the auto-typing sequence finishes.

Gamepad / Joystick

The Qt frontend uses the SDL2 GameController API (XInput on Windows, evdev on Linux, GameController on macOS). The SDL frontend uses the legacy joystick API. Both detect controllers at startup and on hot-plug; the first controller found maps to CPC joystick port 1.

Button	Action (while running)	Action (while paused)
A	Fire 1	—
B	Fire 2	—
X	Fire 3	—
Y / Guide	Pause	Resume
Start / +	Quick-save to current slot	Cycle to next slot
Select / −	Quick-load from current slot	Cycle to previous slot
Left stick / D-pad	Directions (Up/Down/Left/Right)	Navigate timelapse (if active)

SDL frontend: uses raw joystick button numbers (Button 0–3 = Fire 1/2/3/Pause, Button 7/9 = Start, Button 6/8 = Select). The CPC Plus analog axis is supported on both frontends.

Web Debug Server

When launched with --web-ui (or --web-server), the emulator starts a local HTTP server that exposes a web interface in the browser: Z80 registers, Gate Array, PSG, FDC, FPS, and controls (pause, reset, model change).

amspirit-lite-sdl --web-ui [--web-addr 0.0.0.0] [--web-port 8765] [--web-html path/to/ui.html]

Option	Description
`--web-ui`	Enable the server (disabled by default)
`--web-addr <address>`	Bind address (default: `127.0.0.1` — local only; use `0.0.0.0` for all interfaces)
`--web-port <port>`	Listening port (default: `8765`)
`--web-html <file>`	Path to the HTML UI file (default: `amspirit-lite.html` next to the binary)

The amspirit-lite.html file can be edited without recompiling. If the file is missing, the UI embedded in the binary is used as a fallback.

BASIC Editor

The web interface includes a BASIC tab for working with Locomotive BASIC programs:

Paste or upload Locomotive BASIC source code
Inject: tokenizes and writes the program directly into CPC RAM at address 0x0170
Export: reads and detokenizes the current BASIC program from RAM
Parameters: ?reset=1 (hard reset first), ?run=1 (auto-type RUN after inject)
Maximum size: ~44 KB per CPC model

Keyboard Mapping

The Keyboard tab displays the current keyboard layout and all mapped keys (read-only reference for debugging keyboard input issues).

Snapshot Slots

The Snapshots tab manages the 4 persistent save slots:

Quick-save: F4
Quick-load: Shift+F4
Each slot shows state (saved/empty), file size, and save timestamp

Command-Line Options

amspirit-lite-sdl [OPTIONS] [FILE]

Emulation

Option	Description
`-m <model>`	CPC model: `464`, `664`, `6128` (default), `6128+`, `464+`, `GX4000`
`-c <type>`	CRTC type (0 to 4)
`-R <path>`	ROMs directory (default: `./ROMs`)
`-C <path>`	Config directory (default: `./config`)
`-k <layout>` / `--keyboard <layout>`	Select keyboard layout: FR, EN, US, ES, DA, DE, IT, PT, BE, SW, CA (default: FR)
`-F`	Start in fullscreen
`-Z` / `--turbo`	Start in turbo mode (full speed)

Auto-loading

Option	Description
`-A` / `--autorun`	Auto-type `RUN"` after boot to launch the first program
`-T <name>` / `--run <name>`	Auto-type `RUN"<name>` at startup
`-t <file>` / `--autotype <file>`	Type the contents of a text file into the CPC after boot
`--basic <file>` / `-b <file>`	Tokenize and inject a Locomotive BASIC program into RAM (~3s after boot)

Audio and display

Option	Description
`-L <ms>` / `--audio-latency <ms>`	Audio buffer latency in milliseconds (default: 80 — increase if audio crackles)
`--show-overlay`	Show FPS indicator in the top-left corner (red = too slow, blue = too fast)

Timelapse / Rewind

Option	Description
`--enable-timelapse`	Enable in-RAM rewind buffer (records a snapshot every N frames)
`--timelapse-interval <N>`	Frames between timelapse snapshots (default: 10)
`--timelapse-slots <N>`	Maximum number of snapshots to keep in the buffer (default: 100, ~13 MB)

Web debug server

Option	Description
`--web-ui` / `--web-server`	Enable the HTTP debug server (disabled by default)
`--web-addr <address>`	Bind address (default: `127.0.0.1`)
`--web-port <port>`	Listening port (default: `8765`)
`--web-html <file>`	Path to the debug UI HTML file

Miscellaneous

Option	Description
`-K`	Enable verbose keyboard debug output to stderr
`--dump-keymap`	Generate a reference `keymap.cfg` file based on the current layout and output to stdout
`-X <seconds>`	Auto-quit after N seconds (automated testing)

Keymap Configuration (keymap.cfg)

Generate a keymap.cfg file using the --dump-keymap option, then edit it to your preferences and restart the emulator:

amspirit-lite-sdl --dump-keymap > keymap.cfg

Place the generated keymap.cfg in your ROMs/ or config/ directory. The file uses INI format with two sections: [keyboard layout] and [emulator hotkeys].

Supported hotkey actions: PAUSE, HELP, SCREENSHOT, SNAPSHOT_SAVE, SNAPSHOT_LOAD, VOLUME_UP, VOLUME_DOWN, TURBO, HARD_RESET, SOFT_RESET, FULLSCREEN, FULL_FRAME, CYCLE_SCREEN, TOGGLE_OVERLAY, CYCLE_CRTC, CYCLE_MONITOR, FRAME_STEP, OPEN_FILE, QUIT

Key format: Single key (F1, A, Escape, Return, Space) or modifiers (Ctrl+X, Shift+F1, Alt+Shift+P). Case-insensitive.

Changes take effect on next restart. To find a key's code, run with -K flag and watch for DOWN messages in the console. Note: SDL and Qt applications use different key codes; use separate keymap files for each if you run both.

AMSpiriT core by David MANUEL — Linux port by Siko — amspirit.fr