How to install the plastic crate // Lib.rs

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install plastic

It will make the plastic command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall plastic uninstalls.

Back to the crate overview.

Readme

NES emulator in Rust

plastic is a NES emulator built from scratch using Rust.

This is a personal project for fun and to experience emulating hardware and connecting them together.

Building and installation

Dependencies

For linux, this project depends on alsa and libudev, you can install them using:

# Debian/Ubuntu
sudo apt install libasound2-dev libudev-dev
# Arch
sudo pacman -S alsa-lib systemd-libs

Installing

You can install the latest version of plastic or plastic_tui using cargo:

cargo install plastic
cargo install plastic_tui

If you are using Debian/Ubuntu, you can directly install the .deb package from here

unzip plastic.deb.zip
sudo dpkg -i plastic_*.deb # will have the version in the name

If you are using Arch Linux, plastic is available in the official repositories:

pacman -S plastic
pacman -S plastic_tui

Building

If you want to experience the latest development version, you can build Plastic yourself. For example:

cargo run --release

Components

6502 CPU, all official and unofficial instructions with accurate timing (without BCD mode).
Picture Processing Unit, almost accurate with some small timing issues that would not effect most games.
Cartridge and INES file handling (still missing INES2.0)
Mappers:
- Mapper 0
- Mapper 1
- Mapper 2
- Mapper 3
- Mapper 4
- Mapper 5 (Milestone)
- Mapper 6
- Mapper 7
- Mapper 8
- Mapper 9
- Mapper 10
- Mapper 11
- Mapper 66
Audio Processing Unit:
- 2 Pulse wave(square)
- Triangle
- Noise
- DMC
- IRQ support
Controller: controllable using the keyboard and controller (tested with PS4 controller)

Interfaces

The main emulator is at plastic_core And its a struct NES, where the UI would clock it, and then take the resulting audio and pixel buffers to handle them.

We have 2 UIs, one main and the other just for fun.

EGui UI

Simple ui built with egui

Advantages

Very simple and easy to use immediate mode UI.

TUI

This is just for fun, but it is actually working way better than I expected. Check the full demo.

If you have one of these terminals mentioned in this docs Then you will have a much better experience, since these terminals support detecting button Release, normally other terminals don't have this feature, so the input for this UI can be a bit wonky.

I used gilrs for gamepad support and its working very nicely, keyboard on the other hand is not very responsive, so it is advised to use gamepad. Also since this uses one character for each pixel, it is advised to use the smallest font size your terminal emulator supports. Have fun.

The gamepad support is for both UIs.

Controls

In all the UI providers I followed the same controlling scheme, as well as the ability to reset through <CTRL-R>:

Keyboard

keyboard	nes controller
J	B
K	A
U	Select
I	Start
W	Up
S	Down
A	Left
D	Right

Gamepad

gamepad (PS4)	nes controller
X	B
O	A
Select	Select
Start	Start
Button Up	Up
Button Down	Down
Button Left	Left
Button Right	Right

For now its static, and there is no way to change it except for doing it in the code, TODO later.

License

This project is under MIT license.

NES is a product and/or trademark of Nintendo Co., Ltd. Nintendo Co., Ltd. and is not affiliated in any way with Plastic or its author

References

Most of the documentation for NES components can be found in the NES dev wiki

For the CPU(6502), this has the instruction set, and I used Klaus2m5's tests for testing the CPU alone without the other NES components.