konCePCja User Manual

konCePCja is an Amstrad CPC emulator based on Caprice32.

© 1997–2015 Ulrich Doewich · © 2016–2025 Colin Pitrat (Caprice32)
© 2024–2026 the konCePCja contributors

konCePCja is free software, distributed under the terms of the GNU General Public License, version 2 (GPLv2), included with the source as COPYING.txt. This manual is distributed with konCePCja under the same terms.

Amstrad, CPC, CPC464, CPC664, CPC6128, and CPC6128+ are trademarks of their respective owners. This is an independent project and is not affiliated with, nor endorsed by, the trademark holders.

Illustrations, diagrams, and screenshots © 2026 Cezar “ikari” Pokorski, ikari.press.

Font credits: Rokkitt (OFL), TeX Gyre Schola (GUST), OCR-B by Matthew Skala, JuliaMono (OFL), Cascadia Code (OFL), and “Amstrad CPC correct” by Damien Guard (CC-BY-SA 3.0). See manual/fonts/LICENSES.md.

About This Manual

This manual is a guide to using konCePCja, from first launch through to its power-user features. It assumes you know roughly what an Amstrad CPC is, but not how the emulator’s internals work.

Early chapters cover installation, loading software, the interface, and configuration. Later chapters document the emulated hardware and peripherals, the developer tools, and the scripting interfaces — the IPC debugging protocol (e.g. mem read 0x4000 16), the telnet console, and the M4 Board’s web interface — for technically inclined readers.

Conventions used throughout: function keys appear as F12 menu paths as Settings›Video configuration keys as system.model I/O ports as &FD06 and Z80 registers as HL.

Getting Started

This chapter takes you from nothing to a running Amstrad CPC: what konCePCja is, what you need, how to build it on your platform, and how to load your first piece of software. If you have already built and launched the emulator, skip ahead to Loading Software on page 1.

What is konCePCja?

konCePCja is an emulator of the Amstrad CPC range of 8-bit home computers. It is built on the well-established Caprice32 emulator core, extended with a modern SDL3 video and audio backend and a Dear ImGui developer interface.

It runs on macOS, Linux, and Windows (the latter via the MinGW toolchain), and emulates the whole classic CPC line as well as the Plus range:

• CPC 464 — cassette-based, 64 KB RAM
• CPC 664 — disc-based, 64 KB RAM
• CPC 6128 — disc-based, 128 KB RAM (the default)
• CPC 6128+ — the Plus machine, with ASIC hardware sprites, an enhanced palette, DMA sound channels, and cartridge support

What sets konCePCja apart from other CPC emulators is its emphasis on inspection and automation: a full developer-tools panel (see F12), a scriptable TCP debugging interface, a telnet console, and an emulated M4 Board with a web file manager. These power-user features are documented in the later chapters.

System Requirements

konCePCja is lightweight by modern standards. The emulated machine is an 8-bit computer; the host requirements come almost entirely from the build toolchain and the windowing layer.

• macOS — a recent macOS release on either Apple Silicon or Intel. Homebrew is used to install the build dependencies.
• Linux — any reasonably current distribution with a C++17 compiler.
• Windows — an MSYS2 / MinGW environment.
• Hardware — a few hundred megabytes of RAM and an OpenGL-capable GPU. A software-render fallback exists for headless and remote use.

Installation

konCePCja is built from source. The build needs a C++17 compiler, plus SDL3 (vendored as a git submodule or supplied by your package manager), FreeType, zlib, libPNG, and CMake. Always clone with submodules:

macOS

Install the dependencies with Homebrew, build the vendored SDL3, then build the emulator:

To produce a double-clickable application bundle (.dmg), run make ARCH=macos macos_bundle.

Linux

Install the build dependencies, then build SDL3 and the emulator:

If your distribution already ships SDL3 (Ubuntu 25.04 and later), you can skip the submodule build:

Useful build options: make debug (or DEBUG=TRUE) for a debug build, WITHOUT_GL=TRUE to build without OpenGL.

Windows (MSYS2 / MinGW)

Install MSYS2 from msys2.org and build from a MinGW shell. konCePCja’s continuous integration builds both the MINGW32 and MINGW64 targets, so either works.

First Launch

Launch konCePCja with no arguments and it boots straight to the default machine — a CPC 6128 with 128 KB of RAM:

You are greeted by the CPC firmware sign-on and the Locomotive BASIC prompt:

The word Ready followed by a flashing cursor means the machine is waiting for a BASIC command. This is a fully working CPC: type PRINT “HELLO” and press RETURN to see it respond.

Press F1 at any time to open the in-emulator menu (it pauses emulation), or F12 to open the developer tools. The complete function-key reference is in Chapter 2.

To start on a different machine — for example the Plus — override the model on the command line (model 3 is the 6128+):

Loading Software

konCePCja loads the standard CPC media formats. The quickest way is to pass a file on the command line, or drag it onto the window; both also work through File›Load.

Disc images (DSK)

The most common format. Load and auto-run a disc in one step with the –autocmd (-a) option:

Or load it and run by hand from BASIC with run"game.

Tape files (CDT / VOC)

Insert a tape image, then in BASIC select the tape, issue LOAD"", and start playback with F4 (tape play/pause):

Cartridge files (CPR)

Cartridges are a Plus-range feature. Pass a .cpr file on a 6128+ machine (system.model = 3) and it boots directly from the cartridge.

Snapshots (SNA)

A snapshot is a frozen machine state — RAM, registers, and hardware — that resumes instantly. Load one from the command line or via File›Load save the current state with Shift+F3.

ZIP archives

konCePCja can also open a .zip archive containing CPC media (DSK, CDT, or SNA) and load the appropriate file from inside it, so you do not have to unpack downloads by hand.

Command-line options

Run koncepcja –help for the full list. The options you will reach for most:

So, for example, to boot a 6128+, inject a loader at 0x4000, and auto-run a disc:

Troubleshooting

The build fails immediately, complaining about SDL. You almost certainly cloned without submodules. Either re-clone with git clone –recurse-submodules, or fetch them in place with git submodule update –init –recursive, then build the vendored SDL3 as shown above (or install your distribution’s libsdl3-dev).

On macOS, a crash dialog mentions “reopening windows” at startup. This is stale macOS saved-application state, not a konCePCja bug. Clear it:

The window is black or OpenGL fails to start. Build or run with WITHOUT_GL=TRUE for the software-render fallback; this also lets konCePCja run on machines and remote sessions without a usable GPU.

A disc or tape image is rejected. Malformed images are refused rather than crashing the emulator; run with –verbose and look for an ERROR line naming the problem.

The konCePCja Interface

konCePCja wraps the emulated machine in a thin modern interface: a menu bar, a set of function-key shortcuts, an on-screen display, and a virtual keyboard. This chapter is your map to the controls.

The main window

The window shows the live CPC display. The emulated machine runs continuously; you interact with it by typing (the host keyboard maps to the CPC keyboard) and through the menu and function keys described below.

Along the top of the window is a toolbar: the Menu (F1) button, the status of each disc drive and the tape, transport controls for tape playback, and a speed indicator showing the current frame rate and emulation speed. It stays visible while the machine runs, so the drive and tape state are always in view.

The menu bar

Press F1 to open the in-emulator menu, which pauses emulation while it is open. From here you can load media, save and load snapshots, reach the settings dialog, and open the developer tools.

Function keys

The function keys are the quickest way to drive the emulator:

Virtual keyboard

Some CPC keys have no obvious host equivalent. Press Shift+F1 for an on-screen CPC keyboard you can click, showing the true CPC layout including the numeric keypad and the COPY key.

On-screen display

Brief status messages — a snapshot saved, the speed limiter toggled — appear as a transient on-screen display overlaid on the CPC picture.

Screenshots

Press F3 to save a PNG screenshot of the current CPC display.

Command palette

For quick access to any action without hunting through menus, press Ctrl+K (or Cmd+K on macOS) to open the command palette. Start typing and it filters a searchable list of every command — each shown with its description and keyboard shortcut — and runs the one you choose. It is the fastest route to a feature whose menu location you have forgotten.

Configuration profiles

A configuration profile is a named bundle of machine settings — model, RAM size, clock speed, frame-skip, screen scale and scanlines, the sound options, and the joystick and keyboard modes. Save the current settings as a named profile and switch between profiles in one step, rather than changing options one at a time. This is convenient for keeping, say, a “464 with tape” setup and a “6128+ with sound” setup side by side.

Disks, Tapes, and Snapshots

Chapter 1 showed the quickest way to load a single file. This chapter covers the media system in more depth: the two disc drives, the tape deck, and the snapshot system for saving and resuming machine state.

Disc drives

The CPC has two 3-inch disc drives, A and B. Insert a .dsk image into a drive by dragging it onto the window, choosing File›Load, or naming it on the command line. With a disc in drive A, run a program from BASIC:

konCePCja reads and writes both standard and extended .dsk images. Write protection is honoured, so software that checks for it behaves correctly.

A standard .dsk stores decoded sector data — every sector on a track the same size, no gaps or sync marks. An extended .dsk (EDSK) adds variable sector sizes and per-sector status bytes, which lets it reproduce deliberately malformed sectors and most copy protection. konCePCja picks the right reader automatically from the file’s header.

The 3-inch discs themselves come in a few standard layouts, all 40 tracks, single-sided, 512-byte sectors:

You rarely need to think about which is which — AMSDOS reads all three — but it explains why a “180 KB” disc holds a little less once formatted, and why the disc tools (Chapter 7) report sectors numbered from &C1 rather than 1.

Tape

On a 464 (or any machine with the tape firmware), select the tape, ask BASIC to load, and press F4 to start playback:

F4 toggles tape play and pause at any time. Both .cdt and .voc tape images are supported.

Cartridges

Cartridge (.cpr) images are a Plus-range feature. On a 6128+ (system.model = 3), loading a cartridge boots the machine directly from it.

Snapshots

A snapshot freezes the entire machine — memory, registers, and hardware state — into a .sna file that resumes instantly. Save the current state with Shift+F3 load one through File›Load or on the command line. Snapshots are ideal for resuming a game exactly where you left it, or for sharing a precise machine state.

ZIP archives

Much CPC software is distributed as .zip archives. konCePCja can open a ZIP directly: it reads the archive’s directory, finds a file with a recognised CPC extension (.dsk, .cdt, or .sna) inside, and loads it — so you do not have to unpack downloads by hand before running them.

IPF discs

Some heavily copy-protected discs are preserved in the .ipf (Interchangeable Preservation Format) rather than .dsk. konCePCja loads .ipf images into a drive just like ordinary disc images, reproducing the original protection so the software runs as it did from the real disc.

Configuration

konCePCja reads its settings from a plain-text configuration file and from command-line arguments. This chapter covers where that file lives, the options you are most likely to change, and how to override any setting without editing the file.

The configuration file

konCePCja looks for a file named koncepcja.cfg in the following locations, in order of precedence (the first one found wins):

1. the path given with –cfg_file (-c) on the command line;
2. koncepcja.cfg in the current working directory;
3. $XDG_CONFIG_HOME/koncepcja.cfg (or ~/.config/koncepcja.cfg);
4.  /.koncepcja.cfg
5. /etc/koncepcja.cfg.

The file is divided into [section] headings, each containing key=value lines.

Key options

System

The system.model option selects which machine to emulate. The default, 2, is the CPC 6128; 3 is the 6128+ (needed for cartridges and ASIC features).

Video

Sound

Overriding settings on the command line

Any configuration option can be overridden for a single run with –override (-O), without touching the file. The argument is section.key=value, and the flag may be repeated:

This is the quickest way to try a different machine or disable sound for one session. A full reference of every configuration option is given in Appendix C.

Emulated Hardware

konCePCja emulates the complete Amstrad CPC: the Z80 processor and every custom chip around it. You do not need any of this to play games, but the developer tools (Chapter 7) expose all of it, and understanding the machine helps when you write or debug CPC code. This chapter covers both the system as a whole — its memory, screen modes, and I/O — and the individual chips.

The processor

At the centre is a Zilog Z80A running at 4 MHz. konCePCja implements the full documented and undocumented instruction set, including the shadow register bank and the interrupt modes. The developer tools can breakpoint, step, and disassemble it (Chapter 7).

The memory map

The Z80 sees a 64 KB address space, divided into four 16 KB banks. Two of those banks can show ROM instead of RAM:

ROM is an overlay: when a ROM is paged in, reads from its range return ROM, but writes still go to the RAM underneath. This is how the firmware lives at &0000 and &C000 while the program’s variables occupy the same addresses in RAM.

The 6128′s extra 64 KB (and the up-to-4 MB Yarek-style expansion) is reached by bank switching: a control register pages 16 KB blocks of the extra RAM into the &4000–&7FFF window (and others), so the 8-bit Z80 can use far more than 64 KB.

The seven standard banking configurations (selected by writing &C0–&C7 to the Gate Array’s RAM-config register at &7Fxx) rearrange which physical 16 KB blocks appear in each window. The most common use is double-buffering: draw the next frame into a hidden bank, then page it into the screen window in one write, so the display never tears. The developer tools’ memory viewer (Chapter 7) always shows the currently-paged view; to inspect a bank that is not currently visible, page it in first.

Screen modes

The CPC has three screen modes, each trading colour for resolution. All three use 80 bytes per scan line:

Switch modes from BASIC with MODE 0, MODE 1, or MODE 2. A mode can even be changed partway down the screen for split-screen effects.

Colour and the palette

The CPC can show 27 distinct hardware colours. Each mode draws from a palette of inks — 16 in mode 0, 4 in mode 1, 2 in mode 2 — and any ink can be assigned any of the 27 colours, plus a separate border colour. Changing an ink updates every pixel drawn in that ink at once, which is the basis of many colour-cycling effects. The Plus machines widen this to 4096 colours.

I/O ports

The custom chips are reached through Z80 OUT and IN instructions. Because the CPC decodes I/O addresses only partially, each device responds to a range of ports identified by the upper address bits:

Note that the Gate Array is write-only — software cannot read back the current mode or palette and must remember what it set. The developer tools, however, show the live state directly (Chapter 7).

Interrupts and timing

The display refreshes at 50 Hz. The Gate Array raises a Z80 interrupt every 52 CRTC scan lines — six times per frame, every  3 milliseconds — which the firmware uses for the keyboard scan, sound, and timing. Because the interrupt is tied to the raster position, demo code can synchronise palette and mode changes to exact points on the screen.

The custom chips

Gate Array. Amstrad’s custom video and memory controller — it holds the palette, selects the screen mode, pages the ROMs, and generates the raster interrupt described above.

CRTC. The Cathode Ray Tube Controller generates video timing. The CPC shipped with several variants, and konCePCja emulates all four types — the HD6845S (0), UM6845R (1), MC6845 (2), and the AMS40489 (3) in the Plus machines — each with its own register-level quirks, so timing-sensitive software runs correctly when the matching type is selected.

PPI 8255. The general-purpose I/O chip: it reads the keyboard matrix, controls the PSG, and drives the cassette motor.

PSG AY-3-8912. Three channels of square-wave tone plus a noise generator and a hardware envelope generator. Its state is visible in the audio developer tools and can be captured to a YM file (Chapter 12).

FDC uPD765A. The floppy disc controller, reading and writing both standard and extended .dsk images, including copy-protected formats.

ASIC. On the 6128+ (system.model = 3) a single ASIC replaces the Gate Array and CRTC and adds hardware sprites, the 4096-colour palette, programmable raster interrupts, and DMA sound channels, all inspectable through the ASIC developer-tools window.

Peripheral Expansions

Beyond the core machine, konCePCja emulates a range of expansion hardware that was sold for the CPC over the years — sound add-ons, real-time clocks, mice, a multi-function interface board, and a light gun. Each is enabled through configuration (Chapter 4) or the menu, and is listed here with the I/O it uses.

Enabling a peripheral

Peripherals are off by default. Most are switched on with a configuration key (Chapter 4): for a single session use the -O override, or set it in koncepcja.cfg to make it permanent. For example, to start with both the AMX mouse and the Symbiface II board active:

The light gun (phaser) is toggled at runtime with its function key instead. Each section below names the I/O ports its device uses — which the developer tools (Chapter 7) can watch with an I/O breakpoint when you are debugging peripheral software.

Digiblaster

A simple 8-bit digital-to-analogue converter on the printer port. konCePCja feeds the printer-port value through a level table and mixes the result into the sound output, reproducing sampled-audio playback software.

AmDrum (Cheetah)

An 8-bit DAC drum machine on port &FFxx (the uncontested I/O space where all upper address bits are high). It mixes into the audio output the same way as the Digiblaster.

Dobbertin SmartWatch

A Dallas DS1216 phantom real-time clock that sits in the upper ROM socket. It intercepts ROM reads using a recognition pattern and returns the host system time in BCD form, so CPC software that expects the SmartWatch reads the correct date and time.

AMX Mouse

A mouse that connects to the joystick port and appears on keyboard-matrix row 9. Movement is reported as direction pulses (“mickeys”) and the buttons map onto the joystick fire lines. Enable it with input.amx_mouse = 1.

Symbiface II

A multi-function expansion board providing three devices:

• IDE hard disc (ATA PIO) at &FD06–&FD0F, backed by a raw .img file — supports reading, writing, and IDENTIFY DEVICE.
• Real-time clock (DS12887) at &FD14 / &FD15, with 14 time registers from the host clock plus 50 bytes of CMOS NVRAM.
• PS/2 mouse at &FD10 / &FD18, using a multiplexed FIFO protocol.

Enable it with peripheral.symbiface = 1.

M4 Board

A virtual-filesystem expansion that exposes a host directory to the CPC as a storage device, with an embedded web file manager. It is covered in full in Chapter 11.

Multiface II

A ROM-based debugging and snapshot interface. Press F6 to trigger its stop button and enter its menu, as on real hardware.

Amstrad Magnum Phaser

A light gun emulated by intercepting the CRTC registers. Aim with the mouse pointer over the display; the trigger maps to a fire button.

Drive and tape sounds

For atmosphere, konCePCja can mix in procedurally generated floppy-drive motor hum and head-seek clicks, and tape loading hiss, alongside the emulated audio.

Developer Tools

konCePCja includes a full suite of developer tools — a debugger, memory inspector, disassembler, and more — modelled on modern emulator debug environments. Press F12 to open them. This chapter tours the windows you will use most.

Overview

The developer tools open as a set of dockable windows over the CPC display. Core windows open automatically the first time you press F12 the rest are reached from the DevTools toolbar.

Z80 registers

The registers window shows the live Z80 register file — AF, BC, DE, HL, the index registers, PC, and SP — together with the individual flag bits. Values update as the machine runs and can be edited while paused.

Disassembly

The disassembly window decodes memory into Z80 mnemonics around the program counter, follows jumps and calls, and shows symbol labels when a symbol file is loaded. Breakpoints can be toggled directly in the listing.

Memory hex viewer

A hex/ASCII viewer over the full 64 KB address space, with search and direct editing (poke).

Stack

The stack window shows the bytes around SP, so you can watch calls and returns as they happen.

Breakpoints and watchpoints

Set execution breakpoints (optionally conditional, with pass counts), memory watchpoints, and I/O breakpoints on port reads and writes. When one fires, emulation pauses and the registers and disassembly update to the breakpoint location.

Symbols

Load a symbol file (with –sym_file) to show labels in the disassembler and to refer to addresses by name.

Video and audio state

Dedicated windows expose the live state of the video hardware (Gate Array palette, CRTC registers, screen mode) and the audio hardware (the three PSG channels, the envelope generator, and any active DAC peripherals).

Other windows

The toolbar also opens windows for the data-area map, disassembly export, the ASIC (on Plus machines), the disc tools, the silicon-disc expansion, and session recording (Chapter 12). The integrated Z80 assembler has its own chapter (Chapter 8).

Graphics finder

The graphics finder decodes raw memory as CPC pixels, so you can locate sprites, fonts, and screen data by eye. Point it at an address, set the screen mode (0, 1, or 2) and the width in bytes, and it renders that region as a zoomable image. It can also encode edits back into memory, making it a simple in-memory pixel editor.

Memory search

The memory search tool scans the full address space for a pattern. You can search for hex byte sequences, text strings, or assembly (matching decoded instructions), with wildcards for unknown bytes. Each hit is reported with its address and surrounding context — the disassembled instruction for an assembly search, or a hex dump otherwise.

Pokes

The pokes system applies game cheats from .pok files. A poke file lists named cheats (for example “infinite lives”), each a set of memory writes. Apply a cheat to patch the running game and un-apply it to restore the original bytes. Where a cheat needs a value you choose — a number of lives, say — konCePCja prompts you for it.

A debugging session

To see how the windows work together, here is a typical investigation — finding where a program writes to the screen.

First, pause the machine (the menu, or pause over IPC) and open the disassembly and memory windows. Suppose you want to catch every write to screen memory, which lives at &C000. Add a watchpoint on that range, set to trigger on writes:

Resume. The moment the program writes to the screen, emulation pauses, the registers window shows the exact PC of the writing instruction, and the disassembly window centres on it. The stack window shows who called the routine. From there you can single-step (F12 tools, or step) to watch the write happen byte by byte, edit a register or memory value to test a hypothesis, and set a permanent breakpoint to return to this spot later.

The same loop — pause, set a breakpoint or watchpoint, run, inspect, step — is the heart of debugging on the CPC. Conditional breakpoints (Chapter 9) narrow it further: break only when a register holds a particular value, or only on the hundredth time a routine runs. Everything available in these windows is also available over the IPC interface, so an investigation you do by hand can be turned into a repeatable script.

Z80 Assembler

konCePCja includes an integrated Z80 assembler, so you can write machine code and assemble it straight into the emulated machine’s memory without leaving the emulator — ideal for patching a game, trying an idea, or learning Z80 by watching code run.

Using the assembler

Open the assembler window from the developer-tools toolbar (F12). Type or paste Z80 source into the editor and assemble it; the resulting bytes are written directly into CPC memory at the addresses your source specifies. Assembly happens in two passes — the first builds the symbol table and measures each instruction, the second emits the bytes — so labels can be referenced before they are defined. Errors are reported with line numbers, and the symbol table from a successful assembly is available for inspection and for the disassembler.

Syntax

The assembler accepts standard Z80 mnemonics, labels, directives, and an expression evaluator.

In expressions, & (or #) introduces a hexadecimal number and % a binary one; the usual arithmetic and bitwise operators are available.

Driving the assembler over IPC

The assembler is also scriptable through the IPC interface (Chapter 9), so a build script can assemble code into the machine and read back the results:

Because assembled symbols feed straight into the disassembler and the IPC sym commands, you can assemble a routine, breakpoint one of its labels by name, and step through it — a complete edit-assemble-debug loop inside the emulator.

IPC Debugging Interface

konCePCja exposes a TCP control interface that lets external scripts and tools drive and inspect the emulated machine in depth: pause and step the processor, read and write memory and every hardware register, set conditional breakpoints and watchpoints, search memory, inject input, and hash state for regression testing. This chapter is the working reference.

Connecting

The server listens on localhost:6543. The protocol is plain text: one command per line, newline-terminated. Every response begins with OK (followed by any result) or ERR ‹code› ‹reason›. Any tool that speaks TCP works:

Numbers may be given in decimal, hexadecimal (0x, #, or & prefix), or binary (0b or % prefix) throughout.

Lifecycle and loading

Registers

Read or write the Z80 register file, and read the custom chips’ live state:

Memory

By default reads see the standard Z80 view, with ROM overlaid at 0x0000. Two options change that: --view=write exposes the underlying RAM beneath the ROM, and --bank=N reads a raw physical 16 KB bank, ignoring the current mapping — useful for inspecting paged-out memory.

Breakpoints

Execution breakpoints can be plain, conditional, or counted:

Watchpoints

Watchpoints break on memory access rather than execution:

A watchpoint condition can use the special variables address, value, and previous to inspect the access that triggered it:

I/O breakpoints

Break on Z80 IN/OUT to a port. Because the CPC decodes I/O addresses incompletely, ports are matched through a mask; the X shorthand wildcards a nibble:

Expression syntax

Conditional breakpoints, watchpoints, and I/O breakpoints share a WinAPE-inspired expression language. All arithmetic is 32-bit signed; comparisons return −1 for true and 0 for false.

Stepping and waiting

The wait commands resume emulation, block until their condition or a timeout (default 5000 ms, then ERR 408 timeout), and pause again — the building block for deterministic test scripts.

Inspecting code and memory

Injecting input

Keyboard, joystick, and mouse input are all driveable (keys take a friendly name or a single character):

Hashes for regression testing

For continuous integration, CRC32 hashes turn machine state into a single comparable value:

A worked example

Type and run a one-line BASIC program, wait for it to settle, then assert on the result by hashing the screen:

Run the emulator headless (no window) for CI with the –headless flag; the protocol is identical in headless and windowed modes. A Python test harness built on these commands lives in the project’s test/integrated directory.

Telnet Console

Alongside the binary IPC protocol, konCePCja offers a human-friendly text console: a remote terminal for the emulated CPC that mirrors everything the machine prints and accepts your keystrokes in return.

Connecting

The console listens on port 6544 (one higher than the IPC port). Connect with any terminal client:

Only one client is served at a time; a new connection replaces the previous one.

What you see and type

Output works in two ways at once. Under AMSDOS, konCePCja hooks the firmware text-output routine, so every character the CPC prints to the screen is echoed to your terminal. Under CP/M it hooks the BDOS console-output call, so CP/M programs are mirrored too — no configuration needed.

Anything you type is fed to the CPC as keyboard input. Printable characters pass straight through, and the common terminal control sequences are translated to their CPC equivalents:

Example: a remote BASIC session

Connect, and you are talking to the CPC’s BASIC prompt directly:

Press Ctrl+C (sent as ESC) to break the running program.

Uses

The console is ideal for driving a CPC BASIC or CP/M session from a script or an SSH session, copying text in and out of the emulated machine, or watching its output without the graphical window. It pairs naturally with the IPC interface (Chapter 9): use IPC to set up the machine deterministically, then the telnet console to interact with it as text. Note that the port probes forward (up to +10) if 6544 is already taken, so the actual port is reported in the log on startup.

M4 Board and Virtual Filesystem

The M4 Board is a popular real-world expansion that gives the CPC a network connection and SD-card storage. konCePCja emulates it, backing the virtual SD card with a directory on your host and serving the same web file manager the real board provides.

Overview

The emulated M4 Board exposes a host directory to the CPC as a storage device through a command/response protocol. CPC software builds a command by writing its bytes one at a time to &FE00, then writes &FC00 to execute it; the board places its reply in a ROM overlay at &E800 for the CPC to read back. A path-traversal guard keeps CPC software confined to the host directory it is given. The board is compatible with the cpcxfer tool and the M4 Board Android app.

The web file manager

An embedded HTTP server provides a browser-based file manager for the virtual SD card. By default it listens on port 8080:

From the browser you can list directories, upload and delete files, create folders, and remotely run a file on the CPC. The endpoints mirror the real M4 Board’s config.cgi interface, so existing M4 tooling works unchanged:

Controlling it over IPC

The HTTP server and its port mappings are managed through IPC (Chapter 9):

Operations that change the CPC’s state (such as a reset triggered from the web interface) are deferred to the emulator’s main thread, so the board is safe to drive from a browser while emulation runs.

Configuration

The board is configured in the [peripheral] section:

Recording

konCePCja can capture what happens on the emulated machine in several formats: video, animated images, chiptune audio, and complete replayable sessions. This chapter covers each, and when to reach for which.

The recording controls live in the developer tools (F12); single screenshots and frame dumps also have function-key shortcuts (F3 for a screenshot). At a glance:

AVI video recording

Record the CPC display and sound together to an .avi video file — useful for capturing gameplay or a demo with synchronised audio.

GIF and frame dumps

For short clips and screenshots, konCePCja can save an animated GIF (LZW-compressed) of the display, or a sequence of numbered PNG frames. These are ideal for documentation and for sharing a moment of a game without a full video file.

YM audio recording

Rather than recording sampled audio, the YM recorder captures the actual register writes to the PSG sound chip and saves them as a .ym chiptune file. The result is a compact, authentic record of the music that can be replayed in YM players, exactly as the CPC produced it.

Session recording and playback

A session recording captures the machine’s input and state over time so that an entire run can be replayed deterministically — the same inputs producing the same result every time. This is valuable for demonstrations, for bug reports (a recording reproduces the problem exactly), and as the basis for automated regression testing alongside the IPC interface (Chapter 9).

Key Reference

The CPC keyboard differs from a modern PC keyboard in a few places. Most keys map directly; the table below lists the ones worth knowing. When a key has no obvious host equivalent, use the virtual keyboard (Shift+F1).

Firmware key numbers

Internally the CPC identifies each key by a number (0–79), not by its character. These are the numbers the firmware’s KM routines use, and the same numbers the keyboard matrix is wired in. They matter when you drive the machine programmatically — injecting key presses over the IPC interface (Chapter 9), or reading the matrix in your own code — because there the key is addressed by number, independent of which character it would type.

IPC Command Reference

A quick reference to the IPC commands (Chapter 9). Connect to port 6543 and send one command per line.

Configuration Reference

The options in koncepcja.cfg (Chapter 4), by section. Any of these can also be set for one run with -O section.key=value.

[system]

[video]

[sound]

[peripheral]

[input]

Supported File Formats

Hardware Specifications (Emulated)

A summary of the emulated machine. See Chapter 5 for what each part does.

Glossary

AMSDOS

The CPC’s disc operating system, layered over BASIC, providing disc file commands.

ASIC

The custom chip in the Plus machines that replaces the discrete Gate Array and CRTC and adds sprites, an enhanced palette, and DMA sound.

CRTC

Cathode Ray Tube Controller — the chip that generates video timing. The CPC shipped with several types, all emulated.

Gate Array

Amstrad’s custom video and memory-management chip.

IPC

The TCP control interface konCePCja exposes on port 6543 for scripting and debugging (Chapter 9).

Mickey

One unit of mouse movement, as reported by the AMX Mouse.

PSG

Programmable Sound Generator (the AY-3-8912) — the CPC’s sound chip.

Snapshot

A saved copy of the entire machine state, in a .sna file, that resumes instantly.

M4 Board

A network and storage expansion, emulated with a web file manager (Chapter 11).

Index

• AmDrum
• AMX Mouse
• ASIC
• asm IPC
• assembler
• AVI recording
• breakpoints
• breakpoints, IPC
• cartridge
• command palette
• command-line options
• configuration file
• configuration profiles
• CP/M
• CPC 464
• CPC 6128+
• CPC model
• CRTC
• DevTools
• Digiblaster
• disassembly
• disc drive
• drive sounds
• DSK format
• expression syntax
• FDC
• function keys
• Gate Array
• GIF recording
• graphics finder
• hashes
• I/O breakpoints
• I/O ports
• input injection
• interrupt
• IPC
• IPF
• key numbers
• konCePCja
• loading software
• M4 Board
• m4 config
• M4 HTTP
• m4 http
• Magnum Phaser
• main window
• memory banking
• memory map
• memory search
• memory viewer
• MSYS2
• Multiface II
• number prefixes
• OSD
• override
• palette
• peripherals, enabling
• pokes
• PPI
• PSG
• RAM banking
• Ready prompt
• registers window
• registers, IPC
• ROM paging
• screen mode
• session recording
• SmartWatch
• snapshot
• Symbiface II
• tape
• telnet console
• troubleshooting
• video state
• virtual keyboard
• watchpoints
• YM recording
• Z80
• ZIP archive