cpcec-gtk

An Amstrad CPC / Plus / GX-4000 emulator for Debian-based Linux.

Emulation code by 2018-2021 Cesar “cngsoft” Nicolas-Gonzalez (http://cngsoft.no-ip.org/cpcec.htm)

GTK-based UI program (including packaging and this documentation) by 2021 Arnaud “norecess” Storq (https://gitlab.com/norecess464/cpcec-gtk)

Overview

cpcec-gtk is an accurate, easy-to-use GTK3-based Amstrad CPC / Plus / GX-4000 emulator featuring a debugger for Debian-based Linux (Debian, Ubuntu, POP-OS, etc.).

Features

• integrated original core emulation from CPCEC (http://cngsoft.no-ip.org/cpcec.htm), providing accurate emulation for most available software
• support for .dsk (floppy disc images)
• support for .cpr (cartridge images for Amstrad Plus / GX-4000)
• support for .sna (memory snapshots)
• manage your own Amstrad software library: quickly find a precise software using advanced filtering (by keyword or by extension type)
• ability to quickly open a file via drag'n'drop, file menu or through your software library (first binary found on disc will be executed)
• a set of debugging tools featuring a Z80 disassembler and various inspectors: memory, video display (ability to position current monitor scanline) and ASIC
• user settings (window positions, library path, last loaded files, audio mute option..) saved into a config file
• support for “virtual joystick” (emulated through arrows keys/Control/Alt keys) featuring an algorythm behaving like a real Amstrad keyboard (cf. press up key -> then override by also pressing down key (up key still pressed, but down key is detected as current pressed one) -> then release down key (up key still pressed)-> up key will continue to be pressed)
• support for external game controllers (can be plugged/unplugged safely while the emulator is running)
• support for numeric keyboard (use Alt+1,2,3.. keys) in case your PC keyboard does not have one (laptops..)
• automatically reload inserted files when their content changed outside the emulator (cf. useful for developers)
• ability to zoom emulator's graphical window and respect 1:1 pixel ratio
• fully support 2 Amstrad disc-drives (possibility to eject inserted discs)
• support for rasm (Roudoudou assembler)'s symbol files
• preconfigured symbols for ASIC registers
• automatic switch to Amstrad Plus machine when a .cpr file is inserted
• very low footprint on RAM and CPU
• can save screenshot using .png file format
• can create new .dsk files from scratch
• can save .sna snapshots
• ability to pause the emulator
• comprehensive shortcuts
• and more..

By default, all emulated Amstrad machines gets created with a memory expansion of 512Kb (expected the GX-4000: 64Kb).

Installation

Once downloaded, use sudo dpkg -i cpcec-gtk.deb to install (and sudo apt purge cpcec-gtk to remove).

There is no bloat:

• cpcec-gtk binary is located into /usr/bin
  
• the required internal resource files (Amstrad ROMs, this documentation, etc.) are located into /usr/share/cpcec-gtk/
  
• the current configuration (the current Amstrad model, the window positions, the current inserted disk images, etc.) are stored into a simple config file ~/.config/cpcec-gtk/config.ini (feel free to delete this file to reset your settings).

Main window

When you launch the emulator, the following window is presented to the user :

From there, the user can:

• drag'n'drop a known image file format directly into the emulator window
• quickly open a known image file format from the file system OR your own software library
• create a new empty DSK file
• insert a .dsk file in simulated Drive A or B
• insert a .cpr file into simulated cartridge port
• save/load a .sna snapshot file

Please take note that if an opened file gets changed externally, it will be automatically reloaded (restarted) by the emulator. This is particularly useful for a developer. Combined with saved configuration, the usual program arguments sent at startup to configure the emulator / disc to load are not necessary anymore.

Compatibility with keyboards missing a numeric keyboard

When launching the Amstrad Plus / GX-4000 machine, a menu is displayed at startup to select between f1 Amstrad BASIC and f2 Burnin' Rubber. Some keyboards - usually the small ones as found in laptops - may not have any numerical keyboards. Please use ALT+0..9/Return/Dot to simulate the missing numeric keyboard (ALT-1 or ALT-2 to select between Amstrad BASIC and Burnin' Rubber gameB).

Compatibility with Amstrad's COPY key

This is handled through ALT key. The common operation SHIFT+arrow keys + CONTROL+ENTER to allow RUN" prefix is functional.

Compatibility with external game controllers

Game controllers such as XBOX controllers are perfectly supported. Plugging (or unplugging) game controllers while the emulator is running is supported (no need to relaunch the emulator).

For users having no game controller, they can rely on the “Virtual Joystick” feature. When enabled, the user can use the arrow keys (Joy Up-Down-Left-Right) + CONTROL (Joy Button 1) + ALT or SHIFT (Joy Button 2). This is useful especially when playing games made for the Amstrad GX-4000 (or any game actually), without learning which keys is required to play the game etc.

Keyboard compatibility

Please take note that PCs behaves poorly with more than 2 keys pressed simultaneously. It depends of the keyboard quality, some keyboards dedicated to gaming may bring better results.

Shortcuts

Those are accessible in both windowed and fullscreen modes. Please take note the icons are listed in order of appeareance in the toolbar:

F1 ... Open Any File...
F2 ... Open Any File in Library...
F3 ... Toggle Virtual Joystick
F4 ... Toggle Audio
F5 ... Reset Emulation
F6 ... Pause Emulation
F7 ... Load Snapshot
F7 ... Save Snapshot
F9 ... Show Debugger
F10 .. Force 1:1 pixel ratio
F11 .. Toggle Fullscreen
F12 .. Save screenshot

Hot reloading

The emulator reloads automatically inserted files (disks, cartridge files and memory snapshots) when their content gets overwritten physically on disk. This is handy for developers relying on toolchains generating disc images etc.

Library window

User can access this feature by clicking “Open Any File in Library…”.

User will have to select a folder on the file system.

Once done, cpcec-gtk will automatically search recursively from that location for known image file formats. The list of found files are displayed.

Then, the user can filter the view by file extension, and/or by typing few characters composing a folder name or a game name. Then, the user can select the software and click the open button (or simply navigate with tab / arrow keys / open the file through Return key).

Debugger

This section is reserved for advanced users only.

When the emulation gets paused, several windows composing a debugger gets presented to the user.

In all the debugger windows (also including the main window):

• pressing the esc key will close all the debugger windows and continue emulation
• pressing the space key will increment PC to the next Z80 instruction.

Z80 Debugger

It basically tries to mimic the workflow from WinAPE (http://www.winape.net/), an excellent emulator that is unfortunately not available natively for Linux.

Main features:

• the ability to set breakpoints (shortcut: B key)
• the ability to reset the NOPs counter (shortcut: T key)
• the ability to go to next instruction (shrotcut: space key)
• the ability to navigate to any other location in memory
• symbols are supported (see dedicated section below)
• user can move the mouse onto any values and the debugger will try to display all possible conversions
• user can scroll up/down through the disassembled code
• all Z80 registers are displayed
• a simple memory monitor is available
• not exactly related to the Z80, but the current ROM/RAM configuration (GateArray/ASIC) is displayed at the bottom of the window. Take note that ROM labels are displayed when available.
• at any time, user can enter a different address to disassemble or inspect memory
• ED FF opcode supported to pause emulation and open debugger (cf. breakpoint)

Symbol files

This window is available through the Main Window's menu.

A symbol allows to associate a label with an address. Those labels are then displayed into the Z80 source code disassembly.

The only supported file format for symbols are the ones produced by the highly-recommended rasm assembler from Roudoudou (https://github.com/EdouardBERGE/rasm).

2 types of symbols are supported:

• label symbols (option -sz in rasm): the one that helps documenting the Z80 disassembly code
• ROM labels (option -er in rasm): the one that allows to give a name to any ROMs. This is particularly useful when programming an Amstrad GX-4000 program cartridge (that rely on multiple ROMs).

Video display

It displays information about the CRTC (video chip), the Gate Array (palette) and some helpers regarding scanline positionning.

Information is presented in a convenient way for any developers willing to observe behavior implemented while “racing the (canon) beam”.

Mode is the current video mode. VMA means “Video Memory Address”.

Please take note that both CRTC Line and Monitor Scanline fields are interactive. A programmer can enter any valid values, and then presses onto the corresponding “Arrow Down” button: then emulator will then continue till the said CRTC line/Monitor scanline gets reached.

ASIC window

This window is displayed only when Amstrad Plus or GX-4000 model is selected.

From there, you get access to all important ASIC registers.

Many contextual informations (such as sprite preview, address of the current register, special bit description for SSCR ..) are displayed as a tooltip, so feel free to move the mouse cursor over the presented values.

Conclusion

We hope you will appreciate this emulator. The Amstrad is a wonderful machine, probably the best one of its generation.

To send us your feature requests and bug reports, please feel free to contact us through our dedicated websites or the cpcwiki forum.