Commodore Plus/4

The Commodore Plus/4 is the 264-series 8-bit home computer: a 7501/8501 CPU with the 6502 instruction set, the TED chip for video and sound, 64 KB of RAM. Our Plus/4 projects are 6502 assembly, assembled by ACME into a .prg file and tested in the VICE emulator (xplus4) — the same toolchain as the Commodore 64, only the machine differs.

ACME: https://sourceforge.net/projects/acme-crossass/ VICE: https://vice-emu.sourceforge.io Tools repository: https://git.teletypegames.org/build/plus4-build Projects built with this toolchain: plus4-demo

What differs from the C64

	C64	Plus/4
BASIC start / `* =` origin	`$0801`	`$1001`
Entry point after a minimal SYS stub	`$0810` (`SYS 2064`)	`$100D` (`SYS 4109`)
Screen RAM	`$0400`	`$0C00`
Colour RAM	`$D800` (hue only)	`$0800` (`luminance << 4 \\| hue`, bit 7 flashes)
Video chip	VIC-II (`$D000`)	TED (`$FF00`–`$FF3F`): `$FF15` background, `$FF19` border, `$FF1D`/`$FF1C` raster line
Sound	SID	TED, two voices
Keyboard	CIA1 (`$DC00`/`$DC01`)	`$FD30` column select + `$FF08` row latch
Emulator	`x64sc`	`xplus4`

The KERNAL jump table is compatible ($FFD2 CHROUT, $FFE4 GETIN), so the exit path of a program looks the same on both machines. ACME needs no special mode: !cpu 6502 covers the 7501/8501.

One ACME habit worth knowing for both machines: !scr maps lowercase ASCII to the uppercase screen codes of the default character set. Write !scr "teletype games" to get TELETYPE GAMES on screen; uppercase source text comes out as graphics symbols.

Makefile

All .asm files live in the project root. main.asm is the single entry point and !src-includes the rest.

TEXT

project-root/
├── main.asm          # entry point, includes the others
├── metadata.json     # catalog metadata + version
├── Makefile
└── README.md

Variables

Variable	Description	Default
`PROJECT`	Name used in artifacts and the catalog	—
`ASM`	Assembler binary	`acme`
`EMU`	Emulator binary	`xplus4`
`SRC`	Entry point	`main.asm`
`TARGET`	Output program	`$(PROJECT).prg`
`METADATA`	Metadata file	`metadata.json`

metadata.json

JSON

{
  "name": "example",
  "title": "Example Plus/4 Game",
  "author": "Teletype Games",
  "desc": "Short description of the game.",
  "site": "https://git.teletypegames.org/games/example",
  "license": "MIT",
  "version": "1.0.0"
}

name must match PROJECT. version drives the pipeline's version step. The rest goes into the game catalog.

Targets

make deps        # brew install acme vice (macOS only)
make build       # assemble main.asm -> <project>.prg, only when an .asm changed
make run         # build, then launch in VICE (xplus4)
make clear       # remove the .prg and CI artifacts
make rebuild     # clear + build
make rebuildrun  # clear + build + run

Headless smoke test

VICE can run a build for a few emulated seconds and leave a screenshot behind, which is enough to see that a title screen comes up:

xplus4 +sound -warp -limitcycles 30000000 -exitscreenshot shot.png -autostartprgmode 1 <project>.prg

VS Code

Copy example-tasks.json to .vscode/tasks.json. It wraps the same targets, with build as the default build task (Cmd+Shift+B).

Generated artifacts

File	Description
`<project>.prg`	The assembled program
`<project>-<version>.prg`	Versioned release copy (CI)
`<project>-<version>.metadata.json`	Versioned metadata (CI)

Requirements

Local only: make, acme, and xplus4 from VICE for run.

Example Makefile: https://git.teletypegames.org/build/plus4-build/src/branch/master/example-makefile.make

Pipeline

The pipeline is not in the game repo. Woodpecker asks the update server, and WarpEngine serves the whole config from /build/config (template lib/warp_engine/ci/woodpecker/platforms/plus4/pipeline.yaml.erb). WarpEngine knows the platform as plus4 since 0.10.1.

The repo needs three things:

YAML

# .woodpecker.yaml
platform: plus4
name: mygame   # only when the software name differs from the repo name

metadata.json
the application_token Woodpecker secret: a WarpEngine ApplicationToken with update + upload scopes

The builder and the player image come from the update server's CI adapter config (platforms: in the WarpEngine initializer). Preview the served pipeline:

curl "https://teletypegames.org/build/config?platform=plus4"

Steps

Step	What it does
1. version	the engine's shared step (since WarpEngine 1.7): the version from `metadata.json`; on a tag a version tag has to match it; outside the repo's default branch and on a `dev-<branch>` tag `dev-<version>-<branch>`, with no version `dev-<commit>`; write `.version`
2. build	assemble with ACME in the `plus4-builder` image, producing `<project>-<version>.prg` and `<project>-<version>.metadata.json`
3. package	on the tag only: `commodore-pack plus4` in the `commodore-player` image: `<project>-<version>.html.zip` (EmulatorJS page with the self-hosted `vice_xplus4` core), plus `-linux-x64.zip`, `-win-x64.zip` and `-mac-arm64.zip` (yapeSDL with a launcher that sets the machine type and autostarts the `.prg`)
4. upload	on the tag only: `POST /build/upload` for the `.prg`, the metadata and the players that were built (all six files when packaging succeeded), `X-Update-Secret` header
5. publish	on the tag only: `POST /build/publish?platform=plus4`
6. tag	the engine's shared step (since WarpEngine 1.9), after a push only: a new version in the source gets its `v<version>` tag, whose pipeline runs the steps marked on the tag only; a version tagged already releases nothing; a dev build moves the branch's `dev-<branch>` tag onto the commit, so the newest dev build is published. See Versions and releases on the WarpEngine page

Raising the version is the release: a push builds and tags, and the tag's pipeline uploads and publishes (WarpEngine 1.9). A push that leaves the version as it is only builds.

Result

The server reads the uploaded metadata, creates or updates the catalog entry, and registers five assets on the release: the .prg as the downloadable cartridge, the EmulatorJS page as the web-playable build (the catalog's "Play in browser" button, served from /file/<name>-<version>/), and the three yapeSDL bundles as the Linux, Windows and macOS downloads. Since WarpEngine 0.11 the two Commodore platforms expect the same asset kinds; earlier releases carry only the cartridge until they are rebuilt.

Since WarpEngine 1.7 the .prg of every public Plus/4 title's latest release is also on the Plus/4 shelf, under a name without a version and with an INDEX.TXT: ftp://ftp.teletypegames.org/PLUS4 and http://archive.teletypegames.org/PLUS4.

Demo project

plus4-demo — the Teletype Games title card: a gold colour wash across the title driven by the TED raster beam, a blinking prompt, and a clean return to BASIC on any key. The Plus/4 sibling of the C64 Demo.