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 起拆成了两层:
- .gbsproj(根目录):只存项目元数据——名称、作者、备注、版本号;
- .gbsres:游戏数据全部拆成独立的 JSON 资源文件,每个文件带
_resourceType与id字段标识身份。
拆分的动机就是版本控制与协作友好:改场景 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 用户的四条建议
- .gbsres 直接提交:它们是纯 JSON,diff 有意义,冲突也能手工合并,别用二进制方式对待;
- PNG 素材靠命名管理:图片是二进制,diff 无意义,用清晰的文件名和提交说明记录改动;
- 别并行编辑同一场景:演员用
_index排序,两个人同时往一个场景加角色最容易撞车; - user_settings.gbsres 建议进 .gitignore:它是编辑器个人偏好,不该污染团队仓库。