Blackbox is an NES emulator app for iOS, iPadOS, macOS, and visionOS.
It’s a work in progress by Grady Haynes and is freely available under the MIT license. Feedback and contributions are welcomed. It requires a minimum of iOS/iPadOS 16.4, macOS Ventura 13.3, or the visionOS 1.0 simulator. Building Blackbox requires Xcode 14. (visionOS support requires the Xcode 15 beta.)
Blackbox is a hobby project for experimentation and learning, but I’d be delighted for anyone to use it, learn from it, or reuse its code in another project.
It’s named for the classic “black box” games released alongside and soon after the NES’s release in North America in 1985.
Blackbox is not the best way to play NES games on its supported platforms, at least not currently. It isn’t compatible with most games and has no audio emulation. That said, I’ve had a great time playing through Super Mario Bros. several times during its development!
If your primary goal is playing NES games on Apple platforms, I’d suggest checking out OpenEmu for Mac, Delta for iOS, or Provenance for iOS and tvOS.
To play a game on Blackbox, you’ll need to open a .nes file (a “ROM”) for the game. I can’t provide copyrighted ROMs, but there are many sources on the internet that can provide more information, including how to “dump” a ROM from a cartridge you own.
A freely-distributable sample ROM is included in the app so the app can be tested. See “Acknowledgments” section below for details on it.
Blackbox uses the SwiftUI app lifecycle. It includes:
- Game controller and keyboard support leveraging the system Game Controller framework
- An onscreen virtual touch controller available as a Swift package
- A set of “accessories” providing realtime information on the emulated NES’s CPU state and the PPU’s palettes and pattern tables
- An onboarding/usage workflow
- Support for opening NES ROM files (iNES format), including a recents list
- A sample ROM for testing
It’s built on top of CoreBlackbox, a module that provides the following:
- A 6502 emulator, “CPU6502”, written in Swift
- Aside from cycle timing, this is an accurate emulator, including “illegal” instructions.
- A Swift wrapper around the C-language
m6502CPU emulator from floooh’s “chips” project- This is useful during testing/debugging as it’s a “known good”, cycle-accurate, cycle-stepped 6502 emulator.
- Emulation of the NES’s Picture Processing Unit (PPU)
- (Very) basic mapper support
- Loading and parsing iNES files (ROMs)
More of the above components may be separated into their own Swift packages in the future. If you have suggestions for what would be particularly useful, please let me know.
Blackbox does not make any network calls; no personal data is recorded or sent by the app.
This project relies heavily on some fantastic resources, most prominently those below. I’m grateful for their work.
- Javidx9’s NES Emulator From Scratch channel on YouTube was tremendously helpful, particularly when building the PPU emulation.
m6502from floooh’s “chips” project is a well-crafted set of highly-accurate 8-bit chip emulators. The project’s 6502 emulator is used in this project for testing and debugging. This document describing it was enlightening reading.- RussianManSMWC’s Donkey Kong NES disassembly saved hours of debugging time while getting the project’s components connected.
- The included “Sample ROM” is
NES-ca65-exampleby Brad Smith. Assembly source is available at the link. - Toffer D. Brutechild beta tested and gave valuable feedback, ideas, and encouragement.