JAMSI // Documentation

Documentation

JavaScript Amstrad CPC / Plus / GX4000 & ZX Spectrum Emulator — features, URL parameters, usage

1 Overview 2 Quick start 3 URL parameters 4 system values 5 Media & formats 6 Drag & drop 7 Virtual keyboard 8 Controls & shortcuts 9 Modes (kiosk / embedded) 10 Debugger 11 File layout 12 Integration (iframe) 13 Themes 14 Notes

1 · Overview

JAMSI (JavaScript Amstrad Machine System Interface) emulates in the browser:

Amstrad CPC 464 / 664 / 6128 (classic models, firmware ROMs)
Amstrad Plus (464 Plus / 6128 Plus) and GX4000 (cartridge console, gamepad only)
ZX Spectrum (48K / 128K / +3)

The page runs through index.php (PHP server — URL parameters are validated server-side). Requires PHP 7.4 or newer.

2 · Quick start

index.php                                  → GX4000, cartridge selection
index.php?system=6128                       → boot a CPC 6128
index.php?cpr=klax.bin                      → GX4000 + cartridge from assets/games
index.php?system=cpc6128&file=dsk/game.dsk&input=RUN%22DISK%22
index.php?system=464&file=cdt/tape.cdt&input=RUN%22!%22
index.php?system=spectrum48k                → ZX Spectrum 48K
index.php?gui=false&cpr=klax.bin            → kiosk (monitor only)
index.php?embedded=true&system=6128         → iframe-friendly, no GUI

3 · URL parameters

Parameter	Example	Effect
`system`	`?system=cpc6128`	Boots the selected machine (values below).
`cpr`	`?cpr=barbarian2.bin`	Starts a cartridge directly from `assets/games/` (forces GX4000).
`file`	`?file=dsk/game.dsk`	Inserts a medium from `assets/`: disk (DSK/EDSK → drive A) or tape (CDT/TZX/TAP → cassette).
`input`	`?input=RUN"DISK"`	Types the text ~3 s after boot and presses Enter. `?input=true` presses Enter only. Literal `\n` = Enter, `\t` = Tab.
`joystick`	`?joystick=false`	Enables/disables the joystick key mapping (`true`/`false`/`1`/`0`).
`gui`	`?gui=false`	Minimal mode: only the `.monitor` section (kiosk / game screen), with mini buttons top-right.
`keyboard`	`?keyboard=true`	Shows the virtual keyboard under the monitor (CPC or ZX layout; GX4000 has none).
`embedded`	`?embedded=true`	No GUI at all — the display scales to the browser window (iframe-friendly).

input details

Quotes: raw (RUN"DISK") or percent-encoded (RUN%22DISK%22) — both work.
input=true (also 1/on/yes): presses only Enter after boot.
Multi-line: a literal \n in the value is typed as Enter — survives link sharing better than %0A (which some messengers strip). Example: input=RUN"DISK"\nCAT.
Autotype lock: while typing, all external keyboard input is ignored (and the virtual keyboard is locked) so the typed command is never disturbed. Afterwards everything is free again.

4 · system values

Case-insensitive. Short forms are supported.

URL value	Machine
`gx4000`	GX4000 (cartridge console)
`plus464` / `464plus`	464 Plus
`plus464fd1` / `464plusfd1`	464 Plus + Floppy
`plus6128` / `6128plus`	6128 Plus
`cpc464` / `464`	CPC 464 (Tape)
`cpc464fd1` / `464fd1`	CPC 464 + Floppy (FD-1)
`cpc664` / `664`	CPC 664
`cpc6128` / `6128`	CPC 6128
`spectrum48k` / `48k`	ZX Spectrum 48K
`spectrum128k` / `128k`	ZX Spectrum 128K
`spectrumplus3` / `plus3`	ZX Spectrum +3

Note: Without system, a sensible machine is chosen automatically when file/input is used: disk → CPC 6128 (floppy + AMSDOS), tape → CPC 464 (the classic tape machine). For disks on a 464 use the + Floppy variants: ?system=464fd1&file=dsk/… or ?system=464plusfd1.

5 · Media & formats

Format	Extension	Where / How
Cartridge	`.cpr`	Official cartridge format — via `?cpr=`, cartridge menu or drag&drop. Starts GX4000 emulation.
Snapshot	`.sna`	Load CPC/Plus snapshots (Type 3) via button or drag&drop. Save via “Save SNA”.
Disk	`.dsk` / `.edsk`	Place in `assets/dsk/`; use `?file=dsk/…`, the button or drag&drop → drive A (B separately).
Tape	`.cdt` / `.tzx` / `.tap`	Place in `assets/cdt/`; use `?file=cdt/…`, the button or drag&drop → cassette.
Internal	`.bin`	Internal raw format for `assets/games/` (library + `?cpr=`). Rejected on drop — please use `.cpr`.

Tape start: On the CPC, RUN"!" (or the loader the tape expects) starts the tape via the firmware’s motor relay. On the ZX Spectrum playback starts automatically, so LOAD "" works directly.

6 · Drag & drop

Drag a media file onto the page — an overlay (DROP MEDIA) appears while dragging: CPR, SNA, DSK/EDSK (→ drive A), CDT/TZX/TAP (→ cassette). Unknown types and .bin are rejected with a clear status message. Works in kiosk and embedded mode as well as inside an iframe.

7 · Virtual keyboard

Show it via ?keyboard=true, the Virtual Keyboard button in the control deck, or the ⌨ icon in minimal mode. The matching layout appears under the monitor: CPC (except GX4000 — that one has only a gamepad) or ZX Spectrum.

Sticky modifiers: SHIFT, CONTROL, CAPS LOCK (CPC) and CAPS SHIFT, SYMB SHIFT (ZX) latch on click (visible, amber) — since you cannot click two keys at once with a mouse. While latched, the modifier is sent with every further key press (e.g. SHIFT + 1 = !, SYMB SHIFT + R = <).
The keys are wired directly to the emulator matrix (joystick-mapped keys like Space/cursors are sent as real matrix keys).
The virtual keyboard is locked during the URL autotype.

8 · Controls & shortcuts

Action	Input
Focus the display	Click the picture
Toggle fullscreen	`ALT + Enter` or the Fullscreen button
Joystick (CPC/GX4000)	Cursor keys + `Space`/`X` (fire), optional `Ctrl`
Reset	Reset Console button or click POWER (in minimal mode)
Rewind	Rewind button or ⏪ icon: click = one step back, press and hold = continuous visible scrubbing (one drawn frame between steps); recording pauses while scrubbing
Audio	The first click/keypress enables Web Audio; a subtle “Click for audio” hint appears in the display when started via URL
CRT effects	CRT Display toggle (off by default, per session)

9 · Modes

Normal

Full interface: cartridge library, media buttons, system settings, status bar.

Kiosk — `?gui=false`

Only the .monitor section, centered on black. Two subtle icons float top-right: ⌨ (toggle virtual keyboard) and ⛶ (fullscreen). POWER acts as reset. Scrolls cleanly when monitor + keyboard are taller than the viewport.

Embedded — `?embedded=true`

No GUI at all (also no mini buttons / keyboard). The display fills the browser window and the canvas is fitted like in fullscreen (aspect ratio preserved, centered, nothing cut). Ideal for iframe embedding.

10 · Debugger

The Debugger (button in the control deck) offers: RUN / STOP / STEP / Step Over, breakpoints (click a disassembly line), search (bytes or mnemonics), registers, stack, editable memory hexdump, memory mapper and a CPC BASIC debugger.

CPC: full feature set incl. the BASIC debugger tab (listing, trace, break @ line).
ZX Spectrum: RUN/STOP/STEP/breakpoints work; the BASIC tab is hidden (CPC-BASIC-specific), the system panel shows ULA/paging info and the memory viewer + mapper show the ZX RAM banks (8 × 16K).
The hexdump and disassembler show many lines with a scrollbar; the mouse wheel scrolls and navigates at the edges.

11 · File layout

assets/
  games/   cartridge images (.bin / .cpr) for the library and ?cpr=
  roms/    firmware ROMs (CPC OS/BASIC/AMSDOS, ZX ROMs)
  dsk/     disk images (.dsk / .edsk)  → ?file=dsk/…
  cdt/     tape images (.cdt / .tzx / .tap) → ?file=cdt/…
index.php       Single entry point (page + server-side parameter validation)
docs.php        Documentation
src/jamsi_app.js      Main logic (emulator binding, boot config, drag & drop, …)
src/jamsi_vkb.js      Virtual keyboard (CPC/ZX layouts)

12 · Integration (iframe)

<iframe src="https://your-server/jamsi/index.php?embedded=true&system=6128&cpr=klax.bin"
        style="width:100%;height:100%;border:0"></iframe>

The embedded mode scales the display automatically to the iframe size (also on resize). All URL parameters can be combined, e.g.:

index.php?embedded=true&system=cpc6128&file=dsk/game.dsk&input=RUN%22DISK%22&joystick=true

Live example

The iframe below embeds the emulator at exactly 384 × 272 px (half of the 768 × 544 canvas, same aspect ratio) — a GX4000 running Navy Seals via ?embedded=true&cpr=navyseals.bin:

<iframe src="index.php?embedded=true&cpr=navyseals.bin"
        style="width:384px;height:272px;border:0"></iframe>

Note: embedded=true is validated and injected server-side by index.php. The embedded iframe must be served from the same origin as the emulator files; in the preview sandbox of this page it may be blocked, but it works on your server.

13 · Themes

JAMSI ships with three themes, configured in settings.php (registry + default). The active theme is stored in a persistent cookie (1 year) and can be set via ?theme=:

Theme	Look
`jamsi`	JAMSI Dark (default) — the classic dark design
`classic`	Classic CPC — light beige Amstrad look
`amber`	Amber Terminal — black / amber monochrome CRT
`ocean`	Ocean — deep blue / aquamarine
`acidwave`	Acidwave — neon synthwave (magenta / cyan)
`retrobeige`	Retro Beige — 80s case beige, dark brown monitor

index.php?theme=amber&system=6128
index.php?theme=classic&cpr=klax.bin
index.php?theme=jamsi&embedded=true&cpr=navyseals.bin

Every theme lives in themes/<name>/ with template.php (page markup, same IDs/classes for app.js) and style.css (stylesheet). The CSS variables --bg/--panel/--text/--muted/--border/--accent/--accent2 are defined in every theme, so this documentation adapts automatically. Add a new theme by adding a folder + an entry in settings.php.

14 · Notes

Fullscreen & audio: The native fullscreen API and Web Audio require a user gesture. In sandboxed environments (e.g. embedded previews) a simulated fullscreen mode shows only the picture.
CRT effects are off by default and are not remembered across sessions (every page load starts pixel-perfect).
PHP required: the whole page is served by index.php (PHP 7.4+). All URL parameters are validated server-side before they reach the emulator.
Security: system is checked against a whitelist; cpr/file do not allow path traversal; input is capped at 500 characters and embedded safely.

← Back to the emulator