<div align="center">

Klive IDE

A retro computer emulator and IDE for Z80 lovers — on Mac, Windows, and Linux

</div>

---

Klive IDE is a cross-platform emulator and full-featured Integrated Development Environment for
Sinclair Z80-based retro computers. It is built by retro-computing enthusiasts, for retro-computing enthusiasts.
Write Z80 Assembly, ZX BASIC (Boriel's Basic), or SJASMPLUS; hit one button, and watch your code run—or step through it—right inside
the emulated machine. No setup ceremony. Just you and the pixels.

---

Table of Contents

• Screenshots
• Supported Machines
• Emulator Features
• Screen Recording
• IDE Features
• Programming Languages
• Scripting
• Getting Started
• Technology
• Community & Contributing

---

---

💻 Supported Machines

Klive targets retro computers built around the Z80 CPU family. Each machine is emulated cycle-accurately with its authentic ROM and hardware behaviour.

| Machine | Status | Notes | | ------------------------- | --------------- | ---------------------------------------------------- | | ZX Spectrum 48K | ✅ Active | PAL, NTSC, and 16K models | | ZX Spectrum 128K | ✅ Active | Full 128K memory paging | | ZX Spectrum +2E / +3E | ✅ Active | Single and dual floppy drive models | | Cambridge Z88 | ✅ Active | Multiple OZ OS versions (3.x – 5.0), various locales | | ZX Spectrum Next | 🔄 In progress | KS2 model; extended Z80 instruction set | | Commodore 64 | 🧪 Experimental | Early stage; 6510 CPU | | ZX 80 / ZX 81 | 🗓️ Planned | — |

---

🕹️ Emulator Features

Machine Control

Run, pause, continue, restart, and stop the emulated machine at any time—without restarting the application. Toggle between normal and debug run modes on the fly.

| Keyboard Shortcut | Action | | ----------------- | -------------------- | | F5 | Start machine | | Shift+F5 | Pause machine | | F4 | Stop machine | | Shift+F4 | Restart machine | | Ctrl+F5 | Start with debugging | | F10 | Step Into | | F11 | Step Over | | Shift+F11 | Step Out |

• CPU clock multiplier — run at 1× to 24× native speed for rapid testing
• Sound control — enable, mute, or adjust the audio level at any time

Debugging Views

| View | What it shows | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | CPU View | All Z80 registers (AF, BC, DE, HL, SP, IX, IY, I, R), interrupt mode, halt state, internal WZ/MEMPTR register, T-state counter, last memory read/write and I/O addresses | | ULA View | Full ULA state | | Memory View | Live hex+ASCII memory explorer with bank selection; edit RAM contents while the machine is paused or running | | Disassembly View | Live disassembly scrolling with the PC; navigate banked memory pages | | Breakpoints Panel | All active breakpoints with type, address, resolved/unresolved status, and enable/disable toggle | | Watch Panel | Monitor named variables with configurable data types (8-bit, 16-bit, 32-bit, flags, strings, arrays) | | BASIC Listing Viewer | Displays the BASIC program currently in the emulator's memory; toggleable non-printable characters, ZX Spectrum font, and corruption detection | | System Variables | Inspect live system variable values |

Loading Programs

• Tape files (.tap, .tzx) with full format parsing
• Fast load — ROM-hook technique; loads tape files in a fraction of a second instead of the real tape time
• Disk files (.dsk) on ZX Spectrum +3E with single or dual drive models
• Manual tape rewind and control

Virtual Keyboard

• ZX Spectrum 48K, ZX Spectrum 128K, Cambridge Z88, and ZX Spectrum Next keyboard overlays
• Fully clickable with a mouse; multi-key and Symbol Shift combinations supported
• Resizable to suit your screen layout

---

🎬 Screen Recording

Capture the emulator screen (plus stereo audio) directly to video files. Perfect for sharing gameplay, creating tutorials, or archiving your retro work.

• One-click armed recording — arm the recorder, start the machine, recording begins instantly
• Flexible output — choose MP4, WebM, or MKV; adjust quality and frame rate to balance file size
• Automatic sync — audio and video stay perfectly synchronized even during pause/resume
• Seamless integration — recordings are saved automatically; files are ready to share

FFmpeg is bundled with Klive — no separate install needed.

Full guide: Recording the Emulator Screen

---

🛠️ IDE Features

One-Click Compile, Inject, and Debug

Klive's signature feature: a single toolbar button takes your source code from the editor to running (or debugging) inside the emulated machine.

| Button | What it does | | ----------- | ------------------------------------------------------- | | Compile | Checks code syntax and reports errors | | Inject | Compiles and injects machine code into a paused machine | | Run | Compiles, injects, and starts the code immediately | | Debug | Compiles, injects, and starts with breakpoints active |

The automated pipeline restarts the machine, injects the compiled bytes at the correct address, sets the program counter, and begins execution—all in one click.

Monaco-Based Code Editor

Klive's editor is powered by the same Monaco engine that runs VS Code, giving you:

• Full VS Code keyboard shortcuts — multi-cursor editing, find/replace with regex, go-to-symbol, and more
• Code folding for assembly blocks (.macro/.endm, .if/.endif, etc.)
• Minimap with error and warning markers
• Auto-indentation and bracket/quote auto-closing

Semantic Syntax Highlighting

Unlike most assembler editors, Klive's syntax highlighting is driven by the compiler itself—not just regex patterns. Every token is coloured according to what it actually means:

• Labels, macros, struct names, .equ constants, variables, and macro parameters each get distinct colours
• Inline error diagnostics with red underlines and hover tooltips
• Macro expansion preview on hover—see the expanded code before it assembles

Additional Editor Intelligence

• Address & byte-count tooltips — hover over any instruction to see its assembled address and the resulting machine code bytes
• Inlay hints showing hex/decimal equivalents of numeric literals side-by-side in the source
• Color decorators for attr(), ink(), paper() functions with an integrated colour picker
• Block-pair highlighting for matching keywords
• Rename symbol (F2) with cross-file refactoring
• Go to included file navigation

Project Management

A Klive project is a folder containing a klive.project config file plus your source files. The Project Explorer gives you a tree view with:

• Build root designation — mark the main file for compilation
• Per-extension file associations — each file type opens in the right viewer automatically:
  • .kz80.asm → Klive Z80 Assembly editor
  • .zxbas → ZX BASIC (Boriel's Basic) editor
  • .sjasm → SJASMPLUS Assembly editor
  • .6510.asm → 6510 Assembly editor
  • .ksx → Klive Script editor
  • .tap / .tzx → Tape viewer
  • .dsk → Disk viewer
  • .nex → NEX file viewer
  • .bin / .rom → Binary hex dump viewer
  • .png, .jpg, .gif, .svg, … → Image viewer

Code Export

Compile your project and export it for use outside Klive or for distribution:

• Export to .tap, .tzx, or Intel HEX format
• Automatic BASIC loader generation (with optional CLEAR and PAUSE 0 statements)
• Customisable border colour during loading screen
• Optional loading screen (.scr) file inclusion