Learn about the Commodore 64 by coding in BASIC and 6502 assembler. A C64 emulator written from scratch in JavaScript, wrapped in a site that explains the machine it is emulating.
Live at turbo8bit.com.
| Route | What it does |
|---|---|
/ |
BASIC lab — type into a live C64 or write BASIC in the editor; a sample gallery, a live view of the running program, a screen inspector, and save/share/download |
/asm |
Assembly lab — assemble 6502, run or single-step it, and watch registers, flags, cycles and memory change |
/games |
Games — five complete games written in 6502 assembly, in the style of Space Invaders, Boulder Dash, Giana Sisters, R-Type and International Karate. Play them with the keyboard as a joystick, then read, change and rerun their source in the Assembly lab's editor |
/hardware |
Bus simulator — replays real bus traffic recorded from the emulator (boot, keyboard scan, VIC-II fetches, SID writes), plus a chip reference |
/memmap |
Memory map explorer — see how banking maps ROM, RAM and I/O into the same 64KB |
/sid |
SID player — play SID tunes (or your own .sid) with voice, note, oscilloscope, filter and register views, and mute/solo per voice |
/about |
What the site is and who made it |
These seven come from SITE_PAGES in web/main.py, which also drives
the nav and sitemap.xml. /robots.txt, /sitemap.xml and /auth/* are served
alongside them.
- Focus the C64 screen to use the emulated keyboard. Search fields, sample selectors and other page controls retain their normal keyboard behavior. Ctrl+V on the screen types the clipboard into the C64.
- The screen toolbar pauses, runs in Turbo, adds a CRT look, saves a snapshot and goes full screen. Pointing at the screen shows the inspector: the character's screen and colour RAM addresses, the POKEs that change it, an enlarged glyph, and the sprite X/Y of that spot.
- Programs submitted during startup wait for the real BASIC
READY.prompt; resetting cancels pending loads and synthetic typing. - Slow sample requests cannot overwrite a newer selection or edits made while the sample is loading.
- The BASIC editor runs the text currently in the editor, including edits to
direct-mode examples. Numbered programs load on a freshly reset C64; the
screen's RUN reruns the existing program without resetting. Direct-mode
commands retain the current machine state. Like the C64's own editor, lines
are sorted, a repeated line number replaces the earlier line, and a bare
number deletes it.
{CLR},{RED},{RVS ON},{3 DOWN}and{147}inside strings become PETSCII control codes. - Errors are marked in the editor gutter (with the message on hover) and in its status bar; the Assembly editor checks as you type.
- Each editor's File menu opens
.bas/.asm/.txt(and BASIC.prg, which is listed back to text), saves the source or a runnable.prg, and copies a share link that carries the whole program in the URL fragment. Edits are kept as a draft in localStorage and restored on the next visit. - Dropping a BASIC
.prgon the screen loads it likeLOAD(setting the variable pointers past it) and typesRUN; machine code is loaded and itsSYSaddress shown. - Assembly Stop returns to BASIC with a cold reset, so it also recovers from
halted CPUs, disabled interrupts and banked-out ROM. This clears emulated RAM
and ejects cartridges, but preserves the editor source. A program's normal
RTSdoes not reset the machine, and one that ends withBRKis noticed too. Pause a running program and Step continues from wherever it is; the memory viewer highlights the bytes each step changed. - The Games page is the Assembly lab with its own library. The arrow keys and Space are joystick 2, and each run (the editor's Run, or Play on a game's card) starts on a freshly reset C64, booted at turbo speed, and turns the sound on unless you have already chosen with the sound button. On both assembly pages, loading a sample or game asks first if it would replace code you have changed.
- The BASIC page's sample gallery shows every sample with a preview recorded on this emulator (stills when reduced motion is preferred); choosing one loads and runs it, asking first if it would replace code you have written. Play the demo reel runs the graphics samples in turn until you take over by typing, editing or pressing a control.
- Inside the program, under the BASIC editor, reads BASIC's own bookkeeping while a program runs: the line it is on (marked in the editor gutter), where the running time goes (a per-line profile that also glows in the gutter), the variables and arrays decoded from memory, and how BASIC has divided its memory between program, variables, arrays, free space and strings.
- Sound starts muted. If an audio device or song cannot be opened, the controls stay consistent with the actual playback state and show an error.
The Memory explorer follows all 32 CPU/cartridge banking configurations, including unmapped Ultimax regions. Its cells can be inspected with keyboard focus and Enter; keys 1, 2 and 3 toggle LORAM, HIRAM and CHAREN. Narrow screens scroll the table rather than collapsing its address columns. Decorative 3D chips pause offscreen and respect reduced-motion preferences.
Memory annotations are generated from the OCR-derived memory-map.txt by parse_memmap.py. The parser validates address ranges and decimal/hex agreement. Ambiguous headers are reported and omitted rather than assigned guessed addresses; the source still has unresolved JMPER and MEMSIZ headers.
Requires Python 3.13 (production runs App Engine's python313 runtime) and
PowerShell.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r web\requirements.txt
pip install pytest py_mini_racer pillow
.\dd.ps1 run # http://localhost:8082dd.ps1 is the entry point for everything:
| Command | Description |
|---|---|
.\dd.ps1 run |
Local dev server on http://localhost:8082 |
.\dd.ps1 test |
Run the test suite (pytest) |
.\dd.ps1 format |
Format Python with Black (-Check reports instead of rewriting) |
.\dd.ps1 gen |
Regenerate the header logo, favicons and social image from raw-images/favicon.png, and re-record the BASIC sample previews |
.\dd.ps1 crt |
Publish CRT cartridge files to Cloud Storage |
.\dd.ps1 deploy |
Deploy to Google App Engine (-NoPromote, -Version <ver>) |
.\dd.ps1 help |
Show all commands |
Sign-in and session cookies need secrets. Copy web/secrets.example.yaml to
web/secrets.yaml and fill it in — the file is git-ignored, app.yaml pulls it
in via includes:, and deploy refuses to run without it.
C64Emulator (emulator.js) SIDPlayer (sid-player.js)
canvas + Web Audio + keyboard Web Audio + tune visualisation
└────────┬────────┘
▼
C64Machine (machine.js)
the bus: read(addr) / write(addr, val)
├── MOS6510 6502/6510 CPU with per-instruction cycle counts
├── VIC-II scanline renderer, all 5 display modes, sprites
├── SID MOS6581/MOS8580 with DAC, filter and ADSR modelling
├── CIA1/CIA2 timers, IRQ/NMI lines, keyboard matrix, joysticks
├── 64KB RAM with $01 banking
└── ROM/IO BASIC $A000, KERNAL $E000, Char ROM, I/O $D000-$DFFF
Everything the CPU touches goes through C64Machine.read/.write, so banking,
I/O and cartridge mapping are decided in exactly one place.
Physical RAM is separate from I/O registers and color RAM, so storing beneath
banked-out I/O does not change the hardware. Debugger memory views use peek
to preserve read-sensitive interrupt and collision latches.
| Module | Purpose |
|---|---|
emulator.js |
C64Emulator — canvas rendering, Web Audio, keyboard, drag-and-drop. Entry point for /, /asm and /games |
sid-player.js |
SIDPlayer and PSID/RSID parsing. Entry point for /sid |
machine.js |
C64Machine — the bus, banking, CIA timers, keyboard matrix, frame loop |
mos6510.js |
The CPU. All 256 opcodes including the undocumented ones |
vic-ii.js |
Scanline graphics renderer and sprites |
sid.js |
SID chip, DAC modelling and resampling |
voice.js / filter.js |
Oscillators, ADSR envelopes, and the 6581/8580 filters |
psid-driver.js |
The small 6502 driver that runs a SID tune's init/play routines |
cartridge.js |
CRT format and bank switching |
assembler.js |
6502 assembler and disassembler |
basic-tokenizer.js |
BASIC V2 tokenizer and syntax highlighting |
debugger.js |
Stepping, breakpoints and memory inspection |
editor.js |
Syntax-highlighted code editor |
roms.js |
BASIC, KERNAL and character ROM data |
Page tools outside the emulator folder build on it without changing it:
| Module | Purpose |
|---|---|
lab/screen-tools.js |
Pause, turbo, CRT, snapshot, full screen, paste, and the screen inspector |
lab/memory-viewer.js |
The Assembly page's live hex dump |
lab/program-files.js, lab/files.js |
File menu, drafts and share links |
lab/basic-monitor.js |
Reads BASIC's state from memory: running line, variables, arrays, memory layout |
lab/program-view.js |
The BASIC page's live program view and line profiler |
lab/sample-gallery.js |
The BASIC page's sample gallery and demo reel |
bus-trace.js |
Records real bus accesses for the hardware page's diagram |
The gallery's previews in web/static/basic/previews/ are recorded by
gen_sample_previews.py, which runs each sample
on the emulator (scripting a short session for the ones that wait for input)
and keeps border and background flashes under three a second. Re-record after
changing a sample with .\dd.ps1 gen, or
python tools/gen_sample_previews.py <id> for just one.
The assembler accepts labels with or without a colon (in column one), ORG or
*=, NAME = value / EQU constants, expressions with $hex, %binary,
'c', * (current address), + - * /, parentheses and </> byte selection,
and BYTE/WORD/TEXT/ASCIIZ data (also as .byte or ACME's !byte).
Quoted text is stored as PETSCII as typed on a C64.
The games in web/static/games/ are one self-contained .asm file each,
listed in its index.json along with the text of the page's game cards. They
share a shape, so reading one helps with the rest: code from $0810
(SYS 2064), the ROM font copied to $3800 with the game's own characters
after it, a raster interrupt that paces a main loop at 50 frames a second, a
table-driven sound effects player (Jumpin' Jo, Nova Strike and Dojo Duel keep
it on voice 3 and play two-voice music on the others), and the settings to
play with as constants at the top. The comments at the top of each file explain what to
look for and what to try changing.
CPU — all 151 documented opcodes plus the undocumented ones (LAX, SAX, DCP,
ISB, SLO, RLA, SRE, RRA, ANC, ALR, ARR, SBX, LXA, LAS, ANE, SHA/SHX/SHY/TAS and
the JAM opcodes), with per-instruction cycle counts including page-crossing
penalties, BCD arithmetic, and the JMP ($xxFF) page-wrap bug.
VIC-II — rendered a scanline at a time, so raster interrupts can change
registers mid-frame and split-screen effects work. All five display modes
(standard and multicolor character, standard and multicolor bitmap, extended
background colour), 8 hardware sprites with multicolor, X/Y expansion, priority
and collision latches, plus smooth scrolling (each text row starts on its Bad
Line), 24-row and 38-column border masking, screen blanking with DEN, VIC bank
selection and Bad Line CPU stalling. The border hides sprites without stopping
their collisions, and unconnected register bits read as 1 (so PEEK(53280) is
254 after start-up, as on a real C64).
SID — 6581 and 8580 waveform generation with combined-waveform tables and
noise-register writeback, ADSR envelopes (including the 8-bit counter wrap some
players trip), ring modulation and oscillator sync, and non-linear waveform and
envelope DACs. The filter, mixer and DC levels follow reSID 0.16's linear model:
each chip's measured cutoff curve, resonance that peaks at the cutoff without
cutting the passband, and the 6581's DC offsets, which are what make
volume-register ($D418) samples audible. The C64's output stage follows, then
a two-stage windowed-sinc resampler brings the 1 MHz stream to the audio rate
without folding ultrasonic harmonics back into it, and a soft limiter catches
rare peaks. libsidplayfp's non-linear 6581 op-amp filter is not modelled.
Register writes are timestamped by CPU cycle and applied at the right point in
the sample stream.
Both audio frontends consume interleaved machine frames. The SID player retains
unused frame samples between output requests, and validates tune metadata,
payload bounds and driver relocation space before replacing the current tune.
CIA — Timer A/B on both chips in one-shot and continuous modes, Timer B counting Timer A underflows, IRQ from CIA1 and NMI from CIA2 (used by digi playback), the 8×8 keyboard matrix scanned in both directions, and two joysticks.
Cartridges — the CRT container format (CCS64/VICE), with bank switching
through the $DE00-$DFFF I/O window for the common hardware types (Normal,
Ocean, Action Replay, Final Cartridge III, EasyFlash and others) and EXROM/GAME
line handling for 8K, 16K and Ultimax modes. Drop a .crt or .prg onto the
emulator screen to load it.
Timing is accurate per instruction rather than per cycle: the CPU runs whole instructions and the VIC-II steals a flat 40 cycles on a Bad Line, so effects that depend on sub-instruction bus timing or sprite DMA will not be exact.
Tests run the emulator's JavaScript inside Python using py_mini_racer, so the CPU, SID, VIC-II and cartridge code are all covered without a browser.
.\dd.ps1 testSome cartridge tests skip unless the matching CRT dump is present locally — CRT files live in Cloud Storage rather than in the repo.
Current baseline: 694 passed, 25 skipped, 0 failed (719 collected), with no unchecked boolean-return test warnings.
The suite also covers browser-wrapper audio/input/lifecycle behavior using
small DOM and Web Audio substitutes, fresh-boot loading against the real
machine, sample-selection races, SID page error/retry paths, and Flask routes.
Every BASIC sample is run on the emulated C64 and must finish without a BASIC
error, and must have a description and recorded previews; every game must
assemble, take over the interrupt, and still be running after fire starts it; the program view's
decoding is checked against what BASIC's own PRINT shows; and the hardware
page's traces are checked against what the KERNAL really does.
These tests need no browser or extra frontend dependencies. Real-browser checks
remain important for native keyboard/undo behavior and responsive layout.
When changing the lab layout, check a 300-line program at desktop and phone
widths: the editor should scroll internally and never overlap the reference
section or stretch the entire workspace to the source's height.
Check validation feedback too: wrapped mobile controls must not clip the status
row below the code area.
MIT
