🇬🇧 🇫🇷 🇪🇸 🇩🇪

# AMSpiriT Lite — Guide rapide

AMSpiriT Lite est un émulateur Amstrad CPC pour Linux 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
`Shift`+`F4` | Sauvegarder un snapshot (.sna) dans l'emplacement courant
`Ctrl`+`F4` | Charger un snapshot depuis l'emplacement courant
`Ctrl`+`0` à `Ctrl`+`9` | Sélectionner l'emplacement de snapshot 0–9 (sauvegardes persistantes)
`Ctrl`+`E` | Exporter (détokeniser) un programme BASIC de la RAM
`F7` | Baisser le volume (-10 %)
`F8` | Augmenter le volume (+10 %)
`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` | Faire défiler les types d'écran (couleur, moniteur vert, variantes ASIC)
`Shift`+`F11` | Afficher / masquer l'indicateur FPS
`Ctrl`+`F11` | Faire défiler les modes de visualisation CRTC (debug)
`F12` | Basculer plein écran / mode fenêtré
`Shift`+`F12` | Basculer l'affichage : zone visible CPC ↔ trame CRTC complète
`Pause` | Pause / Reprendre l'émulation
`Ctrl`+`O` | Ouvrir une boîte de dialogue de sélection de fichier
`Alt`+`F4` | Fermer la fenêtre (géré par le gestionnaire de fenêtres)
`Echap` | Quitter (uniquement si l'émulation est en pause)
`Ctrl`+`1` à `Ctrl`+`0` | Pavé numérique CPC 1–0 (pour les portables sans pavé numérique)

## Chargement de fichiers

Glissez-déposez un fichier sur la fenêtre de l'émulateur pour le charger, ou utilisez `Ctrl`+`O` pour ouvrir une boîte de dialogue (zenity ou kdialog requis).

Astuce : maintenez `Ctrl` pendant le glisser-déposer pour effectuer un hard reset avant le chargement, utile pour charger un disque dans un émulateur « 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 6128+ et le CRTC type 3

## 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 `F9` pour activer ou désactiver le mode turbo.
- Lancé avec `--turbo` + `--autotype` ou `-A` : le turbo s'arrête automatiquement à la fin de la frappe automatique.

## Joystick

Les joysticks USB sont détectés automatiquement au démarrage et à la connexion. Le premier joystick connecté est mappé sur le port joystick 1 du CPC.

Bouton | Action CPC
--- | ---
Bouton 0 | Feu 1
Bouton 1 | Feu 2
Bouton 2 | Feu 3
Bouton 3 / Start | Pause / Reprendre l'émulation
LB (bouton gauche) | Sauvegarde rapide du snapshot dans l'emplacement courant
RB (bouton droit) | Chargement rapide du snapshot depuis l'emplacement courant
Axe X / Y ou chapeau | Directions (haut, bas, gauche, droite)

## Serveur de debug web

Lancé avec `--web-ui`, l'émulateur démarre un mini-serveur HTTP local qui expose une interface de debug 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` | Active 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 l'application. 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 10 emplacements persistants (0–9) :

- Sauvegarde rapide : `Shift`+`F4` ou bouton gauche LB
- Chargement rapide : `Ctrl`+`F4` ou bouton droit RB
- Changer d'emplacement : `Ctrl`+`0` à `Ctrl`+`9`
- Chaque emplacement affiche son état (sauvegardé/vide), la taille du fichier et l'horodatage

## Disposition du clavier et configuration

La disposition par défaut est française (AZERTY). AMSpiriT supporte 11 dispositions de clavier : `FR` (Français), `EN` (Anglais), `US` (USA), `ES` (Espagnol), `DA` (Danois), `DE` (Allemand), `IT` (Italien), `PT` (Portugais), `BE` (Belge), `SW` (Suisse), `CA` (Canadien).

Pour sélectionner une disposition, utilisez : `amspirit-lite-sdl --keyboard EN` ou `-k EN`

### Détails AZERTY FR

Le layout AZERTY est actif par défaut. Les lettres et les touches spéciales standard fonctionnent normalement. Le tableau ci-dessous résume les particularités dues aux différences entre le clavier PC AZERTY et le CPC.

### Rangée des chiffres

Touche PC (sans Shift) | Résultat CPC | Touche PC (avec Shift) | Résultat CPC
--- | --- | --- | ---
`&` | & | `Shift`+`&` (touche 1) | 1
`é` | é | `Shift`+`é` (touche 2) | 2
`"` | " | `Shift`+`"` (touche 3) | 3
`'` | ' | `Shift`+`'` (touche 4) | 4
`(` | ( | `Shift`+`(` (touche 5) | 5
`-` | - | `Shift`+`-` (touche 6) | 6
`è` | è | `Shift`+`è` (touche 7) | 7
`_` | _ | `Shift`+`_` (touche 8) | 8
`ç` | ç | `Shift`+`ç` (touche 9) | 9
`à` | à | `Shift`+`à` (touche 0) | 0

### Ponctuation et symboles

Touche PC | Résultat CPC | Avec Shift | Résultat CPC
--- | --- | --- | ---
`,` | , | `Shift`+`,` | ?
`;` | ; | `Shift`+`;` | .
`:` | : | `Shift`+`:` | /
`=` | = | `Shift`+`=` | +
`<` (touche ISO) | < | `Shift`+`<` | >
`ù` | ù | `Shift`+`ù` | %
`$` | $ | `Shift`+`$` | £
`µ` | µ | — | —
`°` | ° | — | —
`)` | ) | — | —

AltGr : la touche AltGr est absorbée par l'émulateur et ne remonte pas au CPC. Les caractères AltGr (|, {, }, ~, @, …) passent via leur sym SDL directement.

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

### 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 les logs clavier détaillés (debug)
`--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)

Créez un fichier `keymap.cfg` dans votre dossier a l'aide de l'option `--dump-keymap` puis modifiez le a votre convenance, et relancez l'émulateur.

Actions de raccourci supportées : PAUSE, HELP, SCREENSHOT, SNAPSHOT_SAVE, SNAPSHOT_LOAD, BASIC_EXPORT, VOLUME_UP, VOLUME_DOWN, FULLSCREEN, MONITOR_TYPE, CRTC_SELECT, VISIBLE_FRAME

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.

Attention, les code des application SDL et Qt ne sont pas les memes, utilisez des fichiers differents pour chaque application si vous utilisez les deux.

AMSpiriT — amspirit.fr