Skip to content

Releases

core v0.3.9 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 10 Nov 14:11

MakeCode Arcade core v0.3.9

一句话:不再被三张卡带打死,加载失败也不再假装成功

这一版有行为改动,但只落在异常分支上:三个基准用例的末帧哈希与 0.3.8
逐位相同。修的是 62 张社区卡带批量冒烟暴露出来的三条问题——两处整数除零
会把整个核心进程直接带死(SIGFPE),以及镜像被 VM 拒绝时前端只看到一片黑屏、
日志里却显示「加载成功」。

建议升级:如果你手上有较新的社区卡带(尤其是带 3D / 缩放特效的),0.3.8
按一下 A 就可能直接退出;0.3.9 会继续跑下去。遇到跑不了的卡带,现在也会
明确告诉你原因和段尺寸,而不是让你对着黑屏猜。

1. PATCH 13:blit() 目标尺寸为 0 时整数除零

CrateMaker / Crate_Dungeon 的爆炸特效会把内置 sprite.scale 设成 0
或逐帧递减到 0/负数,最终走到 runtime/pxtapp/screen---ext/image.cpp:1092:

int xSrcStep = (wSrc << 16) / wDst;
int ySrcStep = (hSrc << 16) / hDst;   // hDst == 0 → SIGFPE

C++ 整数除以 0 是硬件异常,0xc0000094(Windows)/ SIGFPE(Linux)直接
终结宿主进程,连 panic 横幅都来不及画。现在目标宽或高 ≤ 0 时提前返回
false——blit 的 false 本来就是「未绘制 / 未检出碰撞」,零尺寸也没有
像素可画,语义完全一致。

2. PATCH 14:Math_::idiv() 除数为 0 时整数除零

FPS game test (menu test) 自带的 raycasting 引擎里 _render_raycasting.ts
的 _fov 没有初值,首帧 wallHeightInView = (SW << (fpx-1)) / this._fov
就是 x/0(或 0/0),落到 runtime/pxtapp/base/core.cpp 的
Math_::idiv(int,int)。这张卡带不按键、第 0 帧就崩。

TS 层对除零期望得到 NaN/Infinity,VM 的整数除法没有浮点可退;现在 y == 0
返回 0,是最保守的兜底:不崩宿主,后续帧还能继续跑。

3. PATCH 15:镜像校验失败时 retro_load_game() 不再谎报成功

sm64thign 的黑屏本来是个纯粹的镜像校验问题:verify.cpp:176 的
CHECK(sect->size < 32000, 1014) 拒绝了一个 109 952 字节的 Function 段,
vmload.cpp 在 VM 线程内 dmesg("validation error 1014 at 0x1520")
后直接 return。但 pxt_vm_start_buffer() 会立刻 spawn 线程并成功返回,主线程
拿不到这个结果,于是 retro_load_game() 返回 true,前端只看到一片黑屏。
围绕「是不是渲染坏了」来回查了三轮才定案。

现在宿主在 spawn 之前用同一条 section 链做一次同步段级预检(段链/
对齐、size ≥ 16、size < 32000),违规就:

  • retro_load_game() 返回 false,前端直接报加载失败;
  • 日志给出可自查的原因,例如
    [MCA] pxt64 image rejected: section at 0x1520 size=109952 >= 32000 (VM error 1014); max VM section size is 32000, this cart cannot run on the pxt VM。

没有放宽 32000:这是上游 pxt VM 给小栈 MCU 设的保守上限,改了就偏离上游;
各真机(掌机 / Android / Lakka musl)的栈大小未逐一审计,且超过函数内 16 位
跳转的 128 KB 量级后还有别的风险。诊断实验里临时放宽到 262144 确实能让原版
出画(与 cartconv 侧把大数组拆成 13 个小函数的 split.pxt64 末帧逐位一致),
但收益只有一张卡带,转换侧已有「预检 + known_bad + 改游戏源码」的完整方案,
所以这一版只让它明确失败,不偷偷改 VM 语义。

4. 回归与验证

  • 画面未变:tools/ci_regress.sh 三个基准用例与 0.3.8 基线逐位一致

    ping 300 帧     0556e78f7ce0e828f2dc922d210dc047
    probe 120 帧    e82844f7160449d1767aa69afe788800
    probe 120 帧按A 0eb7884cb40cef0cb549946af3a942ab
    
  • 契约测试:两种像素格式路径均全绿,新增两条断言——超限段镜像必须
    load_game 返回 false,且前端日志里要出现 1014 与 32000。

  • 回归夹具(tools/fixtures/,CI 新增 crash-regression job):
    crash-scale.pxt64 / crash-idiv.pxt64 各跑满 600 帧且宿主存活(0.3.8
    是进程直接死);oversize-section.pxt64 必须 load_game -> FAIL。

  • 63 张社区卡带全量复跑(0.3.9 win-x64,A@60 + LEFT@100,140,…,540,600 帧):

    0.3.8 0.3.9
    正常出画 57 59
    进程级崩溃 3 0
    VM panic(宿主存活) 0 1
    明确加载失败 0 1
    预期静态 demo 2 2

    CrateMaker / Crate_Dungeon 从 crash 转 ok;FPS_game_test_menu_test
    除零被兜住后走到游戏自身的 PANIC 980(核心自动重启、宿主存活、600 帧
    跑满、末帧 032c69da…),不再是进程级 SIGFPE;sm64thign 从黑屏变成
    load_game -> FAIL。其余 59 张末帧哈希与 0.3.8 逐位一致,没有一张
    正常卡带画面发生变化。

  • 补丁表:tools/check_pxt_patches.py 从 11 条扩到 14 条,
    --strict 校验 PATCH 13/14/15 都在位。

  • 发版包体检:tools/verify_release.py 仍是 release job 的硬门槛,
    6 个主包 + 3 个调试包全 PASS 才建 Release。

已知限制(未变 / 修订)

  • 32 位前端不支持(PXT64 镜像在 32 位 VM 下无法执行)。
  • 即时存档 / rewind / 快进 / 金手指 / Netplay 不提供(v0.3.0 起的范围收敛)。
  • 核心选项仍为零(刻意设计,见 docs/INPUT.md)。
  • Strawberry_Slam 的 PANIC 980 是游戏脚本读未初始化数据,且依赖输入序列
    (A 口径与四方向口径触发,A@60 + LEFT 口径 600 帧不触发),不是必然 panic。
  • 单个 VM 段 ≥ 32000 字节的卡带仍无法运行,但现在会明确报 error 1014
    而不是黑屏。要救只能改游戏源码(拆大数组字面量)或换非 VM 前端。
  • Windows 的「退出 139」等价问题(PE 无 NODELETE 标志)未处理,取决于前端
    是否 FreeLibrary。
  • Switch NX 是独立发布线(nx-v*),本版不发 NX 包。

升级建议

建议升级,尤其是收录社区卡带较多的固件/整合包:0.3.8 上有 3 张卡带能让
RetroArch 直接退出,0.3.9 只是「继续跑」或「明确报失败」,正常卡带画面一位
都没变。


MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

core v0.3.8 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 09 Nov 16:26

MakeCode Arcade core v0.3.8

一句话:画面一行没动,包小了一大半,符号还能找回来

这一版没有任何行为改动:三个基准用例的末帧哈希与 0.3.7 逐位相同。改的全是
「出厂形态」——发行包一律 strip,同时另发 <平台>-debuginfo.zip 保留符号,用
build-id 把两边绑在一起。顺手补上了 0.3.7 漏掉的 Android 链接选项。

建议升级:同样的核心,linux-arm64 从 5.0 MB 降到 732 KB,六个包总量
4.1 MB → 1.5 MB。对固件仓库(muOS / Knulli / ArkOS 都要求 strip 产物)和
SD 卡空间有限的手持设备来说,这一版才是「能直接收录」的形态。

1. 发行包 strip:linux-arm64 5 007 984 → 732 312 B

此前三个 Linux 发布件把 .debug_info 直接发给了玩家,而 Android 被 NDK 自动
strip、Windows 本就不带符号表——同版本六个包的状态并不统一(曾经被固件仓库
拒收,理由就是「带调试信息的核心」)。

平台 strip 前 strip 后 zip
linux-arm64 5 007 984 B 732 312 B(−85%) 1 380 KB → 287 KB
linux-x64 4 621 152 B 733 032 B(−84%) 1 347 KB → 299 KB
lakka-arm64 1 956 104 B 593 840 B(−70%) 731 KB → 239 KB
android-arm64 455 136 B 455 136 B(NDK 已 strip) 不变
windows-x64 / arm64 615 424 / 689 152 B 同左(PE 无符号表) 不变

strip 工具按目标架构挑:GNU 交叉 binutils 优先,其次 llvm-strip,最后才试
宿主 strip——宿主 binutils 多为单目标,遇到 aarch64 会直接报格式错误。所以
打包脚本对每个候选实际执行并用 readelf -h 验产物,不看 which。
发版环境(MCA_REQUIRE_STRIP=1)里 strip 失败直接红,不允许静默发出 5 MB 的包。

2. 调试包:<平台>-debuginfo.zip × 3

strip 掉的符号没有丢,三个 ELF 平台各多一个调试包(只有 .so 原件,没有
.info——它不是给玩家装的)。主包与调试包靠 build-id 配对,所以本版把
build-id 从 none 统一改成 --build-id=sha1:

# 玩家报的崩溃地址(-e 指定主包里的 .so,符号取自调试包)
aarch64-linux-gnu-addr2line -f -C -e makecode_arcade_linux-arm64-debuginfo.so 0x0001a2b4
# 先确认两边 build-id 一致(都在 .note.gnu.build-id 里)
readelf -n makecode_arcade_libretro.so | grep 'Build ID'

build-id 是文件内容的哈希,同样输入仍得同样结果,不影响可复现构建。SHA-1 是
20 字节固定长度,不影响产物尺寸。

3. 补上 0.3.7 漏掉的两处链接选项(Android / musl)

0.3.7 修「退出 RetroArch 即 139」靠的是链接期 -Wl,-z,nodelete,当时改了
core/Makefile 与 tools/build_target.sh。但链接入口一共五个:

链接入口 管谁 0.3.7 0.3.8
core/Makefile unix / android 本地构建 有 有
tools/build_target.sh zig 发版矩阵 有 有
tools/build_musl.sh Lakka(musl 全静态) 漏 已补
core/jni/Android.mk Android 发行包(ndk-build) 漏 已补
tools/package_release.sh 只打包,不链接 — —

也就是说 0.3.7 的 Android 包和 Lakka 包都没有 DF_1_NODELETE,只有三个
glibc 平台吃到了修复。本版补上,并在四个地方设断言防回归:

  • CI 的 android-arm64 job 编完就 readelf -d 查 FLAGS_1 ... NODELETE;
  • CI 的 lakka-musl job 产物检查里同查(零 NEEDED ≠ 带 NODELETE,必须单独查);
  • tools/build_musl.sh 自检里也查,本地手跑同样挡得住;
  • tools/verify_release.py 对所有 ELF 包查同一个标志(Windows 是 PE,跳过),
    且这个体检现在是 release job 的硬门槛:有 FAIL 就不建 Release。

说句实话:这条是发出去之后才发现的——第一版 0.3.8 已经上传,verify_release.py
一跑就报 lakka-arm64 缺 DF_1_NODELETE,于是撤回 Release 与 tag、补链接选项和
断言、重新构建重发。现在这道体检挡在发布之前,同类问题不会再出厂。

4. 验证

  • 末帧哈希:三个基准用例与 0.3.7 逐位相同(strip 不改变指令)

    ping 300 帧     0556e78f7ce0e828f2dc922d210dc047
    probe 120 帧    e82844f7160449d1767aa69afe788800
    probe 120 帧按A 0eb7884cb40cef0cb549946af3a942ab
    
  • 发行包体检:tools/verify_release.py 6 个主包 + 3 个调试包全 PASS
    (已 strip、架构/机器类型正确、glibc ≤ 2.17、无 libc++_shared、
    16KB 页对齐、带 DF_1_NODELETE、debug-info 与 build-id 配对)。

  • 发版二进制本身:发行包里的 linux-arm64(732 496 B,md5 eb4eb217…)
    放进 aarch64 chroot 用 qemu 跑上面三条用例,逐位一致——不是"CI 绿了就算"。

  • CI:package job 末尾会把打好的包解开 dlopen 跑 60 帧;golden-hash
    守像素;pxt-patches 校验 11 条补丁;release job 在发布前跑上面那份体检。

已知限制(未变)

  • 32 位前端不支持(PXT64 镜像在 32 位 VM 下无法执行)。
  • 即时存档 / rewind / 快进 / 金手指 / Netplay 不提供(v0.3.0 起的范围收敛)。
  • Strawberry_Slam 在固定 tick 触发 PANIC 980,游戏自身 bug,核心侧不修。
  • Windows 的「退出 139」等价问题(PE 无 NODELETE 标志)未处理,取决于前端
    是否 FreeLibrary。
  • Switch NX 是独立发布线(nx-v*),本版不发 NX 包。

升级建议

建议升级,尤其是给固件仓库提交/自带核心的场景:同样的画面、同样的兼容性,
包体积小 4 倍。若你从不看崩溃回溯,可以只下主包;要报 crash 就同时下对应平台
的 -debuginfo.zip。


MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

core v0.3.7 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 09 Nov 13:14

MakeCode Arcade core v0.3.7

一句话:两个「每张卡带都会踩」的越界,加一个「退出就崩」

这一版的行为改动只有三处,全部来自新装的三类检查工具(覆盖率 / fuzz / 真前端冒烟),
没有新功能。三张基准卡带的末帧哈希与 0.3.6 逐位相同 —— 修的是装载期和退出期的
内存安全
,不是画面。

建议升级:其中一条是「退出 RetroArch 时 SIGSEGV」,如果你在用 Linux/Android 掌机,
大概率已经遇到过。

1. 装载期越界写:名字表少分配 7 字节(PATCH 11)

core---vm/verify.cpp 里上游的宏少了一对括号:

#define ALLOC_ARRAY(tp, sz) (tp *)xmalloc(sz == 0 ? 1 : sizeof(tp) * sz)

唯一的传表达式调用点是 loadIfaceNames() 的 ALLOC_ARRAY(uintptr_t, len + 1),
展开后是 sizeof(uintptr_t) * len + 1 —— 先乘后加,比需要少分配 7 字节,末尾两个
dst[i] 写出了边界。

每张卡带装载都会走到这里(562 个接口名对应分配 4497 字节,应为 4504)。生产路径上
之所以一直没崩,是 glibc 的 malloc 对 16 字节对齐请求有额外余量;Android / musl 的
分配器不保证这一点。ASAN 用精确分配立刻就报 heap-buffer-overflow @ verify.cpp:361。

修法:宏给 sz 补上括号。

2. 装载期越界读:段表遍历先算后判(PATCH 12)

// 改之前
for (sect = (VMImageSection *)img->dataStart;
     (next = vmNextSection(sect), (uint64_t *)sect < img->dataEnd); sect = next)

逗号表达式从左往右算:走到 dataEnd 那一轮先读了 sect->size,再判边界,
等于越界读 4 字节。countSections() 里剩余不足 8 字节时同样照读段头。

生产路径上被 vmStartFile() 多分配的 16 字节兜住,fuzz 里精确分配即报
heap-buffer-overflow(READ of size 4)。修法:先判边界,再读段头。

3. 退出即 139:static 析构 + dlclose

用真 RetroArch 无头加载核心,第一次实跑就复现了用户报的那个现象:游戏能玩,退出
RetroArch 时进程 139
。

原因:pxt 运行时带 static 析构,retro_unload_game() 之后前端 dlclose() 卸掉核心,
但 atexit 链上的析构函数仍然指向那片已解除映射的代码段,进程退出时跳进去就段错误。

修法:链接期加 -Wl,-z,nodelete(core/Makefile 的 unix 目标 + tools/build_target.sh
的 linux/android 分支),产物多一个 DF_1_NODELETE 标志,ld.so 退出前不回收。代价是
换核心时不释放内存,单次会话可忽略。

已验证范围:Linux x86_64 / aarch64、Android(ELF)。Windows 是 PE,没有对应标志,
修复方式取决于前端是否 FreeLibrary,本版未改也未实测。

4. 验证工具:三个探照灯都进了仓库

这轮的价值不在三个修复,而在「以后能自己发现」。三件工具都带脚本,可重复跑:

工具 命令 首轮结果
覆盖率 tools/coverage.sh 7294 行可执行,46% 覆盖;最大盲区 screen---ext/image.cpp 仅 18%
fuzz tools/fuzz_pxt.sh 首次变异第 3 轮即崩(就是上面 PATCH 12);修后 208,744 runs / 301 秒无崩溃
真前端 tools/retroarch_smoke.sh 3 张卡带 3/3 PASS,截图是真实 160×120 画面(就是上面第 3 条)

顺带修了 SANITIZE=address 与 undefined 共用对象目录的老坑(切换构型会链到旧对象,
报 undefined symbol: __ubsan_handle_*)。现在目录名带 sanitizer 名,COVERAGE=1 也是
独立目录,互不覆盖。

5. CI

新增 retroarch-smoke job(ubuntu-24.04 + 发行版 RetroArch + Xvfb,2 张夹具卡带
各 120 帧)。它守的是 golden hash 守不到的那一层:dlopen 路径、.info 解析、
SET_PIXEL_FORMAT 协商、退出时的 dlclose。

pxt-patches 现在校验 11 条补丁(PATCH 1/2/3/5~12,PATCH 4 记 RETIRED)。

fuzz 没进 CI:单轮 5 分钟起步、且需要 -fsanitize=fuzzer 的全套运行时,留在本地按需跑。

验证

  • 末帧哈希:三个基准用例与 0.3.6 逐位相同

    ping 300 帧     0556e78f7ce0e828f2dc922d210dc047
    probe 120 帧    e82844f7160449d1767aa69afe788800
    probe 120 帧按A 0eb7884cb40cef0cb549946af3a942ab
    
  • 契约自检:contract_test 27 项断言,常规与 --reject-rgb565 两种构型全过;
    UBSan 构型同样全过。

  • ASAN:修复前 arcade-cube-land 5 帧即报两处越界;修复后 60 帧零报告。

  • fuzz:208,744 runs / 301 秒,零崩溃。

  • 真前端:ping / probe / Jumpy Platformer 各 120 帧,3/3 PASS,退出码 0。

已知限制(未变)

  • 32 位前端不支持(PXT64 镜像在 32 位 VM 下无法执行)。
  • 即时存档 / rewind / 快进 / 金手指 / Netplay 不提供(v0.3.0 起的范围收敛)。
  • Strawberry_Slam 在固定 tick 触发 PANIC 980,游戏自身 bug,核心侧不修。
  • Switch NX 是独立发布线(nx-v*),本版不发 NX 包。

升级建议

建议升级。画面与 0.3.6 完全一致(末帧哈希逐位相同),但装卡带时少两次越界、
退出前端时不再 139。用 musl 的工具链(Lakka / Knulli / muOS 一类)尤其应该升:那类
分配器不保证 glibc 的对齐余量,第 1 条本来就可能真的踩坏堆。


MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

core v0.3.6 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 08 Nov 10:14

MakeCode Arcade core v0.3.6

一句话:零行为变化 —— 这一版只动构建与验证的基础设施

游戏运行时、VM、音画输出、卡带兼容性一行都没改。三张基准卡带的末帧哈希与 0.3.5
逐位相同,contract_test 两种构型全过。改的是「源码清单有几份」「CI 验到哪一层」
「NX 诊断的取证链要不要一直自动跑」这三件工程债。

如果你的 0.3.5 用着正常,不需要升级。

1. 源文件清单收敛到一处

以前 5 个构建入口各自列一遍要编哪些源文件:

core/Makefile · core/jni/Android.mk · tools/build_core.sh
tools/build_target.sh · tools/build_musl.sh

v0.3.5 删 PNG 解码链路那轮就漏改了两处,靠 CI 链接失败才发现。反方向更糟:漏列一个源
不会报错,只会静默少符号,等到真机某个功能不响应才回头查。

现在唯一真源是 core/sources.mk(三行「名字 := 空格分隔值」),shell 侧由
tools/lib/sources.sh 用 sed 读同一份文件。顺带把链接时的 "$OBJV"/*.o 换成由清单
推出的对象数组 —— 老构建目录里躺着的 cart.o / png_loader.o / LzmaDec.o 不会
再被 glob 静默链进产物。

2. CI 补两处「没人验过」的洞

末帧哈希回归(golden-hash job)

契约测试只能断言「核心有没有按 libretro 规范说话」,抓不住「契约全绿但画面画错了」。
新增 tools/ci_regress.sh:跑卡带 → 比 FINAL-FRAME-HASH → 不一致就 exit 1。三个用例:

用例 验的是
ping 300 帧,无输入 静态场景 + 定时器路径
probe 120 帧,无输入 纯色渲染基线
probe 120 帧,按住 A RetroPad A → MakeCode A 的按键映射

probe.pxt64 由仓库内 tools/make_probe_cartridge.py 现场生成,自有卡带,无版权问题。
基线在 tools/fixtures/golden-frames.txt,--record 重生成时只替换正文、保留注释头;
--bmp-dir 落末帧,失败时 CI 会把三张 BMP 当 artifact 传上来,方便直接看「变成什么样」。

发行包自验(package job 末尾新增一步)

以前打包完就上传,玩家下载到的那个 zip 没人跑过——v0.3.1 的 Windows 包里只有
.pdb 没有 .dll 就是这么漏出去的。现在打包后会解包、dlopen、load_game、跑 60 帧,
真正装不上就红在发版之前。

pxt 补丁校验(pxt-patches job)

vendored 的 pxt 树里 9 个必要补丁(MCA PATCH 1/2/3/5~10)以前只靠
docs/M3-VM-HOST.md 的人工步骤重放,换机器、重 clone 后没有任何东西能确认它们还在。
新增 tools/check_pxt_patches.py 表驱动校验:每条补丁声明「哪个文件 + 什么正则」,
失配时报出编号与后果;--strict 还会抓树上未登记的补丁编号。

3. NX 诊断收窄

  • 实现拆出:129 行开机 trace 从 libretro_core.cpp 搬到 core/src/nx_diag.{h,cpp},
    接口层只剩 10 处 MCA_NX_BOOT(...),该文件内已无 __SWITCH__。非 Switch 平台编成
    空 TU(零符号),所以能直接列进清单、不用加平台条件。
  • 自动触发取消:nx-diag.yml 只保留 workflow_dispatch。原先每次 push 命中
    core/src/**、runtime/**、core/Makefile 就自动跑两个 job(装 portlibs + 克隆
    RetroArch + 编 4 个 NRO,十几分钟 ×2)并覆盖预发布页。NX 线是挂起在等上游
    libretro/RetroArch#18905
    (根因在系统侧 mesa nv50_ir,核心从未出现在任何崩溃栈上),恢复前不会有新证据。
  • 删掉启动时的 __attribute__((constructor)):它唯一的作用是证明「本文件的目标文件
    真被链进 NRO」,而这件事 nx.yml 已用符号断言回答(retro_load_game /
    pxt_vm_start_buffer / mca_tick_init 必须在 NRO 的 ELF 里)。正式 NX 包因此少一次
    每次启动写 SD 卡。

4. 文档漂移

  • tools/nx-probe/diag-notes.md 前后两段结论互相矛盾:开头说「根因 = Atmosphère 1.11.1
    版本错配,升级 1.12.1 即可」,文末说「机器已是 1.12.1,仍崩,根因是 mesa」。后者才对
    (升级后复测同症状)。已删掉被推翻的那段,降级成一条「已作废的中间判断」留作教训 ——
    它刚好说明崩溃签名逐位一致 ≠ 找到根因。
  • docs/M3-VM-HOST.md 修掉两处:.png 同名 .pxt64 自动旁载(v0.3.5 已删)、
    「9 个补丁固化进 build_vmapp.sh」(早就不对)。

验证

  • 5 个构建入口逐个实跑(工具机 gcc 13.3 / Ubuntu 24.04 / NDK r27):make platform=unix、ndk-build -j4(37 个 .o → 623496 B)、build_core.sh、
    build_musl.sh(零 NEEDED、25 个 retro_*)、build_target.sh
    → aarch64-linux-gnu.2.17 = 5034672 字节(0.3.5 是 5034216,+456 字节,
    是空 TU 的段/对齐差,不是代码变化)。libnx / win64 分支用 make -n 干跑确认
    清单都含 nx_diag.cpp。

  • 跨构型像素等价:三个基准用例在 zig/x86_64-windows、gcc13/x86_64-linux、
    zig2.17/aarch64-linux(qemu chroot,用新产物跑的)三处逐位相同:

    ping 300 帧     0556e78f7ce0e828f2dc922d210dc047
    probe 120 帧    e82844f7160449d1767aa69afe788800
    probe 120 帧按A 0eb7884cb40cef0cb549946af3a942ab
    
  • 契约自检:contract_test 常规与 --reject-rgb565 两种构型各 27 项断言全过。

勘误(0.3.5 说明)

0.3.5 的说明里写「各 28 项断言全过」,实为 27 项(按 contract_test 实际输出的
ok 行计,两种构型都是 27)。数字写错,结论不变:全部通过。

已知限制(未变)

  • 32 位前端不支持(PXT64 镜像在 32 位 VM 下无法执行)。
  • 即时存档 / rewind / 快进 / 金手指 / Netplay 不提供(v0.3.0 起的范围收敛)。
  • Strawberry_Slam 在固定 tick 触发 PANIC 980,游戏自身 bug,核心侧不修。
  • Switch NX 是独立发布线(nx-v*),本版不发 NX 包。

升级建议

不是必须升级 —— 行为与 0.3.5 完全相同(末帧哈希逐位一致)。只有自己用
make / gcc / ndk-build 从源码编的用户会看到区别:清单少了一处维护点,产物多 456 字节。


MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

core v0.3.5 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 08 Nov 04:19

MakeCode Arcade core v0.3.5

一句话:把 libretro 契约上的三处欠账补上,再把「只认 .pxt64」贯彻到底

游戏运行时、VM、音画输出、卡带兼容性一行都没改——21 张语料 × 600 帧与 0.3.3/0.3.4
逐张末帧哈希全一致。这一版改的是核心与前端之间的约定,以及把早已废弃的 PNG 解码
链路整条删掉。

三处契约修复

1. 换卡带不再「谎报成功」

// 0.3.4 及以前:打一条 WARN 就 return true,前端以为换好了,实际还在跑旧游戏
if (runtime_available()) {
    log_printf(RETRO_LOG_WARN, "[MCA] VM already running; reload the core...\n");
    return true;
}
// 0.3.5:先停干净,再装新镜像
if (runtime_available()) vm_stop();

vm_host 的 vm_stop() 本来就能把 VM 线程收干净(卸载/关闭游戏一直走这条),
文档也写着「同一进程内 unload→load 已支持」,唯独 retro_load_game 里那句提前返回
把这条路堵死了。修复后实测三连换卡带(ping→cubeland→jumpy→ping)每张都真正重新
装载镜像(148832 → 181608 → … 字节),各自出帧正常,最后 dlclose 不崩。

2. 像素格式协商提前,失败有回退

以前 SET_PIXEL_FORMAT 是在 retro_load_game 里才发的,失败只打一条 WARN,
渲染路径却无条件按 RGB565 写——前端按默认 0RGB1555 解读,颜色就全错。

现在:

  • 协商放在 retro_set_environment(前端视频驱动已就绪),load_game 时再兜一次;
  • 前端不接受 565 时,真的按 0RGB1555 输出(out_color() 统一转换),
    包括 panic 横幅和测试画面;
  • 回填值也会校验(个别前端返回 true 却改格式)。

3. 只认 .pxt64,PNG 处理全部删除

.info 与 get_system_info 一直只声明 pxt64,前端按扩展名过滤,.png 卡带
根本到不了核心。所以核心侧那套 PNG 入口(try_sidecar_pxt64() 旁载、PNG→彩条分支、
arcade_png_load_project())是纯废料:

删除:core/src/{png_loader.cpp,h, cart.c,h, decompress.c,h}
      core/third_party/{miniz/*, lzma/*}
      core/tests/cart_smoke.cpp
      libretro_core.cpp 里的 PNG 分支与 sidecar 逻辑

代价从 5 处构建清单(Makefile / Android.mk / build_core.sh / build_target.sh /
build_musl.sh)一起摘掉。aarch64 发行产物 5197360 → 5034216 字节,源码净减
约 8700 行。非 .pxt64 现在只在通用镜像校验处失败(not a valid .pxt64 image),
核心不再为 PNG 输出任何专门提示。

顺带删掉了 SET_SUPPORT_NO_GAME(false) 这次无效调用(传 false 等于没声明)。

新增:假前端契约自检(CI 里跑两遍)

0.3.4 修的 SET_CONTROLLER_INFO 缺终止哨兵,是「只有干净 gcc 构型才炸」的未定义
行为——靠真机撞太贵。新增 core/tests/contract_test.cpp,用严格假前端把契约走一遍:

  • get_system_info:valid_extensions 只能等于 pxt64,need_fullpath/block_extract 为 false;
  • 像素格式必须在首次 load_game 之前协商;--reject-rgb565 时验证退回 0RGB1555;
  • SET_INPUT_DESCRIPTORS / SET_CONTROLLER_INFO / SET_VARIABLES 三个数组必须能在
    界内找到终止哨兵(缺哨兵 = 越界读);
  • 喂 PNG 魔数、垃圾字节、NULL:load_game 必须返回 false;
  • 失败后 retro_run 仍要按 16bpp 出帧(尺寸 160×120、pitch 320)。

接入方式:

make -C core platform=unix contract-test                            # buildbot 同构型(gcc/make)
make -C core platform=unix SANITIZE=undefined contract-test          # UBSan 构型,对象独立目录

两条都已加进 .github/workflows/build.yml 的 makefile-compat job。本地实测
gcc 13 与 -fsanitize=undefined -fno-sanitize-recover 下各 28 项断言全过。

验证

  • 21 张语料 × 600 帧:真机 0.3.3 与 0.3.5 逐张末帧哈希全一致,
    ping = f93e4597…、arcade-cube-land = 23210fb3…;判定 ok 20 / panic 1
    (Strawberry_Slam 的 PANIC 980 仍是已知游戏自身 bug)。
  • 架构等价:x86_64 与 aarch64 产物 ping 末帧哈希同为 f93e4597…。
  • 换卡带:三连切换每张都重新装载镜像并出帧,unload → dlclose 正常退出。
  • 发版矩阵:5 个 zig 目标(win-x64/win-arm64/linux-x64/linux-arm64/android-arm64)
    • 4 个发行版工具链构型(gcc x64/arm64、MinGW、ndk-build)全绿。
  • Lakka/musl 全静态:musl.cc aarch64-linux-musl-cross(GCC 11.2.1)编出零 NEEDED
    的 1956064 字节 DSO,与 glibc 版 21 张语料逐张末帧哈希完全一致(ping = f93e4597…)。
  • 发行包体检:6 个包逐个体检 PASS——架构、.info 版本与源码版本一致、
    NEEDED 白名单(lakka 包为 0)、glibc 2.17 基线、25 个 retro_* 导出、包内无 .pdb。

已知限制(未变)

  • 32 位前端不支持(PXT64 镜像在 32 位 VM 下无法执行)。
  • 即时存档 / rewind / 快进 / 金手指 / Netplay 不提供(v0.3.0 起的范围收敛)。
  • Strawberry_Slam 在固定 tick 触发 PANIC 980,游戏自身 bug,核心侧不修。
  • Switch NX 是独立发布线(nx-v*),本版不发 NX 包。

升级建议

行为与 0.3.4 完全相同(哈希一致),所以不是必须升级;但从 0.3.5 起:

  • 换卡带(不重载 core 直接 load 第二张)才真正可用;
  • 拒绝 RGB565 的前端不会再出现配色错误;
  • 自己用 gcc/make 从源码编的用户,产物小了约 160 KB、少 5 个编译单元。

MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

core v0.3.4 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 07 Nov 15:31

MakeCode Arcade core v0.3.4

一句话:只修一个「大多数设备没暴露、但确实存在」的崩溃隐患

0.3.4 与 0.3.3 之间,游戏运行时、VM、音画输出、性能、卡带兼容性一行都没改。
改的是核心初始化时给前端的一小段元数据:

// 0.3.3 及以前
static struct retro_controller_info infos[1] = {};
// 0.3.4
static struct retro_controller_info infos[2] = {};
infos[1].types = nullptr;   // 补上终止哨兵

RETRO_ENVIRONMENT_SET_CONTROLLER_INFO 约定前端按 port 顺序一直读到 types == nullptr
才停
,不接受额外的数组长度参数。只给一个元素,前端就会去读不存在的 infos[1].types
——典型的越界读,读到什么完全取决于那一刻栈上/静态区里剩下什么。

为什么以前没炸,为什么必须修

构型 表现
已发布的 zig 发行包(glibc 2.17 基线) 那块内存恰好是 0,前端读到 NULL 就正常停下;运气好,不是正确
gcc 12 干净源码构建(Linux x86_64) 残留是 0x65646f43656b614d,也就是小端字符串 "MakeCode",被当指针 strlen → 稳定 SIGSEGV,核心加载即崩

这次是在新搭的常驻验证节点上,用 debootstrap 建了一个只装 g++/make 的干净
Debian rootfs 编源码时才撞出来的。zig、clang 与几种 ARM 设备都没暴露,说明问题不在
某个平台,而在未定义行为对编译器布局的依赖。换前端、换编译器、换优化等级都可能
让它从「没事」变成「必崩」;而官方 buildbot 收录用的正是 gcc/make 构型,所以这个修复
必须在收录推进前发出去。

给前端开发者的提示:如果你自己写 libretro 前端,请不要因为 0.3.3 能跑就把
SET_CONTROLLER_INFO 当成定长数组处理——规范里它就是 NULL 终止的。

行为确实没变(逐帧验证过)

  • 21 张语料 × 600 帧:真机 0.3.3 与修复版 逐张末帧哈希全一致,
    ping = f93e4597…、arcade-cube-land = 23210fb3…,与历史基准对齐。
    唯一异常仍是已知的 Strawberry_Slam PANIC 980(游戏自身 bug,跨平台一致)。
  • 修复后四路构型语义等价:zig x86_64 / zig aarch64 / gcc 干净 x86_64 / Windows .dll,
    ping 末帧哈希同为 f93e4597…。
  • cubeland 连跑 20000 帧,RSS 稳定在约 16 MB,22 次采样无增长。
  • 真 RetroArch 前端层(宿主 1.18 与 arm64 chroot 1.14):.info 被识别、核心加载、
    内容载入、持续出帧到 16 万+ tick;tick 41683 的已知 panic 后核心自动重载、宿主存活。

同时修掉的测试工具缺陷(不进发行包)

  • tools/libretro_host.py:把 retro_log_printf_t 的第一个变参声明成 c_char_p,
    ctypes 转 Python 对象时会无条件 strlen 它;在 Linux x86_64 / Python 3.12 下同样会
    读到垃圾指针而崩。已改为只声明固定的两个参数(日志里的 %s 显示占位符,
    画面与哈希判据不受影响)。这是测试宿主的锅,不是核心的。
  • tools/sweep_carts.py:新增 --turbo,批量回归跳过 27fps 节拍 sleep;默认行为不变。
    加上后 qemu-user 里 21 张卡带全量回归约 2.5 分钟。

验证与打包

  • 发版矩阵 5 个 zig 目标 + 4 个发行版工具链构型(gcc x64/arm64、MinGW、ndk-build)全绿。
  • 6 个包「装一遍再验」:架构、.info 版本与 tag 一致、ELF NEEDED 白名单、
    glibc 2.17 基线、retro_* 导出数、Android 16KB 段对齐、包内无 .pdb,全部 PASS。
  • 干净 buildbot 构型单独验过:Debian bookworm + g++12 + make 编出 373 KB .so、
    25 个 retro_* 导出,依赖全在白名单内;它的 glibc 基线是 2.34,与发版 zig 包的
    2.17 基线不同——这正是两套 CI 分开跑、不互相替代的原因。

已知限制

  • 32 位前端仍不支持(PXT64 镜像在 32 位 VM 下无法执行,见 v0.3.1 说明)。
  • 即时存档 / 快进仍不提供(见 v0.3.0 说明)。
  • Strawberry_Slam 在固定 tick 触发 PANIC 980,属游戏自身 bug,核心侧不修。
  • Switch NX 是独立发布线(nx-v* tag),本版不发 NX 包,现有 NX 产物仍是 0.3.3。
    它编的是同一份核心源码,因此同样带着上面那个哨兵缺陷;下次 NX 发版会一并带上修复。

升级建议

  • 自己用 gcc/make 从源码编译的用户:建议尽快升级,旧的干净构型在 Linux x86_64 上会崩。
  • 用现成发行包的用户:0.3.3 大概率一直跑得好好的,不是紧急升级;但这是未定义行为,
    换前端或换版本后没有保证,建议顺手换掉。
  • Linux / Windows / Android 的游戏表现与 0.3.3 完全相同,升级不会带来画质、帧率或
    兼容性变化。

MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

nx v0.3.3 - Switch NRO (RetroArch + core)

Choose a tag to compare

@github-actions github-actions released this 06 Nov 08:24

MakeCode Arcade core for Nintendo Switch — nx v0.3.3

Switch 线的首次独立发布。这是 Switch 专用的 NRO,不是核心 .so。

先说清楚它是什么

Switch 上没法像 PC / Android 那样往 cores/ 目录丢一个 .so——libnx 没有
dlopen。所以核心必须编成静态库,和 RetroArch 前端一起链成一个 NRO:

makecode_arcade_libretro_libnx.nro   ← RetroArch 前端 + MakeCode Arcade 核心
makecode_arcade_libretro.info
安装说明.txt

也就是说:一个核心对应一个 NRO,换核心等于换前端本体。这与 RetroArch 官方
在线更新器在 Switch 上的做法一致(那边下载的 core 也是一个一个 .nro)。
玩别的模拟器要装别的 NRO,两者不冲突。

核心源码与 core-v0.3.3 的 6 个平台包完全同一份,游戏行为、音画、性能一致。
本包只是把链接形态换成了 aarch64-none-elf 静态链。

安装

  1. 把 makecode_arcade_libretro_libnx.nro 与 makecode_arcade_libretro.info
    一起拷到 SD 卡:sdmc:/retroarch/cores/
  2. 卡带(*.pxt64)放任意目录,例如 sdmc:/roms/makecode/
  3. 在 hbmenu 里启动这个 NRO,选卡带即可游戏

启动方式建议用 title takeover:按住 R 点任意已装游戏进入 hbmenu,
这样拿到的是完整内存(约 3.2GB)。从相册(applet 模式)进也能跑,但该模式
只有 448MB——本核心 RSS 约 11MB,两种模式都够用。

按键:Start = 游戏内菜单,Select = 重启游戏。方向 / ABXY 在
Quick Menu → Controls 里改。

验证到哪一步(请务必读这一段)

这个包还没有在真机上运行过。 手上暂时没有 Switch。

已经做到的验证:

  • 静态库层:成员数 == 对象数(防同名对象被 ar 覆盖)、AArch64 架构、
    retro_* 全局符号 ≥20 个、retro_init / retro_run / retro_load_game /
    retro_set_environment 逐个存在。
  • NRO 层:链接后回头查 ELF 符号表,确认 retro_load_game、
    pxt_vm_start_buffer、mca_tick_init 三个只属于本项目的符号真的进了
    最终可执行体——链接成功不等于归档成员被引用进来了,没这一步的话核心可能
    整个被链接器丢掉而表面上"构建成功"。

但这只证明 ABI 与符号对得上,不证明运行期正常。最可能出事的地方是 libnx
那套精简 pthread:本核心的 VM 线程用到 pthread_cond_timedwait 与递归互斥量,
如果启动后黑屏或卡在加载,八成在这里。

如果遇到问题,请把现象说清楚(能不能进 RetroArch 菜单 / 加载卡带后是黑屏、
卡住还是崩溃回 hbmenu),有日志就更好。

与 6 平台包的关系

渠道 内容 适用
core-v0.3.3 Release 6 个 .zip(linux / windows / android / lakka) PC、掌机、Android、Lakka
本条 Release(nx-v0.3.3) 1 个 .zip(NRO + .info + 说明) Nintendo Switch

两条线版本号同步,但是分别发布:NRO 要拉 RetroArch 源码 + 装 portlibs,
构建十几分钟,绑在主发版流水线里会拖慢每一次核心发版。


非官方第三方项目,与 Microsoft、Nintendo 均无关。Nintendo Switch 是任天堂的商标。

core v0.3.3 - libretro core (6 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 06 Nov 07:50

MakeCode Arcade core v0.3.3

这一版是两个新平台的接入,游戏本身没有任何变化

0.3.2 到 0.3.3 之间,游戏运行时、VM、音画输出、性能、卡带兼容性一行都没改。
这一版做的事是让同一个核心能装到两种此前装不上的系统上:

平台 本版之前 本版之后
Lakka / LibreELEC(aarch64) 装不上 新增 musl 全静态包
Nintendo Switch(libnx) 不支持 新增静态核心 + NRO 打包链路

如果你的设备是 Linux / Windows / Android,这一版与 0.3.2 行为完全一致,没有升级理由。
已经能跑的设备不必动。

Lakka / LibreELEC:为什么必须静态链接

Lakka 与 LibreELEC 用的是 musl libc,而此前发布的 .so 全部是 glibc 动态链接的——
放到 Lakka 上 RetroArch 会直接报 "无法加载核心",因为 rootfs 里根本没有 libc.so
(只有 ld-musl-aarch64.so.1)。

修法是把这个包做成零依赖的全静态 DSO:readelf -d 看不到任何 NEEDED 条目,
libc 与 libstdc++ 全部链进 .so 本体。Lakka 官方 buildbot 产的核心也是这么做的。

技术上走过一条弯路,记在这里供参照:zig 的 musl 交叉编译做不出可用的全静态
DSO——-shared 会留下 NEEDED libc.so,-static -shared 顺序反了会产出 ar 归档,
-nostdlib 手工链静态库时 zig 的 musl 树缺 dup3.c / mprotect.c,且它的
libc.a 是 exe 专用非 PIC,塞进 DSO 只能靠 -Wl,-z,notext 硬来(结果是 TEXTREL,
在强制 W^X 的系统上加载即失败)。最终改用 dockcross 的
linux-arm64-musl + GNU ld 的 -shared -static,与 buildbot 同构型。

包名:makecode_arcade_libretro_lakka-arm64.zip
装法:.so 与 .info 一起放到 /storage/cores/,重启 RetroArch。

Nintendo Switch:独立发布,不在本页的 6 个包内

Switch 的形态很特殊:libnx 没有 dlopen,核心不能是独立 .so。它必须编成
静态库 libretro_libnx.a,和 RetroArch 前端源码一起链成一个 retroarch_switch.nro。
也就是说 一个核心对应一个 NRO,换核心等于换前端本体——这与"把核心放进前端
cores 目录"的常规玩法不是一回事。

因此 Switch 产物不进本页的 6 个包,由独立的 NX 流水线产出
(artifact 名 nx-switch-nro),内容为:

makecode_arcade_libretro_libnx.nro
makecode_arcade_libretro.info

装法:两个文件一起放 sdmc:/retroarch/cores/,卡带放 sdmc:/roms/makecode/。
NRO 采用 title takeover(覆盖相册/任意已装 title 启动)。

请注意这一条:Switch 链路目前只做到"编译 + 链接 + 符号验证",尚未在真机运行过。
CI 里做了实证校验(确认 retro_load_game、pxt_vm_start_buffer、mca_tick_init
这几个符号真的出现在最终 NRO 的 ELF 里,而不是链接时被静默丢弃),但这只证明
ABI 与符号对得上,不证明运行期正常。最可能出问题的地方是 libnx 那套精简 pthread
与本核心 VM 线程使用的 pthread_cond_timedwait / 递归互斥量。首次上真机若出现
黑屏或卡住,属于预期内的未验证风险。

顺带修掉的一个构建期真 bug

把 pxt 运行时编成静态库时发现:runtime/pxtapp 里 base/control.cpp 与
core---vm/control.cpp 同名(分别定义 millis/reset 与 raiseEvent/_ramSize,
符号互补不重叠)。GNU ar 归档时只保留基名、丢弃目录,两个 control.o 进同一个
.a 时后者会静默覆盖前者,符号就此消失,要等到链接期才以 undefined symbol
形式炸出来,且看起来与文件名毫无关系。

修法是在归档前把对象拷成路径扁平的唯一名(o_<完整路径下划线化>),归档后立刻
断言成员数等于对象数,不一致就直接失败。这个问题只影响静态链接路径(即 Switch),
所有动态 .so / .dll / .dylib 包不受影响
——它们是把带完整路径的对象列表
直接交给链接器,从不经过 ar。

验证到哪一步

  • 核心行为回归:与 0.3.2 同一份源码树,运行时零改动,20 张语料的行为基线不变。
  • Lakka 包:全程用 dockcross 构建,CI 里跑 900 帧 miniretro 冒烟
    (ubuntu-24.04-arm),并断言产物 NEEDED 为空、导出符号 ≥20 个。
  • Switch 包:静态库与 NRO 两段都做了校验——库成员数、AArch64 架构、
    retro_* 全局符号数量、关键符号逐个存在,NRO 里再查一遍核心符号是否真的链进去。
  • 尚未做:两个新平台都没有实际硬件运行(手上暂时没有 Switch 与 Lakka 设备)。
    已在 0.3.2 验证过的 8 台 Linux ARM 掌机、以及 Android 目标是稳定的。

已知限制

  • Switch 与 Lakka 均为首次支持,未经真机验证。报障请附上前端日志。
  • 32 位前端仍不支持(PXT64 镜像在 32 位 VM 下无法执行,原因见 v0.3.1 说明)。
  • 即时存档 / 快进仍不提供(原因见 v0.3.0 说明)。

升级建议

  • Linux / Windows / Android 用户:无功能变化,可以不升级。
  • Lakka / LibreELEC 用户:这是目前唯一能用的版本,取 lakka-arm64 包。
  • Switch 用户:可以试,但请预期这是未经真机验证的首次支持。

MakeCode Arcade core 是非官方的第三方项目,与 Microsoft、Nintendo 均无关。

nx-diag - 排查用探针(不是发版)

Choose a tag to compare

@github-actions github-actions released this 06 Nov 13:17

自动生成的诊断产物,用于定位 Switch 上"加载游戏后黑屏几秒就崩"的问题。不是发版,不是给玩家玩的东西。

最终结论(2026-11-07):根因在系统侧,不在核心

用户侧决定性发现:官方 RetroArch 前端加载其他核心的游戏同样崩 —— 与我们的核心无关。
用户启动方式为 NSP forwarder(title takeover 全内存),applet 内存额度论也排除。

用符号表(mca_boot.symbols.txt + addr2sym.py)解析 4 份 crash report,
所有崩点全在 mesa/nouveau(Switch GL 驱动)的 malloc/free 路径里,核心函数从未上栈:

场景 栈(自底向上截取)
ozone 菜单画光标 _malloc_r ← nouveau_mm_allocate ← nouveau_buffer_transfer_map ← glBufferData ← ozone_draw_cursor
swap buffers _free_r ← nouveau_fence_trigger_work ← eglSwapBuffers ← gl2_frame
游戏运行期(旧报告) dlmalloc 拆链 ← nouveau_buffer_create ← nvc0_launch_grid

野指针高位全是 0x3f…(double 位模式)—— 堆空闲链表被浮点数据覆盖,是系统级内存被破坏的表现。

根因:固件 22 + Atmosphère 1.11.1 错配。 官方 release notes 对照:
1.11.0=22.0.0 基础支持 → 1.11.1=22.1.0 → 1.11.2(2026-06)才补全 22.x → 1.12.1(2026-10-16)= 22.x 全量 + 23.0.0。
fw 22 发布时 GBAtemp 帖子的症状(自制必崩、forwarder 能进但加载内容报错)与本机逐字吻合。
解法:升级 Atmosphère 到 1.12.1(fusee 必须同步更新,fusee-primary 已废弃;Hekate 一并升)。

我们的 NRO(CI libnx 4.12.0)证据链健康:菜单能进、VM 10ms 就绪、Lakka 真机全通过。
教训:没有符号表时纯反汇编"还原"函数会把 nouveau_buffer_create 误读成"我们的清理循环" ——
nx-diag 附带 symbols.txt + addr2sym.py 是诊断链的固定环节,不要省。

已经确认的事实

真机:固件 22.0.0 / Atmosphere 1.11.1,从 hbmenu 启动。

观察 结果
ra_plain.nro(RetroArch 本体,不含核心) 能启动,正常
mca_boot.nro / 发版包(前端 + 我们的核心) 能启动,VM 10ms 就绪进主循环,但画面黑,几秒后进程崩

mca_trace.log 停在 === core started ===,再往后一行都没有 —— 说明 VM 起来了、游戏在跑,是运行期崩的,不是启动问题。

崩溃报告(Atmosphere)读出来的结论:

Result 2168-0002 (Data Abort)
PC = retroarch_switch + 0x7d20c4
 7d20c0  ldr x1, [x6, #0x18]     ; 空闲块 chunk->bk->fd
 7d20c4  str x1, [x0, #0x18]     ; 崩在这,x0 = 0x3f0a8a8b3dc8c8ca(野指针)

这段是 newlib 的 free() 在拆空闲链表。堆被人写坏了(空闲块的 fd 被覆盖),不是 libnx ABI / 链接 / 内存不足。
(后注:该 PC 实为 _dtoa_r+0x11e4 处的 dlmalloc 例程,调用方是 nouveau——见上表;当时没有符号表,归属判断部分有误。)

模块归属也是确定的:报告里模块的 text 段 8,286,208 字节,与本 NRO 的 text_size 逐字节相等(ra_plain 是 8,151,040,差 135,168)。所以崩的确实是"前端 + 我们的核心"这个包。

这一版加了什么

1. sdmc:/switch/mca_run.log —— 运行期 trace,每 30 帧(0.5 秒)一行:

[host] stack request=8388608 set=0 get=0 got=... create=0
[vm] thread entry local=0x...
[run] first retro_run (mode=0)
[run] f=30 online=1 thr=1 up=1 panic=0 mode=0 sp=0x...
[run] f=60 online=1 ...

每行写完之后还会做一次 malloc(24) + free() 的堆探针。也就是说:如果日志最后一行是 f=1230,那崩溃就发生在第 1230 帧之后的这次探针里 —— 帧号直接给你。

日志用裸 open/write/close 写,不走 stdio:堆坏了以后 fprintf 自己可能要 malloc,写不出去。

stack request=8388608 ... got=? 这一行是专门查"VM 线程真的拿到 8MB 栈了吗"——libnx/newlib 有可能把它悄悄限成 128KB,那样 VM 深递归就会踩穿相邻堆,症状和现在完全一致。

2. sdmc:/switch/mca_mode.txt —— 切通路口径,用记事本建一个纯文本,内容写一个数字:

内容 行为
0 或没有这个文件 正常(默认)
1 不往前端推视频帧(画面全黑)
2 不往前端推音频
3 完全不拉 VM 数据(黑帧 + 静音),只跑 VM 自己

同一份包跑四次,就能判断堆是死在 video 回调 / audio 回调 / pxt 取帧拷贝 哪一条上,还是与这三条都无关(那就是 VM 线程自身)。

请这么跑

全部放 sdmc:/switch/,按住 R 点任意已装游戏进 hbmenu。

  1. 先跑一次 mode 0(不放 mca_mode.txt 就是 0),等它自己崩掉。
  2. 回传 sdmc:/switch/mca_run.log(整个文件,不只是最后几行)+ 新的崩溃报告。
  3. 如果还有余力,再把 mca_mode.txt 依次写成 1 / 2 / 3,每次跑完记一句"崩了没崩、大约几秒",并保留当次的 mca_run.log(会被追加,不是覆盖,所以在行首记一下当前批次也行)。

崩溃报告在哪

sdmc:/atmosphere/crash_reports/

按修改时间取最新那份 .log。重点看 PC / LR 的 retroarch_switch + 0x... 偏移——配上本页的 mca_boot.symbols.txt 能直接翻成函数名。

附带文件

  • mca_boot.nro — 我们的核心 + 诊断打点(-DMCA_NX_DIAG=1,正式发版包不带这些打点)
  • ra_stubcore.nro — RetroArch + 空核心(只验证静态核心机制)
  • probe_nacp.nro — 纯 libnx 控制台程序(带 NACP 的版本)
  • ra_plain.nro — RetroArch 本体,不含核心
  • *.symbols.txt — 对应 NRO 的 nm -n 符号表,崩溃偏移靠它对到函数
  • *-build.log — 构建日志

最终定案(2026-11-07 凌晨)

机器:固件 22.0.0 + Atmosphère 1.12.1(用户已从 1.11.1 升级)。

**这不是我们核心的问题。**证据链:

  1. crash report 里的栈从未出现核心函数;VM 侧 mca_trace 一路跑到
    "core started"(镜像装载/GC/initRuntime/主循环全通,10ms 就绪)。
  2. 官方 RetroArch 1.21.0 与 1.22.2(不含任何第三方核心)裸前端同样崩,
    用户配置重置(retroarch.cfg 重生 + 无着色器缓存)后依旧。
  3. 崩点在 mesa/nouveau 的 nv50_ir 着色器编译器(1.22.2 符号已确认:
    NVC0LegalizePostRA::findFirstUses 读哈希表野指针)。1.21.0 与 1.22.2
    寄存器签名逐位一致(X5=0xfffffffe, X6=0x21),野值每次不同(符号扩展
    负值垃圾)。
  4. 连非 RA 的自制 GUI(tencent-switcher-gui)也崩,野值特征相同;
    melonDS 正常(软件渲染,不走 GL 着色器管线)。
  5. 启动方式矩阵:title takeover = 菜单✓、加载核心崩(Application 进程崩);
    applet = NRO 跑在 hbloader 进程里,RA 1.21.0 一启动整个 hbloader 崩
    (Program ID 010000000000100d)→ 整机重启。

上游:libretro/RetroArch#18905(open,fw21.2 起有人报,fw22.5 复现);
Atmosphere-NX/Atmosphere#2717(同错误码的 applet 崩溃讨论)。

NRO text 大小对照表(判 crash report 归属用):
我们的 NRO=8,286,208 / 官方1.22.2=8,134,656 / 官方1.21.0≈7,741,440(个别
报告 7,737,344,段对齐差一页)/ tencent-switcher-gui=4,984,832。

core v0.3.2 - libretro core (5 platforms, 64-bit)

Choose a tag to compare

@github-actions github-actions released this 03 Nov 15:27

MakeCode Arcade core v0.3.2

游戏崩溃不再带崩前端(本版最重要的一条)

上一版存在一个真实且高频的缺陷:游戏一旦 panic,核心会把整个 RetroArch
一起拖死
——玩家看到的是前端直接退出,而不是"游戏出错 → 回到菜单"。

本版把它修掉了,同时修掉同一根因下的第二个隐患(VM 的 try/catch)。

问题一:panic 后进程 0xC0000005

上游 pxt 的约定是 soft_panic() / target_panic() 不返回(在 ESP32 上
直接 abort()),VM 里的 C++ 全部按这个约定书写:

if (!isPointer(v)) failedCast(v);   // 不返回
return getVTable((RefObject *)v);   // 于是这里假定 v 一定可用

v0.2.14 起把 panic 改成"置一个标志就返回",于是这些调用方拿着 undefined
继续解引用——以社区游戏 Strawberry Slam 为例,它在 asRefCollection() 上踩
PANIC 980(把 undefined 当数组用)后,进程当场访问违例,前端跟着退出。

修法:panic 之后不许 return。在 mainRunLoop 装 setjmp 回弹点,
VM 线程上的 soft_panic / target_panic 直接 longjmp 回去,由循环顶部的
if (panicCode) 分支执行原有的 cleanup 与正常线程退出——前端照旧自动重启
游戏,连续失败 3 次后放弃,宿主进程始终存活。

问题二:VM 的 try/catch 同样带崩前端

同一根子的另一半,只是在 Windows 上以另一种方式炸:0xC0000028 STATUS_BAD_STACK。

mingw-w64 的 longjmp 在 x86_64 上走 SEH(RtlUnwindEx),逐帧回退必须有
.pdata,而本工程此前按 -fno-unwind-tables 编译——longjmp 自己就崩,
还没轮到 panic 逻辑。游戏里只要用到 try { … } catch { … } 就能触发。

修法:Windows 目标打开 -funwind-tables -fasynchronous-unwind-tables
(DLL 体积 +22KB),panic 回弹点与 VM 异常回跳(FiberContext::loopjmp)
共用这套机制,恢复标准的 setjmp / longjmp 写法。

验证

  • 卡带回归:20 张语料全量跑完,19 ok + 1 panic,逐张数值与修复前一致
    (无行为变化)。
  • 崩溃样本:Strawberry Slam 6000 帧 → PANIC 980 → 自动重启 3 次 →
    到上限停机,进程退出码 0,trace 完整走完 cleanup 0/6 → 6/6。
  • 异常样本:新增 tools/fixtures/trycatch-main.ts(throw → catch →
    继续跑),600 帧正常出画面。
  • 真机:RG353M(RK3566)、R36S(RK3326)、RG353V(RK3566)三台都装上
    同一个 arm64 构建,功能与桌面一致——panic 后前端存活、异常样本正常、
    音频正常。性能数据见 docs/DEVICE-TEST.md 的 v0.3.2 一节。
  • CI:64 位编译矩阵 + miniretro 冒烟 + makefile-compat 三平台全绿。

已知限制

  • R36S(RK3326 / 918MB)跑最重的 arcade-cube-land 只有约 1.08 倍余量
    (65 fps , 60fps 目标),是全系列下限;其余机型与组合余量均在 1.5 倍以上。
  • 32 位前端仍不支持(原因见 v0.3.1 说明)。
  • 即时存档 / 快进仍不提供(原因见 v0.3.0 说明)。

升级建议

直接覆盖旧的 .so / .dll / .dylib 即可,.pxt64 卡带与配置完全兼容。
强烈建议升级:本版解决的是"个别游戏把前端一起带死"的问题,
不升级的代价是玩家需要硬重启设备。


MakeCode Arcade core 是非官方的第三方项目,与 Microsoft 无关。