diff --git a/debian/plastic-build/DEBIAN/control b/debian/plastic-build/DEBIAN/control new file mode 100644 index 0000000..bce9ff0 --- /dev/null +++ b/debian/plastic-build/DEBIAN/control @@ -0,0 +1,9 @@ +Package: plastic +Version: 0.3.1 +Section: utils +Priority: optional +Architecture: amd64 +Depends: libasound2-dev, libudev-dev +Maintainer: Hadi Chokr +Description: A NES emulator with GUI and TUI + diff --git a/debian/plastic-build/usr/bin/plastic b/debian/plastic-build/usr/bin/plastic new file mode 100644 index 0000000..9ccb4ca Binary files /dev/null and b/debian/plastic-build/usr/bin/plastic differ diff --git a/debian/plastic-build/usr/bin/plastic_tui b/debian/plastic-build/usr/bin/plastic_tui new file mode 100644 index 0000000..e6d59c6 Binary files /dev/null and b/debian/plastic-build/usr/bin/plastic_tui differ diff --git a/debian/plastic-build/usr/share/applications/plastic.desktop b/debian/plastic-build/usr/share/applications/plastic.desktop new file mode 100644 index 0000000..2b5c5ba --- /dev/null +++ b/debian/plastic-build/usr/share/applications/plastic.desktop @@ -0,0 +1,10 @@ +#!/usr/bin/env xdg-open +[Desktop Entry] +Version=1.1 +Type=Application +Name=Plastic - NES +Comment=Plastic - NES Emulator +Icon= /usr/share/icons/plastic-icon.png +Exec= /usr/bin/plastic +Actions= +Categories=Game; diff --git a/debian/plastic-build/usr/share/doc/plastic/README.md b/debian/plastic-build/usr/share/doc/plastic/README.md new file mode 100644 index 0000000..d92bc47 --- /dev/null +++ b/debian/plastic-build/usr/share/doc/plastic/README.md @@ -0,0 +1,177 @@ +

+ + plastic +

NES emulator in Rust

+

+ + +[![Build status](https://github.com/Amjad50/plastic/workflows/Rust/badge.svg)](https://actions-badge.atrox.dev/Amjad50/plastic/goto) +[![codecov](https://codecov.io/gh/Amjad50/plastic/branch/master/graph/badge.svg)](https://codecov.io/gh/Amjad50/plastic) +[![dependency status](https://deps.rs/repo/github/Amjad50/plastic/status.svg)](https://deps.rs/repo/github/Amjad50/plastic) +[![license](https://img.shields.io/github/license/Amjad50/plastic)](./LICENSE) +
+[![Crates.io Version](https://img.shields.io/crates/v/plastic_core?label=plastic_core)](https://crates.io/crates/plastic_core) +[![docs.rs](https://img.shields.io/docsrs/plastic_core)](https://docs.rs/plastic_core/latest/plastic_core/) +
+[![Crates.io Version](https://img.shields.io/crates/v/plastic?label=plastic)](https://crates.io/crates/plastic) +[![Crates.io Version](https://img.shields.io/crates/v/plastic_tui?label=plastic_tui)](https://crates.io/crates/plastic_tui) + + +**plastic** is a [NES][NES-wiki] emulator built from scratch using [Rust][Rust]. + +This is a personal project for fun and to experience emulating hardware and connecting them together. + +- [Building and installation](#building-and-installation) + - [Dependencies](#dependencies) + - [Installing](#installing) + - [Building](#building) +- [Components](#components) +- [Interfaces](#interfaces) + - [EGui UI](#ui) + - [TUI](#tui) +- [Controls](#controls) + - [Keyboard](#keyboard) + - [Gamepad](#gamepad) +- [License](#license) +- [References](#references) + +### Building and installation + +#### Dependencies + +For linux, this project depends on `alsa` and `libudev`, you can install them using: +```sh +# ubuntu/debian +sudo apt install libasound2-dev libudev-dev +# arch +sudo pacman -S alsa-lib systemd-libs +``` + +#### Installing +You can install the latest version of [plastic](https://crates.io/crates/plastic) or [plastic_tui](https://crates.io/crates/plastic_tui) using cargo: +``` +cargo install plastic +cargo install plastic_tui +``` + +If you are using Arch Linux, `plastic` is available in the [official repositories](https://archlinux.org/packages/extra/x86_64/plastic/): + +``` +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 +- [x] 6502 CPU, all official and unofficial instructions with accurate timing (without BCD mode). +- [x] Picture Processing Unit, almost accurate with some small timing issues that would not effect most games. +- [x] Cartridge and INES file handling (still missing INES2.0) +- [x] Mappers: + - [x] Mapper 0 + - [x] Mapper 1 + - [x] Mapper 2 + - [x] Mapper 3 + - [x] Mapper 4 + - [ ] Mapper 5 (Milestone) + - [ ] Mapper 6 + - [x] Mapper 7 + - [ ] Mapper 8 + - [x] Mapper 9 + - [x] Mapper 10 + - [x] Mapper 11 + - [x] Mapper 66 +- [x] Audio Processing Unit: + - [x] 2 Pulse wave(square) + - [x] Triangle + - [x] Noise + - [x] DMC + - [x] IRQ support +- [x] Controller: + controllable using the keyboard and controller (tested with PS4 controller) + +### Interfaces + +The main emulator is at [`plastic_core`](./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 +1. Very simple and easy to use immediate mode UI. + +#### TUI +[![TUI demo](https://img.youtube.com/vi/3wKILnY0AHU/0.jpg)](https://www.youtube.com/watch?v=3wKILnY0AHU) + +This is just for fun, but it is actually working way better than +I expected. Check the [demo](https://www.youtube.com/watch?v=3wKILnY0AHU). + +If you have one of these terminals mentioned [in this docs](https://docs.rs/crossterm/0.28.1/crossterm/event/struct.PushKeyboardEnhancementFlags.html) +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][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. + +### Controls +In all the UI providers I followed the same controlling scheme, +as well as the ability to reset through ``: + +#### 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) 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](http://wiki.nesdev.com/w/index.php/Nesdev_Wiki) + +For the CPU(6502), [this](https://www.masswerk.at/6502/6502_instruction_set.html) has the instruction set, and I used +[Klaus2m5's tests](https://github.com/Klaus2m5/6502_65C02_functional_tests) for testing the CPU alone without the other NES components. + + + +[NES-wiki]: https://en.wikipedia.org/wiki/Nintendo_Entertainment_System +[Rust]: https://www.rust-lang.org/ +[gilrs]: https://gitlab.com/gilrs-project/gilrs +[egui]: https://github.com/emilk/egui +[ratatui]: https://github.com/ratatui/ratatui diff --git a/debian/plastic-build/usr/share/icons/plastic-icon.png b/debian/plastic-build/usr/share/icons/plastic-icon.png new file mode 100644 index 0000000..35ef765 Binary files /dev/null and b/debian/plastic-build/usr/share/icons/plastic-icon.png differ diff --git a/debian/plastic-build/usr/share/licenses/plastic/LICENSE b/debian/plastic-build/usr/share/licenses/plastic/LICENSE new file mode 100644 index 0000000..587036c --- /dev/null +++ b/debian/plastic-build/usr/share/licenses/plastic/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2020 Amjad Alsharafi + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/debian/plastic-build/usr/share/man/man1/plastic.1 b/debian/plastic-build/usr/share/man/man1/plastic.1 new file mode 100644 index 0000000..c90530d --- /dev/null +++ b/debian/plastic-build/usr/share/man/man1/plastic.1 @@ -0,0 +1,88 @@ +PLASTIC(1) General Commands Manual PLASTIC(1) + +NAME + + plastic - NES emulator with both graphical (GUI) and terminal (TUI) interfaces. + +SYNOPSIS + + plastic + plastic_tui [rom-file] [-a] + +DESCRIPTION + + plastic is a NES emulator written in Rust, designed to run NES games through two different interfaces: a graphical (GUI) interface and a terminal-based (TUI) interface. + + The graphical interface (plastic) does not require any arguments and launches the emulator with a simple, user-friendly graphical interface. + + The terminal-based interface (plastic_tui) allows users to run the emulator in the terminal with optional flags. + + Saved states are stored in the following path: + ~/.local/share/plastic/saved_states + +OPTIONS + + plastic + Launches the graphical interface of the emulator. This mode does not take any arguments. + + plastic_tui [rom-file] [-a] + Launches the terminal-based interface. The following options are supported: + - rom-file: Specifies the NES ROM file to load. + - -a: Disables audio output while running the emulator in TUI mode. + +INSTALLATION + + The latest version of plastic and plastic_tui can be installed using Cargo: + + cargo install plastic + cargo install plastic_tui + +KEYBOARD CONTROLS + + Key NES Button + ----------- -------------- + J B + K A + U Select + I Start + W Up + S Down + A Left + D Right + CTRL-R Reset + +GAMEPAD CONTROLS (PS4) + + Gamepad Button NES Button + -------------- -------------- + X B + O A + Select Select + Start Start + D-pad Up Up + D-pad Down Down + D-pad Left Left + D-pad Right Right + +EXAMPLES + + Run plastic with the GUI interface: + + plastic + + Run plastic_tui with a specific ROM file: + + plastic_tui path/to/rom.nes + + Run plastic_tui without audio: + + plastic_tui path/to/rom.nes -a + +LICENSE + + This project is licensed under the MIT License. + +CREDITS + + plastic emulator is a project by Amjad Alsharafi. + This man page was written by Hadi Chokr. diff --git a/debian/plastic.deb b/debian/plastic.deb new file mode 100644 index 0000000..fb2ad40 Binary files /dev/null and b/debian/plastic.deb differ