konCePCja — Amstrad CPC Emulator

© 2026 Cezar "ikari" Pokorski

https://github.com/ikari-pl/konCePCja

What is it?

konCePCja is a software emulator of the Amstrad CPC 8-bit home computer series for Linux, macOS and Windows. It faithfully imitates the CPC464, CPC664 and CPC6128, plus the CPC464+, CPC6128+ and GX4000 Plus Range machines.

At its heart is a sub-cycle, pin-level hardware simulation: the Z80, Gate Array, CRTC, PSG, PPI, FDC, ASIC and the expansion peripherals are modelled as components on a bus, clocked below the microsecond, from documented silicon behaviour (the specifications live in docs/hardware/). Programs and games run unmodified, at real-time or well above it.

konCePCja is also designed as an IPC-controllable debugging tool — every feature is accessible over a TCP text protocol, making it scriptable by automation pipelines, CI systems and LLM agents. The 18-window Dear ImGui DevTools UI is built on top of the same API.

The engine

• Pin-level component simulation — devices exchange signals on a simulated bus; debugger surfaces (DevTools, IPC readback, snapshots) read device truth, not emulator approximations
• Run tiers — one machine, selectable fidelity/speed trade-offs: Auto (the default: full speed, switching itself to per-cycle observability whenever a breakpoint or watchpoint is armed), Fast, Wake, Soldered and Faithful (always-on pin-level observability). Cycle with Shift+F9, the Machine menu, or tier over IPC
• Deterministic core — byte-exact repeatable runs, exercised by a record/replay test harness
• Flux-level disk support — clean-room decoders for IPF (SPS), SCP, HFE, KryoFlux STREAM and A2R images; copy-protected originals run from real flux, complete with weak bits
• 1,545 tests across 189 suites

Debugger

• Breakpoints with conditional expressions (if A > #10 and peek(HL) = #C9) and pass counts
• Watchpoints — memory access breakpoints on read, write or both, with address ranges
• IO breakpoints — break on Z80 IN/OUT with port masks and conditions
• Step over / step out / step to — function-level stepping, not just single instructions
• Expression parser — WinAPE-compatible syntax with registers, peek(), ay(), crtc(), bitwise operators
• Debug timers — measure T-state durations between code points via expression side-effects
• Z80 Assembler — integrated assembler with labels, expressions, &/$/% number formats, two-pass assembly, error reporting and IPC access
• Symbol table — load/save .sym files, bidirectional lookup, symbols in disassembly output
• Memory search — find hex patterns (?? wildcards), ASCII text, or Z80 mnemonics (ld (*),hl)
• Call stack — heuristic stack walk with CALL/RST detection and symbol labels
• Data areas — mark address ranges as bytes/words/text for correct disassembly output
• Disassembly export — export address ranges to source files with optional symbol labels
• Instruction trace — ring-buffer Z80 execution trace with dump to file
• Memory bank viewer — read through Z80 banking, write path, or raw physical banks
• Disassembly niceties — PC pinned at a fixed position, ROM region colour-coding, bank boundary markers

IPC automation

• IPC protocol — TCP server on port 6543 for remote control by scripts and LLM agents (80+ commands — see docs/ipc-protocol.md)
• Telnet console — persistent TCP text terminal on port 6544, mirrors CPC output and accepts keyboard input (nc localhost 6544)
• Headless mode (--headless) — run without a window for CI and automation
• Input replay — type text, press keys, drive joysticks and the mouse over IPC
• Auto-Type — autotype command with ~KEY~ syntax for scripted keyboard input
• Frame stepping — advance exact frame counts for deterministic testing
• Exit control — --exit-after, --exit-on-break and quit for scripted runs
• Hash commands — CRC32 of VRAM, memory ranges and registers for CI assertions
• Event system — fire IPC commands on PC match, memory write or VBL interval

For example, type and run a BASIC program over the IPC socket:

echo 'input type "10 print \"hello\""' | nc -w 2 localhost 6543
echo 'input key RETURN'                | nc -w 2 localhost 6543
echo 'autotype "run~RETURN~"'          | nc -w 2 localhost 6543   # ~KEY~ via autotype
echo 'input mouse move 10 -4'          | nc -w 2 localhost 6543   # needs a mouse device

Disc & media tools

• Flux images — read IPF (SPS), SCP, HFE, KryoFlux STREAM and A2R; export discs back to SCP/HFE; flux-backed discs are writable (clean tracks keep their protection-grade flux, written tracks re-synthesize)
• Disc file editor — disk ls/get/put/rm for AMSDOS files on DSK images
• Sector editor — read/write individual sectors by track/side/sector ID
• Disc formatting — create blank discs in standard CPC, IBM and custom formats, sector- or flux-backed
• WAV recording — capture audio output to WAV files
• YM recording — capture PSG register writes to YM chiptune files
• AVI recording — capture video+audio to AVI files
• Frame dumps — save sequential PNG screenshots or animated GIFs

Hardware & Plus Range

• Full Plus Range — CPC464+/CPC6128+/GX4000 with ASIC hardware sprites, enhanced palette, DMA sound channels and vectored interrupts
• CRTC type selection — types 0, 1, 2 and 3 with per-type register behaviour
• 4MB RAM expansion (Yarek-compatible) — configurable up to 4096 KB
• Silicon Disc — 256 KB battery-backed RAM disc in banks 4-7
• 32 ROM slots — load/unload/query ROM images
• ASIC register viewer — sprites, DMA channels, palette, interrupts
• Video / Audio state — live CRTC, Gate Array and PSG register viewers with audio oscilloscope

Peripheral expansions

• M4 Board — virtual filesystem with host directory backing, 52 firmware commands, RSX commands, DSK container support, LED status and embedded HTTP server (web file browser, ROM management, CPC control, live video preview — compatible with cpcxfer and the M4 Board Android app)
• Symbiface II — IDE hard disc (ATA PIO with raw .img files), DS12887 RTC with NVRAM, PS/2 mouse
• Digiblaster — printer port 8-bit DAC mixed into audio output
• AmDrum (Cheetah) — 8-bit DAC on port &FFxx
• Dobbertin SmartWatch — Dallas DS1216 phantom RTC returning host system time
• AMX Mouse — joystick port mouse on keyboard matrix
• Amstrad Magnum Phaser — light gun via CRTC register intercept
• Multiface II — stop-button debugging interface
• Drive/tape sounds — procedurally generated FDC motor hum, head seek clicks and tape loading hiss

UI & session

• Dear ImGui interface with a dockable workspace — Classic (floating windows) or Docked mode with Debug, IDE and Hardware layout presets, plus custom save/load
• DevTools toolbar — toggleable second topbar (F12) with dropdown menus and step/pause controls
• Bottom status bar — drive LEDs, tape controls and filenames
• Session recording — record and replay full emulator input/state sessions
• Graphics finder — decode CPC Mode 0/1/2 pixel data at any address with zoom and paint
• Pokes system — load, apply and manage game cheats in .pok format
• Configuration profiles — save and switch between named config presets
• Virtual keyboard — fully playable with a joystick alone
• Joystick emulation — joystick-only games playable from the keyboard
• English, French or Spanish keyboard layouts
• Software scanlines, CRT shader styles, auto frameskip, high-resolution speed limiter, SDL_Renderer fallback for systems without OpenGL

File formats

DSK and flux images (IPF, SCP, HFE, KryoFlux STREAM, A2R) for discs — VOC and CDT for tapes — CPR for cartridges — SNA snapshots — direct load of ZIP files.

Something missing? Open an issue to suggest it.

DevTools

Press F12 or send devtools via IPC to toggle the DevTools toolbar below the main topbar. The toolbar provides dropdown menus (CPU, Memory, Hardware, Media, Export) and step/pause controls. All 18 windows are also accessible from the command palette:

Window	Description
Registers	Z80 registers and flags, editable in-place
Disassembly	Live disassembly with follow-PC, goto address, symbol labels and data area formatting
Memory Hex	Hex editor with configurable bytes-per-row and goto address
Stack	Stack view with heuristic CALL/RST detection and symbol names
Breakpoints	Unified table of breakpoints, watchpoints and IO breakpoints with add/delete forms
Symbols	Symbol table with filter, add/delete, load/save .sym files
Data Areas	Mark memory ranges as bytes/words/text for correct disassembly
Disasm Export	Export disassembly to source files with address range and symbol options
Session Recording	Record, stop and replay emulator sessions with progress display
Recording Controls	Transport controls for session playback with progress bar
Graphics Finder	Decode CPC pixel data at any address in Mode 0/1/2, with zoom, palette selector and paint
Silicon Disc	Enable/disable, bank usage display, clear/save/load the 256K RAM disc
ASIC Viewer	Plus Range hardware: 16 sprites, 3 DMA channels, 32-colour palette, interrupt state
Disc Tools	Drive selector, disc formatting, AMSDOS file browser, sector-level read
Video State	Live CRTC and Gate Array register display
Audio State	Live PSG (AY-3-8912) register display with oscilloscope
Assembler	Z80 assembler with labels, expressions, error list and assemble-to-memory
Instruction Reference	Searchable Z80 opcode table (1268 entries across 7 prefix groups)

In Docked mode, windows snap into a tiled layout. Three presets are available (Debug, IDE, Hardware) and custom layouts can be saved/loaded from the Layout menu.

Installation

macOS

See INSTALL.md.

Linux

From Git

git clone --recurse-submodules https://github.com/ikari-pl/konCePCja.git
cd konCePCja
make APP_PATH="$PWD"
./koncepcja

Note: A plain make without APP_PATH produces a debug-oriented build that looks for koncepcja.cfg in the current working directory, not next to the executable. Set APP_PATH to get the documented behaviour.

From releases

Download a release from https://github.com/ikari-pl/konCePCja/releases, decompress it and run:

./koncepcja

Windows

Download a release from https://github.com/ikari-pl/konCePCja/releases, decompress it and double-click koncepcja.exe.

Usage

See the manual page for details. If you are lost, launch the emulator without arguments and press F1 for the in-emulator menu.

Building

See INSTALL.md for build instructions.

License

konCePCja is a clean, hardware-inspired emulator authored from silicon behaviour, not based today on any other. Its source is distributed under the terms of the konCePCja Source License 1.0.0 — a source-available license based on PolyForm Internal Use 1.0.0 with an added Personal & Hobby Use grant. In short: you may read, use, and modify the source for any personal, hobby, or internal purpose — including using it as a tool to create your own works, commercial or not — but you may not redistribute the software or publish your own forks/builds of it. See LICENSE.md for the exact terms and NOTICE.md for the provenance statement and third-party attributions.

Third-party components are vendored under their own (permissive) licenses in vendor/ — see vendor/README.md and NOTICE.md.

The bundled ROM images in rom/ are © Amstrad plc and Locomotive Software Ltd, redistributed with permission and not covered by the source license above. Amstrad have kindly given their permission for the redistribution of their copyrighted material but retain that copyright. See rom/ROM-LICENSE.txt for full details including the Multiface II ROM.

Contributing

Contributions are welcome. Because the project is source-available (the license grants use and modification but not distribution), contributions are accepted under the terms in CONTRIBUTING.md: open an issue or submit a PR with a Signed-off-by line certifying the Developer Certificate of Origin and granting the project the right to use your contribution.