# RapidNES

**Repository Path**: RapidAI/RapidNES

## Basic Information

- **Project Name**: RapidNES
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-07
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# RapidNES

[English README](README.md)

本程序为纯 AI 编程开发，无人工编程痕迹。

RapidNES 是一个使用 C++20 编写的 NES/FC 模拟器，重点支持常见亚洲/中文多合一卡带 ROM，尤其是 `roms\fc` 目录下的 n 合一 ROM。程序窗口标题显示为 `RapidNES`；当前可执行文件名仍是 `gpt_nes.exe`。

## 当前状态

当前 `roms\fc` 参考验收集已经通过：

- 画面参考帧对比：`96/96` 通过。
- 音频参考 WAV 对比：`96/96` 通过。
- 最终验收审计：`FailRows=0`。
- 验收包审计：`40/40` 通过。

验收证据：

- `screenshots\reference_from_full3\reference_acceptance_report.html`
- `screenshots\reference_from_full3\reference_acceptance_package.zip`

## 功能

- 在单个可执行文件中实现 NES/FC 的 CPU、PPU、APU、手柄、存档 RAM 和 Mapper。
- 有 SDL2 时支持窗口运行、键盘输入和声音输出。
- Windows 上没有 SDL2 时，会自动使用原生 Win32 前端：GDI 画面、waveOut 声音、键盘输入。
- 支持无窗口测试/采集模式，可输出确定性的截图、WAV、CHR/命名表/背景层 dump、存档文件，并支持脚本化按键。
- 当前测试语料覆盖多种常见 Mapper，包括 Mapper 0/1/2/3/4/MMC3、5/MMC5、7、9、23/VRC、34、45、58/213、64、66、71、90/JY、176、212、227、238、242。
- 针对 `roms\fc` 启用 FC 二号手柄语义：P2 Start/Select 会被屏蔽，因为 FC 原机内置二号手柄没有这两个键。
- 提供参考模拟器画面/音频对比脚本，用于验收画面和音乐是否正常。

## 快速运行

运行一个已有 Windows 构建：

```powershell
.\build\Release\gpt_nes.exe "roms\fc\超级魂斗罗菜单版2.nes"
```

无窗口运行，并输出截图和音频：

```powershell
.\build\Release\gpt_nes.exe "roms\fc\超级魂斗罗菜单版2.nes" --frames 1800 --dump screenshots\sample.ppm --wav screenshots\sample.wav
```

脚本化菜单按键：

```powershell
.\build\Release\gpt_nes.exe "roms\fc\超级魂斗罗菜单版2.nes" --frames 1800 --press start@120:30 --dump screenshots\start.ppm --wav screenshots\start.wav
```

## 编译

需要 C++20 编译器和 CMake。SDL2 是可选依赖：

- 找到 SDL2 时，会构建带窗口、键盘输入和声音输出的版本。
- Windows 上找不到 SDL2 时，会构建原生 Win32 前端。
- 非 Windows 且没有 SDL2 时，会构建无窗口核心检查程序。

Windows + Visual Studio：

```powershell
cmake -S . -B build -G "Visual Studio 18 2026" -A x64
cmake --build build --config Release
.\build\Release\gpt_nes.exe roms\Super Mario Bros.nes
```

Windows + vcpkg SDL2：

```powershell
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake
cmake --build build --config Release
.\build\Release\gpt_nes.exe path\to\game.nes
```

Linux：

```bash
sudo apt install cmake g++ libsdl2-dev
cmake -S . -B build
cmake --build build -j
./build/gpt_nes game.nes
```

## 按键说明

通用按键：

| 功能 | 按键 |
| --- | --- |
| 退出 | `Esc` |
| 重置 | `F1` |

SDL 前端按键：

| FC 按键 | 玩家 1 | 玩家 2 |
| --- | --- | --- |
| A | `X` | `O` |
| B | `Z` | `U` |
| Select | `A` | `Y` |
| Start | `S` | `P` |
| 上 | `Up` | `I` |
| 下 | `Down` | `K` |
| 左 | `Left` | `J` |
| 右 | `Right` | `L` |

原生 Win32 前端按键：

| FC 按键 | 玩家 1 | 玩家 2 |
| --- | --- | --- |
| A | `X` 或 `K` | `Numpad 2` |
| B | `Z` 或 `J` | `Numpad 1` |
| Select | `Space` | `Numpad 0` |
| Start | `Enter` | `Numpad 9` |
| 上 | `Up` 或 `W` | `Numpad 8` |
| 下 | `Down` 或 `S` | `Numpad 5` |
| 左 | `Left` 或 `A` | `Numpad 4` |
| 右 | `Right` 或 `D` | `Numpad 6` |

对于从 `roms\fc` 载入的 ROM，玩家 2 的 Start/Select 会被忽略，用来匹配 FC 原机内置二号手柄的行为。

## 常用验收命令

运行当前完整参考验收：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\reference_run_acceptance.ps1 -PlanCsv screenshots\reference_from_full3\reference_capture_plan_prepared.csv -OutDir screenshots\reference_from_full3 -NoImport -AllowExactImageRows 30 -Strict
```

单独运行画面对比：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\reference_frame_compare.ps1 -CandidateCsv screenshots\reference_from_full3\reference_capture_plan_prepared.csv -OutCsv screenshots\reference_from_full3\reference_frame_compare.csv -Strict
```

单独运行音频对比：

```powershell
powershell -ExecutionPolicy Bypass -File scripts\reference_audio_compare.ps1 -CandidateCsv screenshots\reference_from_full3\reference_capture_plan_prepared.csv -OutCsv screenshots\reference_from_full3\reference_audio_compare.csv -Strict
```