Commodore 64

The Commodore 64 is the classic 8-bit home computer. Our C64 projects are 6502 assembly, assembled by ACME into a .prg file and tested in the VICE emulator (x64sc).

ACME: https://sourceforge.net/projects/acme-crossass/ VICE: https://vice-emu.sourceforge.io Tools repository: https://git.teletypegames.org/build/c64-tools Projects built with this toolchain: Teletype Games C64 Demo, Rabbit Scooter — C64, Blessing of Ra

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
├── defs.asm
├── common.asm
├── 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	`x64sc`
`SRC`	Entry point	`main.asm`
`TARGET`	Output program	`$(PROJECT).prg`
`METADATA`	Metadata file	`metadata.json`

metadata.json

JSON

{
  "name": "example",
  "title": "Example C64 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
make clear       # remove the .prg and CI artifacts
make rebuild     # clear + build
make rebuildrun  # clear + build + run

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 x64sc from VICE for run.

Example Makefile: https://git.teletypegames.org/build/c64-tools/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_templates/c64.yaml.erb).

The repo needs three things:

YAML

# .woodpecker.yaml
platform: c64
name: rabbit   # 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_platforms config. Preview the served pipeline:

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

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 `c64-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=c64`

Result

The server reads the uploaded metadata, creates or updates the catalog entry, and registers the .prg as the downloadable cartridge of the release.