c64-basic/README.md

13 KiB
Raw Blame History

C64 Program Collection

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

Browse and run the collection at c64.p20.dev.

Programs

Program Released Category Language Controls Description Source Run
Meteor Dodge 2026-10-07 Arcade BASIC A, D, Q Dodge falling meteors and build your score. BAS Run
Code Breaker 2026-10-07 Logic BASIC 0-9, Return, Q Deduce a four-digit secret in ten guesses. BAS Run
Submarine Hunt 2026-10-07 Strategy BASIC Row, Column, Return Find three hidden submarines with limited sonar shots. BAS Run
Lunar Lander 2026-10-07 Simulation BASIC 0-9, Return, -1 Choose engine burns and touch down gently. BAS Run
Memory Matrix 2026-10-07 Memory BASIC 1-4, Q Repeat a growing sequence of flashing quadrants. BAS Run
Robot Maze 2026-10-07 Puzzle BASIC W, A, S, D, Q Navigate a freshly generated maze to its exit. BAS Run
Music Box 2026-10-07 Music BASIC A-K, 1-3, Q Play the SID chip as a small computer keyboard. BAS Run
Pixel Painter 2026-10-07 Creative BASIC Cursor keys, Space, C, Q Draw character-cell pictures on the screen. BAS Run
Stock Trader 2026-10-07 Simulation BASIC B, S, W, Q Trade a volatile stock over twenty market days. BAS Run
Starfield 2026-10-07 Demo BASIC 1-3, Q Watch and control a layered animated starfield. BAS Run
Snake Trail 2026-10-07 Arcade BASIC W, A, S, D, Q Guide a growing snake through a field of food and danger. BAS Run
Dice Poker 2026-10-07 Dice BASIC 1-5, Return, Q Keep your best dice and chase a winning poker combination. BAS Run
Word Scramble 2026-10-07 Word BASIC A-Z, Return, Q Unscramble five computer-themed words from helpful clues. BAS Run
Nim Challenge 2026-10-07 Strategy BASIC 1-3, 0 Outthink the computer in the classic game of twenty-one sticks. BAS Run
Reaction Timer 2026-10-07 Reflex BASIC Any key, Q Test your reactions across five unpredictable timed rounds. BAS Run
Morse Trainer 2026-10-07 Educational BASIC A-Z, Return, Q Learn Morse letters by reading and hearing their signals. BAS Run
Kaleidoscope 2026-10-07 Demo BASIC Space, C, Q Grow colorful symmetrical patterns across the character screen. BAS Run
World Quiz 2026-10-07 Trivia BASIC 1-3, Q Take a seven-stop tour of world geography and landmarks. BAS Run
Life Lab 2026-10-07 Simulation BASIC Space, R, Q Observe generations of Conway's cellular automaton evolve. BAS Run
Cipher Wheel 2026-10-07 Utility BASIC E, D, N, Q Encode and decode secret messages with a Caesar shift. BAS Run
Sprite Playground 2026-10-16 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 2026-10-16 Demo Machine Code 1-3, C, Q Paint animated bands of color with cycle-aware VIC-II raster timing. ASM Run
SID Arpeggiator 2026-10-16 Music Machine Code A-K, 1-3, +, -, Space, Q Shape a looping SID arpeggio with notes, waveforms, and tempo controls. ASM Run
Paddle Ball 2026-10-16 Arcade Machine Code A, D, Space, Q Keep a fast-moving ball in play with a screen-edge paddle. ASM Run
Smooth Scroller 2026-10-16 Demo Machine Code +, -, C, Q Send a message gliding across the screen with VIC-II fine scrolling. ASM Run
Fireworks 2026-10-16 Demo Machine Code Space, A, C, 1-3, Q Launch colorful, noisy PETSCII fireworks above a twinkling city skyline. ASM Run
Jiffy Clock 2026-10-16 Utility Machine Code R, Space, Q Turn the C64 jiffy timer into a large live digital clock. ASM Run
Typing Sprint 2026-10-16 Word Machine Code A-Z, Space, Q Race the clock while copying a Commodore-themed phrase. ASM Run
PETSCII Aquarium 2026-10-16 Simulation Machine Code F, 1-3, Q Watch a tiny animated aquarium and feed its roaming fish. ASM Run
Fifteen Puzzle 2026-10-16 Puzzle Machine Code W, A, S, D, R, Q Slide numbered tiles until the classic four-by-four board is restored. ASM Run
Plasma Grid 2026-10-16 Demo Machine Code 1-3, C, Space, Q Fill the screen with a flowing field of color generated in real time. ASM Run
Neon Rift 2026-10-16 Demo Machine Code 1-3, C, M, Space, Q Enter a neon-colored world of orbiting sprites, a scrolling message, and a three-voice SID score. ASM Run
Infinite Road 2026-10-21 Demo Machine Code A, D, 1-3, C, M, Space, Q Cruise along an endless synthwave highway with sweeping curves and a driving three-voice SID score. ASM Run
Projectile Lab 2026-10-22 Physics BASIC 5-30, 10-80, R, Q Plot a projectile's flight from launch speed and angle. BAS Run
Prime Workshop 2026-10-22 Mathematics BASIC 2-9999, Return, Space, Q Factor whole numbers and calculate divisor counts and Euler's totient. BAS Run
Pi Drop 2026-10-22 Mathematics BASIC Space, Q Estimate pi by dropping random coordinates into a virtual unit circle. BAS Run
Wave Composer 2026-10-22 Physics BASIC A, Z, S, X, Space, Q Combine two sine waves and watch interference reshape the graph. BAS Run
Orbit Lab 2026-10-22 Physics BASIC 1-3, T, R, Space, Q Explore how velocity and gravity shape a simple two-dimensional orbit. BAS Run
Haunted Night 2026-10-23 Demo Machine Code 1-3, L, C, M, Space, Q Visit a moonlit haunted manor alive with ghosts, bats, lightning, and a sinister three-voice SID score. ASM Run
Happy Birthday, Beca! 2026-10-23 Demo Machine Code F, C, M, Space, Q Celebrate Beca's fifth birthday with cake, balloons, confetti, purrs, and a cheerful three-voice SID serenade. ASM Run
TV Fireplace 2026-10-24 Demo Machine Code 1-3, F, C, S, Space, Q Settle beside a classic brick fireplace with dancing flames, glowing embers, rising sparks, and crackling SID sound. ASM Run

Running the programs

Start the local browser app with Docker Compose:

docker compose up --build -d

Open http://localhost:8134, or visit the hosted collection at c64.p20.dev. 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 overview renders programs in small batches and is ready to scale without creating every card at once. 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"PADDLE-BALL.PRG",8
RUN

Substitute the filename and device number as needed. 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.

Capturing screenshots

Every program has a recipe in screenshots.json. The recipe waits for the emulator, focuses it, dismisses the splash screen, performs any program-specific actions, and captures a clean 960×720 PNG from the browser compositor. Screenshots are stored as screenshot.png beside each program and appear automatically in the grid view; no web-app rebuild is required.

Capture screenshots that do not exist yet:

docker compose --profile tools run --rm screenshots

Capture one program again, or rebuild the whole gallery:

docker compose --profile tools run --rm screenshots haunted-night --force
docker compose --profile tools run --rm screenshots --force

When adding a program, add its slug to screenshots.json. In most cases an empty object uses the collection's standard splash-screen recipe. Add explicit timed key actions when a program needs a particular scene. Always run and inspect the new screenshot before committing the program.

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.

New programs must open with an English splash screen containing a highlighted title, a short description, the full URL https://c64.p20.dev, the release date, and a prompt to continue with Space. The splash must include a Controls heading and visually distinguish its keys from their explanations. Gameplay instructions belong on the splash screen rather than occupying permanent rows in the running program.

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