Skip to content

rustzx/rustzx

Repository files navigation

RustZX

RustZX CI Crates.io License Discord

logo

ZX Spectrum emulator written in Rust.

  • Watch this video showcase (v0.9.x)
  • Read CHANGELOG.md for info on the latest version changes

Features

  • Written in pure rust
  • Cross-platform
  • Full ZX Spectrum 48K and 128K emulation
  • Highly accurate emulation of Z80 core
  • Highly precise AY chip emulation
  • Beeper sound emulation
  • Supported formats:
    • tap - tape
    • sna - snapshot, both 48K and 128K versions supported
    • szx - snapshot, both 48k and 128k versions supported along with zlib compression.
    • scr - screenshot
  • Fast loading of tap files with standard loader
  • Very accurate timings
  • Full border emulation
  • Joystick emulation: Kempston, Sinclair
  • Kempston mouse emulation
  • Extended 128K keys emulation (arrows, backspace, caps lock)
  • Quick save/load
  • Compressed assets support (only .gz for now)
  • Separate no_std core library which can be used to port emulator almost anywhere.
    • Global allocator is still needed, but all dynamic allocations are minimized
    • All resource-heavy features are configurable via cargo features
  • Obscure Z80 features emulation:
    • WZ/memptr register (F3/F5 flags obscure behavior in BIT n, (HL))
    • Q register (F3/F5 flags obscure behavior in SCF and CCF)
    • Block instruction flags oddities (LDxR/CPxR/INxR/OTxR)

Install

  1. Ensure that you have C compiler and CMake to build bundled sdl2
  2. Linux only: Install required development packages: [libasound2-dev]
  3. Install it with cargo
cargo install rustzx

How to use

rustzx --help # Show help
rustzx test.tap # Autodetect file type and run in 48K mode
rustzx --ay test.tap # Run in 48K mode with AY sound chip
rustzx -m128 --tape test128.tap # Run in 128K mode with tape
rustzx --rom tester.rom -s3 # Run with custom rom and 3x screen scaling
rustzx --nofastload test.tap # Run without fast tape loading
rustzx --mouse test.tap # Run with Kempston mouse support

For loading tape in 48K mode, press j then Ctrl+p twice, as on a real Spectrum. You should see LOAD "" on emulator's screen, then press Enter (in 128K mode just press enter). In --nofastload mode, press Insert to play the tape and Delete to stop.

If you have choppy audio, try --sound-latency option with bigger values.

Default key bindings:

Shortcut Key Function
F1 Quick save
F2 Quick load
F3 Set normal emulation speed
F4 Set 2x emulation speed
F5 Max possible emulation speed
F6 Enable frame trace info
F9 Enable Kempston/Sinclair joy keyboard layer
Insert Start tape
Delete Stop tape
End Break command
Caps Lock Caps lock command
Backspace Delete
<Arrows> 128K arrow keys
Esc Unlock mouse (if --mouse is used)

In joy keyboard layer mode (F9)

Shortcut Key Function
<Arrows> Kempston joy arrows
Alt Kempston fire
WASD Sinclair Joy 1 arrows
Caps Lock Sinclair Joy 1 fire
IJKL Sinclair Joy 2 arrows
Enter Sinclair Joy 2 fire

Screenshots

References

Many resources were used to find out how to build this emulator. Huge thanks to the following resources that helped figure out a lot of details about ZX Spectrum.

ROMs

Emulator contains ROMs, created by by Sinclair Research Ltd (now owned by Amstrad plc).

Amstrad has given permission to distribute their ROM's in conjunction with emulators.

In RustZX these ROMs are included in the source of the core emulator library mod rustzx_core::zx::roms. Embedded roms can be opted-out from the core library by disabling feature embedded-roms.