# NES support in NESER

This file covers NES-specific usage. For installation, generic build/run commands, configuration file locations, and development setup, see [README.md](README.md).

## Supported hardware modes

NESER supports several NES-family timing modes:

- `nes-ntsc`
- `nes-pal`
- `famicom`
- `dendy`
- `playchoice10` / `playchoice-10`

Select a mode on the command line:

```bash
neser --nes-hardware nes-pal path/to/game.nes
```

Or in `neser.conf`:

```text
nes-hardware=nes-pal
```

## System palettes

The NES generates a composite NTSC signal rather than using a fixed RGB
palette, so NESER ships several well-known reference palettes. Choose one with
the `nes-palette` config key or `--nes-palette` flag (case-insensitive):

- `default` — Neser's built-in palette (preserves prior behavior)
- `nesdev` — NESdev wiki 2C02 reference palette
- `smooth` — FBX "Smooth" NTSC palette
- `classic` — FBX "Classic" palette
- `composite-direct` — FBX "Composite Direct" palette
- `mesen` — Mesen2's default palette; use it to compare captures with Mesen2

```bash
neser --nes-palette smooth path/to/game.nes
```

An unknown value is ignored with a warning and the default palette is kept.
Press `F8` in the native or web frontend to cycle palettes at runtime (NES
only); a toast shows the newly selected palette.

## Running NES ROMs

```bash
neser path/to/game.nes
cargo run --release --bin neser -- path/to/game.nes
```

NESER also provides a ROM browser when launched without a ROM path. The browser can scan configured cartridge search paths, show metadata and cover art, filter entries, and launch selected ROMs.

Relevant catalog settings are documented in [neser.conf.example](neser.conf.example), including metadata database paths, image cache paths, unofficial-ROM filtering, and cartridge search paths.

## Input and controllers

Default keyboard mapping for standard NES controllers:

| Control | Player 1 | Player 2 |
| --- | --- | --- |
| D-pad | `W`/`A`/`S`/`D` | `I`/`J`/`K`/`L` |
| A | `T` | `O` |
| B | `R` | `P` |
| Select | `4` | `9` |
| Start | `5` | `0` |

The native frontend also supports gamepads through `gilrs`.

NES-specific controller features include:

- Standard joypads
- SNES controllers
- SNES Mouse
- Zapper
- Arkanoid paddle
- Power Pad
- Four Score
- Famicom expansion-port controllers
- VS System and PlayChoice-10 inputs

Controller selection is configured with keys such as:

```text
nes-controller_port1=joypad
nes-controller_port2=joypad
nes-expansion-port=none
nes-enable_4_score=false
```

See [neser.conf.example](neser.conf.example) for the current accepted values and additional controller options.

## Video and shaders

NES shader presets are selected with `--nes-filter` or `nes-filter`:

```bash
neser --nes-filter crt path/to/game.nes
```

Documented presets include:

- `crt`
- `ntsc`
- `smooth`
- `pal`
- `none`

NES overscan removal is controlled with:

```text
nes-horizontal_overscan=8
nes-vertical_overscan=8
```

## Debugging and autorun

NESER includes debugger and trace options useful for NES development:

```bash
neser --debugger path/to/game.nes
neser --trace-cpu path/to/game.nes
neser --breakpoint pc=C000 path/to/game.nes
```

Autorun recording/playback is available for deterministic input workflows:

```bash
neser --create-recording path/to/game.nes
neser --playback path/to/game.nes
neser --playback-headless path/to/game.nes
```

Use `neser --help` for the complete current CLI reference.

## Automated NES tests

NES automated tests live under:

- `src/nes/integration_tests/`
- `roms/nes/automated_tests/`
- `roms/automated_tests/`

They cover CPU behavior, PPU behavior, APU/audio behavior, DMA, input devices, mapper behavior, autorun workflows, RAM initialization, and assorted regression ROMs.

Useful commands:

```bash
./scripts/test-dir.sh src/nes --skip-integration
./scripts/test-dir.sh src/nes/cartridge
cargo test --no-default-features --lib nes::integration_tests::
```

For source-level architecture details, see [architecture.md](architecture.md).