🇬🇧 🇫🇷 🇪🇸 🇩🇪

# AMSpiriT Lite — Quick Reference

AMSpiriT Lite is a Linux 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
`Shift`+`F4` | Save a snapshot (.sna) to current slot
`Ctrl`+`F4` | Load snapshot from current slot
`Ctrl`+`0` to `Ctrl`+`9` | Switch to snapshot slot 0–9 (persistent saves)
`Ctrl`+`E` | Export (detokenize) BASIC program from RAM
`F7` | Volume down (-10%)
`F8` | Volume up (+10%)
`F9` | Toggle turbo mode (full speed, audio muted)
`F10` | Hard reset (cold boot)
`Shift`+`F10` | Soft reset (warm restart)
`F11` | Cycle screen types (colour, green monitor, ASIC variants)
`Shift`+`F11` | Toggle FPS overlay
`Ctrl`+`F11` | Cycle CRTC debug visualisation modes
`F12` | Toggle fullscreen / windowed
`Shift`+`F12` | Toggle display: visible CPC screen ↔ full CRTC frame
`Pause` | Pause / Resume emulation
`Ctrl`+`O` | Open a file selection dialog
`Alt`+`F4` | Close window (handled by the window manager)
`Esc` | Quit (only when emulation is paused)
`Ctrl`+`1` to `Ctrl`+`0` | CPC numpad 1–0 (for laptops without a numeric keypad)

## Loading Files

Drag and drop a file onto the emulator window to load it, or use `Ctrl`+`O` to open a file dialog (requires zenity or kdialog).

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

## 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 `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.

## Joystick

USB joysticks are detected automatically at startup and on connection. The first joystick found is mapped to CPC joystick port 1.

Button | CPC action
--- | ---
Button 0 | Fire 1
Button 1 | Fire 2
Button 2 | Fire 3
Button 3 / Start | Pause / Resume emulation
LB (Left Bumper) | Quick-save snapshot to current slot
RB (Right Bumper) | Quick-load snapshot from current slot
Axis X / Y or hat | Directions (up, down, left, right)

## Web Debug Server

When launched with `--web-ui`, the emulator starts a local HTTP server that exposes a debug 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 10 persistent save slots (0–9):

- Quick-save: `Shift`+`F4` or gamepad LB
- Quick-load: `Ctrl`+`F4` or gamepad RB
- Switch slot: `Ctrl`+`0` to `Ctrl`+`9`
- Each slot shows state (saved/empty), file size, and save timestamp

## Keyboard Layout and Configuration

The default keyboard layout is French (AZERTY). AMSpiriT supports 11 keyboard layouts: `FR` (French), `EN` (English), `US` (USA), `ES` (Spanish), `DA` (Danish), `DE` (German), `IT` (Italian), `PT` (Portuguese), `BE` (Belgian), `SW` (Swiss), `CA` (Canadian).

To select a layout, use: `amspirit-lite-sdl --keyboard EN` or `-k EN`

### AZERTY FR Layout Details

When using the French AZERTY layout, letters and standard special keys work normally. The table below summarises the differences between the PC AZERTY layout and the CPC.

### Number row

PC key (unshifted) | CPC result | PC key (with Shift) | CPC result
--- | --- | --- | ---
`&` | & | `Shift`+`&` (key 1) | 1
`é` | é | `Shift`+`é` (key 2) | 2
`"` | " | `Shift`+`"` (key 3) | 3
`'` | ' | `Shift`+`'` (key 4) | 4
`(` | ( | `Shift`+`(` (key 5) | 5
`-` | - | `Shift`+`-` (key 6) | 6
`è` | è | `Shift`+`è` (key 7) | 7
`_` | _ | `Shift`+`_` (key 8) | 8
`ç` | ç | `Shift`+`ç` (key 9) | 9
`à` | à | `Shift`+`à` (key 0) | 0

### Punctuation and symbols

PC key | CPC result | With Shift | CPC result
--- | --- | --- | ---
`,` | , | `Shift`+`,` | ?
`;` | ; | `Shift`+`;` | .
`:` | : | `Shift`+`:` | /
`=` | = | `Shift`+`=` | +
`<` (ISO key) | < | `Shift`+`<` | >
`ù` | ù | `Shift`+`ù` | %
`$` | $ | `Shift`+`$` | £
`µ` | µ | — | —
`°` | ° | — | —
`)` | ) | — | —

AltGr: the AltGr key is absorbed and never forwarded to the CPC. AltGr-modified characters (|, {, }, ~, @, …) reach the emulator through their SDL sym directly.

## 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)

### 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, BASIC_EXPORT, VOLUME_UP, VOLUME_DOWN, FULLSCREEN, MONITOR_TYPE, CRTC_SELECT, VISIBLE_FRAME

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