PocketCPC

PocketCPC is an Amstrad CPC core for the Analogue Pocket openFPGA.

Status: early public release. It is hardware-tested and usable, but some features are still incomplete and a few areas remain experimental.

PocketCPC defaults to CPC 6128 and can also switch to CPC 664 or CPC 464 from the Pocket menu. It supports .dsk disks, .cdt tapes, .sna snapshots, and a built-in virtual keyboard with shortcut macros. It is built by adapting MiSTer-devel/Amstrad_MiSTer for CPC machine behaviour and dave18/OpenFPGA_ZX-Spectrum for Analogue Pocket integration.

This project was developed with AI assistance, directed by a human who knows and cares about the Amstrad CPC.

For licensing and provenance details, see LICENSE.md.

Install On Pocket

For a normal install, download the latest release and copy its Assets, Cores, and Platforms folders to the root of the Pocket SD card.

Then place the required ROM bundle here:

/Assets/amstrad/stilvoid.PocketCPC/boot.rom

Optional experimental custom ROM:

/Assets/amstrad/stilvoid.PocketCPC/custom.rom

Optional media goes anywhere under:

/Assets/amstrad/common/

A simple SD-card layout looks like this:

• Assets/amstrad/stilvoid.PocketCPC/boot.rom
• Assets/amstrad/stilvoid.PocketCPC/custom.rom optional, 16 KiB, maps to upper ROM slot 6
• Assets/amstrad/common/disks/*.dsk
• Assets/amstrad/common/tapes/*.cdt
• Assets/amstrad/common/snapshots/*.sna
• Cores/stilvoid.PocketCPC/*
• Platforms/amstrad.json

Required boot.rom

PocketCPC expects the same boot.rom bundle published by the MiSTer Amstrad CPC core project:

• MiSTer Amstrad_MiSTer releases folder
• Direct boot.rom link

Current loader requirements:

• boot.rom must be exactly 0x28000 bytes (160 KiB)
• the file must live at Assets/amstrad/stilvoid.PocketCPC/boot.rom
• the Pocket menu defaults to CPC 6128 and can switch to CPC 664 or CPC 464
• custom.rom is an experimental optional 16 KiB upper ROM mapped to slot 6

See docs/ROM_ASSET_LAYOUT.md for the exact bank layout and rationale.

First Boot And Use

1. Start PocketCPC from openFPGA on the Pocket.
2. If the ROM bundle is valid, the core should boot to the normal CPC startup screen.
3. Open the Pocket menu and go to Core Settings when you want to mount media or restart the core. Entering the Pocket menu pauses the running CPC and leaving the menu resumes it.

Core Settings

The Pocket menu's Core Settings entries do this:

• Machine Model: choose CPC 6128, CPC 664, or CPC 464; changing it resets the core immediately, and it defaults back to CPC 6128 on the next launch CPC 464 follows stock hardware more closely and does not expose the built-in FDC.
• Drive A: mount or change the disk image in drive A
• Drive B: mount or change the disk image in drive B
• Tape: mount or change a tape image
• Snapshot: load a snapshot immediately
• Display Framing: choose Default, Tight, or Overscan
• Activity Indicator: show or hide the disk activity overlay
• Disk Access Sound: enable or disable drive access sound effects
• Stereo Mix: enable or disable the default 25% stereo crossfeed
• Restart Core: reboot the CPC after changing media or settings

custom.rom is an experimental optional upper ROM. It must be exactly 16 KiB, lives at Assets/amstrad/stilvoid.PocketCPC/custom.rom, and is exposed as CPC upper ROM slot 6. Restart the core after adding, removing, or replacing it.

Load software

Typical flow for a disk:

1. Mount a .dsk in Drive A.
2. Return to the CPC screen.
3. Type CAT to list files on the disk.
4. Start a program with RUN"PROGRAM or whatever command that disk expects.

This applies directly to CPC 6128 and CPC 664. In CPC 464 mode, the core follows stock hardware more closely and does not expose the built-in FDC.

Useful CPC disk commands:

• CAT lists files on the current disk
• RUN" loads and starts a program, for example RUN"DISC
• |A and |B switch between disk drives

Typical flow for a tape:

1. Mount a .cdt in Tape.
2. Return to the CPC screen.
3. Type |TAPE to switch to tape mode.
4. Type RUN" to start loading.

Typical flow for a snapshot:

1. Mount a .sna in Snapshot.
2. The snapshot should start immediately.

Default controls

Normal play:

• D-pad: joystick directions
• A: joystick fire 1
• B: joystick fire 2
• X: joystick fire 3
• Y: Escape
• L: Shift
• R: Ctrl
• Select: open virtual keyboard
• Start: currently unbound

Most CPC software expects a one-button joystick. Fire 2 and Fire 3 are extra compatibility mappings and may be ignored by many programs.

Virtual keyboard mode:

• D-pad: move selection
• A: press selected key
• B: Space
• X: Return
• Y: Delete
• L: Shift
• R: next VKB page
• Select: close virtual keyboard
• Start: currently unbound

The VKB includes a shortcut page with one-tap macros for:

• |TAPE + Return
• |DISC + Return
• CAT + Return
• RUN" + Return
• RUN"DISC + Return

Dock USB keyboard support is available through the Analogue Dock, but it is still experimental. Most common typing keys and modifiers work, including COPY on Insert with a Right Alt fallback for compact keyboards. Numpad keys follow the CPC keypad layout, including numpad Enter -> CPC Enter and numpad . -> FDot. On ISO/UK layouts, the #~ key maps to CPC ].

Current Limitations

• Mounted .dsk images should currently be treated as read-only. Write activity is acknowledged so software keeps running, but changes are not persisted back to the image yet.
• Pocket savestates / Memories are not currently supported.
• Tape support works but should still be treated as experimental.
• Snapshot loading is supported, but snapshot saving is not currently exposed as a finished feature.
• There is no finished user-friendly control remapping UI yet.
• Only one experimental custom upper ROM slot is currently exposed, fixed as custom.rom -> slot 6.

Reporting Issues

Please report bugs through GitHub Issues.

The most useful reports include the PocketCPC version or commit tested, whether you were using Pocket or Dock, exact reproduction steps, the media type involved, and any relevant menu or input details.

Developer Notes

If you are here to build or work on the core rather than just use it, start with:

• CONTRIBUTING.md
• AGENTS.md
• docs/DEVELOPER_GUIDE.md
• docs/COMPONENT_MAP.md
• docs/ROM_ASSET_LAYOUT.md
• TODO.md

ROMs And Copyright

Do not commit or redistribute copyrighted Amstrad ROM images unless you are sure you have the right to do so. This repository intentionally does not ship them.

This repository contains a mix of original PocketCPC glue, adapted upstream code, and preserved notices from those upstream sources. Review LICENSE.md and the relevant file headers before redistributing derived work.