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 (rewind, 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
`Ctrl`+`F12`	Basculer l'écran de debug (trame courante ↔ superposition)
`Pause`	Pause / Reprendre l'émulation
`→` (en pause)	Avancer d'une trame
`←` / `→` (en pause, rewind 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`	Cassette (CDT)
`.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.

Rewind / Rembobinage

La fonctionnalité rewind 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 rewind au démarrage avec --enable-rewind. Dans le frontend Qt, utilisez le menu Émulation → Rewind pour l'activer et ajuster les paramètres.

Touche / Action	Description
`←` (en pause)	Reculer d'une trame dans l'historique rewind
`→` (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 rewind
D-pad → (joystick, en pause)	Avancer dans le rewind / 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 1,6 Mo. Le buffer par défaut contient 100 snapshots (~160 Mo); ajustez avec --rewind-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 rewind (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

L'émulateur embarque un serveur de debug HTTP (actif par défaut, sur 127.0.0.1:6128) qui expose une interface web complète dans le navigateur : registres Z80, Gate Array, PSG, FDC, heat map mémoire, ASIC, disque, config, script, et plus.

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

Option	Description
`--web-server`	Activer le serveur (actif par défaut)
`--no-web-server`	Désactiver le serveur
`--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 : `6128`)
`--web-html <fichier>`	Chemin vers le fichier HTML de l'interface (défaut : `amspirit-lite.html` à côté du binaire)
`--lua-full-stdlib`	Laisser les scripts envoyés (POST) à l'API web utiliser la stdlib Lua complète (`io`, `os.execute`, `package`, `debug`). Désactivé par défaut — ces scripts sont sandboxés, avec un accès fichiers limité à la table `fs.*` jailée. N'importe quelle page ouverte dans votre navigateur peut atteindre l'API : n'activez ceci que sur une machine de confiance.

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.

L'interface est organisée en onglets : Keyboard, BASIC, Debug (Z80/désassemblage/breakpoints), ROMs (carte des ROM), Audio, Heat Map (mémoire), ASIC, Poke, Script, Config, Disk, et Settings.

Éditeur BASIC

L'onglet BASIC permet de 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 Keyboard 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).

Carte des ROM

L'onglet ROMs montre le catalogue des ROM en cours : quel firmware, quelle ROM d'extension (R<n>:) et quelle banque de cartouche est chargée dans chaque emplacement, et d'où elle vient. Il propose une vue compacte et une vue par emplacement.

Les emplacements de snapshots ne se gèrent pas depuis l'interface web — utilisez F4 / Shift+F4, ou le menu Qt Émulation → Snapshots.

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)
`--ram <Ko>`	RAM totale en Ko : 128 (défaut), 192, 320, 576
`-R <chemin>` / `--rom-path <chemin>`	Répertoire des ROMs
`-C <chemin>` / `--config <chemin>`	Répertoire de configuration
`-l <langue>` / `--lang <langue>`	Langue ROM (définit le `CPC_COUNTRY` du core) : FR (défaut), EN, SP, DA
`--lang-ui <langue>`	Langue de l'interface web : en (défaut), fr, es, de (auto-détectée depuis `$LANG`)
`-k <disposition>` / `--keyboard <disposition>`	Disposition de clavier hôte : fr (défaut), uk, us
`--keymap <fichier>`	Charger un fichier de mappage clavier personnalisé
`-F` / `--fullscreen`	Démarrer en plein écran
`-w` / `--windowed`	Mode fenêtré (prime sur `--fullscreen`)
`--zoom <N>`	Facteur de zoom initial de la fenêtre (1=768×542, 2=1536×1084, …); défaut 2, repli automatique à 1
`--size <LxH>`	Taille initiale de la fenêtre, ex. `1280x960`
`-Z` / `--turbo`	Démarrer en mode turbo (vitesse maximale)
`--monitor <préréglage>`	Préréglage moniteur CRT : off (défaut), ctm644, gt65, tv
`--reset`	Ignorer la config sauvegardée, démarrer avec les valeurs par défaut
`--no-splash` / `--splash`	Sauter / forcer l'écran de démarrage (`--splash` prime sur `--no-splash` de la config)

Chargement automatique et frappe automatique

Option	Description
`-A` / `--autorun[=FICHIER]`	Lancer automatiquement le disque de boot : devine le bon `RUN"<fichier>`/`\|CPM`, ou forcer un nom avec `--autorun=FICHIER`
`-T <nom>` / `--run <nom>`	Taper automatiquement `RUN"<nom>` au démarrage
`-t <texte>` / `--autotype <texte>`	Taper une chaîne littérale dans le CPC après le démarrage (`\n` = Entrée)
`--autotype-file <fichier>`	Taper le contenu d'un fichier texte dans le CPC 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)
`--audio-device <nom>`	Nom du périphérique audio de sortie (défaut : celui du système)
`--show-overlay`	Afficher l'indicateur FPS en haut à gauche (rouge = trop lent, bleu = trop rapide)

Scripting

Option	Description
`--script <fichier>`	Exécuter un script CSL ou Lua (stdlib complète — `--script` est un chargement local de confiance, contrairement aux scripts envoyés à l'API web)
`--ssm`	Activer le mode SSM : agir sur les opcodes Z80 `ED FE`/`FF`/`00`
`--ssm-both`	Avec `--ssm`, sauvegarder à la fois un snapshot et une capture d'écran sur `ED FE` ou `ED FF`
`--debug-script`	Journaliser chaque ligne CSL/Lua exécutée pendant que le script tourne

Rewind / Rembobinage

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

Serveur web de debug

Option	Description
`--web-server`	Activer le serveur HTTP de debug embarqué (actif par défaut)
`--no-web-server`	Désactiver le serveur
`--web-addr <adresse>`	Adresse d'écoute (défaut : `127.0.0.1`)
`--web-port <port>`	Port d'écoute (défaut : `6128`)
`--web-html <fichier>`	Chemin vers le fichier HTML de l'interface de debug
`--lua-full-stdlib`	Laisser les scripts envoyés à l'API web utiliser la stdlib Lua complète au lieu du sandbox (voir la section Serveur de debug web)

Fichiers binaires

Option	Description
`--bin-address <adresse>`	Adresse de chargement pour un fichier `.bin` brut/sans en-tête (ex. `4000`, `B04:2000` — une valeur seule vise les 64K de base) ; ignorée pour les fichiers avec en-tête AMSDOS et remplacée par la convention de nom `nom@adresse.bin`
`--bin-entry <adresse>`	Point d'entrée où sauter après le chargement d'un fichier `.bin` brut (adresse 16 bits plate) ; implique une exécution immédiate

Diagnostic et divers

Option	Description
`-v` / `--verbose`, `-q` / `--quiet`	Augmenter ou réduire la verbosité des logs
`-K` / `--debug-keys`	Activer la sortie de debug clavier verbeux
`-J` / `--debug-joystick`	Activer la sortie de debug joystick verbeux
`--debug-rewind`	Journaliser les sauvegardes/rappels rewind avec l'index d'emplacement et la taille d'historique
`--debug-webapi`	Journaliser les requêtes, réponses et événements SSE de l'API web
`--debug-audio`	Journaliser les statistiques audio (sous-alimentation/octets perdus) chaque seconde
`--dump-keymap[=FICHIER]`	Exporter le keymap actuel vers `FICHIER` (défaut : `keymap-sdl.cfg`) et quitter
`-X <N>` / `--autoExit <N>`	Quitter automatiquement après N trames de la boucle 50 Hz (les trames en pause comptent) — pour les tests automatisés
`--save-log <fichier>`	Sauvegarder toute la sortie des logs dans `<fichier>`
`--report[=chemin]`	Générer un rapport de diagnostic
`--update-url <url>`	Redéfinir l'URL du manifeste de mise à jour (tests)

Configuration du clavier (keymap.cfg)

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

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

(Sans nom de fichier, --dump-keymap écrit keymap-sdl.cfg dans le répertoire courant.)

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

Actions de raccourci supportées : PAUSE, MUTE, HELP, SCREENSHOT, SNAPSHOT_SAVE, SNAPSHOT_LOAD, VOLUME_UP, VOLUME_DOWN, TURBO, HARD_RESET, SOFT_RESET, FULLSCREEN, FULL_FRAME, CYCLE_SCREEN, CYCLE_DEBUG_SCREEN, TOGGLE_OVERLAY, CYCLE_CRTC, CYCLE_MONITOR, FRAME_STEP, DEBUG_STEP, DEBUG_STEP_OVER, DEBUG_RESUME, DEBUG_STEP_BACK, DEBUG_CLEAR_BREAKPOINTS, 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