如何从零构建Sonic 3 A.I.R.:多平台编译(Windows/Linux/Android/Web)快速上手指南
如何从零构建Sonic 3 A.I.R.:多平台编译(Windows/Linux/Android/Web)快速上手指南
Sonic 3 A.I.R.(Angel Island Revisited)是一个非商业粉丝重制项目,基于开源的 Oxygen Engine 引擎和 Lemonscript 脚本语言,将经典《Sonic 3 & Knuckles》全面重制。本教程带你完成 Sonic 3 A.I.R. 的多平台编译:Windows、Linux、Web(WebAssembly)和 Android 四大平台,从克隆仓库到打包出可运行游戏,全程只需几小时。
📦 项目结构一览:Sonic 3 A.I.R. 由什么组成
在动手编译前,先用 30 秒了解仓库的分层结构(详见 README.md):
| 目录 | 作用 |
|---|---|
| framework/external/ | 第三方依赖:SDL2、Ogg/Vorbis、zlib、libcurl、Dear ImGui |
| librmx/ | 基础库 rmxbase / rmxmedia,提供游戏框架能力 |
| Oxygen/lemonscript/ | Lemonscript 脚本语言(编译器 + 运行时),游戏逻辑主要由它编写 |
| Oxygen/oxygenengine/ | Oxygen Engine:输入、图形、音频与世嘉 Mega Drive 硬件模拟环境 |
| Oxygen/sonic3air/ | S3AIR 本体的 C++ 代码、scripts/ 游戏脚本与游戏数据 |
每个平台都有独立的构建目录 Oxygen/sonic3air/build/,官方在各子目录中提供了 how-to-build.txt 说明文档,本教程与之一一对应。
🛠️ 编译准备:获取代码与 S3&K ROM
所有平台编译前都要完成两步:
1. 克隆仓库
git clone https://gitcode.com/gh_mirrors/so/sonic3air
2. 放置游戏 ROM
Sonic 3 A.I.R. 需要原版《Sonic 3 & Knuckles》ROM(Sonic_Knuckles_wSonic3.bin),将其放入 Oxygen/sonic3air/ 或 Oxygen/sonic3air/___internal/ 目录即可。
⚠️ 本项目为免费非商业粉丝作品,与 SEGA 无任何关联,禁止商业用途(见 LICENSE)。
🪟 Windows 快速构建:Visual Studio 三步走
环境要求:Visual Studio 2022(Community 版即可)+ "Desktop development with C++" 工作负载。
操作步骤(参考 _vstudio/how-to-build.txt):
- 编译第三方依赖(只需一次):
- 用文本编辑器打开 framework/external/get_msbuild_path.bat,把
msbuildPathCom(或msbuildPathPro)改为你本机 MSBuild.exe 的路径; - 运行同目录下的 framework/external/build_externals_windows.bat;
- 成功后
framework/lib下会生成x64、x64d、x84、x84d等目录,包含 curl、sdl、zlib 等静态库。
- 用文本编辑器打开 framework/external/get_msbuild_path.bat,把
- 打开解决方案:用 Visual Studio 打开 Oxygen/sonic3air/build/_vstudio/sonic3air.sln。
- 选择
sonic3air为启动项目,Build / Run 即可。项目默认将所有库静态链接进单个 exe。
🐧 Linux 编译教程:CMake 一条命令搞定
Debian/Ubuntu 系系统先安装依赖:
sudo apt-get install g++ cmake libgl1-mesa-dev libglu1-mesa-dev libasound2-dev libpulse-dev libxcomposite-dev libxxf86vm-dev libcurl4-openssl-dev
然后在仓库根目录执行(参考 _cmake/how-to-build.txt):
mkdir ./Oxygen/sonic3air/build/_cmake/build
cd ./Oxygen/sonic3air/build/_cmake/build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . -j 6 # -j 6 表示用 6 个核心并行编译
运行游戏:
cd ./Oxygen/sonic3air
./sonic3air_linux
只想体验引擎本身的话,可以编译并运行 Oxygen/oxygenengine 下的 oxygenapp_linux。构建脚本见 Oxygen/sonic3air/build/_cmake/CMakeLists.txt。
🌐 Web 编译指南:Emscripten + Docker 生成 WebAssembly 版
Web 版通过 Docker 容器(仓库自带 Dockerfile)构建,避免污染本机编译器环境(参考 _emscripten/how-to-build.txt):
# 1. 构建 emscripten_gl 容器
cd ./Oxygen/sonic3air/build/_emscripten
docker build -t emscripten_gl .
# 2. 回到仓库根目录,执行 emmake cmake 编译
cd ../../../../
docker run --rm -v $(pwd):/src -u $(id -u):$(id -g) --name sonic3air_build \
emscripten_gl /bin/bash -c "cd /src/Oxygen/sonic3air/build/_emscripten/build; emmake cmake -DCMAKE_BUILD_TYPE=Release ..; emmake cmake --build ."
编译完成后用 file_packager.py 把 config.json、scripts、data 等打包成 sonic3air.data(文档中区分开发版与最终用户版两种打包命令),最后把输出目录部署到支持 .wasm MIME 类型的 Web 服务器,打开 sonic3air_web.html 即可在浏览器中游玩。
💡 在手机上用 Safari/Chrome 打开网页后,通过"添加到主屏幕"就能像原生 App 一样启动游戏。
📱 Android APK 制作:Android Studio + Gradle 快速上手
- 复制游戏数据:把 Sonic 3 A.I.R. 主目录下的
data、scripts、config.json拷贝到 _android/app/src/main/assets/(开发阶段可省略音频数据以加快构建,参考 _android/how-to-build.txt)。 - 用 Android Studio 打开
Oxygen/sonic3air/build/_android目录作为工程。 - 检查
abiFilters:开发时只保留一个架构(如 arm64-v8a)可大幅缩短编译时间;发布版建议启用全部四种目标架构。 - 等待 Gradle 同步后,Make 并 Run 即可。
🎮 引擎自带虚拟手柄触摸层,移植到 Android/Web 后无需额外开发触屏输入。
📦 打包与发布:mastering 脚本入门
想制作可分发的完整版本(而非本地开发版),仓库提供了 mastering 脚本集 Oxygen/sonic3air/___internal/mastering/:
- 先用当前平台构建一次 S3AIR,并以 Release 模式启动游戏一次(用于编译脚本);
- 核对版本号 Oxygen/sonic3air/source/sonic3air/version.inc;
- Windows 版:执行
mastering_windows_32bit.bat/mastering_windows_64bit.bat; - Linux 版:执行 mastering_linux.sh(VM 或 WSL 中也可);
- Android 版:先用
mastering_build_data_*.bat生成打包数据,再在 Android Studio 中"Generate Signed Bundle / APK"生成签名 APK。
最终产物统一输出到 Oxygen/_MASTER 目录。详细说明见 _mastering_notes.txt。
📚 Sonic 3 A.I.R. 构建目录速查表
| 平台 | 构建目录 | 官方说明文档 |
|---|---|---|
| Windows | _vstudio/ | how-to-build.txt |
| Linux | _cmake/ | how-to-build.txt |
| Web | _emscripten/ | how-to-build.txt |
| Android | _android/ | how-to-build.txt |
| macOS / iOS | _xcode/ | HowToBuild.txt |
构建遇到问题时,优先查看对应平台的官方说明文档与 framework/external/ 下各依赖库的 how-to-build.txt;游戏逻辑脚本集中在 Oxygen/sonic3air/scripts/,方便你进一步阅读与魔改。


