neser 1.2.0

NESER - Nintendo Emulation Systems Engine (Rust). Desktop and WebAssembly frontends.
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
131
132
133
134
135
136
137
138

# Game Boy Advance support in NESER

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

## Supported hardware models

NESER exposes these GBA hardware model settings:

- `agb`
- `sp`
- `micro`

Example:

```bash
neser --gba-hardware sp path/to/game.gba
```

Or in `neser.conf`:

```text
gba-hardware=sp
```

## Running GBA ROMs

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

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

## BIOS behavior

NESER includes a built-in open-source GBA BIOS, so an external BIOS file is not required.

BIOS selection order:

1. `--gba-bios-path <path>` / `gba-bios-path=<path>` if configured
2. `~/.neser/gba_bios.bin` if it exists
3. Built-in BIOS fallback

The external BIOS must be exactly 16 KiB. Use the special value `embedded` to force the built-in BIOS:

```bash
neser --gba-bios-path embedded path/to/game.gba
```

Skip only the visual/audio BIOS intro while preserving hardware initialization:

```bash
neser --skip-bios-intro path/to/game.gba
```

## Input

Default keyboard mapping:

| GBA button | Keyboard |
| --- | --- |
| D-pad | `W`/`A`/`S`/`D` or arrow keys |
| A | `T` |
| B | `R` |
| L | `Q` |
| R | `E` |
| Select | `4` |
| Start | `5` |

The native frontend also supports gamepads through `gilrs`.

## Video and color

GBA shader presets are selected with `--gba-filter` or `gba-filter`:

```bash
neser --gba-filter gba-lcd path/to/game.gba
```

Documented presets include:

- `none`
- `gba-lcd`
- `agb001`
- `nso-gba-color`
- `sp101-color`
- `gba-lcd-grid`

GBA LCD color correction can be enabled with:

```bash
neser --gba-color-correction path/to/game.gba
```

Or in `neser.conf`:

```text
gba-color-correction=true
```

## Diagnostics

GBA trace channels are available for emulator diagnostics:

```bash
neser --gba-trace-cpu path/to/game.gba
neser --gba-trace-bus path/to/game.gba
neser --gba-trace-dma path/to/game.gba
neser --gba-trace-swi path/to/game.gba
neser --gba-trace-mgba-log path/to/game.gba
```

## Automated GBA tests

GBA automated tests live under:

- `src/gba/integration_tests/`
- `roms/gba/automated_tests/`

The repository includes the jsmolka `gba-tests` suite as a submodule at:

```text
roms/gba/automated_tests/gba-tests
```

Run the ARM/Thumb/Memory suite tests with:

```bash
cargo test --no-default-features --lib gba::integration_tests::gba_suite_tests::
```

These execute:

- `roms/gba/automated_tests/gba-tests/arm/arm.gba`
- `roms/gba/automated_tests/gba-tests/thumb/thumb.gba`
- `roms/gba/automated_tests/gba-tests/memory/memory.gba`

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