GB Studio 项目解剖:磁盘上的游戏长什么样

你在编辑器里保存过几十次项目,但未必打开过 .gbsproj 看一眼。这一篇把 GB Studio 项目在磁盘上的真实形态摊开讲:一个只存元数据的入口文件、一堆可以独立 diff 的 JSON 资源、一套按类型归档的素材目录。看懂它,版本控制和团队协作才真正开始。

先记住一句话架构

GB Studio 由 Electron 编辑器 + GBVM 引擎两部分组成。编辑器负责让你画场景、拖事件;真正跑在 Game Boy 上的,是 GBVM——一个用 C 语言写成、基于 GBDK 工具链编译的游戏引擎,独立维护在 github.com/chrismaltby/gbvm。所以项目文件里存的不是"游戏程序",而是"游戏数据":你的场景、演员、脚本,最终都会被编译成 GBVM 指令。想深入这条编译链路,读 构建与导出篇。

4.x 新格式:一个入口 + 一堆资源

老版本把整个游戏塞进一个巨大的 .gbsproj 文件,Git 协作是灾难:改一句台词,整个 JSON 重新序列化,diff 没法看。4.x 起拆成了两层:

拆分的动机就是版本控制与协作友好:改场景 3 只会动场景 3 的文件,diff 干净,合并冲突被限制在单文件粒度,两个人同时做不同场景基本不会撞车。

目录树:每个文件住哪儿

路径内容
你的游戏.gbsproj项目入口,只存名称、作者、备注、版本等元数据
project/scenes/scene_1/scene.gbsres场景 1 的数据:背景、尺寸、类型、脚本(目录名即场景编号)
project/scenes/scene_1/actor_*.gbsres该场景的每个演员一个文件,用 _index 字段保留排序
project/scenes/scene_1/trigger_*.gbsres该场景的触发器资源,同样是独立文件
project/variables.gbsres全局变量与常量定义
project/settings.gbsres项目设置,随项目走、进版本库
user_settings.gbsres用户设置,编辑器个人偏好,与项目设置分开存放
assets/backgrounds/、assets/sprites/图片素材按类型分目录,配套元数据 .gbsres 就存在素材文件旁边

注意两个细节:演员和触发器是场景目录下独立的资源文件,不是塞在 scene.gbsres 里——这就是为什么它们可以单独提交、单独还原;素材的元数据贴着素材放,复制一张背景图时记得连同它的 .gbsres 一起带走。

保存时会清理过时的 .gbsres

编辑器保存时会清理"不再有对应资源"的过时 .gbsres 文件。反过来说,别在编辑器开着的时候手工增删这些文件——想用脚本批量改数据,先关编辑器、备份、改完再打开验证。另外,本文基于 develop 分支的 4.x 新格式拆解,旧版单文件项目需要升级后才有这套目录结构,细节以发布版为准。

新建项目 = 复制一份模板

编辑器的 appData/templates 目录下有 blank、gbhtml、gbs2 等模板,每个模板自带完整的 project.gbsproj 与资源内容。新建项目的内部流程是四步:校验模板元数据 → 改写项目名与作者 → 复制模板内容(过滤排除文件)→ 写入你指定的目标位置。所以"新建项目"没有任何魔法,就是一次受控复制。blank 是白纸;gbhtml 自带官方示例游戏,适合拆开学习;不确定就从最接近你目标形态的模板起步,能省掉大量搭积木的时间。

给 Git 用户的四条建议

下一步

还没装上 GB Studio?回到 自制游戏入门篇 补基础;想知道这套文件如何一步步变成能跑的 ROM,读 构建与导出篇;找编辑器安装包和周边工具,去 下载资源索引。

↑