Thank you for using RustyNES! This document provides guidance on how to get help and support.
-
Check the Documentation
- README.md - Project overview and quick start
- docs/ - Comprehensive documentation
to-dos/ROADMAP.md- Current development status (the rootROADMAP.mdis a pre-1.0 historical snapshot)- FAQ - Common questions (below)
-
Search Existing Resources
- GitHub Issues - Known bugs and feature requests
- GitHub Discussions - Community Q&A
- Closed Issues - Previously resolved issues
-
Verify You Have the Latest Version
git pull origin main cargo build --release --workspace
For questions, ideas, and general discussion:
Use discussions for:
- General questions about RustyNES
- Usage help ("How do I...?")
- Feature ideas and brainstorming
- Showing off your projects using RustyNES
- Community chat
Categories:
- Q&A: Ask questions and get answers
- Ideas: Share feature ideas and enhancements
- Show and Tell: Share your projects and screenshots
- General: Everything else
For bug reports and concrete feature requests:
Use issues for:
- Bug reports (crashes, incorrect behavior)
- Specific feature requests
- Documentation errors
- Build problems
Do NOT use issues for:
- General questions (use Discussions)
- Support requests (use Discussions)
- Vague ideas (use Discussions first)
NESdev Community (for general NES emulation questions):
Rust Community (for Rust language questions):
Q: What is RustyNES?
A: RustyNES is a cycle-accurate NES emulator written in pure Rust, clearing the Mesen2 / higan / ares accuracy bar, with advanced features like netplay, TAS tools, and RetroAchievements.
Q: Can I use RustyNES now?
A: Yes. RustyNES is well past its first stable release — the current release is v2.6.4 "Rubric" (OAM DMA lands and all nine AccuracyCoin disagreements close, every rule that closed the last three stated by the test ROM and by neither nesdev page — and then the gate that certified them is measured to cover 88 of 146 entries. The emulation core is unchanged, on v2.6.3 "Mainspring" — the DUT runs on one master clock, and four enables that were never enabling — plus AccuracyCoin end to end and a status vector that names its disagreements by test. The emulation core is unchanged, on v2.6.2 "Witness" — rung 4 closes: blargg APU battery 11/11 on the co-simulation DUT, six defects no self-written gate could see, and a suite that had been asserting nothing for five minor releases. The emulation core is unchanged, on v2.6.1 "Interleave" — the DMC and its DMA cycle steal in the MiSTer co-simulation DUT, cycle-exact on the bus. The emulation core is unchanged, on v2.6.0 "Assay" — the triangle, the noise channel and the sweep unit in the MiSTer co-simulation DUT — and an audit of how much of the APU was fitted to the oracle rather than derived from documentation. The emulation core is unchanged, on v2.5.9 "Overture" — rung 4 opens: the two pulse channels, the frame counter, and four ROM defects the stimulus measurement found first, on v2.5.8 "Blanking" — VBlank, NMI and the PPUSTATUS race close rung 3 — and both fixes were deletions, on v2.5.7 "Collimation" — sprite rendering closes exact — the phase was wrong by two dots, and every window was compensating, on v2.5.6 "Vestige" — Sprite evaluation closes: all 59,993 overlapping cycles match, nine of nine behavioural mutants caught and two proved inert (announced as seven of eight at the cut), and the fix is a byte index that outlives the walk that set it, on v2.5.5 "Raster" — the first full frame, and three blind spots in the stimulus that fed it, on v2.5.4 "Escapement" — the background fetch pipeline, and an access two dots early that five gates could not see, on v2.5.3 "Hysteresis" — toggling rendering takes effect three dots after the write, and four instruments to prove it, on v2.5.2 "Dormant" — the 2C02 register file, and a gate that passed while testing nothing, on v2.5.1 "Retrace" — the interrupt sweep closes rung 2, and a gate reported a pass it could not have earned, on v2.5.0 "Rungwork" — the 6502 rung, and the two gates it cannot reach, on v2.4.9 "Plumbline II" — the bus half of rung 2, and what it found the day it existed, on v2.4.8 "Palimpsest" — read-modify-write, and a gate that cannot see its own subject, on v2.4.7 "Keystone" — the stack closes, and a dead line proves itself dead, on v2.4.6 "Abacus" — the core learns arithmetic, on v2.4.5 "Compass" — the core reaches memory, and chooses, on v2.4.4 "Ignition" — the first real RTL of the co-simulation programme, on v2.4.3 "Touchstone", the two Fabric risks settled before any RTL, on v2.4.2 "Cairn", the rung-0 compare surface of the v2.4.1 → v2.5.0 "Fabric" line, on v2.4.1 "Fabric" and the never-tagged v2.4.0 "Concordance", atop the v2.0.0 "Timebase" one-clock scheduler base), a complete, playable desktop application plus native Android / iOS / Libretro builds and a browser build. See to-dos/ROADMAP.md for what shipped and the forward directions.
Q: How accurate is RustyNES?
A: AccuracyCoin 100% (141/141) — every assigned test passes, including the two newest upstream PPU tests ("ALE + Read", "Hybrid Addresses"), which the v2.0.3 2-cycle-ALE PPU-fetch promotion closed — nestest 0-diff, and the blargg / kevtris suites green, validated by a byte-identical commercial-ROM regression oracle. See docs/STATUS.md for the authoritative pass-count matrix.
Q: How can I contribute?
A: See CONTRIBUTING.md for contribution guidelines. We welcome code, documentation, testing, and design contributions.
Q: Is RustyNES open source?
A: Yes! RustyNES is licensed under GPL-3.0-or-later. You're free to use, modify, and distribute it under the terms of that license (including making source available for derivatives).
Q: What platforms are supported?
A: Native Windows, Linux, and macOS, plus a WebAssembly / GitHub Pages browser build — all from one winit + wgpu + cpal + egui frontend.
Q: What ROMs are supported?
A: iNES and NES 2.0 ROM formats across 174 mapper families (including expansion audio) plus the UNIF (.unf) container, the Famicom Disk System (real-BIOS boot), and Vs. System / PlayChoice-10 arcade hardware. Additional mapper families are added demand-driven; see to-dos/ROADMAP.md.
Q: Does RustyNES support [feature]?
A: The feature set includes rollback netplay (2–4 players), RetroAchievements (opt-in), TAS movie record/playback, save-states, rewind, run-ahead, Game Genie + raw-RAM cheats, an egui debugger, Lua scripting, a TAS editor, HD packs, and shader/NTSC filters — plus native Android / iOS / Libretro builds. Check to-dos/ROADMAP.md for delivered milestones and forward directions.
Q: Can I embed RustyNES in my project?
A: Yes! The rustynes-core crate is designed to be embeddable. See the rustynes-core rustdoc (cargo doc -p rustynes-core --open) for the library API.
Q: How do I build RustyNES?
A: See docs/dev/BUILD.md for detailed build instructions. Quick start:
git clone https://github.com/doublegate/RustyNES.git
cd RustyNES
cargo build --release --workspaceQ: What are the prerequisites?
A: Rust 1.96 (pinned in rust-toolchain.toml; rustup auto-installs it) and the winit + wgpu + cpal system libraries (libxkbcommon / wayland / alsa / udev on Linux; nothing extra on macOS/Windows). See docs/dev/BUILD.md for platform-specific instructions.
Q: Build is failing, what do I do?
A:
- Ensure you have Rust 1.96 or newer:
rustc --version - Install the frontend system libraries (see BUILD.md)
- Try a clean build:
cargo clean && cargo build --workspace - Check GitHub Issues for known build problems
- Ask for help in Discussions
Q: Can I use RustyNES on [my platform]?
A: Check the Platform Support section in the README. If your platform isn't listed, ask in Discussions about porting feasibility.
Q: How do I load a ROM?
A: cargo run --release -p rustynes-frontend -- path/to/rom.nes (binary: rustynes), or launch with no ROM and use the File menu / F12 / drag-and-drop.
Q: What are the default controls?
A: See the Controls Table in the README. Controls will be configurable in the settings.
Q: Where are save files stored?
A: Save files are stored in platform-specific directories following OS conventions. See the save-states guide for details.
Q: Can I use a gamepad?
A: Yes. USB gamepads auto-bind to player 1 (Xbox-style: South = A, West = B, Start, Back = Select, D-Pad) and are rebindable. Most standard controllers (Xbox, PlayStation, Switch Pro, etc.) work.
Q: How is the codebase structured?
A: RustyNES is a Cargo workspace of rustynes-* crates (cpu / ppu / apu / mappers / core / frontend, plus netplay / cheevos / test-harness). See ARCHITECTURE.md for the complete architecture overview.
Q: Where do I start if I want to contribute?
A:
- Read CONTRIBUTING.md
- Check good first issue labels
- Ask in Discussions what needs help
Q: What coding standards does RustyNES follow?
A: See docs/dev/STYLE_GUIDE.md for detailed style guidelines. TL;DR: cargo fmt and cargo clippy -- -D warnings.
Q: How do I run tests?
A: See docs/dev/TESTING.md for the complete testing guide. Quick start: cargo test --workspace
Q: Where can I find reference documentation?
A: The docs/ folder contains comprehensive documentation covering CPU, PPU, APU, mappers, testing, and more. Start with docs/DOCUMENTATION_INDEX.md.
If you've found a bug, please create an issue with:
- Clear description of the bug
- Steps to reproduce
- Expected vs. actual behavior
- System information
- ROM information (if applicable)
- Logs/screenshots
See the bug report template for the complete format.
For feature requests, please create an issue with:
- Clear description of the feature
- Problem it solves
- Proposed solution
- Use cases
- Impact analysis
See the feature request template for the complete format.
This is a volunteer-driven project. Please be patient while waiting for responses:
- Critical bugs: 1-3 days
- Bug reports: 3-7 days
- Feature requests: 1-2 weeks
- Questions in Discussions: 1-7 days (community may respond faster)
- Pull requests: 3-14 days
All community interactions must follow our Code of Conduct. Please be respectful, constructive, and welcoming.
Report violations privately to: parobek@gmail.com
| Document | Description |
|---|---|
| README.md | Project overview |
| OVERVIEW.md | Philosophy and goals |
| ARCHITECTURE.md | System design |
| ROADMAP.md | Development plan |
| docs/ | Complete documentation |
| Resource | Link |
|---|---|
| NESdev Wiki | https://www.nesdev.org/wiki/ |
| NESdev Forums | https://forums.nesdev.org/ |
| 6502 Reference | https://www.nesdev.org/obelisk-6502-guide/ |
| TASVideos | https://tasvideos.org/ |
| RetroAchievements | https://retroachievements.org/ |
RustyNES draws inspiration from:
- Mesen2 - Accuracy and debugging
- FCEUX - TAS tools
- puNES - Mapper coverage
- TetaNES - Rust implementation
- Pinky - PPU rendering
- GitHub Issues: Bug reports and feature requests
- GitHub Discussions: Questions and community chat
- Email: parobek@gmail.com (for security issues and private matters only)
Thank you for using RustyNES! We're excited to have you in the community.