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 és a player image az update szerver CI-adapter konfigurációjából jön (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	az engine közös lépése (a WarpEngine 1.7 óta): a verzió a `metadata.json`-ból; tagnél a verziótagnek egyeznie kell vele; a repó alapágán kívül és egy `dev-<ág>` tagen `dev-<verzió>-<ág>`, verzió nélkül `dev-<commit>`; 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. package	csak tagre: `commodore-pack plus4` a `commodore-player` image-ben: `<project>-<verzió>.html.zip` (EmulatorJS-oldal a saját mappából kiszolgált `vice_xplus4` core-ral), valamint `-linux-x64.zip`, `-win-x64.zip` és `-mac-arm64.zip` (yapeSDL egy indítóval, amely beállítja a géptípust és elindítja a `.prg`-t)
4. upload	csak tagre: `POST /build/upload` a `.prg`-re, a metaadatra és az elkészült lejátszókra (sikeres csomagolásnál mind a hat fájlra), `X-Update-Secret` fejléccel
5. publish	csak tagre: `POST /build/publish?platform=plus4`
6. tag	az engine közös lépése (a WarpEngine 1.9 óta), csak push után: a forrás új verziója megkapja a `v<verzió>` tagjét, és annak pipeline-ja futtatja a csak tagre jelölt lépéseket; egy már tagelt verzió nem ad ki semmit; egy dev build az ág `dev-<ág>` tagjét a commitra helyezi, így mindig a legfrissebb dev build van kiadva. Lásd: Verziók és kiadások a WarpEngine oldalon

A verzió emelése maga a kiadás: a push buildel és tagel, a tag pipeline-ja tölt fel és publikál (WarpEngine 1.9). Egy push, amely nem emeli a verziót, csak buildel.

Eredmény

A szerver beolvassa a feltöltött metaadatot, létrehozza vagy frissíti a katalógusbejegyzést, és öt assetet regisztrál a kiadáson: a .prg-t letölthető kazettaként, az EmulatorJS-oldalt böngészőben futtatható buildként (a katalógus „Játék böngészőben” gombja, a /file/<név>-<verzió>/ alól kiszolgálva), a három yapeSDL-csomagot pedig linuxos, windowsos és macOS-es letöltésként. A WarpEngine 0.11-től a két Commodore-platform ugyanazokat az assetfajtákat várja; a korábbi kiadásokon újraépítésig csak a kazetta van.

A WarpEngine 1.7 óta minden nyilvános Plus/4-cím legfrissebb kiadásának .prg-je a Plus/4-polcon is ott van, verzió nélküli néven, egy INDEX.TXT-vel: ftp://ftp.teletypegames.org/PLUS4 és http://archive.teletypegames.org/PLUS4.

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.