A cross-platform, multi-system console emulator written in Rust. NES emulation is fully working with ~90% game coverage. Other systems (Game Boy, CHIP-8, SMS, ColecoVision, SG-1000, Atari 2600, SNES, N64, PC/DOS) are in various stages of development.

• 🎮 Multiple Systems: NES, Game Boy, CHIP-8, SMS, ColecoVision, SG-1000, Atari 2600, SNES, N64, PC/DOS
• 💾 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

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
│   │   ├── chip8/         # CHIP-8 variants
│   │   ├── sms/           # Sega Master System
│   │   ├── colecovision/  # ColecoVision
│   │   ├── sg1000/        # Sega SG-1000
│   │   ├── atari2600/     # Atari 2600
│   │   ├── snes/          # Super Nintendo
│   │   ├── n64/           # Nintendo 64
│   │   └── 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.