构建管线与调试器:从 JSON 到 .gb ROM
在编辑器里点下 Build,几秒后你得到一个 .gb 文件。这中间发生了四件事:脚本编译、素材编译、GBDK 构建、链接出 ROM。这篇把四步拆开讲清,顺带澄清流传最广的 GBA 误解,并教你读懂调试器里那个信息量巨大的 ROM Usage 面板。
四步管线:从 JSON 到 ROM
- 脚本编译。
compileData.ts遍历项目里的所有脚本(场景钩子、角色脚本、自定义脚本),带着场景、实体、素材、变量与引擎上下文调用脚本编译器,输出 GBVM 汇编 .s 文件和脚本头文件——你拖的每个事件方块,此刻都变成了 GBVM 指令序列。debug 关闭时,相同编译产物可以复用缓存符号,这也是为什么改一行事件后重 Build 有时快得反常。 - 素材编译。九类素材生成器按需把"在用"素材编译为 C 源码与头文件,未使用的素材不进 ROM(清单见素材管线一篇)。
- GBDK 构建。
makeBuild.ts根据项目设置配置 GBDK:目标平台、卡带类型、颜色/SGB/debug 选项、编译器预设,然后运行生成的构建命令,产出链接文件。 - 链接出 ROM。调用 GBDK 的 lcc 链接器把所有目标文件链接成最终 ROM:非彩色命名为 .gb,彩色命名为 .gbc。
看清这条链的好处是报错可定位:链接阶段报 Bank 溢出,问题多半在数据体量;脚本编译报错,问题一定在你拖的某个事件里,错误信息会带上上下文。
三个导出目标
develop 分支的 buildProject.ts 接受三种导出目标:
| 目标 | 产物 | 说明 |
|---|---|---|
| rom | .gb / .gbc | 标准卡带镜像,R36S 拷进 gb/gbc 目录即玩 |
| web | 网页构建 | 走 exportWebBuild,产出浏览器可玩的版本 |
| build/pocket | 把 ROM 拷入 build/pocket,供 Analogue Pocket 使用 |
CLI 里三个命令一一对应:make:rom、make:web、make:pocket(用法见插件系统与 CLI一篇)。
重要澄清:没有原生 GBA 构建目标
一个流传很广的误解值得专门说清:develop 分支源码里不存在 GBA 构建目标。你在事件表里看到的 "If GBA Mode Is Available" 事件是运行时检测——它读取 _is_GBA 标志(等于 1 才走该分支),并要求项目的 Color Options 设为 Color+Monochrome 或 Color Only。它检测的是"这个 GB/GBC ROM 此刻正跑在 GBA 硬件上",让游戏在 GBA 实机上能做能力分支处理,而不是把项目编译成 .gba 文件。对 R36S 玩家结论很简单:GB Studio 的产出本来就是 GB/GBC ROM,用掌机的 GB/GBC 模拟核心游玩即可。此为 develop 分支状态,以发布版为准。
调试器:debug 构建才有的超能力
调试功能依赖 debug 模式构建:这类构建会把调试符号、内存映射、全局变量、断点、监视变量和 GBVM 脚本数据一并传给调试器。你能用的武器有三件:断点,停在任意脚本位置单步观察;Watch 控件与 Watched 视图,盯住任意全局变量的实时值;以及最省时间的 "Pause On Watched Variable Change"——监视变量一发生变化就自动暂停。
实战建议:任务没触发、状态没切换时,把相关变量加进 Watch、打开变量变化暂停,跑一遍场景——变量在哪一步变成了不该变的值,一目了然。这比在脚本里塞十几行"显示变量"对话框快得多,也不会忘了删。
ROM Usage 面板:你的容量仪表盘
调试器的 ROM Usage 面板显示 ROM 已用量、当前尺寸与最大容量,并列出 Bank 0 与 WRAM 用量,以及各部分构成:引擎、音乐驱动、GBDK 运行时、项目数据、插件、保留空间。部分构建类型在接近上限时会给出警告,并显示剩余可用部分。
读这个面板的正确姿势:项目数据是你能直接省的部分——删素材、精简场景、少用几首音乐;引擎、音乐驱动、GBDK 运行时是固定开销,不值得纠结;插件用得越多占用越大,装之前先想想值不值。另一个容易被忽略的点:Bank 0 和 WRAM 接近上限是比 ROM 总量更危险的信号——它们溢出时链接器直接报错,哪怕 ROM 总量还剩一大半。
debug 构建别拿去发行
debug 构建包含额外的符号与调试数据,体积和运行表现都与正式构建不同。发给别人玩、拷进 R36S 之前,务必用非 debug 设置重新构建。
下一步
想知道插件如何影响构建占用、CLI 怎么把构建搬上命令行,读 插件系统与 CLI:扩展 GB Studio 的正确姿势;想看数据从哪来,读 项目文件解剖:.gbsproj 与目录结构;构建完怎么系统化验证,读 测试与验收清单。