3ric

3ric

A from-scratch, Apple-II-class 65C02 personal computer — real hardware plus a cycle-honest emulator that also runs in your browser.

▶ Try it now — no install, no account

Built from Bits: the Hackaday showcase is a one-minute tour of the machine: a hi-res starfield, 16-color plasma, a rotating wireframe, and an original six-voice stereo chiptune, all running as real 65C02 code. Run and remix the demo at 1x, then click the emulator for sound. Use 1-4 for scenes, Space to pause, M to mute, and Q/Esc to return to the monitor. Source and .PRG / .woz exports are available in the editor; the program targets 3RIC, not an unmodified Apple II.

https://ebadger.github.io/3ric/ runs the entire machine client-side via WebAssembly. Click the canvas and start typing at the DOS > prompt (MON enters the monitor's * prompt). Then:

• Boot Disk — boot the demo 5.25″ floppy (a self-booting machine-code disk).
• Mount SD — mount the micro-SD card and use the ROM's DOS shell (DIR, etc.).
• Play Dirt Bike — ebadger.github.io/3ric/?brun=DIRTBIKE/DIRTBIKE.PRG boots Arnaud Verhille's Apple II motocross from the SD card through the ROM DOS (CD DIRTBIKE, BRUN DIRTBIKE.PRG 0800). It takes about 10 seconds to load; play with the keyboard or a gamepad.
• Assemble & Run — open the built-in 65C02 editor, write assembly, and run it like BRUN — all in the browser. Programs are shareable via a ?src= deep link.

What is 3ric?

3ric is a personal learn-by-building project: an 8-bit computer designed at the chip level — KiCad schematics, a custom PCB, and 74-series address-decode logic — paired with a C++ emulator of the exact same machine. The emulator compiles to WebAssembly, so the same VM core that models the real hardware also boots the unmodified 512 KB ROM in any browser. The whole journey is documented in a YouTube build series.

Why it exists: to understand, build, document, and demonstrate how an Apple-II-class computer works end to end — and to let anyone poke at it with zero friction. See docs/MISSION.md.

Features

• 65C02 CPU with a faithful memory map and soft switches, adjustable clock speed.
• Video: 40×24 text, lo-res, and hi-res color, rendered to a canvas.
• Input & I/O: keyboard ($C000/$C010), 6551-style ACIA serial, 6522 VIA.
• Disk II 5.25″ floppy via .woz images (self-booting machine-code disks).
• Micro-SD storage: a bit-banged SPI FAT32 card with a ROM DOS shell.
• In-browser 65C02 assembler/editor — assemble & run, download a .PRG, share ?src= links; ships ~11 sample programs.
• AI-generated 6502 games (STAR DUEL, Snake, Life, Minesweeper, 2048, Star Swarm, and more) built through the project's own codegen pipeline — see emulator/AICodeGen/.
• Runs everywhere the same way: one shared C++ VM core drives both the native Windows build and the browser (WebAssembly) build.

Write your first program in the browser

1. Open the live emulator and pick a sample from the editor's program menu.
2. Edit the assembly, hit Assemble & Run, and watch it execute on the machine.
3. Use Download .PRG to save it, or copy the ?src= link to share the exact program.

Prebuilt samples live in web/programs/; their source and design notes are under emulator/AICodeGen/ and codegen/.

Build from source

Full, current instructions are in status/SYSTEM-STATUS.md.

Native emulator (Windows): open emulator/Badger6502VM.sln in Visual Studio 2022 and build/run the Console or WinUI (Badger6502Emulator) host.

Browser / WebAssembly build (emsdk 6.0.1, Node, Python 3):

pwsh web/build.ps1     # Emscripten -> web/badger6502.js + .wasm, stages data/
pwsh web/serve.ps1     # serves http://localhost:8011/index.html

Verify it's healthy (headless smoke tests — no WASM build needed for the first one):

$node = "C:\Users\ebadger\emsdk\node\22.16.0_64bit\bin\node.exe"
& $node codegen/tools/asm6502.test.mjs   # assembler encoding tests
& $node web/test_boot.cjs                # ROM boots to a sane state

How it works

flowchart TD
    ROM["6502 ROM + software<br/>(badger6502.bin, fontrom.dat, .s / .prg)"]
    VM["Emulator core — 65C02 VM in C++<br/>(WozLib floppy · MockMicroSD · video/keyboard/ACIA/VIA)"]
    NATIVE["Native hosts<br/>(Windows / Console)"]
    WASM["Emscripten bridge → WebAssembly"]
    BROWSER["Browser client (index.html)<br/>→ GitHub Pages"]
    CODEGEN["Codegen<br/>(asm6502 + headless harness)"]
    HW["Hardware<br/>(KiCad · 74-series logic · logisim)"]

    ROM --> VM
    VM --> NATIVE
    VM --> WASM --> BROWSER
    CODEGEN -->|assembles & tests on the same VM| VM
    HW -. mirrors the same memory map .-> VM

The memory map is a shared contract: emulator/Badger6502VMLib/vm.h is mirrored by the hardware decode schematic, the web bridge, and the codegen platform reference. The architecture and each layer are documented in specs/ — start with specs/SYSTEM.md.

Repository layout

Known gaps

• DOS 3.3 / Applesoft disks don't run. This clone's $E000 BASIC is generic Microsoft BASIC, not Applesoft, so games that chain through an Applesoft auto-run greeting won't boot. Self-booting machine-code disks work.

Contributing

Contributions and experiments are welcome — especially new 6502 programs for the gallery.

Add a program (the easy path). No C++, no local build: have an AI coding tool write a 65C02 program by pointing it at llms.txt, test it in the browser editor, and open a one-file pull request to the Community Gallery. Step-by-step, with a copy-paste prompt: CONTRIBUTING.md.

Change the machine itself. A few house rules keep it trustworthy:

• Specs before code. Update the relevant spec in specs/ in the same change.
• Trace every layer a change touches (ROM/software → C++ VM core → web bridge/WASM), and keep the native and browser builds behavior-identical.
• Open a PR — changes land via pull request, not direct pushes to main.

The full workflow rules live in docs/LEARNINGS.md; bug reports use the templates under .github/ISSUE_TEMPLATE/.

The build series

3ric is built in public. Watch the design and construction, episode by episode: YouTube build series.

The porting logs tell the software side of that story: A2Robots, Spy vs Spy, Spy Hunter, and Pitfall II, with the changes, failed experiments, hardware evidence, and lessons for future sessions.

Support

If this project helps you learn or you just enjoy the build, please consider sponsoring it on GitHub — or use the Sponsor button at the top of this repository (see .github/FUNDING.yml). Sponsorship funds parts, boards, and more build videos, and every sponsor is credited in BACKERS.md.

License

3ric is dual-licensed:

• Software — MIT.
• Hardware designs & documentation — Creative Commons Attribution-ShareAlike 4.0 International.

Bundled third-party components keep their own licenses, and some bundled data (the ROM's Microsoft BASIC, Apple II disk images used as test fixtures) is third-party copyrighted material not licensed by this project. The emulators' micro-SD card holds Dirt Bike, a separate game under the GNU GPL v3, modified for 3RIC (see emulator/Data/sd-card/). See NOTICE for the full breakdown before redistributing.