diff --git a/README.md b/README.md
index b427c54..20ecd94 100644
--- a/README.md
+++ b/README.md
@@ -1,34 +1,38 @@
-# C64 BASIC Collection
+# C64 Program Collection
-Twenty small, polished programs for the Commodore 64, written entirely in stock
-Commodore BASIC V2. The collection mixes arcade action, puzzles, simulations,
-creative tools, sound, and visual effects. No cartridge, BASIC extension, or
-machine-language payload is required.
+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 | Type | Controls | Description | Run locally |
-| --- | --- | --- | --- | --- |
-| [Meteor Dodge](meteor-dodge/meteor-dodge.bas) | Arcade | `A`, `D`, `Q` | Dodge falling meteors and build your score. | [Run program](http://localhost:8134/program/meteor-dodge) |
-| [Code Breaker](code-breaker/code-breaker.bas) | Logic | `0`-`9`, `Q` | Deduce a four-digit secret in ten guesses. | [Run program](http://localhost:8134/program/code-breaker) |
-| [Submarine Hunt](submarine-hunt/submarine-hunt.bas) | Strategy | Row, Column, `Q` | Find three hidden submarines with limited sonar shots. | [Run program](http://localhost:8134/program/submarine-hunt) |
-| [Lunar Lander](lunar-lander/lunar-lander.bas) | Simulation | `0`-`9`, `Q` | Choose engine burns and touch down gently. | [Run program](http://localhost:8134/program/lunar-lander) |
-| [Memory Matrix](memory-matrix/memory-matrix.bas) | Memory | `1`, `2`, `3`, `4`, `Q` | Repeat a growing sequence of flashing quadrants. | [Run program](http://localhost:8134/program/memory-matrix) |
-| [Robot Maze](robot-maze/robot-maze.bas) | Puzzle | `W`, `A`, `S`, `D`, `Q` | Navigate a freshly generated maze to its exit. | [Run program](http://localhost:8134/program/robot-maze) |
-| [Music Box](music-box/music-box.bas) | Music | `A`-`K`, `1`, `2`, `3`, `Q` | Play the SID chip as a small computer keyboard. | [Run program](http://localhost:8134/program/music-box) |
-| [Pixel Painter](pixel-painter/pixel-painter.bas) | Creative | Cursor keys, Space, `C`, `Q` | Draw character-cell pictures on the screen. | [Run program](http://localhost:8134/program/pixel-painter) |
-| [Stock Trader](stock-trader/stock-trader.bas) | Simulation | `B`, `S`, `W`, `Q` | Trade a volatile stock over twenty market days. | [Run program](http://localhost:8134/program/stock-trader) |
-| [Starfield](starfield/starfield.bas) | Demo | `1`, `2`, `3`, `Q` | Watch and control a layered animated starfield. | [Run program](http://localhost:8134/program/starfield) |
-| [Snake Trail](snake-trail/snake-trail.bas) | Arcade | `W`, `A`, `S`, `D`, `Q` | Guide a growing snake through a field of food and danger. | [Run program](http://localhost:8134/program/snake-trail) |
-| [Dice Poker](dice-poker/dice-poker.bas) | Dice | `1`-`5`, Return, `Q` | Keep your best dice and chase a winning poker combination. | [Run program](http://localhost:8134/program/dice-poker) |
-| [Word Scramble](word-scramble/word-scramble.bas) | Word | `A`-`Z`, Return, `Q` | Unscramble five computer-themed words from helpful clues. | [Run program](http://localhost:8134/program/word-scramble) |
-| [Nim Challenge](nim-challenge/nim-challenge.bas) | Strategy | `1`, `2`, `3`, `0` | Outthink the computer in the classic game of twenty-one sticks. | [Run program](http://localhost:8134/program/nim-challenge) |
-| [Reaction Timer](reaction-timer/reaction-timer.bas) | Reflex | Any key, `Q` | Test your reactions across five unpredictable timed rounds. | [Run program](http://localhost:8134/program/reaction-timer) |
-| [Morse Trainer](morse-trainer/morse-trainer.bas) | Educational | `A`-`Z`, Return, `Q` | Learn Morse letters by reading and hearing their signals. | [Run program](http://localhost:8134/program/morse-trainer) |
-| [Kaleidoscope](kaleidoscope/kaleidoscope.bas) | Demo | Space, `C`, `Q` | Grow colorful symmetrical patterns across the character screen. | [Run program](http://localhost:8134/program/kaleidoscope) |
-| [World Quiz](world-quiz/world-quiz.bas) | Trivia | `1`, `2`, `3`, `Q` | Take a seven-stop tour of world geography and landmarks. | [Run program](http://localhost:8134/program/world-quiz) |
-| [Life Lab](life-lab/life-lab.bas) | Simulation | Space, `R`, `Q` | Observe generations of Conway's cellular automaton evolve. | [Run program](http://localhost:8134/program/life-lab) |
-| [Cipher Wheel](cipher-wheel/cipher-wheel.bas) | Utility | `E`, `D`, `N`, `Q` | Encode and decode secret messages with a Caesar shift. | [Run program](http://localhost:8134/program/cipher-wheel) |
+| Program | Category | Language | Controls | Description | Source | Run locally |
+| --- | --- | --- | --- | --- | --- | --- |
+| Meteor Dodge | Arcade | BASIC | `A`, `D`, `Q` | Dodge falling meteors and build your score. | [BAS](meteor-dodge/meteor-dodge.bas) | [Run](http://localhost:8134/program/meteor-dodge) |
+| Code Breaker | Logic | BASIC | `0`-`9`, Return, `Q` | Deduce a four-digit secret in ten guesses. | [BAS](code-breaker/code-breaker.bas) | [Run](http://localhost:8134/program/code-breaker) |
+| Submarine Hunt | Strategy | BASIC | Row, Column, Return | Find three hidden submarines with limited sonar shots. | [BAS](submarine-hunt/submarine-hunt.bas) | [Run](http://localhost:8134/program/submarine-hunt) |
+| Lunar Lander | Simulation | BASIC | `0`-`9`, Return, `-1` | Choose engine burns and touch down gently. | [BAS](lunar-lander/lunar-lander.bas) | [Run](http://localhost:8134/program/lunar-lander) |
+| Memory Matrix | Memory | BASIC | `1`, `2`, `3`, `4`, `Q` | Repeat a growing sequence of flashing quadrants. | [BAS](memory-matrix/memory-matrix.bas) | [Run](http://localhost:8134/program/memory-matrix) |
+| Robot Maze | Puzzle | BASIC | `W`, `A`, `S`, `D`, `Q` | Navigate a freshly generated maze to its exit. | [BAS](robot-maze/robot-maze.bas) | [Run](http://localhost:8134/program/robot-maze) |
+| Music Box | Music | BASIC | `A`-`K`, `1`, `2`, `3`, `Q` | Play the SID chip as a small computer keyboard. | [BAS](music-box/music-box.bas) | [Run](http://localhost:8134/program/music-box) |
+| Pixel Painter | Creative | BASIC | Cursor keys, Space, `C`, `Q` | Draw character-cell pictures on the screen. | [BAS](pixel-painter/pixel-painter.bas) | [Run](http://localhost:8134/program/pixel-painter) |
+| Stock Trader | Simulation | BASIC | `B`, `S`, `W`, `Q` | Trade a volatile stock over twenty market days. | [BAS](stock-trader/stock-trader.bas) | [Run](http://localhost:8134/program/stock-trader) |
+| Starfield | Demo | BASIC | `1`, `2`, `3`, `Q` | Watch and control a layered animated starfield. | [BAS](starfield/starfield.bas) | [Run](http://localhost:8134/program/starfield) |
+| Snake Trail | 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](http://localhost:8134/program/snake-trail) |
+| Dice Poker | Dice | BASIC | `1`-`5`, Return, `Q` | Keep your best dice and chase a winning poker combination. | [BAS](dice-poker/dice-poker.bas) | [Run](http://localhost:8134/program/dice-poker) |
+| Word Scramble | Word | BASIC | `A`-`Z`, Return, `Q` | Unscramble five computer-themed words from helpful clues. | [BAS](word-scramble/word-scramble.bas) | [Run](http://localhost:8134/program/word-scramble) |
+| Nim Challenge | Strategy | BASIC | `1`, `2`, `3`, `0` | Outthink the computer in the classic game of twenty-one sticks. | [BAS](nim-challenge/nim-challenge.bas) | [Run](http://localhost:8134/program/nim-challenge) |
+| Reaction Timer | Reflex | BASIC | Any key, `Q` | Test your reactions across five unpredictable timed rounds. | [BAS](reaction-timer/reaction-timer.bas) | [Run](http://localhost:8134/program/reaction-timer) |
+| Morse Trainer | Educational | BASIC | `A`-`Z`, Return, `Q` | Learn Morse letters by reading and hearing their signals. | [BAS](morse-trainer/morse-trainer.bas) | [Run](http://localhost:8134/program/morse-trainer) |
+| Kaleidoscope | Demo | BASIC | Space, `C`, `Q` | Grow colorful symmetrical patterns across the character screen. | [BAS](kaleidoscope/kaleidoscope.bas) | [Run](http://localhost:8134/program/kaleidoscope) |
+| World Quiz | Trivia | BASIC | `1`, `2`, `3`, `Q` | Take a seven-stop tour of world geography and landmarks. | [BAS](world-quiz/world-quiz.bas) | [Run](http://localhost:8134/program/world-quiz) |
+| Life Lab | Simulation | BASIC | Space, `R`, `Q` | Observe generations of Conway's cellular automaton evolve. | [BAS](life-lab/life-lab.bas) | [Run](http://localhost:8134/program/life-lab) |
+| Cipher Wheel | Utility | BASIC | `E`, `D`, `N`, `Q` | Encode and decode secret messages with a Caesar shift. | [BAS](cipher-wheel/cipher-wheel.bas) | [Run](http://localhost:8134/program/cipher-wheel) |
+| Sprite Playground | 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](http://localhost:8134/program/sprite-playground) |
+| Raster Bars | Demo | Machine Code | `1`, `2`, `3`, `C`, `Q` | Paint animated bands of color with cycle-aware VIC-II raster timing. | [ASM](raster-bars/raster-bars.asm) | [Run](http://localhost:8134/program/raster-bars) |
+| SID Arpeggiator | 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](http://localhost:8134/program/sid-arpeggiator) |
## Running the programs
@@ -38,22 +42,16 @@ Start the local browser app with Docker Compose:
docker compose up --build -d
```
-Open [http://localhost:8134](http://localhost:8134), or click a **Run program**
-link in the table. The app runs the VICE x64sc core through WebAssembly and
-downloads the selected PRG through its own backend, avoiding browser CORS
-restrictions. 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.
+Open [http://localhost:8134](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.
-Docker Compose mounts this repository read-only at `/programs`, and the app
-serves PRG files from that local mount. There is no runtime dependency on the
-Git server and no browser CORS boundary. Add a program to `programs.json` and
-place its PRG in the referenced path; it appears after clicking **Refresh list**
-without rebuilding the image. The default host port is configured as `8134` in
-`.env`.
-
-Each directory contains an editable, line-numbered `.bas` listing and a matching
-tokenized `.prg` file. The PRGs use the normal C64 BASIC load address, `$0801`.
+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:
@@ -62,17 +60,29 @@ LOAD"METEOR-DODGE.PRG",8
RUN
```
-Substitute the filename and device number as needed. In VICE or another C64
-emulator, drag a PRG into the emulator window or use its autostart command.
+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:
+
+```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
-The `.bas` files are plain ASCII for comfortable reading and editing on a modern
-computer. They use uppercase BASIC V2 keywords and avoid embedded control-code
-glyphs. Their corresponding `.prg` files contain the tokenized PETSCII program
-that the C64 loads directly.
+Each program directory contains a loadable `.prg` and its readable source:
-All programs are self-contained and designed for an ordinary PAL or NTSC
-Commodore 64. Randomized programs seed BASIC's random-number generator from the
-machine clock, so every session is different.
+- 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.
diff --git a/compose.yaml b/compose.yaml
index 6ddaf58..6998697 100644
--- a/compose.yaml
+++ b/compose.yaml
@@ -9,3 +9,12 @@ services:
- .:/programs:ro
restart: unless-stopped
+ assembler:
+ profiles: ["tools"]
+ build:
+ context: .
+ dockerfile: tools/acme/Dockerfile
+ working_dir: /programs
+ volumes:
+ - .:/programs
+
diff --git a/programs.json b/programs.json
index af63b2b..1500226 100644
--- a/programs.json
+++ b/programs.json
@@ -1,143 +1,140 @@
[
{
- "title": "Meteor Dodge",
- "type": "Arcade",
+ "title": "Meteor Dodge", "category": "Arcade", "language": "basic",
"description": "Dodge falling meteors and build your score.",
- "controls": ["A", "D", "Q"],
- "path": "meteor-dodge/meteor-dodge.prg"
+ "controls": [{"keys":["A"],"description":"Move left"},{"keys":["D"],"description":"Move right"},{"keys":["Q"],"description":"Quit"}],
+ "path": "meteor-dodge/meteor-dodge.prg", "source": "meteor-dodge/meteor-dodge.bas"
},
{
- "title": "Code Breaker",
- "type": "Logic",
+ "title": "Code Breaker", "category": "Logic", "language": "basic",
"description": "Deduce a four-digit secret in ten guesses.",
- "controls": ["0-9", "Q"],
- "path": "code-breaker/code-breaker.prg"
+ "controls": [{"keys":["0-9"],"description":"Enter a four-digit guess"},{"keys":["RETURN"],"description":"Submit the guess"},{"keys":["Q"],"description":"Quit"}],
+ "path": "code-breaker/code-breaker.prg", "source": "code-breaker/code-breaker.bas"
},
{
- "title": "Submarine Hunt",
- "type": "Strategy",
+ "title": "Submarine Hunt", "category": "Strategy", "language": "basic",
"description": "Find three hidden submarines with limited sonar shots.",
- "controls": ["ROW", "COLUMN", "Q"],
- "path": "submarine-hunt/submarine-hunt.prg"
+ "controls": [{"keys":["ROW","COLUMN"],"description":"Enter sonar coordinates"},{"keys":["RETURN"],"description":"Fire a sonar shot"},{"keys":["0","0"],"description":"Quit"}],
+ "path": "submarine-hunt/submarine-hunt.prg", "source": "submarine-hunt/submarine-hunt.bas"
},
{
- "title": "Lunar Lander",
- "type": "Simulation",
+ "title": "Lunar Lander", "category": "Simulation", "language": "basic",
"description": "Choose engine burns and touch down gently.",
- "controls": ["0-9", "Q"],
- "path": "lunar-lander/lunar-lander.prg"
+ "controls": [{"keys":["0-9"],"description":"Choose engine burn strength"},{"keys":["RETURN"],"description":"Commit the burn"},{"keys":["-1"],"description":"Quit"}],
+ "path": "lunar-lander/lunar-lander.prg", "source": "lunar-lander/lunar-lander.bas"
},
{
- "title": "Memory Matrix",
- "type": "Memory",
+ "title": "Memory Matrix", "category": "Memory", "language": "basic",
"description": "Repeat a growing sequence of flashing quadrants.",
- "controls": ["1", "2", "3", "4", "Q"],
- "path": "memory-matrix/memory-matrix.prg"
+ "controls": [{"keys":["1","2","3","4"],"description":"Repeat the flashed quadrant"},{"keys":["Q"],"description":"Quit"}],
+ "path": "memory-matrix/memory-matrix.prg", "source": "memory-matrix/memory-matrix.bas"
},
{
- "title": "Robot Maze",
- "type": "Puzzle",
+ "title": "Robot Maze", "category": "Puzzle", "language": "basic",
"description": "Navigate a freshly generated maze to its exit.",
- "controls": ["W", "A", "S", "D", "Q"],
- "path": "robot-maze/robot-maze.prg"
+ "controls": [{"keys":["W","A","S","D"],"description":"Move the robot"},{"keys":["Q"],"description":"Quit"}],
+ "path": "robot-maze/robot-maze.prg", "source": "robot-maze/robot-maze.bas"
},
{
- "title": "Music Box",
- "type": "Music",
+ "title": "Music Box", "category": "Music", "language": "basic",
"description": "Play the SID chip as a small computer keyboard.",
- "controls": ["A-K", "1", "2", "3", "Q"],
- "path": "music-box/music-box.prg"
+ "controls": [{"keys":["A-K"],"description":"Play notes"},{"keys":["1","2","3"],"description":"Select square, saw, or triangle wave"},{"keys":["Q"],"description":"Quit"}],
+ "path": "music-box/music-box.prg", "source": "music-box/music-box.bas"
},
{
- "title": "Pixel Painter",
- "type": "Creative",
+ "title": "Pixel Painter", "category": "Creative", "language": "basic",
"description": "Draw character-cell pictures on the screen.",
- "controls": ["CURSOR KEYS", "SPACE", "C", "Q"],
- "path": "pixel-painter/pixel-painter.prg"
+ "controls": [{"keys":["CURSOR KEYS"],"description":"Move the drawing cursor"},{"keys":["SPACE"],"description":"Draw a pixel"},{"keys":["C"],"description":"Clear the canvas"},{"keys":["Q"],"description":"Quit"}],
+ "path": "pixel-painter/pixel-painter.prg", "source": "pixel-painter/pixel-painter.bas"
},
{
- "title": "Stock Trader",
- "type": "Simulation",
+ "title": "Stock Trader", "category": "Simulation", "language": "basic",
"description": "Trade a volatile stock over twenty market days.",
- "controls": ["B", "S", "W", "Q"],
- "path": "stock-trader/stock-trader.prg"
+ "controls": [{"keys":["B"],"description":"Buy shares"},{"keys":["S"],"description":"Sell shares"},{"keys":["W"],"description":"Wait for the next day"},{"keys":["Q"],"description":"Quit"}],
+ "path": "stock-trader/stock-trader.prg", "source": "stock-trader/stock-trader.bas"
},
{
- "title": "Starfield",
- "type": "Demo",
+ "title": "Starfield", "category": "Demo", "language": "basic",
"description": "Watch and control a layered animated starfield.",
- "controls": ["1", "2", "3", "Q"],
- "path": "starfield/starfield.prg"
+ "controls": [{"keys":["1","2","3"],"description":"Select slow, medium, or fast speed"},{"keys":["Q"],"description":"Quit"}],
+ "path": "starfield/starfield.prg", "source": "starfield/starfield.bas"
},
{
- "title": "Snake Trail",
- "type": "Arcade",
+ "title": "Snake Trail", "category": "Arcade", "language": "basic",
"description": "Guide a growing snake through a field of food and danger.",
- "controls": ["W", "A", "S", "D", "Q"],
- "path": "snake-trail/snake-trail.prg"
+ "controls": [{"keys":["W","A","S","D"],"description":"Steer the snake"},{"keys":["Q"],"description":"Quit"}],
+ "path": "snake-trail/snake-trail.prg", "source": "snake-trail/snake-trail.bas"
},
{
- "title": "Dice Poker",
- "type": "Dice",
+ "title": "Dice Poker", "category": "Dice", "language": "basic",
"description": "Keep your best dice and chase a winning poker combination.",
- "controls": ["1-5", "RETURN", "Q"],
- "path": "dice-poker/dice-poker.prg"
+ "controls": [{"keys":["1-5"],"description":"Choose dice positions to keep"},{"keys":["RETURN"],"description":"Roll the remaining dice"},{"keys":["Q"],"description":"Quit"}],
+ "path": "dice-poker/dice-poker.prg", "source": "dice-poker/dice-poker.bas"
},
{
- "title": "Word Scramble",
- "type": "Word",
+ "title": "Word Scramble", "category": "Word", "language": "basic",
"description": "Unscramble five computer-themed words from helpful clues.",
- "controls": ["A-Z", "RETURN", "Q"],
- "path": "word-scramble/word-scramble.prg"
+ "controls": [{"keys":["A-Z"],"description":"Type your answer"},{"keys":["RETURN"],"description":"Submit the answer"},{"keys":["Q"],"description":"Quit"}],
+ "path": "word-scramble/word-scramble.prg", "source": "word-scramble/word-scramble.bas"
},
{
- "title": "Nim Challenge",
- "type": "Strategy",
+ "title": "Nim Challenge", "category": "Strategy", "language": "basic",
"description": "Outthink the computer in the classic game of twenty-one sticks.",
- "controls": ["1", "2", "3", "0"],
- "path": "nim-challenge/nim-challenge.prg"
+ "controls": [{"keys":["1","2","3"],"description":"Choose how many sticks to take"},{"keys":["0"],"description":"Quit"}],
+ "path": "nim-challenge/nim-challenge.prg", "source": "nim-challenge/nim-challenge.bas"
},
{
- "title": "Reaction Timer",
- "type": "Reflex",
+ "title": "Reaction Timer", "category": "Reflex", "language": "basic",
"description": "Test your reactions across five unpredictable timed rounds.",
- "controls": ["ANY KEY", "Q"],
- "path": "reaction-timer/reaction-timer.prg"
+ "controls": [{"keys":["ANY KEY"],"description":"React when NOW appears"},{"keys":["Q"],"description":"Quit"}],
+ "path": "reaction-timer/reaction-timer.prg", "source": "reaction-timer/reaction-timer.bas"
},
{
- "title": "Morse Trainer",
- "type": "Educational",
+ "title": "Morse Trainer", "category": "Educational", "language": "basic",
"description": "Learn Morse letters by reading and hearing their signals.",
- "controls": ["A-Z", "RETURN", "Q"],
- "path": "morse-trainer/morse-trainer.prg"
+ "controls": [{"keys":["A-Z"],"description":"Enter the decoded letter"},{"keys":["RETURN"],"description":"Submit the answer"},{"keys":["Q"],"description":"Quit"}],
+ "path": "morse-trainer/morse-trainer.prg", "source": "morse-trainer/morse-trainer.bas"
},
{
- "title": "Kaleidoscope",
- "type": "Demo",
+ "title": "Kaleidoscope", "category": "Demo", "language": "basic",
"description": "Grow colorful symmetrical patterns across the character screen.",
- "controls": ["SPACE", "C", "Q"],
- "path": "kaleidoscope/kaleidoscope.prg"
+ "controls": [{"keys":["SPACE"],"description":"Start a new pattern"},{"keys":["C"],"description":"Change color"},{"keys":["Q"],"description":"Quit"}],
+ "path": "kaleidoscope/kaleidoscope.prg", "source": "kaleidoscope/kaleidoscope.bas"
},
{
- "title": "World Quiz",
- "type": "Trivia",
+ "title": "World Quiz", "category": "Trivia", "language": "basic",
"description": "Take a seven-stop tour of world geography and landmarks.",
- "controls": ["1", "2", "3", "Q"],
- "path": "world-quiz/world-quiz.prg"
+ "controls": [{"keys":["1","2","3"],"description":"Choose an answer"},{"keys":["Q"],"description":"Quit"}],
+ "path": "world-quiz/world-quiz.prg", "source": "world-quiz/world-quiz.bas"
},
{
- "title": "Life Lab",
- "type": "Simulation",
+ "title": "Life Lab", "category": "Simulation", "language": "basic",
"description": "Observe generations of Conway's cellular automaton evolve.",
- "controls": ["SPACE", "R", "Q"],
- "path": "life-lab/life-lab.prg"
+ "controls": [{"keys":["SPACE"],"description":"Pause or continue"},{"keys":["R"],"description":"Create a new random colony"},{"keys":["Q"],"description":"Quit"}],
+ "path": "life-lab/life-lab.prg", "source": "life-lab/life-lab.bas"
},
{
- "title": "Cipher Wheel",
- "type": "Utility",
+ "title": "Cipher Wheel", "category": "Utility", "language": "basic",
"description": "Encode and decode secret messages with a Caesar shift.",
- "controls": ["E", "D", "N", "Q"],
- "path": "cipher-wheel/cipher-wheel.prg"
+ "controls": [{"keys":["E","D"],"description":"Choose encode or decode"},{"keys":["N"],"description":"Enter another message"},{"keys":["Q"],"description":"Quit"}],
+ "path": "cipher-wheel/cipher-wheel.prg", "source": "cipher-wheel/cipher-wheel.bas"
+ },
+ {
+ "title": "Sprite Playground", "category": "Creative", "language": "machine-code",
+ "description": "Move and recolor a hardware sprite in a responsive VIC-II playground.",
+ "controls": [{"keys":["W","A","S","D"],"description":"Move the sprite"},{"keys":["C"],"description":"Change sprite color"},{"keys":["Q"],"description":"Return to BASIC"}],
+ "path": "sprite-playground/sprite-playground.prg", "source": "sprite-playground/sprite-playground.asm"
+ },
+ {
+ "title": "Raster Bars", "category": "Demo", "language": "machine-code",
+ "description": "Paint animated bands of color with cycle-aware VIC-II raster timing.",
+ "controls": [{"keys":["1","2","3"],"description":"Select slow, medium, or fast movement"},{"keys":["C"],"description":"Change color palette"},{"keys":["Q"],"description":"Return to BASIC"}],
+ "path": "raster-bars/raster-bars.prg", "source": "raster-bars/raster-bars.asm"
+ },
+ {
+ "title": "SID Arpeggiator", "category": "Music", "language": "machine-code",
+ "description": "Shape a looping SID arpeggio with notes, waveforms, and tempo controls.",
+ "controls": [{"keys":["A-K"],"description":"Select the root note"},{"keys":["1","2","3"],"description":"Select triangle, saw, or pulse wave"},{"keys":["+","-"],"description":"Increase or decrease tempo"},{"keys":["SPACE"],"description":"Pause or resume playback"},{"keys":["Q"],"description":"Return to BASIC"}],
+ "path": "sid-arpeggiator/sid-arpeggiator.prg", "source": "sid-arpeggiator/sid-arpeggiator.asm"
}
]
-
diff --git a/public/app.js b/public/app.js
index 08d778b..5a2f471 100644
--- a/public/app.js
+++ b/public/app.js
@@ -4,47 +4,102 @@ const status = document.querySelector('#status');
const programsElement = document.querySelector('#programs');
const refreshButton = document.querySelector('#refresh');
const searchInput = document.querySelector('#search');
-const typeFilter = document.querySelector('#type-filter');
+const categoryFilter = document.querySelector('#category-filter');
+const languageFilter = document.querySelector('#language-filter');
const sortOrder = document.querySelector('#sort-order');
const gridViewButton = document.querySelector('#grid-view');
const listViewButton = document.querySelector('#list-view');
const sourceModal = document.querySelector('#source-modal');
const sourceTitle = document.querySelector('#source-title');
+const sourceKind = document.querySelector('#source-kind');
const sourceStatus = document.querySelector('#source-status');
const sourceCode = document.querySelector('#source-code');
+const programBadges = document.querySelector('#program-badges');
+const programDescription = document.querySelector('#program-description');
+const programControls = document.querySelector('#program-controls');
let allPrograms = [];
-function titleFromPath(path) {
- const filename = path.split('/').at(-1).replace(/\.prg$/i, '');
- return filename.split('-').map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(' ');
+const categoryMeta = {
+ Arcade: { icon: '🎮', color: '#d65f5f' },
+ Creative: { icon: '✎', color: '#65b96d' },
+ Demo: { icon: '✦', color: '#75a9dc' },
+ Dice: { icon: '⚄', color: '#d8d4c4' },
+ Educational: { icon: '⌁', color: '#b98a64' },
+ Logic: { icon: '◆', color: '#67b6bd' },
+ Memory: { icon: '◫', color: '#9b6bd6' },
+ Music: { icon: '♪', color: '#d668a4' },
+ Puzzle: { icon: '⌘', color: '#d6c85c' },
+ Reflex: { icon: '⚡', color: '#ef725f' },
+ Simulation: { icon: '⚙', color: '#6d8ed6' },
+ Strategy: { icon: '♟', color: '#d98f45' },
+ Trivia: { icon: '?', color: '#dfaa45' },
+ Utility: { icon: '⚒', color: '#a5acb8' },
+ Word: { icon: 'Aa', color: '#55b7a4' }
+};
+
+const languageLabels = {
+ basic: 'BASIC',
+ 'machine-code': 'Machine Code'
+};
+
+function slugify(value) {
+ return value.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
}
-const typeIcons = {
- Arcade: '🎮',
- Logic: '◆',
- Strategy: '♟',
- Simulation: '⚙',
- Memory: '◫',
- Puzzle: '⌘',
- Music: '♪',
- Creative: '✎',
- Demo: '✦',
- Dice: '⚄',
- Word: 'Aa',
- Reflex: '⚡',
- Educational: '⌁',
- Trivia: '?',
- Utility: '⚒'
-};
+function categoryFromRoute() {
+ const match = location.pathname.match(/^\/category\/([a-z0-9]+(?:-[a-z0-9]+)*)\/?$/);
+ return match?.[1] || '';
+}
+
+function createCategoryPill(category) {
+ const meta = categoryMeta[category] || { icon: '●', color: '#a5acb8' };
+ const pill = document.createElement('a');
+ pill.className = 'category-pill';
+ pill.href = `/category/${slugify(category)}`;
+ pill.style.setProperty('--category-color', meta.color);
+ const icon = document.createElement('span');
+ icon.setAttribute('aria-hidden', 'true');
+ icon.textContent = meta.icon;
+ const label = document.createElement('span');
+ label.textContent = category;
+ pill.append(icon, label);
+ pill.setAttribute('aria-label', `Show all ${category} programs`);
+ return pill;
+}
+
+function createLanguageBadge(language) {
+ const badge = document.createElement('span');
+ badge.className = `language-badge language-${language}`;
+ badge.textContent = languageLabels[language] || language;
+ return badge;
+}
+
+function createKeyGroup(keys) {
+ const group = document.createElement('span');
+ group.className = 'key-group';
+ for (const keyName of keys) {
+ const key = document.createElement('kbd');
+ key.textContent = keyName;
+ group.append(key);
+ }
+ return group;
+}
+
+function searchText(program) {
+ const controls = program.controls.flatMap(control => [...control.keys, control.description]);
+ return `${program.title} ${program.description} ${program.category} ${languageLabels[program.language]} ${controls.join(' ')}`.toLowerCase();
+}
function renderPrograms() {
const query = searchInput.value.trim().toLowerCase();
- const selectedType = typeFilter.value;
+ const selectedCategory = categoryFilter.value;
+ const selectedLanguage = languageFilter.value;
const programs = allPrograms
- .filter(program => !selectedType || program.type === selectedType)
- .filter(program => !query || `${program.title} ${program.description} ${program.type} ${program.controls.join(' ')}`.toLowerCase().includes(query))
+ .filter(program => !selectedCategory || program.category === selectedCategory)
+ .filter(program => !selectedLanguage || program.language === selectedLanguage)
+ .filter(program => !query || searchText(program).includes(query))
.sort((left, right) => {
- if (sortOrder.value === 'type') return left.type.localeCompare(right.type) || left.title.localeCompare(right.title);
+ if (sortOrder.value === 'category') return left.category.localeCompare(right.category) || left.title.localeCompare(right.title);
return left.title.localeCompare(right.title);
});
@@ -57,9 +112,9 @@ function renderPrograms() {
if (!event.target.closest('a, button')) location.href = programUrl;
});
- const pill = document.createElement('span');
- pill.className = 'type-pill';
- pill.textContent = `${typeIcons[program.type] || '●'} ${program.type}`;
+ const badges = document.createElement('div');
+ badges.className = 'card-badges';
+ badges.append(createCategoryPill(program.category), createLanguageBadge(program.language));
const title = document.createElement('h2');
title.className = 'program-title';
@@ -69,15 +124,6 @@ function renderPrograms() {
description.className = 'program-description';
description.textContent = program.description;
- const controls = document.createElement('div');
- controls.className = 'controls';
- controls.setAttribute('aria-label', `Controls: ${program.controls.join(', ')}`);
- for (const control of program.controls) {
- const key = document.createElement('kbd');
- key.textContent = control;
- controls.append(key);
- }
-
const actions = document.createElement('div');
actions.className = 'program-actions';
const run = document.createElement('a');
@@ -91,14 +137,16 @@ function renderPrograms() {
source.disabled = !program.source;
source.addEventListener('click', () => showSource(program));
actions.append(run, source);
- card.append(pill, title, description, controls, actions);
+ card.append(badges, title, description, actions);
programsElement.append(card);
}
+ status.className = 'status';
status.textContent = `${programs.length} of ${allPrograms.length} programs shown`;
}
async function showSource(program) {
sourceTitle.textContent = program.title;
+ sourceKind.textContent = program.language === 'machine-code' ? 'Assembly source' : 'BASIC V2 source';
sourceStatus.hidden = false;
sourceStatus.className = 'status';
sourceStatus.textContent = 'Loading source…';
@@ -117,6 +165,15 @@ async function showSource(program) {
}
}
+function populateFilters(programs) {
+ const categories = [...new Set(programs.map(program => program.category))].sort();
+ categoryFilter.replaceChildren(new Option('All categories', ''), ...categories.map(category => new Option(category, category)));
+ const routeSlug = categoryFromRoute();
+ const routeCategory = categories.find(category => slugify(category) === routeSlug);
+ if (routeCategory) categoryFilter.value = routeCategory;
+ else categoryFilter.value = '';
+}
+
async function loadPrograms() {
status.hidden = false;
status.className = 'status';
@@ -127,10 +184,7 @@ async function loadPrograms() {
if (!response.ok) throw new Error('The program list could not be loaded.');
const { programs } = await response.json();
allPrograms = programs;
- const currentType = typeFilter.value;
- const types = [...new Set(programs.map(program => program.type))].sort();
- typeFilter.replaceChildren(new Option('All types', ''), ...types.map(type => new Option(type, type)));
- if (types.includes(currentType)) typeFilter.value = currentType;
+ populateFilters(programs);
renderPrograms();
} catch (error) {
status.className = 'status error';
@@ -140,18 +194,31 @@ async function loadPrograms() {
}
}
+function renderProgramDetails(program) {
+ programBadges.replaceChildren(createCategoryPill(program.category), createLanguageBadge(program.language));
+ programDescription.textContent = program.description;
+ programControls.replaceChildren();
+ for (const control of program.controls) {
+ const row = document.createElement('div');
+ row.className = 'control-row';
+ const description = document.createElement('span');
+ description.textContent = control.description;
+ row.append(createKeyGroup(control.keys), description);
+ programControls.append(row);
+ }
+}
+
function startEmulator(program) {
- const programPath = program.path;
library.hidden = true;
player.hidden = false;
- const title = program.title || titleFromPath(programPath);
- document.title = `${title} — C64 BASIC Collection`;
- document.querySelector('#program-title').textContent = title;
+ document.title = `${program.title} — C64 Program Collection`;
+ document.querySelector('#program-title').textContent = program.title;
+ renderProgramDetails(program);
window.EJS_player = '#game';
window.EJS_core = 'vice_x64sc';
- window.EJS_gameUrl = `/api/program?path=${encodeURIComponent(programPath)}`;
- window.EJS_gameName = programPath.split('/').at(-1);
+ window.EJS_gameUrl = `/api/program?path=${encodeURIComponent(program.path)}`;
+ window.EJS_gameName = program.path.split('/').at(-1);
window.EJS_pathtodata = 'https://cdn.emulatorjs.org/stable/data/';
window.EJS_startOnLoaded = true;
window.EJS_language = 'en-US';
@@ -188,9 +255,17 @@ async function loadProgramPage(slug) {
}
}
+function setCategory(category) {
+ categoryFilter.value = category;
+ const url = category ? `/category/${slugify(category)}` : '/';
+ history.pushState({}, '', url);
+ renderPrograms();
+}
+
refreshButton.addEventListener('click', loadPrograms);
searchInput.addEventListener('input', renderPrograms);
-typeFilter.addEventListener('change', renderPrograms);
+categoryFilter.addEventListener('change', () => setCategory(categoryFilter.value));
+languageFilter.addEventListener('change', renderPrograms);
sortOrder.addEventListener('change', renderPrograms);
gridViewButton.addEventListener('click', () => setView('grid'));
listViewButton.addEventListener('click', () => setView('list'));
@@ -198,6 +273,12 @@ document.querySelector('#close-source').addEventListener('click', () => sourceMo
sourceModal.addEventListener('click', event => {
if (event.target === sourceModal) sourceModal.close();
});
+window.addEventListener('popstate', () => {
+ if (!library.hidden) {
+ populateFilters(allPrograms);
+ renderPrograms();
+ }
+});
function setView(view) {
const list = view === 'list';
@@ -217,4 +298,3 @@ if (legacyProgramPath) {
location.replace(`/program/${encodeURIComponent(slug)}`);
} else if (programPage) loadProgramPage(decodeURIComponent(programPage[1]));
else loadPrograms();
-
diff --git a/public/index.html b/public/index.html
index 97df76e..5e7b928 100644
--- a/public/index.html
+++ b/public/index.html
@@ -3,34 +3,42 @@
-
- C64 BASIC Collection
+
+ C64 Program Collection
- C64 BASIC Collection
+ C64 Program CollectionVICE x64sc · WebAssembly
Program library
Small programs. Pure 8-bit fun.
-
Explore a growing collection of games, puzzles, creative tools, and audiovisual experiments written in Commodore 64 BASIC. Pick something that catches your eye, run it instantly, or open the source to see how every line works.
+
Explore a growing collection of games, puzzles, creative tools, and audiovisual experiments written in Commodore 64 BASIC and 6502 machine code. Pick something that catches your eye, run it instantly, or open the source to see how it works.