English | 中文
在 UEFI Shell 环境下用 C 语言复刻红白机游戏《沙罗曼蛇》（Salamander / Life Force，Konami 1986）：不模拟 NES 硬件，而是把原游戏的 6502 反汇编翻译成平台无关的 C 核心，再以 UEFI GOP 做图形输出、UEFI 服务做输入与定时，在 QEMU（OVMF）或真实 UEFI 环境中原生运行。最终 app 无声音——音效调用点保留等价的状态/时间行为，但不引入任何音频依赖。
| 标题画面 | 第一关头部（起飞） | 第一关波次战斗 |
|---|---|---|
 |
 |
 |
| 第一关尾部（Boss 前地形段） | 第一关 Boss 战 | demo 火山关 | demo 火星关 |
|---|---|---|---|
 |
 |
 |
 |
本仓库包含全部原创源代码与工具链（UEFI 应用 + ROM 资源提取器 + 宿主测试 + 验证/截图工具），不包含原游戏 ROM、反汇编产物及由 ROM 提取的数据文件（版权原因，见文末"版权边界"）。
游戏逻辑不凭印象重写，全部对照反汇编还原：
- 逐帧主循环与原版 NMI 驱动模型一致（每帧一次的节拍，非自由运行循环）；
- 主状态机（
$18）/ 游戏内阶段机（$2C）/ 敌人相位机（$042A）的编号与迁移条件跟反汇编一致； - 标题/吸引模式（含标题流星动画
$F838、演示输入脚本$F2C9解释器）、HUD 的 VRC3 IRQ 底部分屏（$E725）、$0700PPU 缓冲执行器（$F1EC，type-5 子块链）等硬件行为按原厂语义建模； - 坐标/速度的高低字节定点行为（
$D4F8移动：16 位定点速度 + 小数累加器进位）、碰撞盒与 HP/死亡状态、链式刷怪（$D9C7）与链消失清算（$D47C）、关卡推进与 Boss 计数逐行还原； - 变量、函数、状态机命名贴近反汇编地址标签（
$E22C半 metatile 渲染、$DBB8事件流、$B8EBdef 驱动…），代码注释逐条标注 ROM 地址，方便回查； - 任何与原版不一致之处，代码附近用中文注释说明原因（见
docs/fidelity-checklist.md的符合/偏差台账）。
保真优先级：帧节拍与状态迁移 > 精灵生成/消亡 > 定点坐标 > 碰撞与 HP > 关卡推进 > 调色板与图案更新 > 渲染缩放。
- 标题画面（logo 动画、星空、菜单）与吸引循环（依次演示 1/2/3 关）；
- 正式关 1-6 的关卡流程、敌人波次、道具（SPEED/MISSILE/RIPPLE/LASER/OPTION/FORCE）力量表与 HUD；
- Game Over / Continue / 过关画面 / 结局流程；
- 已知偏差集中在分数 BCD 显示与个别 Boss 大精灵组装，详见
docs/fidelity-checklist.md。
SalamanderPkg/Application/SalamanderUefi/
SalamanderUefi.c 入口与主循环（GOP 上屏、输入、60fps 节拍）
core/ 平台无关游戏核心：RAM 镜像、状态机、PPU 缓冲/渲染、
滚屏引擎、精灵/敌人/子弹、碰撞、力量表、HUD、标题/demo/
结局、各关事件流与 Boss
platform/ GOP 帧缓冲、键盘→NES 按键映射、帧节拍
SalamanderPkg/Generated/ ROM 提取产物（由工具生成，不入库，见该目录 readme）
tools/
rom_extract/ ROM 资源提取器：iNES 解析、VRC3 bank 切分、CHR RAM tile
流/调色板/元精灵/关卡布局解码，输出 C 头文件（确定性，可回归）
disasm/ 6502 反汇编器（递归下降，区分代码/数据，标注跳转表）
core_test/ 宿主端测试：cl 直编 core + tests 逐断言运行（run_tests.py），
capture_frames.c 帧捕获工具
Build-Salamander.ps1 / Test-AppVersion.ps1 构建（自动版本递增）与版本核验
qemu_capture.py QEMU 运行 + monitor screendump 截图 + sendkey 按键注入闭环
make_demo_gif.py 演示 GIF 组装（消费 capture_frames 产物）
verify_planb.py 端到端验收（串口状态断言 + 截图门）
docs/
demo.gif 演示动画；screenshots/ 关键画面截图
fidelity-checklist.md 保真对照清单（证据基准：ROM 字节 + 反汇编）
参考用反汇编（asm/）与参考截图 dump（ref_shots/）不随仓库分发（版权原因）；反汇编器本身在 tools/disasm/，可自行对合法持有的 ROM 重新生成。
- Windows + Visual Studio 2019（工具链 tag
VS2019） - EDK2 源码树（脚本默认
D:\Work\Code\edk2，WORKSPACE=D:\Work\Code；路径不同请改tools/Build-Salamander.ps1内变量） - QEMU（默认
C:\Program Files\qemu\qemu-system-x86_64.exe）与 OVMF 固件（默认D:\Work\Code\tools\ovmf\OVMF_full.fd） - Python 3.10+（提取器/测试/截图工具链；GIF 组装另需 Pillow）
# 1. 准备资源（需要你自己的 ROM 文件，见 Generated/readme.md）
python tools/rom_extract/run_extract.py
# 2. 宿主端回归（可选但推荐）：23 个测试程序全部 ALL TESTS PASSED
python tools/core_test/run_tests.py
# 3. EDK2 构建（版本号自动递增，产物同步到 run/hda/）
powershell -ExecutionPolicy Bypass -File tools/Build-Salamander.ps1
# 产物：%WORKSPACE%\Build\SalamanderPkg\DEBUG_VS2019\X64\SalamanderUefi.efi
# 4. QEMU 运行验证（monitor screendump 截图 + 串口日志断言）
python tools/qemu_capture.py --seconds 60| 按键 | NES 功能 |
|---|---|
| 方向键 | 十字键（移动） |
| Enter | START（开始/暂停） |
| S | SELECT（1P/2P 切换） |
| Z | B（射击） |
| X | A（力量表确认） |
| ESC | 退出 app |
- 宿主测试：
tools/core_test把平台无关核心直接在 Windows 上编译运行，断言覆盖状态机迁移、滚屏/渲染缓冲语义、标题画面 nametable 逐列对照（FCEUX 参考）、事件流刷怪、Boss 计数等； - QEMU 闭环：构建版本戳 → 串口
APP_VERSION=断言 → monitor screendump 抓显存帧 → 多模态读图核对（SDL 窗口抓屏必黑，一律走 monitor 通道）； - 参考对照：关键画面与 FCEUX（精确模拟器）逐帧/nametable dump 交叉核对。
《沙罗曼蛇》游戏程序与素材版权归 Konami 所有。本仓库仅包含原创的复刻代码与工具：
- 不分发原游戏 ROM（
Refer/orgrom.nes需自备，且必须合法持有）； - 不分发反汇编产物（
asm/）与 ROM 提取的数据文件（SalamanderPkg/Generated/*.h），提取器可在你自己的 ROM 上重复生成； docs/内的 GIF/截图为本复刻实现的运行画面，仅用于技术演示与文档说明。
本项目仅供逆向工程与固件开发学习研究使用。