跳转至

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 定制固件。

搜索