Commodore Plus/4

A Commodore Plus/4 a 264-es sorozat 8 bites otthoni számítógépe: 7501/8501-es CPU a 6502 utasításkészletével, a TED chip a képhez és a hanghoz, 64 KB RAM. A Plus/4-es projektjeink 6502 assemblyben készülnek, az ACME fordítja őket .prg fájllá, a tesztelés pedig a VICE emulátorban (xplus4) történik — ugyanaz az eszközlánc, mint a Commodore 64-nél, csak a gép más.

ACME: https://sourceforge.net/projects/acme-crossass/ VICE: https://vice-emu.sourceforge.io Eszközrepó: https://git.teletypegames.org/build/plus4-build Ezzel az eszközlánccal készült projektek: plus4-demo

Mi más, mint a C64-en

	C64	Plus/4
BASIC kezdőcím / `* =` origó	`$0801`	`$1001`
Belépési pont a minimális SYS-stub után	`$0810` (`SYS 2064`)	`$100D` (`SYS 4109`)
Képernyő-RAM	`$0400`	`$0C00`
Szín-RAM	`$D800` (csak árnyalat)	`$0800` (`fényesség << 4 \\| árnyalat`, a 7. bit villog)
Videochip	VIC-II (`$D000`)	TED (`$FF00`–`$FF3F`): `$FF15` háttér, `$FF19` keret, `$FF1D`/`$FF1C` rasztersor
Hang	SID	TED, két hang
Billentyűzet	CIA1 (`$DC00`/`$DC01`)	`$FD30` oszlopválasztás + `$FF08` sor-latch
Emulátor	`x64sc`	`xplus4`

A KERNAL ugrótábla kompatibilis ($FFD2 CHROUT, $FFE4 GETIN), így egy program kilépési útja mindkét gépen ugyanúgy néz ki. Az ACME-nek nem kell külön mód: a !cpu 6502 lefedi a 7501/8501-et.

Egy ACME-szokás, amit mindkét gépen érdemes tudni: a !scr a kisbetűs ASCII-t képezi az alap karakterkészlet nagybetűs screen code-jaira. !scr "teletype games"-t írj, hogy TELETYPE GAMES legyen a képernyőn; a nagybetűs forrásszövegből grafikus jelek lesznek.

Makefile

Minden .asm fájl a projekt gyökerében van. Az egyetlen belépési pont a main.asm, amely !src-cel behúzza a többit.

TEXT

project-root/
├── main.asm          # belépési pont, ez húzza be a többit
├── metadata.json     # katalógus-metaadatok + verzió
├── Makefile
└── README.md

Változók

Változó	Leírás	Alapérték
`PROJECT`	Az artifactokban és a katalógusban használt név	—
`ASM`	Az assembler binárisa	`acme`
`EMU`	Az emulátor binárisa	`xplus4`
`SRC`	Belépési pont	`main.asm`
`TARGET`	Kimeneti program	`$(PROJECT).prg`
`METADATA`	Metaadatfájl	`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"
}

A name értékének egyeznie kell a PROJECT értékével. A version vezérli a pipeline verziólépését. A többi a játékkatalógusba kerül.

Célok

make deps        # brew install acme vice (csak macOS)
make build       # a main.asm fordítása -> <project>.prg, csak ha változott egy .asm
make run         # build, majd indítás a VICE-ban (xplus4)
make clear       # a .prg és a CI-artifactok törlése
make rebuild     # clear + build
make rebuildrun  # clear + build + run

Headless próbafutás

A VICE néhány emulált másodpercig futtatja a buildet, és képernyőképet hagy maga után — ez elég ahhoz, hogy lássuk, feljön-e a címképernyő:

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

VS Code

Másold az example-tasks.json fájlt .vscode/tasks.json néven. Ugyanezeket a célokat csomagolja be, a build az alapértelmezett buildfeladat (Cmd+Shift+B).

Előálló artifactok

Fájl	Leírás
`<project>.prg`	A lefordított program
`<project>-<verzió>.prg`	Verziózott kiadási példány (CI)
`<project>-<verzió>.metadata.json`	Verziózott metaadat (CI)

Követelmények

Csak helyben: make, acme, illetve a run-hoz a VICE xplus4 binárisa.

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

Pipeline

A pipeline nincs benne a játékrepóban. A Woodpecker az update szervertől kéri el, a WarpEngine pedig a teljes konfigurációt a /build/config végponton szolgálja ki (sablon: lib/warp_engine/ci/woodpecker/platforms/plus4/pipeline.yaml.erb). A WarpEngine a 0.10.1-től ismeri a platformot plus4 néven.

A repóhoz három dolog kell:

YAML

# .woodpecker.yaml
platform: plus4
name: mygame   # csak akkor, ha a szoftvernév eltér a repó nevétől

metadata.json
az application_token Woodpecker-secret: egy WarpEngine ApplicationToken az update + upload jogosultságokkal

A builder image-ek az update szerver CI-adapter konfigurációjából jönnek (platforms: a WarpEngine-initializerben). A kiszolgált pipeline megtekintése:

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

Lépések

Lépés	Mit csinál
1. version	kiolvassa a verziót a `metadata.json`-ból, fejlesztői ágakon hozzáfűzi az ág nevét, és megírja a `.version` fájlt
2. build	ACME-vel fordít a `plus4-builder` image-ben, `<project>-<verzió>.prg` és `<project>-<verzió>.metadata.json` fájlokat előállítva
3. artifact	`POST /build/upload` mindkét fájlra, `X-Update-Secret` fejléccel
4. publish	`POST /build/publish?platform=plus4`

Eredmény

A szerver beolvassa a feltöltött metaadatot, létrehozza vagy frissíti a katalógusbejegyzést, és a .prg fájlt regisztrálja a kiadás letölthető kazettájaként. A Plus/4-es kiadások csak letölthetők: a motor elutasítja a böngészőben futtatható (html) assetet rajtuk, ahogy a C64-nél is.

Demóprojekt

plus4-demo — a Teletype Games címkártya: arany színfutás a címen a TED rasztersugarához igazítva, villogó felirat, és tiszta visszatérés a BASIC-be bármelyik billentyűre. A C64 Demo Plus/4-es testvére.