素材管线:从 PNG 到 ROM 里的一块图

你在编辑器里拖进一张 PNG、画好一个场景,点下 Build 之后,这些"素材"到底经历了什么,才变成 ROM 里的一块图块数据?这篇从源码视角把素材管线拆开——看完你会明白,为什么删掉没用过的素材对 ROM 毫无影响,以及 .gbsres 为什么比 PNG 本身更值得仔细对待。

一条链:编辑器 → 素材编译器 → GBDK

GB Studio 的数据编译由 compileData.ts 统一驱动:它先遍历项目里的所有脚本,带着场景、实体、素材、变量与引擎上下文调用脚本编译器,产出 GBVM 汇编(.s 文件和脚本头文件);随后素材生成器接管,把编辑器里的九类素材逐一翻译成 GBDK 能编译的 C 源码和头文件。脚本决定"游戏怎么跑",素材决定"游戏长什么样",两条编译线在构建阶段汇合,最终由 GBDK 的 lcc 链接器打包成 ROM。

理解这条链的关键在于:你在编辑器里看到的素材,和 ROM 里的素材,中间隔着一整层"翻译"。翻译规则吃透了,很多构建期的报错和体积问题都能自己定位。

素材编译器清单:九类素材各自产出什么

素材生成器覆盖 scenes、sprites、tilesets、palettes、fonts、images、emotes、music、sounds 九类。它们的产物不是"图片文件",而是 C 源码与头文件:

素材类型编译产物(GBDK 侧)
scenes每个场景一份 .c/.h:场景主数据加 _collisions 碰撞图;场景里若有角色、触发器、精灵、弹幕,还会另出 _actors、_triggers、_sprites、_projectiles 对应文件
sprites每个用到的精灵一份 .c/.h;其 VRAM 图块数据单独归入图块集产物
tilesets图块集 .c/.h(背景图块集与精灵图块集分别编译)
palettes每个用到的调色板一份 .c/.h
fonts每个用到的字体一份 .c/.h;如果一个字体都没被引用,编译器会检查默认字体资产,找不到直接抛缺失字体的错误
images(背景)背景 .c/.h,外加 tilemap 与 tilemap 属性表的 .c/.h;UI 边框和光标也会转换成图块数据(frame_image、cursor_image 等)
emotes每个用到的情绪表情一份 .c/.h
musicmusic_data.h 加逐曲编译的音乐轨道数据(详见音乐与音效一篇)
soundsWAV/VGM 被转成内嵌 C 数组的原始数据(带静音掩码声明);FXHammer 音效走专用编译路径

注意"每个"二字:编译粒度是单个素材,而不是整个目录。这正是按需编译能成立的结构基础。

未使用的素材不进 ROM

编译器不会把 assets 目录整个塞进 ROM,而是在正式生成数据前先做一轮使用判定:从场景与脚本引用反推哪些素材真的被用到,只有"在用"的才进入生成队列。你项目里囤一百张没人引用的 PNG,构建产物一个字节都不会多。

这个机制的意义有两层。第一是 ROM 体积管理:GB 卡带最大也就几 MB,几十个场景加几首曲子就能把预算吃掉,按需编译保证实验用的废稿不占正式预算——想知道预算还剩多少,看调试器的 ROM Usage 面板(构建管线一篇有详解)。第二是编译速度:在用素材越少,每次 Build 要生成的 C 文件越少,增量编译也越快。

没进 ROM ≠ 不存在

素材不占 ROM,但 .gbsres 元数据仍在项目里,git 提交、编辑器加载、全文搜索都会带着它。项目越大,无主素材越拖编辑器。定期清理素材目录,比指望编译器替你瘦身更可靠。

素材文件与 .gbsres:一张 PNG 背后有两个文件

打开项目的 assets 目录,很多素材旁边躺着一个同名再追加 .gbsres 后缀的文件——比如 player.png 旁边有 player.png.gbsres。这是 GB Studio 的资源元数据,JSON 格式:记录资源类型与 ID,以及精灵切片方式、动画帧定义、调色板槽位这类"编辑器里的设置"。

分工很明确:PNG 是像素,.gbsres 是"这些像素怎么用"。两者分离的好处是素材本体可以随时替换重画——只要尺寸和切片约定不变,元数据里的动画、引用关系原样保留。官方 changelog 里有一条重要变化:素材元数据改为跟随素材文件放置(早前版本集中存放),为的是让素材插件打包时能把 PNG 和它的动画元数据装进同一个文件夹分发。旧项目升级后 assets 目录结构变了别慌,这是正常现象,以发布版为准。

版本管理建议:.gbsres 和 PNG 一起提交。丢了 PNG 游戏还能报错提示,丢了 .gbsres,你花一下午切的动画帧就真的没了。

下一步

想看项目文件的全貌(.gbsproj、assets、plugins 如何组织),读 项目文件解剖:.gbsproj 与目录结构;想知道素材编译产物如何被 GBDK 打包进 ROM,读 构建管线与调试器:从 JSON 到 .gb ROM;要从源头画出更省容量的素材,读 像素画实战。

↑