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

Builder images 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	read the version from `metadata.json`, add the branch name on development branches, write `.version`
2. build	assemble with ACME in the `plus4-builder` image, producing `<project>-<version>.prg` and `<project>-<version>.metadata.json`
3. artifact	`POST /build/upload` for both files, `X-Update-Secret` header
4. publish	`POST /build/publish?platform=plus4`

Result

The server reads the uploaded metadata, creates or updates the catalog entry, and registers the .prg as the downloadable cartridge of the release. Plus/4 releases are download-only: the engine rejects a web-playable (html) asset on them, as it does for the C64.

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.