GBAEmu

面向 macOS 与 Apple Silicon 的 Game Boy Advance 模拟器。项目使用 C++20 实现核心模拟，使用 Objective-C++、MetalKit 和 AudioQueue 提供原生显示与音频输出。

本项目仍在开发中。它可以加载和运行部分 ROM，但尚不具备完整 GBA 硬件兼容性。

环境要求

• macOS，建议使用 Apple Silicon Mac
• Xcode 或 Command Line Tools，包含 clang++、Cocoa、Metal、MetalKit 与 AudioToolbox framework
• GNU Make

ROM、BIOS 与存档不随仓库分发。请仅使用你有权使用的文件。

构建

构建图形应用：

make

输出文件为 bin/GBAEmu。

仅构建并运行核心回归测试：

make test

make check 是 make test 的别名。核心测试不依赖 Cocoa、Metal 或平台 Objective-C++ 源码。

运行

将 .gba ROM 放入 rom/ 目录后运行：

./bin/GBAEmu

也可使用会自动定位仓库目录的启动脚本：

./run_game.sh

运行后可通过菜单栏的 File -> Open ROM... 选择并加载 ROM。ROM 文件应放在 rom/ 目录中。

可选 BIOS 路径：

• rom/gba_bios.bin
• rom/bios.bin

BIOS 文件必须为 16 KiB。没有有效 BIOS 时，模拟器使用当前的 HLE 启动路径。存档会与 ROM 放在同一目录，使用同名 .sav 文件。

运行截图

键盘控制

GBA 按键	键盘映射
方向键	Left / Up / Right / Down
A	Z
B	X
L	A
R	S
Start	Enter
Select	Backspace

当前实现

• ARM 与 Thumb 指令执行、HLE BIOS 调用和基础中断/DMA 路径。
• BIOS、WRAM、IWRAM、IO、Palette、VRAM、OAM、ROM、SRAM/Flash/EEPROM 的基础内存映射。
• 显式 little-endian 内存访问，避免宿主对齐和 strict-aliasing 问题。
• Mode 0/1 平铺背景和 Mode 3/4/5 位图渲染的基础实现；支持基础 OBJ 绘制。
• Metal compute 渲染路径与三重 VRAM staging buffer，避免 CPU 覆写 GPU 正在使用的 staging buffer。
• DirectSound FIFO A/B、基础 Square 1 方波和 44.1 kHz AudioQueue 输出。
• SRAM、Flash 与 EEPROM 存档后端，以及 .sav 文件读写校验。
• 核心测试覆盖 ARM、Thumb、LZ77、APU 寄存器/FIFO 和存档 round-trip。

线程与资源管理

图形前端将仿真运行在串行队列中，输入事件也会排队进入该队列。ROM 切换、存档、渲染快照和调试逻辑通过核心锁协调。关闭视图时会停止仿真、唤醒音频等待、释放 AudioQueue 和 RingBuffer，并保存当前存档。

目录结构

• src/core/：CPU、Bus、PPU、APU、DMA、存档等核心实现。
• src/platform/：macOS、MetalKit、AudioQueue 与 Objective-C++ 桥接。
• src/platform/shaders/：Metal compute 和 render shader。
• src/test/：核心回归测试。
• rom/：本地 ROM、BIOS 与存档目录，默认被 Git 忽略。

已知限制

• PPU 尚未完整实现 Mode 2、affine 背景/OBJ、window、mosaic、alpha blend 与 brightness 效果。
• GPU shader 与软件 PPU 路径都未覆盖完整的 GBA 图层合成语义。
• APU 仍缺少完整的 sweep、envelope、length、wave 和 noise 通道实现。
• EEPROM 的完整 DMA 访问粒度和所有商业 ROM 的存档识别仍需进一步验证。
• 暂无手柄映射、即时存档和通用 ROM 兼容性测试套件。