TITLE=Commodore Plus/4
ROUTE=/platforms/plus4
LOCALE=en
MODIFIED=1792409344
URL=https://wiki.teletypegames.org/platforms/plus4
L=1 #57
L=2 https://git.teletypegames.org/demos/plus4-demo

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 
bACME
0 into a 
c.prg
0 file and
tested in the 
bVICE
0 emulator (
cxplus4
0) — the same toolchain as the 1Commodore 64,
only the machine differs.


bACME:
0 https://sourceforge.net/projects/acme-crossass/ 
bVICE:
https://vice-emu.sourceforge.io 
bTools repository
0:
https://git.teletypegames.org/build/plus4-build 
bProjects built with this

btoolchain:
0 2plus4-demo


r──────────────────────────────────────────────────────────────────────────────


1What differs from the C64

1═════════════════════════


t┌───────────────────────────┬────────────────────┬───────────────────────────┐

t│
h                           
t│
h C64                
t│
h Plus/4                    
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 BASIC start / 
c* =
0 origin  
t│
0 
c$0801
0              
t│
0 
c$1001
0                     
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Entry point after a       
t│
0 
c$0810
0 (
cSYS 2064
0)   
t│
0 
c$100D
0 (
cSYS 4109
0)          
t│

t│
0 minimal SYS stub          
t│
0                    
t│
0                           
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Screen RAM                
t│
0 
c$0400
0              
t│
0 
c$0C00
0                     
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Colour RAM                
t│
0 
c$D800
0 (hue only)   
t│
0 
c$0800
0 (
cluminance << 4 \|
0  
t│

t│
0                           
t│
0                    
t│
0 
chue
0, bit 7 flashes)       
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Video chip                
t│
0 VIC-II (
c$D000
0)     
t│
0 TED (
c$FF00
0–
c$FF3F
0): 
c$FF15
0  
t│

t│
0                           
t│
0                    
t│
0 background, 
c$FF19
0 border, 
t│

t│
0                           
t│
0                    
t│
0 
c$FF1D
0/
c$FF1C
0 raster line   
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Sound                     
t│
0 SID                
t│
0 TED, two voices           
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Keyboard                  
t│
0 CIA1 (
c$DC00
0/
c$DC01
0) 
t│
0 
c$FD30
0 column select +     
t│

t│
0                           
t│
0                    
t│
0 
c$FF08
0 row latch           
t│

t├───────────────────────────┼────────────────────┼───────────────────────────┤

t│
0 Emulator                  
t│
0 
cx64sc
0              
t│
0 
cxplus4
0                    
t│

t└───────────────────────────┴────────────────────┴───────────────────────────┘

The KERNAL jump table is compatible (
c$FFD2
0 CHROUT, 
c$FFE4
0 GETIN), so the exit
path of a program looks the same on both machines. ACME needs no special mode:

c!cpu 6502
0 covers the 7501/8501.

One ACME habit worth knowing for both machines: 
c!scr
0 maps 
ilowercase
0 ASCII to
the uppercase screen codes of the default character set. Write 
c!scr "teletype

cgames"
0 to get 
cTELETYPE GAMES
0 on screen; uppercase source text comes out as
graphics symbols.


r──────────────────────────────────────────────────────────────────────────────


1Makefile

1════════

All 
c.asm
0 files live in the project root. 
cmain.asm
0 is the single entry point
and 
c!src
0-includes the rest.


p project-root/                                                                

p ├── main.asm          # entry point, includes the others                     

p ├── metadata.json     # catalog metadata + version                           

p ├── Makefile                                                                 

p └── README.md                                                                


2Variables

2─────────


t┌──────────┬────────────────────────────────────────┬────────────────┐

t│
h Variable 
t│
h Description                            
t│
h Default        
t│

t├──────────┼────────────────────────────────────────┼────────────────┤

t│
0 
cPROJECT
0  
t│
0 Name used in artifacts and the catalog 
t│
0 —              
t│

t│
0 
cASM
0      
t│
0 Assembler binary                       
t│
0 
cacme
0           
t│

t│
0 
cEMU
0      
t│
0 Emulator binary                        
t│
0 
cxplus4
0         
t│

t│
0 
cSRC
0      
t│
0 Entry point                            
t│
0 
cmain.asm
0       
t│

t│
0 
cTARGET
0   
t│
0 Output program                         
t│
0 
c$(PROJECT).prg
0 
t│

t│
0 
cMETADATA
0 
t│
0 Metadata file                          
t│
0 
cmetadata.json
0  
t│

t└──────────┴────────────────────────────────────────┴────────────────┘


2metadata.json

2─────────────


p {                                                                            

p   "name": "example",                                                         

p   "title": "Example Plus/4 Game",                                            

p   "author": "Teletype Games",                                                

p   "desc": "Short description of the game.",                                  

p   "site": "https://git.teletypegames.org/games/example",                     

p   "license": "MIT",                                                          

p   "version": "1.0.0"                                                         

p }                                                                            


cname
0 
bmust match
0 
cPROJECT
0. 
cversion
0 drives the pipeline's version step. The rest
goes into the game catalog.


2Targets

2───────


p make deps        # brew install acme vice (macOS only)                       

p make build       # assemble main.asm -> <project>.prg, only when an .asm cha»

p nged                                                                         

p make run         # build, then launch in VICE (xplus4)                       

p make clear       # remove the .prg and CI artifacts                          

p make rebuild     # clear + build                                             

p make rebuildrun  # clear + build + run                                       


2Headless smoke test

2───────────────────

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:


p xplus4 +sound -warp -limitcycles 30000000 -exitscreenshot shot.png -autostar»

p tprgmode 1 <project>.prg                                                     


2VS Code

2───────

Copy 
cexample-tasks.json
0 to 
c.vscode/tasks.json
0. It wraps the same targets, with

cbuild
0 as the default build task (
cCmd+Shift+B
0).


2Generated artifacts

2───────────────────


t┌───────────────────────────────────┬─────────────────────────────┐

t│
h File                              
t│
h Description                 
t│

t├───────────────────────────────────┼─────────────────────────────┤

t│
0 
c<project>.prg
0                     
t│
0 The assembled program       
t│

t│
0 
c<project>-<version>.prg
0           
t│
0 Versioned release copy (CI) 
t│

t│
0 
c<project>-<version>.metadata.json
0 
t│
0 Versioned metadata (CI)     
t│

t└───────────────────────────────────┴─────────────────────────────┘


2Requirements

2────────────

Local only: 
cmake
0, 
cacme
0, and 
cxplus4
0 from VICE for 
crun
0.

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


r──────────────────────────────────────────────────────────────────────────────


1Pipeline

1════════

The pipeline is not in the game repo. Woodpecker asks the update server, and
WarpEngine serves the whole config from 
c/build/config
0 (template

clib/warp_engine/ci/woodpecker/platforms/plus4/pipeline.yaml.erb
0). WarpEngine
knows the platform as 
cplus4
0 since 0.10.1.

The repo needs three things:


p # .woodpecker.yaml                                                           

p platform: plus4                                                              

p name: mygame   # only when the software name differs from the repo name      

• 
cmetadata.json
• the 
capplication_token
0 Woodpecker secret: a WarpEngine ApplicationToken with
  
cupdate
0 + 
cupload
0 scopes

The builder and the player image come from the update server's CI adapter
config (
cplatforms:
0 in the WarpEngine initializer). Preview the served
pipeline:


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


2Steps

2─────


t┌─────────────┬──────────────────────────────────────────────────────────────┐

t│
h Step        
t│
h What it does                                                 
t│

t├─────────────┼──────────────────────────────────────────────────────────────┤

t│
0 1. version  
t│
0 read the version from 
cmetadata.json
0, add the branch name on  
t│

t│
0             
t│
0 development branches, write 
c.version
0                         
t│

t├─────────────┼──────────────────────────────────────────────────────────────┤

t│
0 2. build    
t│
0 assemble with ACME in the 
cplus4-builder
0 image, producing     
t│

t│
0             
t│
0 
c<project>-<version>.prg
0 and                                  
t│

t│
0             
t│
0 
c<project>-<version>.metadata.json
0                            
t│

t├─────────────┼──────────────────────────────────────────────────────────────┤

t│
0 3. package  
t│
0 
ccommodore-pack plus4
0 in the 
ccommodore-player
0 image:          
t│

t│
0             
t│
0 
c<project>-<version>.html.zip
0 (EmulatorJS page with the       
t│

t│
0             
t│
0 self-hosted 
cvice_xplus4
0 core), plus 
c-linux-x64.zip
0,          
t│

t│
0             
t│
0 
c-win-x64.zip
0 and 
c-mac-universal.zip
0 (yapeSDL with a launcher 
t│

t│
0             
t│
0 that sets the machine type and autostarts the 
c.prg
0)          
t│

t├─────────────┼──────────────────────────────────────────────────────────────┤

t│
0 4. artifact 
t│
0 
cPOST /build/upload
0 for all six files, 
cX-Update-Secret
0 header 
t│

t├─────────────┼──────────────────────────────────────────────────────────────┤

t│
0 5. publish  
t│
0 
cPOST /build/publish?platform=plus4
0                           
t│

t└─────────────┴──────────────────────────────────────────────────────────────┘


2Result

2──────

The server reads the uploaded metadata, creates or updates the catalog entry,
and registers five assets on the release: the 
c.prg
0 as the downloadable
cartridge, the EmulatorJS page as the web-playable build (the catalog's "Play
in browser" button, served from 
c/file/<name>-<version>/
0), and the three
yapeSDL bundles as the Linux, Windows and macOS downloads. Since WarpEngine
0.11 the two Commodore platforms expect the same asset kinds; earlier releases
carry only the cartridge until they are rebuilt.


2Demo project

2────────────

2plus4-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.