yane 1.1.7

An N.E.S. emulator and emulation library.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

# Y.A.N.E. - Yet Another N.E.S. Emulator

[Nintendo Entertainment System](https://en.wikipedia.org/wiki/Nintendo_Entertainment_System) emulator and emulation library.

[![Crates.io](https://img.shields.io/crates/v/yane)](https://crates.io/crates/yane)
[![Rust](https://github.com/josefwaller/yane/actions/workflows/rust.yml/badge.svg)](https://github.com/josefwaller/yane/actions/workflows/rust.yml)
[![Docs.rs](https://docs.rs/yane/badge.svg)](https://docs.rs/yane/)

Can be used as either a standalone CLI emulator or as a ready-out-of-the-box rust crate for emulating an N.E.S.

## Usage as an emulator

**WINDOWS USERS**: Make sure the appropriate `SDL2.dll` is in your `$PATH`.
See [the official releases](https://github.com/libsdl-org/SDL/releases).

### Install via `cargo`

```terminal, ignore
> cargo install yane
...
> yane [COMMAND] [OPTIONS]
...
```

Make sure your cargo install directory (default `~/.cargo/bin`) is in your `$PATH`.

### Build from scratch

**WINDOWS USERS**: Add the appropriate `SDL2.lib` and `SDL2.dll` to the root of the crate (i.e. `/yane/`).
See [the official releases](https://github.com/libsdl-org/SDL/releases).

```terminal, ignore
> git clone https://github.com/josefwaller/yane.git
...
> cd yane
> cargo build -r
...
> ./target/release/yane [COMMAND] [ARGS]
```

## Run the emulator

Once installed, run `yane ines path/to/my/rom.nes`.
Yane uses a simple command line interface, use `yane -h` and `yane [COMMAND] -h` to see the available options.

```terminal, ignore
> yane -h
An N.E.S. emulator.

Usage: yane [COMMAND]

Commands:
  setup      Initialize the configuration files at $HOME/.yane/
  ines       Load and run an iNES (.nes) file
  savestate  Load and run a savestate (.yane.bin) file.
  help       Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

> yane ines -h
Usage: yane ines [OPTIONS] <NES_FILE>

Arguments:
  <NES_FILE>  The iNes file to run

Options:
  -s, --savedata-file <SAVEDATA_FILE>  The savedata file (.SRM). Only used if the NES game supports battery backed static ram. Will default to using the NES file name and location
      --config-file <FILE>             The configuration file for the emulator's settings [default: ~/.yane/settings.yaml]
  -d, --debug                          Start in debug mode
  -p, --paused                         Start paused, after advancing one frame in order to render one frame
  -m, --muted                          Start the emulator muted
      --keymap-file <FILE>             The .YAML file defining the key mappings for the NES [default: ~/.yane/key_map.yaml]
      --tail                           Tail the logs in terminal as well as the logging file
      --log-dir <DIRECTORY>            Directory to save logs to [default: ~/.yane/logs]
  -h, --help                           Print help

> yane setup
Successfully created configuration files

> yane ines path/to/my/rom.nes --muted --debug --keymap-file=my/custom/keymap.yaml
```

See [KeyMap](https://docs.rs/yane/latest/yane/app/struct.KeyMap.html) for the default key bindings.

Running `yane setup` will create a bunch of configuration files at `$HOME/.yane`.
These can then be edited to change the keymappings, settings, logging directory, etc.
Yane will check for these files before running every time and fall back on the defaults if they don't exist,
so you can run the emulator without running `yane setup` if you want.

## Usage as a library

All of Yane's functionality is available as a standalone, pure rust crate.

```rust
use yane::core::{Nes, Settings, Cartridge, Controller};
// Create a new N.E.S. console with an empty cartridge inserted
// You could use Cartridge::from_bytes(include_bytes!("path/to/my/game.nes", None)) to load from an iNes file instead.
let mut nes = Nes::new();
// Use the default settings for the emulator
let settings = Settings::default();
// Advance the N.E.S. by 1 frame (i.e. until the VBlank interval)
nes.advance_frame(&settings);
// Advance the N.E.S. by one single instruction
nes.advance_instruction(&settings);
// Press the A button on player 1's controller
nes.set_controller_state(0, Controller {
  a: true,
  ..Controller::default()
});
// Reset the N.E.S.
nes.reset();
```

See the [documentation on the library portion](https://docs.rs/yane/latest/yane/core/index.html) or the [examples](https://github.com/josefwaller/yane/tree/main/examples) for more.

## Feature Flags

Yane includes two feature flags
* `sdl`, which is enabled by default, includes the SDL interface that comes with Yane (i.e. everything in [yane::app](https://docs.rs/yane/latest/yane/app/index.html)).
If you want to use yane as a pure rust library, you can omit this flag.
* `wasm-bindgen` makes [Controller](https://docs.rs/yane/latest/yane/core/struct.Controller.html) exportable to javascript via `wasm_bindgen` so that it can be passed between javascript and wasm easily.
See [the wasm-bindgen docs](https://crates.io/crates/wasm-bindgen).

# Credits

All test roms are from [the nes-test-rom](https://github.com/christopherpow/nes-test-roms) repository,
without which this project would probably not be possible.
Some examples use models or NES games not made by me, there are `credits.txt` files where appropriate.