c64-basic/README.md

# C64 Program Collection

Thirty 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, 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](https://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](meteor-dodge/meteor-dodge.bas) | [Run](https://c64.p20.dev/program/meteor-dodge) |
| Code Breaker | 2026-10-07 | Logic | BASIC | `0`-`9`, Return, `Q` | Deduce a four-digit secret in ten guesses. | [BAS](code-breaker/code-breaker.bas) | [Run](https://c64.p20.dev/program/code-breaker) |
| Submarine Hunt | 2026-10-07 | Strategy | BASIC | Row, Column, Return | Find three hidden submarines with limited sonar shots. | [BAS](submarine-hunt/submarine-hunt.bas) | [Run](https://c64.p20.dev/program/submarine-hunt) |
| Lunar Lander | 2026-10-07 | Simulation | BASIC | `0`-`9`, Return, `-1` | Choose engine burns and touch down gently. | [BAS](lunar-lander/lunar-lander.bas) | [Run](https://c64.p20.dev/program/lunar-lander) |
| Memory Matrix | 2026-10-07 | Memory | BASIC | `1`-`4`, `Q` | Repeat a growing sequence of flashing quadrants. | [BAS](memory-matrix/memory-matrix.bas) | [Run](https://c64.p20.dev/program/memory-matrix) |
| Robot Maze | 2026-10-07 | Puzzle | BASIC | `W`, `A`, `S`, `D`, `Q` | Navigate a freshly generated maze to its exit. | [BAS](robot-maze/robot-maze.bas) | [Run](https://c64.p20.dev/program/robot-maze) |
| Music Box | 2026-10-07 | Music | BASIC | `A`-`K`, `1`-`3`, `Q` | Play the SID chip as a small computer keyboard. | [BAS](music-box/music-box.bas) | [Run](https://c64.p20.dev/program/music-box) |
| Pixel Painter | 2026-10-07 | Creative | BASIC | Cursor keys, Space, `C`, `Q` | Draw character-cell pictures on the screen. | [BAS](pixel-painter/pixel-painter.bas) | [Run](https://c64.p20.dev/program/pixel-painter) |
| Stock Trader | 2026-10-07 | Simulation | BASIC | `B`, `S`, `W`, `Q` | Trade a volatile stock over twenty market days. | [BAS](stock-trader/stock-trader.bas) | [Run](https://c64.p20.dev/program/stock-trader) |
| Starfield | 2026-10-07 | Demo | BASIC | `1`-`3`, `Q` | Watch and control a layered animated starfield. | [BAS](starfield/starfield.bas) | [Run](https://c64.p20.dev/program/starfield) |
| Snake Trail | 2026-10-07 | Arcade | BASIC | `W`, `A`, `S`, `D`, `Q` | Guide a growing snake through a field of food and danger. | [BAS](snake-trail/snake-trail.bas) | [Run](https://c64.p20.dev/program/snake-trail) |
| Dice Poker | 2026-10-07 | Dice | BASIC | `1`-`5`, Return, `Q` | Keep your best dice and chase a winning poker combination. | [BAS](dice-poker/dice-poker.bas) | [Run](https://c64.p20.dev/program/dice-poker) |
| Word Scramble | 2026-10-07 | Word | BASIC | `A`-`Z`, Return, `Q` | Unscramble five computer-themed words from helpful clues. | [BAS](word-scramble/word-scramble.bas) | [Run](https://c64.p20.dev/program/word-scramble) |
| Nim Challenge | 2026-10-07 | Strategy | BASIC | `1`-`3`, `0` | Outthink the computer in the classic game of twenty-one sticks. | [BAS](nim-challenge/nim-challenge.bas) | [Run](https://c64.p20.dev/program/nim-challenge) |
| Reaction Timer | 2026-10-07 | Reflex | BASIC | Any key, `Q` | Test your reactions across five unpredictable timed rounds. | [BAS](reaction-timer/reaction-timer.bas) | [Run](https://c64.p20.dev/program/reaction-timer) |
| Morse Trainer | 2026-10-07 | Educational | BASIC | `A`-`Z`, Return, `Q` | Learn Morse letters by reading and hearing their signals. | [BAS](morse-trainer/morse-trainer.bas) | [Run](https://c64.p20.dev/program/morse-trainer) |
| Kaleidoscope | 2026-10-07 | Demo | BASIC | Space, `C`, `Q` | Grow colorful symmetrical patterns across the character screen. | [BAS](kaleidoscope/kaleidoscope.bas) | [Run](https://c64.p20.dev/program/kaleidoscope) |
| World Quiz | 2026-10-07 | Trivia | BASIC | `1`-`3`, `Q` | Take a seven-stop tour of world geography and landmarks. | [BAS](world-quiz/world-quiz.bas) | [Run](https://c64.p20.dev/program/world-quiz) |
| Life Lab | 2026-10-07 | Simulation | BASIC | Space, `R`, `Q` | Observe generations of Conway's cellular automaton evolve. | [BAS](life-lab/life-lab.bas) | [Run](https://c64.p20.dev/program/life-lab) |
| Cipher Wheel | 2026-10-07 | Utility | BASIC | `E`, `D`, `N`, `Q` | Encode and decode secret messages with a Caesar shift. | [BAS](cipher-wheel/cipher-wheel.bas) | [Run](https://c64.p20.dev/program/cipher-wheel) |
| 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](sprite-playground/sprite-playground.asm) | [Run](https://c64.p20.dev/program/sprite-playground) |
| 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](raster-bars/raster-bars.asm) | [Run](https://c64.p20.dev/program/raster-bars) |
| 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](sid-arpeggiator/sid-arpeggiator.asm) | [Run](https://c64.p20.dev/program/sid-arpeggiator) |
| 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](paddle-ball/paddle-ball.asm) | [Run](https://c64.p20.dev/program/paddle-ball) |
| Smooth Scroller | 2026-10-16 | Demo | Machine Code | `+`, `-`, `C`, `Q` | Send a message gliding across the screen with VIC-II fine scrolling. | [ASM](smooth-scroller/smooth-scroller.asm) | [Run](https://c64.p20.dev/program/smooth-scroller) |
| Fireworks | 2026-10-16 | Demo | Machine Code | Space, `C`, `Q` | Launch colorful PETSCII fireworks into a night sky. | [ASM](fireworks/fireworks.asm) | [Run](https://c64.p20.dev/program/fireworks) |
| Jiffy Clock | 2026-10-16 | Utility | Machine Code | `R`, Space, `Q` | Turn the C64 jiffy timer into a large live digital clock. | [ASM](jiffy-clock/jiffy-clock.asm) | [Run](https://c64.p20.dev/program/jiffy-clock) |
| Typing Sprint | 2026-10-16 | Word | Machine Code | `A`-`Z`, Space, `Q` | Race the clock while copying a Commodore-themed phrase. | [ASM](typing-sprint/typing-sprint.asm) | [Run](https://c64.p20.dev/program/typing-sprint) |
| PETSCII Aquarium | 2026-10-16 | Simulation | Machine Code | `F`, `1`-`3`, `Q` | Watch a tiny animated aquarium and feed its roaming fish. | [ASM](petscii-aquarium/petscii-aquarium.asm) | [Run](https://c64.p20.dev/program/petscii-aquarium) |
| 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](fifteen-puzzle/fifteen-puzzle.asm) | [Run](https://c64.p20.dev/program/fifteen-puzzle) |

## Running the programs

Start the local browser app with Docker Compose:

```text
docker compose up --build -d
```

Open [http://localhost:8134](http://localhost:8134), or visit the hosted collection at [c64.p20.dev](https://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:

```text
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:

```text
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`.

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.