A cross-platform, multi-system console emulator written in Rust. NES emulation is fully working with ~90% game coverage. GBA emulation is functional with most games working. 17 systems are supported in various stages of development — see System Status below.

• 🎮 Multiple Systems: 17 emulated platforms — see System Status for details
• 💾 Save States: 5 slots per game with menu-based save/load (Ctrl+1-5 / Ctrl+Shift+1-5)
• ⚙️ Persistent Settings: Customizable controls, window scaling, and project files
• 🖥️ Cross-Platform GUI: Built with SDL2 for Windows, Linux, and macOS
• 🎨 CRT Filters: Software and OpenGL-accelerated shader-based effects (scanlines, phosphor, full CRT)
• 🎵 Audio Support: Integrated audio playback via rodio
• 📁 ROM Auto-Detection: Automatically detects ROM formats and system types
• 🖱️ Modern Interface: Menu bar, status bar, Inspector panel for debugging

Legend:

• ✅ Fully Working - Production ready
• 🚧 In Development - Partial functionality
• ⚠️ Experimental - Early development

• 📚 Complete Documentation Site - User guides, developer references, system details
• 📖 User Manual - Controls, configuration, and usage
• 🏗️ Architecture Guide - System architecture and design patterns
• 🤝 Contributing Guide - Development workflow
• 🤖 Agent Guidelines - CI requirements and implementation guidelines

Download the latest release from the Releases page.

Linux Dependencies:

sudo apt-get install libasound2-dev cmake pkg-config

Build and Run:

# Clone the repository
git clone https://github.com/Hexagon/hemulator.git
cd hemulator

# Build (optimized for iterative development)
cargo build --profile release-quick

# Run the emulator
cargo run --profile release-quick -p emu_gui

# Or build for distribution
cargo build --release
./target/release/hemu path/to/game.nes

Pre-commit Checks (required before committing):

cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo build --profile release-quick
cargo test --workspace

The emulator supports ARM64 (aarch64) platforms including Raspberry Pi 5.

Pre-built ARM packages are available from GitHub Actions or can be built locally:

# Option 1: Build natively on ARM device (Raspberry Pi 5, etc.)
cargo build --profile release-quick

# Option 2: Cross-compile from x86_64 Linux using 'cross'
cargo install cross --git https://github.com/cross-rs/cross
cross build --profile release-quick --target aarch64-unknown-linux-gnu

# Option 3: Use GitHub Actions workflow
# ARM64 packages (.tar.gz and .deb) are automatically built on tagged releases

Dependencies on Raspberry Pi OS:

sudo apt-get install libasound2-dev cmake pkg-config libsdl2-dev

The ARM build produces both a standalone binary (hemu) and a Debian package (hemu_*_arm64.deb) for easy installation.

hemulator/
├── crates/
│   ├── core/              # Shared CPU implementations, audio/graphics utilities, traits
│   ├── systems/           # System implementations (NES, GB, SNES, N64, PC, etc.)
│   │   ├── nes/           # Nintendo Entertainment System
│   │   ├── gb/            # Game Boy / Game Boy Color
│   │   ├── gba/           # Game Boy Advance
│   │   ├── chip8/         # CHIP-8 variants
│   │   ├── sms/           # Sega Master System
│   │   ├── colecovision/  # ColecoVision
│   │   ├── sg1000/        # Sega SG-1000
│   │   ├── atari2600/     # Atari 2600
│   │   ├── atari5200/     # Atari 5200
│   │   ├── gameandwatch/  # Game & Watch (SM510)
│   │   ├── megadrive/     # Sega Mega Drive / Genesis
│   │   ├── snes/          # Super Nintendo
│   │   ├── n64/           # Nintendo 64
│   │   ├── ps1/           # Sony PlayStation 1
│   │   └── pc/            # IBM PC/XT
│   └── frontend/gui/      # GUI frontend (SDL2 + egui) - builds as 'hemu'
├── docs/                  # Documentation site source (Lumocs)
├── ARCHITECTURE.md        # Architecture documentation
└── AGENTS.md              # Agent/CI guidelines

See ARCHITECTURE.md for detailed architecture information and the documentation site for system-specific implementation details.

Contributions are welcome! Please see:

• Contributing Guide - Development workflow, coding standards, debug tools
• AGENTS.md - CI requirements and agent guidelines
• System READMEs - Implementation details for each system

MIT License - see the LICENSE file for details.

Founded and maintained by @Hexagon and @Oliodh.

This is a free and open source community project. Contributions from the community are crucial and invaluable.

Note: This emulator is for educational purposes. Users must provide their own legally obtained ROM files. The project does not include or distribute any copyrighted game data.