From 974a40b33038f0469bfe565d8101703a1a19bb66 Mon Sep 17 00:00:00 2001 From: Miguel <67387789+Polar-404@users.noreply.github.com> Date: Thu, 30 Apr 2026 19:37:31 -0300 Subject: [PATCH 1/3] update README for the v0.1.0-alpha (#12) * Rename workflow from Rust Tests to Cargo Tests, Nestest * Revise README for SelectNES with badges and updates Updated project name and improved README structure with badges and additional information. --- .github/workflows/test.yml | 2 +- README.md | 93 ++++++++++++++++++++------------------ 2 files changed, 51 insertions(+), 44 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b67c782..43a4c94 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1,4 +1,4 @@ -name: Rust Tests +name: Cargo Tests, Nestest on: push: diff --git a/README.md b/README.md index def3be5..d045fa1 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,18 @@ -# NES Emulator +
+ +# SelectNES -**A Nintendo Entertainment System (NES) emulator built in Rust.** +[![Rust Tests](https://github.com/Polar-404/SelectNes/actions/workflows/test.yml/badge.svg)](https://github.com/Polar-404/SelectNes/actions/workflows/test.yml) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Rust](https://img.shields.io/badge/Rust-Stable-orange.svg)](https://www.rust-lang.org/) -![Rust](https://img.shields.io/badge/rust-%23000000.svg?style=for-the-badge&logo=rust&logoColor=white) ![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge) +**A Nintendo Entertainment System (NES) emulator built in Rust.** +
---- ## Showcase - -

SMB Gameplay with Debug Info

+| Super Mario Bros. | Kirby's Adventure | +| :---: | :---: | +Image | Image > [!NOTE] @@ -22,10 +27,10 @@ Make sure you have [Rust and Cargo](https://www.rust-lang.org/tools/install) ins ```bash # Clone the repository -git clone https://github.com/Polar-404/NES_Emulator.git +git clone https://github.com/Polar-404/SelectNES.git # Navigate to the directory -cd NES_Emulator +cd SelectNES # Compile and run cargo run --release @@ -33,23 +38,16 @@ cargo run --release ## Controls -| NES Button | Primary | Secondary | -| :-------------- | :-----: | :-----------: | -| **D-Pad Up** | `W` | `Up Arrow` | -| **D-Pad Down** | `S` | `Down Arrow` | -| **D-Pad Left** | `A` | `Left Arrow` | -| **D-Pad Right** | `D` | `Right Arrow` | -| **A** | `J` | `Z` | -| **B** | `K` | `X` | -| **Select** | `N` | `C` | -| **Start** | `M` | `V` | - -**System Commands:** -* **Volume Up:** `+` -* **Volume Down:** `-` -* **Pause/Menu:** `Esc` -* **Change Color Palette:** `.` (Period) -* **Paste ROM Path:** `Ctrl + V` +| NES Button | Primary | +| :-------------- | :-----------: | +| **D-Pad Up** | `Up Arrow` | +| **D-Pad Down** | `Down Arrow` | +| **D-Pad Left** | `Left Arrow` | +| **D-Pad Right** | `Right Arrow` | +| **A** | `Z` | +| **B** | `X` | +| **Select** | `C` | +| **Start** | `V` | --- ## Current Features @@ -67,38 +65,45 @@ cargo run --release - NROM (Mapper 0) - MMC1 (Mapper 1) - + + - MMC3 (Mapper 4) + +- Debug Tools: (Pattern Table viewer, Palette viewer e Hex Memory viewer) + --- ## Tech Stack -- **[Rust](https://www.rust-lang.org/):** Main language used for the project. - -- **[Macroquad](https://macroquad.rs/):** Core library for graphics rendering and input handling. - -- **[Cpal](https://github.com/RustAudio/cpal):** Library for audio processing and output. - -- **[Ringbuf](https://crates.io/crates/ringbuf):** Lock-free circular buffer for audio. - -- **[Arboard](https://crates.io/crates/arboard):** System clipboard access. - -- **Others:** `image`, `lazy_static`, `sysinfo`. - +- **[Rust](https://www.rust-lang.org/):** Main language used for the project, ensuring memory safety and high performance. + +- **Graphics & UI:** + - **[Glow](https://github.com/grovesNL/glow):** "GL on Whatever" — used for cross-platform OpenGL bindings. + - **[Egui](https://github.com/emilk/egui):** Immediate mode GUI library used for the debugging tools (PPU, Memory, and CPU viewers). + - **OpenGL:** Low-level rendering for the NES screen and implementation of custom shaders. + +- **[Cpal](https://github.com/RustAudio/cpal):** Low-level library for audio processing and output. +- **[Ringbuf](https://crates.io/crates/ringbuf):** Lock-free circular buffer for efficient audio synchronization. + +- **[Arboard](https://crates.io/crates/arboard):** Native system clipboard access for easy ROM path pasting. + +- **Others:** `image`, `rfd`, `serde`. + + --- ## Roadmap / To-Do As this is an ongoing learning project, several areas still need improvement: -- [ ] **User Interface:** Improve the start menu and add more graphics and audio configuration options. +- [x] **User Interface:** Improve the start menu and add more graphics and audio configuration options. - [ ] **Audio (APU):** Implement the DMC (Delta Modulation Channel). - [ ] **Synchronization:** Sync audio with FPS to maintain a more stable frame rate, faithful to the original console. -- [ ] **Mappers:** Add support for more mappers (e.g., MMC3) to increase game compatibility. +- [ ] **Mappers:** Add support for more mappers to increase game compatibility. -- [ ] **Saves:** Implement Save/Load states functionality. +- [x] **Saves:** Implement Save/Load states functionality. (only in-game saves so far, saving the emulator state isn't implemented yet) - [ ] **Code Quality:** Refactor and clean up the codebase, and potentially add documentation and internationalization (EN/PT-BR). @@ -108,15 +113,16 @@ As this is an ongoing learning project, several areas still need improvement: - [ ] **Scripting:** Implement user script support with Lua. -- [ ] **More Palettes:** Implement the ability for the user to insert their own palettes via interface and/or a designated folder with `.pal` files (maybe even `.hex` files). +- [x] **More Palettes:** Implement the ability for the user to insert their own palettes via interface and/or a designated folder with `.pal` files (maybe even `.hex` files). -- [ ] **Custom Graphics Pipeline:** Transition from Macroquad to OpenGL/Glow for +- [x] **Custom Graphics Pipeline:** Transition from Macroquad to OpenGL/Glow for - lower input latency - better frame synchronization. - Custom CRT/NTSC shaders. - [ ] **WebAssembly (WASM):** Browser-based emulation — play directly without installing anything. + --- ## Acknowledgments & References @@ -128,6 +134,7 @@ This project would not have been possible without the incredible emulation commu - **[bugzmanov/nes_ebook](https://github.com/bugzmanov/nes_ebook):** The e-book "Writing NES Emulator in Rust" was a fundamental reference. Parts of the CPU implementation and Design Patterns were heavily based on his code to understand Rust's nuances applied to emulation. + --- ## Licenses From 0ac9fa41027869b70f939d9360b72cfeb800ec83 Mon Sep 17 00:00:00 2001 From: Miguel <67387789+Polar-404@users.noreply.github.com> Date: Thu, 30 Apr 2026 19:48:20 -0300 Subject: [PATCH 2/3] Adjust image sizes in README Showcase --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index d045fa1..f1d0dec 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ ## Showcase | Super Mario Bros. | Kirby's Adventure | | :---: | :---: | -Image | Image +Image | Image > [!NOTE] From d36494550414db32d20275c28a7fed8ff583683d Mon Sep 17 00:00:00 2001 From: Miguel <67387789+Polar-404@users.noreply.github.com> Date: Thu, 30 Apr 2026 19:49:10 -0300 Subject: [PATCH 3/3] Update README with image display formatting --- README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index f1d0dec..65f8ac9 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,13 @@ ## Showcase +
+ | Super Mario Bros. | Kirby's Adventure | | :---: | :---: | -Image | Image +| | | +
> [!NOTE] > This project was created purely as a hobby, a personal challenge, and an opportunity to practice low-level programming and system architecture in Rust. So for the foreseeable future it is not intended to compete with established emulators but rather serves as a proof of concept and a deep learning experience regarding low-level programming and the NES hardware.