# AMSpiriT-Lite

**An accuracy-focused Amstrad CPC emulator for Linux**

AMSpiriT is a high-fidelity emulator of the Amstrad CPC series (464, 664, 6128, 6128+, 464+, and GX4000), ported from the original Windows application to Linux with different flavours

## Features

### Emulation
- **Accurate Z80 CPU** emulation with cycle-perfect timing
- **Multiple CPC models** with hardware-specific support (6128+, GX4000, etc.)
- **Authentic sound** via AY-3-8912 PSG with stereo output
- **Multiple CRTC variants** for hardware-accurate video output

### Media Support
- **Disk images**: DSK, HFE, IPF formats
- **Tape emulation**: CDT and WAV cassette images
- **Snapshots**: Save and restore full emulator state
- **Cartridges**: CPC Plus/GX4000 CPR format

### User Interface
- **SDL2 frontend**: Lightweight, minimal, portable UI for desktop
- **Qt frontend**: Full-featured desktop application with menus and dialogs
- **Web interface**: Real-time emulator state inspection via browser
  - Z80 register viewer
  - Gate Array and sound chip monitoring
  - RAM hex dump and memory write tools
  - Virtual keyboard for input
  - Configuration panel for model/CRTC switching

### Developer Tools
- **Autotype feature**: Automatically type text into the emulated machine
- **BASIC injector**: Tokenize and inject a Locomotive BASIC program directly into RAM at startup or via the interface
- **Turbo mode**: Full-speed emulation without 50 Hz pacing
- **Screenshots**: Save CPC screen output as PNG
- **Web API**: REST endpoints for remote control and state inspection

## Getting Started

Download the latest release from the [website](www.amspirit.fr). Pre-built binaries for Linux are available for both SDL2 and Qt frontends.

**System ROMs are included** in the release package—no additional setup required to start emulating.

**Run:**
```bash
./amspirit-lite-sdl              # SDL2 frontend
./amspirit-lite-qt               # Qt frontend (if installed)
```

## Usage

### Basic Operation
1. **Load ROM**: The emulator requires standard Amstrad CPC ROMs (OS + BASIC)
   - Place ROM files in a directory and point the emulator to it
   - Common locations: `./roms/`, `~/.amspirit/roms/`

2. **Load Media**: Drag and drop disk/tape images, or use the File menu
   - Supported formats: `.dsk`, `.cdt`, `.wav`, `.sna`

3. **Control**: Use keyboard to type, or the virtual keyboard in the web interface. Joysticks are automatically detected.

### Web Interface
Enable with `--web-server` flag (SDL2) or via View menu (Qt), then:
1. Browser opens automatically to `http://127.0.0.1:8765`
2. Use the virtual keyboard or text input to type into the CPC
3. Monitor CPU/audio state in real-time
4. Write code to memory and execute it directly
5. **BASIC Injector panel**: paste Locomotive BASIC source, click *Inject* — the program is tokenized server-side and written into RAM immediately (type `RUN` or `LIST` in the emulator)

### BASIC Injection

AMSpiriT can tokenize standard Locomotive BASIC text and write it directly into the emulated machine's RAM, bypassing the cassette/disk loading process entirely.

**Source format**: one statement per line, line numbers mandatory:
```
10 MODE 1
20 PRINT "HELLO FROM AMSPIRIT"
30 GOTO 20
```

The full Locomotive BASIC keyword set is supported (all 6128 commands, functions, and operators).

**Via the command line** (`--basic`): the program is loaded from a `.bas` text file and injected ~3 seconds after boot, once BASIC has finished initialising. Then type `RUN` in the emulator.

**Via the web interface** (`/api/basic` or the BASIC Injector panel): the program is injected on the next emulated frame. The title bar confirms success or reports an error if the program is too large. Then type `RUN` or `LIST`.

**Technical details**:
- Program is written starting at address `0x0170` (standard Locomotive BASIC start)
- BASIC end-of-program pointers at `0xAE66` are updated automatically
- `AUTO`, `ERR`, and `PROTECT` flags are cleared
- Maximum size: from `0x0170` up to `0xAE66` (~44 KB)

### Command-Line Options (SDL2)
- `-m 6128` — Select CPC model (464, 664, 6128, 6128+, 464+, GX4000)
- `--autotype "LOAD\n"` — Auto-type text on startup
- `-t file.txt` — Auto-type contents of file
- `--basic file.bas` — Tokenize and inject a BASIC program into RAM at startup (~3 s after boot)
- `--web-server --web-port 9000` — Start web server on custom port
- `FILE` — Load disk/tape/snapshot on startup

## Architecture

- **amspirit-core**: Emulation engine (static library)
  - Z80 processor
  - Gate Array, FDC, PSG, CRTC
  - Disk/tape/cartridge controllers

- **amspirit-helpers**: Cross-platform utilities (static library)
  - ROM and media file loading
  - Keyboard mapping
  - Web server 
  - Audio resampling

- **amspirit-SDL2**: Minimal SDL2 frontend (binary)
- **amspirit-QT**: Full-featured Qt frontend (binary)
- **amspirit-retroarch**: Libretro core for RetroArch (shared library)

## Credits

**Development Team:**
- **Dmanu78** — Amspirit Core developer
- **Longshot** — Accuracy advisor
- **Siko** — Amspirit Lite developer
- **Gurneyh** — Mac Port & VScode Plugins
- **Tronic** — Basic Tokenizer

**Graphics:**
- **CeD** — Graphic artist
- **Made** — Graphic artist

**Quality Assurance:**
- **Fred/Fugitif** — Beta tester
- **LordHeavy** — Beta tester
- **Ricolaoz** — Beta tester
- **Ldir Hector** — Beta tester


## Contributing

Bug reports, feature requests, and contributions are welcome. The project is actively developed; visit the website [[www.amspirit.fr](https://www.amspirit.fr) for the latest information.

## Changelog

See [CHANGELOG](../doc/Changelog) for version history and release notes.

## Finding Games and Demos

**System ROMs** are already included in the release—you can start emulating immediately.

**Game disks and demos** can be found on:
- **[Pouët.net](https://www.pouet.net/)** — Largest scene demo archive
- **[CPCRulze.fr](https://cpcrulze.fr/)** — French CPC community resources
- **[CPC Power](https://www.cpc-power.com/)** — Comprehensive game and software database

## Community

Join the AMSpiriT community on **Discord** — link available on [www.amspirit.fr](https://www.amspirit.fr)

## Frequently Asked Questions

**Q: Can I inject a BASIC program without a disk image?**  
A: Yes. Use `--basic myfile.bas` on the command line to have the program injected ~3 seconds after boot, or use the BASIC Injector panel in the web interface at any time while the emulator is running. Then type `RUN` in the emulator.

**Q: Do I need to provide ROM files?**  
A: No. System ROMs are included in the release package—AMSpiriT is ready to use out of the box. Of course, you can use your own ROMs by utilizing the .cro format.

**Q: Can I use this to play games?**  
A: Yes! AMSpiriT can run most Amstrad CPC software including commercial games. Game disks and demos are freely available from the community resources listed above.

**Q: How accurate is the emulation?**  
A: Very accurate. The core emulation targets cycle-perfect Z80 timing and includes hardware-specific quirks for authentic behavior. However, some obscure edge cases may still differ from real hardware.

**Q: What games are known to work well?**  
A: Most commercial titles—if not all—as well as homebrew games work correctly. The emulator aims for broad compatibility with the entire CPC library. Although Amspirit has been intensively tested (including the infamous Shaker acid test), some games, demos, or Amstrad CPC programs might still encounter issues. In such cases, please let us know!

---

**For more information, visit [www.amspirit.fr](https://www.amspirit.fr) **
