play-nes
v2.0.0
Published
Desktop NES emulator in Node.js
Readme
play-nes is a desktop NES emulator written in TypeScript and running on Node.js. It uses JSNES for emulation and sfml.js for native windows, graphics and audio. Local ROM files and keyboard input for two players are supported.
Screenshots
| Contra | Concentration Room | NESert Golfing | Interglactic Transmissing! | | :---: | :---: | :---: | :---: | | | | | |
Captured from the player on macOS.
Installation
Install from npm and launch a bundled game:
$ npm install -g play-nes
$ nes contraNode.js 22 is recommended. Installation also requires Python and a C++20 compiler because sfml.js builds a native addon.
| Platform | Toolchain | | :--- | :--- | | macOS 13+, Intel or Apple Silicon | Xcode Command Line Tools | | Linux x64 | GCC or Clang, make, X11, OpenGL and audio development libraries | | Windows x64 / ia32 | Visual Studio 2022 C++ Build Tools |
The sfml.js installation guide has the platform-specific commands. The supported Node.js range is ^18.19.0 || >=20.5.0.
A graphical desktop and an audio output device are required to run the player.
Usage
Pass a ROM path to nes:
$ nes "/path/to/your game.nes"The following aliases load the four bundled ROMs:
$ nes contra # Contra
$ nes croom # Concentration Room
$ nes dgolf # NESert Golfing
$ nes transmissing # Interglactic Transmissing!Controls
| NES button | Player 1 | Player 2 | | :--- | :---: | :---: | | A | J | Numpad 5 | | B | K | Numpad 6 | | Select | Right Shift | Numpad 8 | | Start | Enter | Numpad 9 | | Up | W | ↑ | | Down | S | ↓ | | Left | A | ← | | Right | D | → |
Press Esc or close the window to exit. The player releases held buttons when the window loses focus.
Edit keybindings.conf to change the controls. Values must use sfml.js key names. Restart the player to apply changes.
Options
$ nes contra --scale 3
$ nes croom -f 60 -s 2
$ nes --help| Option | Default | Description |
| :--- | :---: | :--- |
| -s, --scale | 2 | Scale the 256 × 240 frame; the default window is 512 × 480. |
| -f, --frameRate | 60 | Emulation and display rate, from 10 to 240 fps. |
| -h, --help | — | Show usage and exit. |
Use -f 60 for normal speed. This option controls emulation speed as well as the display rate, so increasing it also accelerates the game. Scale must be positive and produce whole-pixel window dimensions.
Development
To run from source:
$ git clone https://github.com/XadillaX/play-nes.git
$ cd play-nes
$ npm install
$ node bin/nes contra$ npm install installs dependencies and compiles src/ into dist/. Run $ npm run build after changing TypeScript. Use $ npm link to register the local checkout as the nes command.
$ npm run check # Check TypeScript types
$ npm run lint # Run ESLint
$ npm test # Build and run tests
$ npm run test:native # Open each bundled ROM and check video, input and audioWe use audio consumption to pace emulation. JSNES runs in an audio Worker and advances when SFML requests more PCM samples. The main thread draws the latest complete frame, so rendering does not block audio generation.
The threads exchange video frames and controller state through shared memory. The main thread reuses its texture and sprite to limit allocation, then yields between frames so Node.js can process I/O. The implementation is in emulator.ts, shared-state.ts and game.ts.
Contributing
For bug reports, open an issue with the ROM name, operating system, Node.js version, reproduction steps and any error output. Pull requests are welcome.
