🇬🇧 🇫🇷 🇪🇸 🇩🇪

# AMSpiriT Lite — Guide rapide

AMSpiriT Lite est un émulateur Amstrad CPC pour Linux/Windows basé sur le core AMSpiriT par David MANUEL.

## Touches de contrôle

Touche | Action
--- | ---
`F1` | Afficher cette aide dans le navigateur
`F2` | Sauvegarder une capture d'écran PNG dans le répertoire courant
`F4` | Sauvegarde rapide dans l'emplacement courant
`Shift`+`F4` | Chargement rapide depuis l'emplacement courant
`F6` | Débogueur : retour arrière (rembobinage timelapse, en pause et si disponible)
`F7` | Débogueur : mettre en pause si en cours d'exécution ; pas à pas (instruction BASIC ou Z80) si en pause
`F8` | Débogueur : pas à pas procédural (`CALL`/`CALL cc` Z80 ou `GOSUB` BASIC ; sinon un pas simple)
`F9` | Débogueur : reprendre (uniquement en pause)
`Shift`+`F9` | Activer/désactiver le mode turbo (vitesse maximale, audio muet)
`F10` | Hard reset (redémarrage à froid)
`Shift`+`F10` | Soft reset (redémarrage à chaud)
`F11` (SDL uniquement) | Sélectionner le mode moniteur (couleur CTM644, vert GT65, TV, variantes ASIC)
`Shift`+`F11` | Sélectionner les types d'écran (couleur, moniteur vert, variantes ASIC)
`Ctrl`+`F11` (SDL uniquement) | Afficher/masquer l'indicateur FPS
`Ctrl`+`Shift`+`F11` (SDL uniquement) | Sélectionner les modes de visualisation CRTC (debug)
`F12` | Basculer plein écran / mode fenêtré
`Shift`+`F12` | Basculer l'affichage : écran CPC visible ↔ trame CRTC complète
`Pause` | Pause / Reprendre l'émulation
`→` (en pause) | Avancer d'une trame
`←` / `→` (en pause, timelapse actif) | Naviguer dans l'historique de rembobinage trame par trame
`Alt`+`F4` | Fermer la fenêtre (géré par le gestionnaire de fenêtres)
`Ctrl`+`1` à `Ctrl`+`0` | Pavé numérique CPC 1–0 (pour les portables sans pavé numérique)
Molette de la souris (haut/bas) | Ajuster le volume (±10% par cran)
Clic bouton central de la souris | Basculer muet / démuet

Note : les touches `F6`-`F9` reproduisent le débogueur pas à pas de la page web (`--web-server`). Le mode BASIC ou Z80 est détecté automatiquement selon qu'un programme BASIC est en cours d'exécution — il n'y a pas d'onglet à sélectionner comme sur la page web.

## Chargement de fichiers

Glissez-déposez un fichier sur la fenêtre de l'émulateur pour le charger. Le frontend Qt dispose également d'un menu Fichier pour ouvrir une boîte de dialogue de sélection de fichiers.

Astuce : maintenez `Ctrl` pendant le glisser-déposer pour effectuer un hard reset avant le chargement — utile pour charger un disque dans un état propre.

Format | Description
--- | ---
`.dsk` | Image disque standard
`.hfe` / `.ipf` | Image disque haute fidélité (CAPS)
`.cdt` / `.wav` | Cassette (CDT ou audio WAV)
`.sna` | Snapshot (sauvegarde d'état)
`.cpr` | Cartouche CPC Plus / GX4000 — bascule automatiquement vers le modèle CPC 6128+ et le CRTC type 3

## Emplacements de snapshots

AMSpiriT Lite dispose de 4 emplacements de sauvegarde rapide (1–4) par jeu. Les emplacements sont stockés à côté de l'image ROM/disque et persistent entre les sessions.

Action | Touche / Bouton
--- | ---
Sauvegarde rapide dans l'emplacement courant | `F4`
Chargement rapide depuis l'emplacement courant | `Shift`+`F4`
Passer à l'emplacement suivant (en pause) | Joystick Start / + bouton
Passer à l'emplacement précédent (en pause) | Joystick Select / − bouton
Sauvegarder dans l'emplacement (en cours d'exécution) | Joystick Start / + bouton
Charger depuis l'emplacement (en cours d'exécution) | Joystick Select / − bouton

Dans le frontend Qt, les emplacements de snapshots sont aussi accessibles via le menu Émulation → Snapshots et l'interface de debug web.

## Timelapse / Rembobinage

La fonctionnalité timelapse optionnelle enregistre un buffer circulaire d'instantanés d'état du CPC en RAM au cours de l'exécution. En pause, vous pouvez naviguer vers l'avant et vers l'arrière dans l'historique enregistré — utile pour déboguer, trouver le bon moment pour une capture d'écran, ou rembobiner après une mauvaise action dans un jeu.

Activez le timelapse au démarrage avec `--enable-timelapse`. Dans le frontend Qt, utilisez le menu Émulation → Timelapse pour l'activer et ajuster les paramètres.

Touche / Action | Description
--- | ---
`←` (en pause) | Reculer d'une trame dans l'historique timelapse
`→` (en pause) | Avancer d'une trame (vers le présent), ou avancer d'une trame normale si au présent
D-pad ← (joystick, en pause) | Reculer dans le timelapse
D-pad → (joystick, en pause) | Avancer dans le timelapse / reprendre si au présent

La barre de statut / titre affiche `< N / M` lors du rembobinage (N trames avant le plus ancien, M total stockées).

Mémoire : chaque snapshot fait environ 130 Ko (CPC 6128). Le buffer par défaut contient 100 trames (~13 Mo); ajustez avec `--timelapse-slots N`.

## Mode turbo

Le mode turbo désactive la cadence 50 Hz et coupe l'audio pour faire tourner l'émulateur à pleine vitesse du CPU hôte. Utile pour passer rapidement un chargement cassette ou une intro longue.

- Appuyez sur `Shift`+`F9` pour activer ou désactiver le mode turbo à tout moment.
- Lancé avec `--turbo` associé à `--autotype` ou `-A` : le turbo s'arrête automatiquement une fois la séquence de frappe automatique terminée.

## Gamepad / Joystick

Le frontend Qt utilise l'API SDL2 GameController (XInput sur Windows, evdev sur Linux, GameController sur macOS). Le frontend SDL utilise l'API joystick legacy. Les deux détectent les manettes au démarrage et à la connexion ; la première manette détectée correspond au port joystick 1 du CPC.

Bouton | Action (en cours d'exécution) | Action (en pause)
--- | --- | ---
A | Feu 1 | —
B | Feu 2 | —
X | Feu 3 | —
Y / Guide | Pause | Reprendre
Start / + | Sauvegarde rapide dans l'emplacement courant | Passer à l'emplacement suivant
Select / − | Chargement rapide depuis l'emplacement courant | Passer à l'emplacement précédent
Stick gauche / D-pad | Directions (Haut/Bas/Gauche/Droite) | Naviguer dans le timelapse (si actif)

Frontend SDL : utilise les numéros de boutons joystick bruts (Bouton 0–3 = Feu 1/2/3/Pause, Bouton 7/9 = Start, Bouton 6/8 = Select). L'axe analogique CPC Plus est supporté sur les deux frontends.

## Serveur de debug web

Lancé avec `--web-ui` (ou `--web-server`), l'émulateur démarre un serveur HTTP local qui expose une interface web dans le navigateur : registres Z80, Gate Array, PSG, FDC, FPS, et contrôles (pause, reset, changement de modèle).

    amspirit-lite-sdl --web-ui [--web-addr 0.0.0.0] [--web-port 8765] [--web-html chemin/vers/ui.html]

Option | Description
--- | ---
`--web-ui` | Activer le serveur (désactivé par défaut)
`--web-addr <adresse>` | Adresse d'écoute (défaut : `127.0.0.1` — local uniquement ; `0.0.0.0` pour toutes les interfaces)
`--web-port <port>` | Port d'écoute (défaut : `8765`)
`--web-html <fichier>` | Chemin vers le fichier HTML de l'interface (défaut : `amspirit-lite.html` à côté du binaire)

Le fichier `amspirit-lite.html` peut être modifié sans recompiler. Si le fichier est absent, l'interface embarquée dans le binaire est utilisée comme repli.

### Éditeur BASIC

L'interface web inclut un onglet BASIC pour travailler avec les programmes Locomotive BASIC :

- Collez ou importez du code source Locomotive BASIC
- Injecter : tokenise et écrit le programme directement dans la RAM du CPC à l'adresse 0x0170
- Exporter : lit et détokenise le programme BASIC actuel depuis la RAM
- Paramètres : `?reset=1` (hard reset d'abord), `?run=1` (auto-type RUN après injection)
- Taille maximale : ~44 Ko par modèle CPC

### Mappage du clavier

L'onglet Clavier affiche la disposition de clavier actuelle et toutes les touches mappées (référence en lecture seule pour déboguer les problèmes de saisie).

### Emplacements de snapshots

L'onglet Snapshots gère les 4 emplacements persistants :

- Sauvegarde rapide : `F4`
- Chargement rapide : `Shift`+`F4`
- Chaque emplacement affiche son état (sauvegardé/vide), la taille du fichier et l'horodatage

## Options de lancement

    amspirit-lite-sdl [OPTIONS] [FICHIER]

### Émulation

Option | Description
--- | ---
`-m <modèle>` | Modèle CPC : `464`, `664`, `6128` (défaut), `6128+`, `464+`, `GX4000`
`-c <type>` | Type de CRTC (0 à 4)
`-R <chemin>` | Répertoire des ROMs (défaut : `./ROMs`)
`-C <chemin>` | Répertoire de configuration (défaut : `./config`)
`-k <disposition>` / `--keyboard <disposition>` | Sélectionner la disposition de clavier : FR, EN, US, ES, DA, DE, IT, PT, BE, SW, CA (défaut : FR)
`-F` | Démarrer en plein écran
`-Z` / `--turbo` | Démarrer en mode turbo (vitesse maximale)

### Chargement automatique

Option | Description
--- | ---
`-A` / `--autorun` | Taper automatiquement `RUN"` après le démarrage pour lancer le premier programme
`-T <nom>` / `--run <nom>` | Taper automatiquement `RUN"<nom>` au démarrage
`-t <fichier>` / `--autotype <fichier>` | Taper le contenu d'un fichier texte dans le CPC après le démarrage
`--basic <fichier>` / `-b <fichier>` | Tokeniser et injecter un programme Locomotive BASIC dans la RAM (~3s après le démarrage)

### Audio et affichage

Option | Description
--- | ---
`-L <ms>` / `--audio-latency <ms>` | Latence du tampon audio en millisecondes (défaut : 80 — augmenter si crépitements)
`--show-overlay` | Afficher l'indicateur FPS en haut à gauche (rouge = trop lent, bleu = trop rapide)

### Timelapse / Rembobinage

Option | Description
--- | ---
`--enable-timelapse` | Activer le buffer de rembobinage en RAM (enregistre un snapshot tous les N trames)
`--timelapse-interval <N>` | Nombre de trames entre les snapshots timelapse (défaut : 10)
`--timelapse-slots <N>` | Nombre maximal de snapshots à conserver dans le buffer (défaut : 100, ~13 Mo)

### Serveur web de debug

Option | Description
--- | ---
`--web-ui` / `--web-server` | Activer le serveur HTTP de debug (désactivé par défaut)
`--web-addr <adresse>` | Adresse d'écoute (défaut : `127.0.0.1`)
`--web-port <port>` | Port d'écoute (défaut : `8765`)
`--web-html <fichier>` | Chemin vers le fichier HTML de l'interface de debug

### Divers

Option | Description
--- | ---
`-K` | Activer la sortie de debug clavier verbeux vers stderr
`--dump-keymap` | Générer un fichier `keymap.cfg` de référence basé sur la disposition actuelle et sortir vers stdout
`-X <secondes>` | Quitter automatiquement après N secondes (tests automatisés)

## Configuration du clavier (keymap.cfg)

Générez un fichier `keymap.cfg` en utilisant l'option `--dump-keymap`, modifiez-le à votre guise et relancez l'émulateur :

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

Placez le fichier `keymap.cfg` généré dans votre répertoire `ROMs/` ou `config/`. Le fichier utilise le format INI avec deux sections : `[keyboard layout]` et `[emulator hotkeys]`.

Actions de raccourci supportées : 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

Format des touches : Touche unique (F1, A, Escape, Return, Space) ou modifieurs (Ctrl+X, Shift+F1, Alt+Shift+P). Insensible à la casse.

Les changements prennent effet au redémarrage. Pour trouver le code d'une touche, lancez l'émulateur avec `-K` et regardez les messages `DOWN` dans la console. Note : Les applications SDL et Qt utilisent des codes de touche différents ; utilisez des fichiers keymap séparés pour chacune si vous exécutez les deux.

Core AMSpiriT par David MANUEL — port Linux par Siko — amspirit.fr