=== Rust 6502 ===
A legendary 8-bit CPU right in your terminal! 🦀 ᕙ( •̀ ᗜ •́ )ᕗ
== What did you make ? ==
I built a fully functional emulator for the MOS 6502 (the microprocessor that powered the Apple II, Commodre 64, and the NES) from scratch using Rust !
Instead of a standard graphical window, I built a Terminal User Interface (TUI) using Ratatui.
Here is what's inside:
- Full CPU Emulation: Execute 6502 machine code with live register (AC, XR, YR, SP) and status flag tracking
- Virtual Screen: A 32x32 memory-mapped display ($0200-$05FF) rendered right in the terminal using Unicode Half-Block and a custom 16-color palette
- Live Disassembler & Hex Viewer: Watch the RAM change in real-time and see the raw binary machine code translated back into readable assembly instructions on the fly
- Built-in File Browser: A visual menu with Nerd Font icons to navigate your system and load compiled .bin ROMs
- Available on crates.io : You can download it via Cargo
== What was challenging ? ==
- The Disassembler: Writing a disassembler that parses raw .bin files is tricky because they don't have headers. I ran into a massive issue where my image data (using the color byte $0A) was being read by the disassembler as infinite ASL A (Shift Left) instructions! I had to engineer a way for the disassembler to properly halt when it hit a BRK instruction so it wouldn't try to execute my pixel art.
- Terminal UI Architecture: Designing a dashboard (hex grids, scrolling stacks, changing colors) required a really solid state-management architecture to keep the UI smooth and responsive while the CPU loop spins at thousands of instructions per second.
== What are you proud of ? ==
I am proud of using this project to learn Rust in a fun way!
ദ്ദി(˵ •̀ ᴗ - ˵ ) ✧
I'm also really proud that it's officially published on crates.io, meaning anyone can install and run my emulator with a single command
== What should people know so they can test your project ? ==
Note: A Nerd Font is recommended in your terminal emulator for a proper rendering of the UI icons on the Home page
How to test:
- Install the emulator directly from crates.io by running:
cargo install rust6502
- Download all the .bin files on the GitHub Releases page.
- Launch the emulator by running rust6502 and use the built-in Home menu to select one of the demo .bin files!
== Things to try ==
- Load hackclub_logo_demo.bin to see the terminal render a 32x32 pixel art logo using 6502 assembly
- Load rainbow_demo.bin to watch a shifting color gradient animation directly manipulating video memory.
- Load helloworld_demo.bin to watch a centered Hello world message
- The Debugger: go to the Settings menu inside the TUI and slow down the CPU speed. Then watch the Memory Viewer and Disassembler track exactly what the code is doing in real-time!
- 44 devlogs
- 36h
