🇬🇧 🇫🇷 🇪🇸 🇩🇪

# AMSpiriT Lite — Kurzreferenz

AMSpiriT Lite ist ein Linux/Windows-Amstrad-CPC-Emulator, der auf dem AMSpiriT-Kern von David MANUEL basiert.

## Steuertasten

Taste | Aktion
--- | ---
`F1` | Diese Hilfe im Browser öffnen
`F2` | PNG-Screenshot im aktuellen Verzeichnis speichern
`F4` | Schnellspeicherung im aktuellen Slot
`Shift`+`F4` | Schnellladung aus dem aktuellen Slot
`F6` | Debugger: Schritt zurück (Timelapse-Rückspulung, im Pausenmodus und falls verfügbar)
`F7` | Debugger: pausieren, falls aktiv; Einzelschritt (BASIC-Anweisung oder Z80-Befehl), falls pausiert
`F8` | Debugger: Prozedurschritt (Z80 `CALL`/`CALL cc` oder BASIC `GOSUB`; sonst ein einfacher Schritt)
`F9` | Debugger: fortsetzen (nur im Pausenmodus)
`Shift`+`F9` | Turbo-Modus ein-/ausschalten (volle Geschwindigkeit, Audio stumm)
`F10` | Kalt-Reset (Cold Boot)
`Shift`+`F10` | Warm-Reset (Warm Restart)
`F11` (nur SDL) | Monitor-Voreinstellung wählen (Farbe CTM644, Grün GT65, TV, ASIC-Varianten)
`Shift`+`F11` | Bildschirmtypen durchschalten (Farbe, Grünmonitor, ASIC-Varianten)
`Ctrl`+`F11` (nur SDL) | FPS-Anzeige ein-/ausblenden
`Ctrl`+`Shift`+`F11` (nur SDL) | CRTC-Debug-Visualisierungsmodi durchschalten
`F12` | Vollbild / Fenstermodus umschalten
`Shift`+`F12` | Ansicht umschalten: sichtbarer CPC-Bildschirm ↔ vollständiger CRTC-Rahmen
`Pause` | Emulation pausieren / fortsetzen
`→` (pausiert) | Um einen Frame vorwärts spulen
`←` / `→` (pausiert, Timelapse aktiv) | Rückspul-Verlauf Frame für Frame navigieren
`Alt`+`F4` | Fenster schließen (vom Fenstermanager verwaltet)
`Ctrl`+`1` bis `Ctrl`+`0` | CPC-Ziffernblock 1–0 (für Laptops ohne Ziffernblock)
Mausrad (oben/unten) | Lautstärke anpassen (±10% pro Schritt)
Mittlere Maustaste | Stummschaltung ein-/ausschalten

Hinweis: `F6`-`F9` entsprechen dem Einzelschritt-Debugger der Webseite (`--web-server`). BASIC- oder Z80-Modus wird automatisch erkannt, je nachdem ob gerade ein BASIC-Programm läuft — es gibt keinen Tab zur Auswahl wie auf der Webseite.

## Dateien laden

Ziehen Sie eine Datei auf das Emulatorfenster, um sie zu laden. Das Qt-Frontend hat auch ein Datei-Menü zum Öffnen eines Dateidialogs.

Tipp: Halten Sie `Ctrl` gedrückt, während Sie eine Datei ablegen, um vor dem Laden einen Kalt-Reset durchzuführen — nützlich, um ein Disk-Image in einem sauberen Maschinenzustand zu starten.

Format | Beschreibung
--- | ---
`.dsk` | Standard-Disk-Image
`.hfe` / `.ipf` | High-Fidelity-Disk-Image (CAPS)
`.cdt` / `.wav` | Kassette (CDT oder WAV-Audio)
`.sna` | Snapshot (gespeicherter Zustand)
`.cpr` | CPC Plus / GX4000 Cartridge — wechselt automatisch zum CPC 6128+-Modell und CRTC-Typ 3

## Snapshot-Slots

AMSpiriT Lite verwaltet 4 Schnellspeicher-Slots (1–4) pro Spiel. Slots werden zusammen mit dem ROM/Disk-Image gespeichert und bleiben zwischen Sitzungen erhalten.

Aktion | Taste / Button
--- | ---
Schnellspeicherung im aktuellen Slot | `F4`
Schnellladung aus dem aktuellen Slot | `Shift`+`F4`
Zum nächsten Slot wechseln (pausiert) | Gamepad Start / + Taste
Zum vorherigen Slot wechseln (pausiert) | Gamepad Select / − Taste
In Slot speichern (laufend) | Gamepad Start / + Taste
Aus Slot laden (laufend) | Gamepad Select / − Taste

Im Qt-Frontend sind Snapshot-Slots auch über das Menü Emulation → Snapshots und die Web-Debug-Oberfläche zugänglich.

## Timelapse / Rückspulen

Die optionale Timelapse-Funktion zeichnet einen zirkulären Puffer von CPC-Zustand-Snapshots im RAM während der Ausführung auf. Im pausiert-Modus können Sie vorwärts und rückwärts durch den aufgezeichneten Verlauf navigieren — nützlich zum Debuggen, zum Finden des richtigen Moments für Screenshots oder zum Rückspulen nach einem falschen Zug in einem Spiel.

Aktivieren Sie Timelapse beim Start mit `--enable-timelapse`. Im Qt-Frontend verwenden Sie das Menü Emulation → Timelapse zum Aktivieren und Anpassen der Einstellungen.

Taste / Aktion | Beschreibung
--- | ---
`←` (pausiert) | Um einen Frame rückwärts im Timelapse-Verlauf spulen
`→` (pausiert) | Um einen Frame vorwärts spulen (zur Gegenwart), oder einen normalen Frame, wenn auf dem aktuellen Stand
D-pad ← (Gamepad, pausiert) | In Timelapse rückwärts spulen
D-pad → (Gamepad, pausiert) | In Timelapse vorwärts spulen / fortsetzen, wenn auf aktuellem Stand

Die Statusleiste / Titel zeigt `< N / M` während des Rückspulens (N Frames vor dem ältesten, M insgesamt gespeichert).

Speicher: jeder Snapshot belegt ungefähr 130 KB (CPC 6128). Der Standard-Puffer enthält 100 Frames (~13 MB); passen Sie mit `--timelapse-slots N` an.

## Turbo-Modus

Der Turbo-Modus deaktiviert die 50-Hz-Kadenz und schaltet das Audio aus, sodass der Emulator mit voller CPU-Geschwindigkeit läuft. Nützlich, um lange Kassettenladezeiten oder Intros zu überspringen.

- Drücken Sie `Shift`+`F9`, um den Turbo-Modus jederzeit ein- oder auszuschalten.
- Bei Start mit `--turbo` zusammen mit `--autotype` oder `-A` stoppt der Turbo automatisch, wenn die automatische Tippsequenz abgeschlossen ist.

## Gamepad / Joystick

Das Qt-Frontend nutzt die SDL2 GameController API (XInput unter Windows, evdev unter Linux, GameController auf macOS). Das SDL-Frontend nutzt die Legacy-Joystick-API. Beide erkennen Controller beim Start und bei Verbindung; der erste gefundene Controller wird dem CPC-Joystick-Port 1 zugeordnet.

Taste | Aktion (während der Ausführung) | Aktion (pausiert)
--- | --- | ---
A | Feuer 1 | —
B | Feuer 2 | —
X | Feuer 3 | —
Y / Guide | Pausieren | Fortsetzen
Start / + | Schnellspeicherung im aktuellen Slot | Zum nächsten Slot wechseln
Select / − | Schnellladung aus dem aktuellen Slot | Zum vorherigen Slot wechseln
Linker Stick / D-pad | Richtungen (Oben/Unten/Links/Rechts) | Timelapse navigieren (falls aktiv)

SDL-Frontend: nutzt rohe Joystick-Buttonnummern (Taste 0–3 = Feuer 1/2/3/Pause, Taste 7/9 = Start, Taste 6/8 = Select). Die CPC Plus analoge Achse wird auf beiden Frontends unterstützt.

## Web-Debug-Server

Beim Start mit `--web-ui` (oder `--web-server`) startet der Emulator einen lokalen HTTP-Server, der eine Web-Oberfläche im Browser bereitstellt: Z80-Register, Gate Array, PSG, FDC, FPS und Steuerungen (Pause, Reset, Modellwechsel).

    amspirit-lite-sdl --web-ui [--web-addr 0.0.0.0] [--web-port 8765] [--web-html Pfad/zur/ui.html]

Option | Beschreibung
--- | ---
`--web-ui` | Server aktivieren (standardmäßig deaktiviert)
`--web-addr <Adresse>` | Bind-Adresse (Standard: `127.0.0.1` — nur lokal; `0.0.0.0` für alle Schnittstellen)
`--web-port <Port>` | Listening-Port (Standard: `8765`)
`--web-html <Datei>` | Pfad zur HTML-UI-Datei (Standard: `amspirit-lite.html` neben der Binärdatei)

Die Datei `amspirit-lite.html` kann ohne Neukompilierung bearbeitet werden. Falls sie fehlt, wird die in der Binärdatei eingebettete UI als Fallback verwendet.

### BASIC-Editor

Die Web-Oberfläche enthält einen BASIC-Tab zum Arbeiten mit Locomotive-BASIC-Programmen:

- Einfügen oder Hochladen von Locomotive-BASIC-Quellcode
- Einspritzen: tokenisiert und schreibt das Programm direkt in den CPC-RAM unter Adresse 0x0170
- Exportieren: liest und detokenisiert das aktuelle BASIC-Programm aus dem RAM
- Parameter: `?reset=1` (Kalt-Reset zuerst), `?run=1` (Auto-Typ RUN nach dem Einspritzen)
- Maximale Größe: ~44 KB pro CPC-Modell

### Tastaturbelegung

Der Tastatur-Tab zeigt das aktuelle Tastatur-Layout und alle zugeordneten Tasten an (Referenz zum Lesen für das Debugging von Tastatureingabeproblemen).

### Snapshot-Slots

Der Snapshots-Tab verwaltet die 4 persistenten Slots:

- Schnellspeicherung: `F4`
- Schnellladung: `Shift`+`F4`
- Jeder Slot zeigt Status (gespeichert/leer), Dateigröße und Zeitstempel

## Befehlszeilenoptionen

    amspirit-lite-sdl [OPTIONEN] [DATEI]

### Emulation

Option | Beschreibung
--- | ---
`-m <Modell>` | CPC-Modell: `464`, `664`, `6128` (Standard), `6128+`, `464+`, `GX4000`
`-c <Typ>` | CRTC-Typ (0 bis 4)
`-R <Pfad>` | ROMs-Verzeichnis (Standard: `./ROMs`)
`-C <Pfad>` | Konfigurationsverzeichnis (Standard: `./config`)
`-k <Layout>` / `--keyboard <Layout>` | Tastatur-Layout wählen: FR, EN, US, ES, DA, DE, IT, PT, BE, SW, CA (Standard: FR)
`-F` | Im Vollbildmodus starten
`-Z` / `--turbo` | Im Turbo-Modus starten (volle Geschwindigkeit)

### Automatisches Laden

Option | Beschreibung
--- | ---
`-A` / `--autorun` | Tippt automatisch `RUN"` nach dem Start, um das erste Programm zu starten
`-T <Name>` / `--run <Name>` | Tippt automatisch `RUN"<Name>` beim Start
`-t <Datei>` / `--autotype <Datei>` | Tippt den Inhalt einer Textdatei nach dem Start in den CPC
`--basic <Datei>` / `-b <Datei>` | Ein Locomotive-BASIC-Programm tokenisieren und in RAM injizieren (~3s nach dem Start)

### Audio und Anzeige

Option | Beschreibung
--- | ---
`-L <ms>` / `--audio-latency <ms>` | Audio-Puffer-Latenz in Millisekunden (Standard: 80 — erhöhen bei Audioknistern)
`--show-overlay` | FPS-Anzeige in der oberen linken Ecke einblenden (rot = zu langsam, blau = zu schnell)

### Timelapse / Rückspulen

Option | Beschreibung
--- | ---
`--enable-timelapse` | Rückspul-Puffer im RAM aktivieren (nimmt alle N Frames einen Snapshot auf)
`--timelapse-interval <N>` | Frames zwischen Timelapse-Snapshots (Standard: 10)
`--timelapse-slots <N>` | Maximale Anzahl von Snapshots im Puffer (Standard: 100, ~13 MB)

### Web-Debug-Server

Option | Beschreibung
--- | ---
`--web-ui` / `--web-server` | HTTP-Debug-Server aktivieren (standardmäßig deaktiviert)
`--web-addr <Adresse>` | Bind-Adresse (Standard: `127.0.0.1`)
`--web-port <Port>` | Listening-Port (Standard: `8765`)
`--web-html <Datei>` | Pfad zur Debug-UI-HTML-Datei

### Verschiedenes

Option | Beschreibung
--- | ---
`-K` | Ausführliche Tastatur-Debug-Ausgabe zu stderr aktivieren
`--dump-keymap` | Eine Referenz-`keymap.cfg`-Datei basierend auf dem aktuellen Layout generieren und auf stdout ausgeben
`-X <Sekunden>` | Nach N Sekunden automatisch beenden (automatisierte Tests)

## Tastenbelegung konfigurieren (keymap.cfg)

Generieren Sie eine `keymap.cfg`-Datei mit der Option `--dump-keymap`, bearbeiten Sie sie nach Ihren Wünschen und starten Sie den Emulator neu:

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

Platzieren Sie die generierte `keymap.cfg`-Datei in Ihrem Verzeichnis `ROMs/` oder `config/`. Die Datei verwendet INI-Format mit zwei Abschnitten: `[keyboard layout]` und `[emulator hotkeys]`.

Unterstützte Tastenkombinationsaktionen: 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

Tastaturformat: Einzelne Taste (F1, A, Escape, Return, Space) oder Modifizierer (Ctrl+X, Shift+F1, Alt+Shift+P). Groß-/Kleinschreibung wird ignoriert.

Änderungen werden beim Neustart wirksam. Um den Code einer Taste zu finden, starten Sie den Emulator mit `-K` und suchen Sie nach `DOWN`-Meldungen in der Konsole. Hinweis: SDL- und Qt-Anwendungen verwenden unterschiedliche Tastencodes; verwenden Sie separate Keymap-Dateien für jede, wenn Sie beide ausführen.

AMSpiriT-Kern von David MANUEL — Linux-Port von Siko — amspirit.fr