nes NES 游戏模拟器
一、概述
nes 是 LuatOS 内置的 NES(FC,俗称红白机)模拟器核心库。它把一份用 C 写的 NES 模拟器(CPU + PPU)编进固件,Lua 脚本只需要做三件事:给出 ROM 路径、把按键状态喂进去、需要时退出并释放。模拟循环跑在独立的 RTOS 任务里(栈 8 KiB、优先级 27),不占 Lua 主协程。
几个关键特性:
1、画面 256 × 240、RGB565。这是 NES 的原始分辨率,不做插值,靠 scale 整数倍放大后送屏;
2、两种输出模式。默认 LCD 模式,直接用 lcd 核心库往屏幕上画,屏要自己先 lcd.init;也可以选 AirUI 模式,把帧缓冲渲染成 LVGL 的 image 对象,能嵌进 AirUI 界面里,还带一组触控按钮(A / B / 方向 / 开始 / 选择);
3、半帧渲染省 RAM。端口配置里 NES_RAM_LACK = 1,即每次只画半帧(0~119 行 / 120~239 行两趟),帧缓冲只用 256 × 240 ÷ 2 个像素,代价是多一次绘制调用;
4、不带声音。上游的 APU 尚未实现,端口里 NES_ENABLE_SOUND 默认 0,即使打开也只影响编译,模拟器本身不出声;
5、不提供游戏本体。ROM 需要自己准备(.nes 文件,放 /luadb/、SD 卡等文件系统路径下均可)。固件默认编入 22 个常用 mapper(0、1、2、3、4、7~13、15~18、21~23、25、28、30),NROM(0)、MMC1(1)、UxROM(2)、CNROM(3)、MMC3(4)、AxROM(7) 这些最常见的都在;mapper 5/6/19/24/26/31 需要自定义固件打开 NES_ENABLE_HEAVY_MAPPERS,32 及以上需要 LUAT_USE_NES_FULL,公开固件都没开。
| 项目 | 约束 |
|---|---|
| 编译开关 | LUAT_USE_NES。公开固件里只有 ec718hm 平台的 17 号固件(AIRUI+NES) 打开了它;ec718pm 平台(Air780EPM / EGP、Air700ECP、Air780EX2)与 8101 系列均未编入 |
| 分辨率 | 256 × 240,RGB565(NES_COLOR_DEPTH = 16) |
| mapper | 默认 22 个:0、1、2、3、4、7、8、9、10、11、12、13、15、16、17、18、21、22、23、25、28、30 |
| 声音 | 不支持(APU 未实现) |
| 实例数量 | 全局单实例,同一时刻只能跑一个 ROM |
| 线程 | 独立 RTOS 任务,nes.init 成功后自动开始跑,nes.deinit 后任务退出 |
⚠️ 用之前先自检,nes 不是所有固件都有:
if nes then
log.info("nes", "当前固件包含 nes")
else
log.info("nes", "当前固件不含 nes,需要选 17 号固件(AIRUI+NES)")
end
二、核心示例
2.1 LCD 模式(默认)
屏要先按自己的硬件参数初始化好,然后直接 nes.init:
-- 屏的初始化按实际型号来,这里只是示意
lcd.init("st7796", {port = lcd.HWID_0, pin_dc = 8, pin_rst = 9, pin_pwr = 20, direction = 0})
if not nes then
log.error("nes", "固件未启用 nes")
return
end
-- ROM 放在 /luadb/ 下
local ok = nes.init("/luadb/super_mario.nes")
if not ok then
log.error("nes", "nes.init 失败,内存不足或模拟任务创建失败")
return
end
-- 按键:1 按下、0 抬起
nes.key(nes.Start, 1)
sys.wait(100)
nes.key(nes.Start, 0)
-- 主线程可以做别的事,模拟器在自己的任务里跑
sys.wait(5000)
nes.deinit()
log.info("nes", "已退出")
2.2 AirUI 模式(带触控按钮)
AirUI 模式下画面渲到 LVGL 的 image 上,并叠加一组触控按钮,适合带触摸屏的整机产品:
if not nes then return end
local ok = nes.init("/luadb/game.nes", {
mode = "airui", -- 启用 AirUI 渲染
scale = 2, -- 放大 2 倍,取值 1~3
show_controls = true, -- 显示触控按钮
})
if not ok then
log.error("nes", "AirUI 模式初始化失败")
return
end
-- 轮询用户是否点了界面上的“退出”按钮
while not nes.quit_requested() do
sys.wait(200)
end
nes.deinit()
mode = "airui"只在编入了LUAT_USE_AIRUI的固件里生效(17 号固件就属于这种);如果固件没编 AirUI,这个参数会被忽略,不会报错,但画面仍然走 LCD 模式。
三、常量详解
核心库常量,顾名思义是由合宙 LuatOS 内核固件中定义的、不可重新赋值或修改的固定值,在脚本代码中不需要声明,可直接调用;
按键常量对应 NES 手柄的 8 个键,nes.key 的第一个参数就传它们(数值从 1 开始,别自己写数字):
| 常量 | 数值 | 解释 | 参数示例 |
|---|---|---|---|
| nes.Up | 1 | 方向键 上 | nes.key(nes.Up, 1) -- 按下“上” |
| nes.Down | 2 | 方向键 下 | nes.key(nes.Down, 0) -- 松开“下” |
| nes.Left | 3 | 方向键 左 | nes.key(nes.Left, 1) -- 按下“左” |
| nes.Right | 4 | 方向键 右 | nes.key(nes.Right, 1) -- 按下“右” |
| nes.A | 5 | A 键 | nes.key(nes.A, 1) -- 按下 A |
| nes.B | 6 | B 键 | nes.key(nes.B, 1) -- 按下 B |
| nes.Start | 7 | START 键 | nes.key(nes.Start, 1) -- 按下 START |
| nes.Select | 8 | SELECT 键 | nes.key(nes.Select, 1) -- 按下 SELECT |
四、函数详解
4.1 nes.init(file_path, opts)
功能
初始化模拟器、加载 ROM 并启动模拟任务。成功后模拟器立即开始运行,画面持续刷新。
参数
file_path
参数含义:ROM 文件的完整路径;
数据类型:string;
取值范围:文件系统里能读到的 .nes 文件,如 "/luadb/game.nes"、"/sd/game.nes";
是否必选:必须传入此参数;
注意事项:ROM 需自备;ROM 的 mapper 必须落在固件已编入的范围内(默认 22 个,见概述),超出范围时 ROM 加载失败但本函数仍返回 true,表现为黑屏、log 里出现 “mapper:xxx is unsupported”;
参数示例:"/luadb/super_mario.nes";
opts
参数含义:可选配置表,仅 AirUI 模式有效;
数据类型:table;
取值范围:{mode = "airui"|"lcd", scale = 1~3, show_controls = true|false};
是否必选:非必须传入此参数;
注意事项:mode 默认 "lcd"(直接画屏);scale 默认 2,取值范围 1~3,2 倍即 512×480 显示区;show_controls 默认 true,控制是否叠加触控按钮;固件未编 AirUI 时本参数被忽略;
参数示例:{mode = "airui", scale = 2, show_controls = true};
返回值
成功返回 true;
ROM 打不开、内存不足、任务创建失败时返回 nil(不会抛异常);
示例
-- LCD 模式
nes.init("/luadb/game.nes")
-- AirUI 模式
nes.init("/luadb/game.nes", {mode = "airui", scale = 2, show_controls = true})
注意事项
1、必须先判断返回值。nes.init 失败返回 nil,此时内部实例为空,再调 nes.key 会直接读空指针导致死机,务必 if not ok then return end;
2、LCD 模式下屏必须已经初始化(lcd.init 成功),否则画面无处可画,nes_draw 里拿不到默认的 lcd 配置;
3、模拟器是全局单实例,重复调用 nes.init 会覆盖上一次的实例,旧实例的内存不会自动释放。要换游戏就先 nes.deinit();
4、ROM 越大占用内存越多。NES 卡带常见的 PRG 128~256 KiB、CHR 128 KiB,加上 8 KiB 的绘图缓冲,跑大 ROM 前先看一下剩余堆内存。
4.2 nes.key(key, val)
功能
设置手柄按键状态,模拟按下或松开。
参数
key
参数含义:按键编号;
数据类型:number;
取值范围:nes.Up / nes.Down / nes.Left / nes.Right / nes.A / nes.B / nes.Start / nes.Select(数值 1~8);
是否必选:必须传入此参数;
注意事项:请用常量,不要写死数字;传入未定义的编号时函数不做任何处理,直接返回 false;
参数示例:nes.A;
val
参数含义:按键状态;
数据类型:number;
取值范围:1 按下,0 抬起;
是否必选:必须传入此参数;
注意事项:非 0 视为按下;要“点一下”必须成对调用 1 再 0,否则按键会一直保持按住;
参数示例:1;
返回值
成功返回 true;
key 不是合法编号时返回 false;
示例
-- 单键点一下
nes.key(nes.A, 1)
sys.wait(50)
nes.key(nes.A, 0)
-- 组合键(例如“上 + B”一起按,用来跑动加跳)
nes.key(nes.Up, 1)
nes.key(nes.B, 1)
sys.wait(100)
nes.key(nes.B, 0)
nes.key(nes.Up, 0)
注意事项
1、nes.key 只是写状态,函数立即返回,不会阻塞;按住多久由你两次调用之间的时间决定;
2、方向键支持多键同时按下(上 + 右 = 右上),模拟器内部按位记录,不需要额外处理;
3、在 GPIO 中断回调里调用时,记得自己做消抖(建议 20 ms 左右),机械按键抖动会让角色连续跳;
4、val 传 0 之外的任何非零值都按“按下”处理,但为了可读性统一写 1。
4.3 nes.quit_requested()
功能
查询用户在 AirUI 界面上是否点了“退出”按钮。用于主循环里判断何时该收尾。
参数
无
返回值
已点击退出返回 true;
未点击返回 false;
LCD 模式(或固件未编 AirUI)恒返回 false;
示例
while not nes.quit_requested() do
sys.wait(200)
end
nes.deinit()
注意事项
1、这个接口只服务 AirUI 模式的触控按钮。LCD 模式下没有按钮可点,永远返回 false——如果用它做循环条件,必须自己再挂一个别的退出条件(GPIO 按键、定时器、云端指令等),否则循环不会结束;
2、查询本身很轻,200 ms 轮询一次足够,不必放到中断里。
4.4 nes.deinit()
功能
退出模拟器并释放资源:置退出标志、停掉模拟任务、销毁帧缓冲(AirUI 模式下还会销毁 LVGL 对象和触控按钮)。
参数
无
返回值
无返回值(nil);
示例
nes.deinit()
log.info("nes", "已退出")
注意事项
1、是异步收尾。deinit 只把退出标志置上就返回,模拟任务跑完当前帧后才真正退出并清理,所以 deinit 之后不要再立刻 nes.init 同一个 ROM,建议隔 100 ms 以上(或用 sys.wait)再重新初始化;
2、deinit 不会释放 ROM 文件本身(它是文件系统里的文件),只释放运行时内存;
3、产品里切页面/切应用时记得调用,否则模拟任务会一直占着 CPU 和内存。
五、产品支持说明
nes 库由 LUAT_USE_NES 控制,公开固件里只有 ec718hm 平台(Air780EHM / Air780EHV / Air780EGH / Air780EGG / Air780EHU / Air780EHN、Air700ECH、Air8000 全系列)的 17 号固件(固件标识 AIRUI+NES) 编入了它。
ec718pm 平台(Air780EPM / Air780EGP、Air700ECP、Air780EX2)与 Air8101 系列没有编入 nes,调用前请先用 if nes then 自检。
17 号固件在打开 nes 的同时关掉了 camera、media、voip、record、tts、gtfont、sfud 等库,选固件时按项目实际需要权衡;如果既要 nes 又要这些库,需要联系合宙 FAE 定制固件。