c64-basic/README.md

C64 Program Collection

Twenty-three small, polished programs for the Commodore 64, written in stock Commodore BASIC V2 and 6502 machine code. The collection mixes arcade action, puzzles, simulations, creative tools, sound, and visual effects. Every entry is self-contained and runs on an ordinary PAL or NTSC C64 without a cartridge or BASIC extension.

Programs

Program	Category	Language	Controls	Description	Source	Run locally
Meteor Dodge	Arcade	BASIC	A, D, Q	Dodge falling meteors and build your score.	BAS	Run
Code Breaker	Logic	BASIC	0-9, Return, Q	Deduce a four-digit secret in ten guesses.	BAS	Run
Submarine Hunt	Strategy	BASIC	Row, Column, Return	Find three hidden submarines with limited sonar shots.	BAS	Run
Lunar Lander	Simulation	BASIC	0-9, Return, -1	Choose engine burns and touch down gently.	BAS	Run
Memory Matrix	Memory	BASIC	1, 2, 3, 4, Q	Repeat a growing sequence of flashing quadrants.	BAS	Run
Robot Maze	Puzzle	BASIC	W, A, S, D, Q	Navigate a freshly generated maze to its exit.	BAS	Run
Music Box	Music	BASIC	A-K, 1, 2, 3, Q	Play the SID chip as a small computer keyboard.	BAS	Run
Pixel Painter	Creative	BASIC	Cursor keys, Space, C, Q	Draw character-cell pictures on the screen.	BAS	Run
Stock Trader	Simulation	BASIC	B, S, W, Q	Trade a volatile stock over twenty market days.	BAS	Run
Starfield	Demo	BASIC	1, 2, 3, Q	Watch and control a layered animated starfield.	BAS	Run
Snake Trail	Arcade	BASIC	W, A, S, D, Q	Guide a growing snake through a field of food and danger.	BAS	Run
Dice Poker	Dice	BASIC	1-5, Return, Q	Keep your best dice and chase a winning poker combination.	BAS	Run
Word Scramble	Word	BASIC	A-Z, Return, Q	Unscramble five computer-themed words from helpful clues.	BAS	Run
Nim Challenge	Strategy	BASIC	1, 2, 3, 0	Outthink the computer in the classic game of twenty-one sticks.	BAS	Run
Reaction Timer	Reflex	BASIC	Any key, Q	Test your reactions across five unpredictable timed rounds.	BAS	Run
Morse Trainer	Educational	BASIC	A-Z, Return, Q	Learn Morse letters by reading and hearing their signals.	BAS	Run
Kaleidoscope	Demo	BASIC	Space, C, Q	Grow colorful symmetrical patterns across the character screen.	BAS	Run
World Quiz	Trivia	BASIC	1, 2, 3, Q	Take a seven-stop tour of world geography and landmarks.	BAS	Run
Life Lab	Simulation	BASIC	Space, R, Q	Observe generations of Conway's cellular automaton evolve.	BAS	Run
Cipher Wheel	Utility	BASIC	E, D, N, Q	Encode and decode secret messages with a Caesar shift.	BAS	Run
Sprite Playground	Creative	Machine Code	W, A, S, D, C, Q	Move and recolor a hardware sprite in a responsive VIC-II playground.	ASM	Run
Raster Bars	Demo	Machine Code	1, 2, 3, C, Q	Paint animated bands of color with cycle-aware VIC-II raster timing.	ASM	Run
SID Arpeggiator	Music	Machine Code	A-K, 1-3, +, -, Space, Q	Shape a looping SID arpeggio with notes, waveforms, and tempo controls.	ASM	Run

Running the programs

Start the local browser app with Docker Compose:

docker compose up --build -d

Open http://localhost:8134, or use a Run link in the table. The app runs the VICE x64sc core through WebAssembly and downloads the selected PRG through its own backend. Click inside the emulator to enable keyboard input and sound. Direct keyboard input is enabled by default, mouse locking is disabled, and moving the pointer anywhere over the emulator reveals its control bar.

The repository is mounted read-only at /programs. Add a manifest entry and its source and PRG files, then click Refresh; the app does not need to be rebuilt. The default host port is configured as 8134 in .env.

On a Commodore 64, transfer a PRG to disk or another supported medium, then use:

LOAD"METEOR-DODGE.PRG",8
RUN

Substitute the filename and device number as needed. The machine-code PRGs include a small BASIC SYS launcher, so the same RUN command starts them.

Building machine-code programs

The assembly sources use ACME syntax. Build every machine-code PRG with the isolated tools profile; no local assembler installation is required:

docker compose --profile tools run --rm assembler

The tools profile is opt-in and is not started by the normal app command.

Source format

Each program directory contains a loadable .prg and its readable source:

• BASIC programs use line-numbered, uppercase .bas files compatible with stock Commodore BASIC V2. Their PRGs are tokenized at the normal $0801 BASIC load address.
• Machine-code programs use commented ACME .asm files. Their PRGs also load at $0801, where a short BASIC line starts the 6502 code with SYS.

All programs are self-contained and designed for ordinary PAL and NTSC C64 hardware as well as VICE-compatible emulators.