🇬🇧 🇫🇷 🇪🇸 🇩🇪

# AMSpiriT Lite — Referencia rápida

AMSpiriT Lite es un emulador Amstrad CPC para Linux/Windows basado en el núcleo AMSpiriT de David MANUEL.

## Teclas de control

Tecla | Acción
--- | ---
`F1` | Abrir esta ayuda en el navegador
`F2` | Guardar una captura de pantalla PNG en el directorio actual
`F4` | Guardado rápido en la ranura actual
`Shift`+`F4` | Carga rápida desde la ranura actual
`F6` | Depurador: retroceder un paso (rebobinado timelapse, en pausa y si está disponible)
`F7` | Depurador: pausar si está en ejecución; avanzar un paso (instrucción BASIC o Z80) si está en pausa
`F8` | Depurador: paso por encima (`CALL`/`CALL cc` Z80 o `GOSUB` BASIC; si no, un paso simple)
`F9` | Depurador: reanudar (solo en pausa)
`Shift`+`F9` | Activar/desactivar modo turbo (velocidad máxima, audio silenciado)
`F10` | Reinicio total (arranque en frío)
`Shift`+`F10` | Reinicio suave (arranque en caliente)
`F11` (solo SDL) | Seleccionar modo de monitor (color CTM644, verde GT65, TV, variantes ASIC)
`Shift`+`F11` | Cambiar tipo de pantalla (color, monitor verde, variantes ASIC)
`Ctrl`+`F11` (solo SDL) | Mostrar/ocultar indicador de FPS
`Ctrl`+`Shift`+`F11` (solo SDL) | Cambiar modos de visualización CRTC (depuración)
`F12` | Alternar pantalla completa / modo ventana
`Shift`+`F12` | Alternar vista: pantalla CPC visible ↔ trama CRTC completa
`Pausa` | Pausar / Reanudar emulación
`→` (en pausa) | Avanzar un fotograma
`←` / `→` (en pausa, timelapse activo) | Navegar en el historial de rebobinado fotograma a fotograma
`Alt`+`F4` | Cerrar la ventana (gestionado por el gestor de ventanas)
`Ctrl`+`1` a `Ctrl`+`0` | Teclado numérico CPC 1–0 (para portátiles sin teclado numérico)
Rueda del ratón (arriba/abajo) | Ajustar volumen (±10% por paso)
Clic botón central del ratón | Activar/desactivar silencio

Nota: las teclas `F6`-`F9` reproducen el depurador paso a paso de la página web (`--web-server`). El modo BASIC o Z80 se detecta automáticamente según si hay un programa BASIC en ejecución — no hay pestaña que seleccionar, a diferencia de la página web.

## Carga de archivos

Arrastre y suelte un archivo sobre la ventana del emulador para cargarlo. El frontend Qt también tiene un menú Archivo para abrir un diálogo de selección de archivos.

Consejo: mantenga `Ctrl` mientras arrastra un archivo para realizar un reinicio total antes de cargarlo — útil para iniciar una imagen de disco en un estado limpio.

Formato | Descripción
--- | ---
`.dsk` | Imagen de disco estándar
`.hfe` / `.ipf` | Imagen de disco de alta fidelidad (CAPS)
`.cdt` / `.wav` | Cinta (CDT o audio WAV)
`.sna` | Snapshot (estado guardado)
`.cpr` | Cartucho CPC Plus / GX4000 — cambia automáticamente al modelo CPC 6128+ y tipo CRTC 3

## Ranuras de snapshot

AMSpiriT Lite mantiene 4 ranuras de guardado rápido (1–4) por juego. Las ranuras se almacenan junto a la imagen ROM/disco y persisten entre sesiones.

Acción | Tecla / Botón
--- | ---
Guardado rápido en la ranura actual | `F4`
Carga rápida desde la ranura actual | `Shift`+`F4`
Cambiar a la siguiente ranura (en pausa) | Gamepad Start / botón +
Cambiar a la ranura anterior (en pausa) | Gamepad Select / botón −
Guardar en ranura (en ejecución) | Gamepad Start / botón +
Cargar desde ranura (en ejecución) | Gamepad Select / botón −

En el frontend Qt, las ranuras de snapshots también son accesibles desde el menú Emulación → Snapshots y la interfaz de depuración web.

## Timelapse / Rebobinado

La función timelapse opcional registra un búfer circular de snapshots de estado del CPC en RAM mientras se ejecuta el emulador. En pausa, puede navegar hacia adelante y hacia atrás en el historial registrado — útil para depuración, encontrar el momento perfecto para capturar pantalla, o rebobinar un movimiento equivocado en un juego.

Active timelapse al inicio con `--enable-timelapse`. En el frontend Qt, use el menú Emulación → Timelapse para activarlo y ajustar configuración.

Tecla / Acción | Descripción
--- | ---
`←` (en pausa) | Retroceder un fotograma en el historial timelapse
`→` (en pausa) | Avanzar un fotograma (hacia el presente), o avanzar un fotograma normal si está al día
D-pad ← (gamepad, en pausa) | Retroceder en timelapse
D-pad → (gamepad, en pausa) | Avanzar en timelapse / reanudar si está al día

La barra de estado / título muestra `< N / M` mientras se rebobina (N fotogramas desde el más antiguo, M total almacenados).

Memoria: cada snapshot ocupa aproximadamente 130 KB (CPC 6128). El búfer predeterminado contiene 100 fotogramas (~13 MB); ajuste con `--timelapse-slots N`.

## Modo turbo

El modo turbo desactiva la cadencia de 50 Hz y silencia el audio, permitiendo que el emulador se ejecute a velocidad máxima de la CPU. Útil para omitir cargas largas de cinta o intros.

- Pulse `Shift`+`F9` para activar o desactivar el modo turbo en cualquier momento.
- Al lanzar con `--turbo` junto con `--autotype` o `-A`, el turbo se detiene automáticamente cuando finaliza la secuencia de escritura automática.

## Gamepad / Joystick

El frontend Qt usa la API SDL2 GameController (XInput en Windows, evdev en Linux, GameController en macOS). El frontend SDL usa la API joystick legacy. Ambos detectan controles al inicio y cuando se conectan; el primer controlador encontrado se asigna al puerto joystick 1 del CPC.

Botón | Acción (en ejecución) | Acción (en pausa)
--- | --- | ---
A | Disparo 1 | —
B | Disparo 2 | —
X | Disparo 3 | —
Y / Guía | Pausar | Reanudar
Start / + | Guardado rápido en la ranura actual | Cambiar a la siguiente ranura
Select / − | Carga rápida desde la ranura actual | Cambiar a la ranura anterior
Stick izquierdo / D-pad | Direcciones (Arriba/Abajo/Izquierda/Derecha) | Navegar timelapse (si está activo)

Frontend SDL: usa números de botón de joystick brutos (Botón 0–3 = Disparo 1/2/3/Pausa, Botón 7/9 = Start, Botón 6/8 = Select). El eje analógico CPC Plus se soporta en ambos frontends.

## Servidor web de depuración

Al lanzar con `--web-ui` (o `--web-server`), el emulador inicia un servidor HTTP local que expone una interfaz web en el navegador: registros Z80, Gate Array, PSG, FDC, FPS y controles (pausa, reinicio, cambio de modelo).

    amspirit-lite-sdl --web-ui [--web-addr 0.0.0.0] [--web-port 8765] [--web-html ruta/a/ui.html]

Opción | Descripción
--- | ---
`--web-ui` | Activar el servidor (desactivado por defecto)
`--web-addr <dirección>` | Dirección de escucha (por defecto: `127.0.0.1` — solo local; use `0.0.0.0` para todas las interfaces)
`--web-port <puerto>` | Puerto de escucha (por defecto: `8765`)
`--web-html <archivo>` | Ruta al archivo HTML de la interfaz (por defecto: `amspirit-lite.html` junto al binario)

El archivo `amspirit-lite.html` puede editarse sin recompilar. Si falta, se usa la interfaz integrada en el binario como alternativa.

### Editor BASIC

La interfaz web incluye una pestaña BASIC para trabajar con programas Locomotive BASIC:

- Pegue o importe código fuente Locomotive BASIC
- Inyectar: tokeniza y escribe el programa directamente en RAM del CPC en la dirección 0x0170
- Exportar: lee y detokeniza el programa BASIC actual desde RAM
- Parámetros: `?reset=1` (reinicio total primero), `?run=1` (auto-escribe RUN después de inyectar)
- Tamaño máximo: ~44 KB por modelo CPC

### Mapeo de teclado

La pestaña Teclado muestra la distribución de teclado actual y todas las teclas asignadas (referencia de solo lectura para depuración de problemas de entrada de teclado).

### Ranuras de snapshots

La pestaña Snapshots administra las 4 ranuras persistentes:

- Guardado rápido: `F4`
- Carga rápida: `Shift`+`F4`
- Cada ranura muestra estado (guardado/vacío), tamaño del archivo e marca de tiempo

## Opciones de línea de comandos

    amspirit-lite-sdl [OPCIONES] [ARCHIVO]

### Emulación

Opción | Descripción
--- | ---
`-m <modelo>` | Modelo CPC: `464`, `664`, `6128` (por defecto), `6128+`, `464+`, `GX4000`
`-c <tipo>` | Tipo CRTC (0 a 4)
`-R <ruta>` | Directorio de ROMs (por defecto: `./ROMs`)
`-C <ruta>` | Directorio de configuración (por defecto: `./config`)
`-k <distribución>` / `--keyboard <distribución>` | Seleccionar distribución de teclado: FR, EN, US, ES, DA, DE, IT, PT, BE, SW, CA (por defecto: FR)
`-F` | Iniciar en pantalla completa
`-Z` / `--turbo` | Iniciar en modo turbo (velocidad máxima)

### Carga automática

Opción | Descripción
--- | ---
`-A` / `--autorun` | Escribe automáticamente `RUN"` tras el arranque para lanzar el primer programa
`-T <nombre>` / `--run <nombre>` | Escribe automáticamente `RUN"<nombre>` al inicio
`-t <archivo>` / `--autotype <archivo>` | Escribe el contenido de un archivo de texto en el CPC tras el arranque
`--basic <archivo>` / `-b <archivo>` | Tokenizar e inyectar un programa Locomotive BASIC en RAM (~3s después del arranque)

### Audio y pantalla

Opción | Descripción
--- | ---
`-L <ms>` / `--audio-latency <ms>` | Latencia del búfer de audio en milisegundos (por defecto: 80 — aumentar si hay crepitaciones)
`--show-overlay` | Mostrar el indicador FPS en la esquina superior izquierda (rojo = demasiado lento, azul = demasiado rápido)

### Timelapse / Rebobinado

Opción | Descripción
--- | ---
`--enable-timelapse` | Activar búfer de rebobinado en RAM (registra un snapshot cada N fotogramas)
`--timelapse-interval <N>` | Fotogramas entre snapshots timelapse (por defecto: 10)
`--timelapse-slots <N>` | Número máximo de snapshots a mantener en el búfer (por defecto: 100, ~13 MB)

### Servidor web de depuración

Opción | Descripción
--- | ---
`--web-ui` / `--web-server` | Activar el servidor HTTP de depuración (desactivado por defecto)
`--web-addr <dirección>` | Dirección de escucha (por defecto: `127.0.0.1`)
`--web-port <puerto>` | Puerto de escucha (por defecto: `8765`)
`--web-html <archivo>` | Ruta al archivo HTML de la interfaz de depuración

### Varios

Opción | Descripción
--- | ---
`-K` | Activar salida de depuración detallada del teclado a stderr
`--dump-keymap` | Generar un archivo `keymap.cfg` de referencia basado en la distribución actual y mostrar en stdout
`-X <segundos>` | Salir automáticamente después de N segundos (pruebas automatizadas)

## Configuración del teclado (keymap.cfg)

Genere un archivo `keymap.cfg` usando la opción `--dump-keymap`, luego edítelo a su conveniencia y reinicie el emulador:

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

Coloque el archivo `keymap.cfg` generado en su carpeta `ROMs/` o `config/`. El archivo utiliza formato INI con dos secciones: `[keyboard layout]` y `[emulator hotkeys]`.

Acciones de atajo admitidas: 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

Formato de teclas: Tecla única (F1, A, Escape, Return, Space) o modificadores (Ctrl+X, Shift+F1, Alt+Shift+P). Sin distinción de mayúsculas.

Los cambios toman efecto al reiniciar. Para encontrar el código de una tecla, ejecute con la opción `-K` y busque mensajes `DOWN` en la consola. Nota: Las aplicaciones SDL y Qt utilizan códigos de tecla diferentes; use archivos keymap separados para cada una si ejecuta ambas.

Núcleo AMSpiriT por David MANUEL — puerto Linux por Siko — amspirit.fr