plus4-build/README.md

plus4-build

CI/CD templates for Commodore Plus/4 (ACME + VICE) game projects, in the same spirit as c64-tools: the Plus/4 shares the C64's 6502 core, so the toolchain is the same ACME assembler — only the emulator (xplus4), the load address ($1001) and the TED registers differ.

• example-makefile.make — project Makefile: local dev targets (deps, build, run, clear, rebuild, rebuildrun).
• example-woodpecker.yaml — a one-line marker (platform: plus4): the full pipeline (version → build → artifact → publish) is served by the update server's Woodpecker configuration extension — preview it with curl "https://teletypegames.org/build/config?platform=plus4".
• example-metadata.json — catalog metadata; the version field drives the pipeline's version step, the rest (name, title, author, desc, site, repo, license) is what WarpEngine::Platforms::Plus4::Service writes into the DB (site becomes the "Source Code", repo the "Repository" external link).
• example-tasks.json — VS Code .vscode/tasks.json wrapping the local make targets.

Usage in a game repo

1. Copy example-makefile.make to Makefile, set PROJECT (and TARGET if the .prg name differs from $(PROJECT).prg).
2. Copy example-metadata.json to metadata.json and fill it in; name must match PROJECT.
3. Copy example-woodpecker.yaml to .woodpecker.yaml (a one-line marker — the pipeline itself is served by the update server; add name: when the software name differs from the repo name) and add the application_token secret in Woodpecker (an ApplicationToken with the update + upload scopes, created in the admin).
4. Copy example-tasks.json to .vscode/tasks.json.

Plus/4 specifics

• A BASIC program starts at $1001 (the C64's is $0801), so the SYS stub and the * = origin differ; the entry point after a minimal stub is $100D (SYS 4109).
• Screen RAM is at $0C00, colour RAM at $0800; a colour byte is luminance << 4 | hue (bit 7 flashes).
• Video is the TED at $FF00–$FF3F ($FF15 background, $FF19 border, $FF1D/$FF1C raster line); there is no VIC-II, no SID and no CIA.
• The KERNAL jump table is compatible ($FFD2 CHROUT, $FFE4 GETIN).

Builder image

builder.Dockerfile bakes the pipeline's build-step dependencies (ACME assembler + make) into git.teletypegames.org/build/plus4-builder, so the build step does not run apt-get on every run (VICE is a local-dev tool only and is not included):

docker build --platform linux/amd64 -f builder.Dockerfile \
  -t git.teletypegames.org/build/plus4-builder:latest .
docker push git.teletypegames.org/build/plus4-builder:latest

The served pipeline uploads $(PROJECT)-$(VERSION).prg and $(PROJECT)-$(VERSION).metadata.json via /build/upload, then triggers /build/publish?platform=plus4&name=$(PROJECT)&version=$(VERSION), which creates/updates the Software row and a Release with cartridge_path.