270 lines
6.7 KiB
Markdown
270 lines
6.7 KiB
Markdown
# Frostbite2D 编译说明
|
||
|
||
本文档记录当前 Windows PC 和 Nintendo Switch 版本的编译方法。命令默认在项目根目录执行：
|
||
|
||
```powershell
|
||
cd X:\NS_unknown_game\Frostbite2D-Engine
|
||
```
|
||
|
||
## 1. Windows PC 编译
|
||
|
||
### 1.1 前置环境
|
||
|
||
当前机器已验证可用：
|
||
|
||
- Visual Studio 2026 MSVC x64 工具链
|
||
- XMake：`C:\Program Files\xmake\xmake.exe`
|
||
- CMake：`C:\Program Files\CMake\bin\cmake.exe`
|
||
- Python 3.13，供 XMake 构建部分依赖包使用
|
||
|
||
XMake 会自动拉取这些 PC 依赖：
|
||
|
||
- SDL2
|
||
- SDL2_image
|
||
- SDL2_mixer
|
||
- SDL2_ttf
|
||
- GLM
|
||
- zlib
|
||
|
||
### 1.2 编译引擎静态库
|
||
|
||
```powershell
|
||
$env:PATH='C:\Program Files\CMake\bin;C:\Program Files\xmake;' + $env:PATH
|
||
|
||
& 'C:\Program Files\xmake\xmake.exe' f -c -p windows -a x64 -m release -y
|
||
& 'C:\Program Files\xmake\xmake.exe' build Frostbite2D
|
||
```
|
||
|
||
产物：
|
||
|
||
```text
|
||
build\windows\x64\release\Frostbite2D.lib
|
||
```
|
||
|
||
### 1.3 编译 Windows 测试 EXE
|
||
|
||
项目内有一个最小 Windows 测试程序：
|
||
|
||
```text
|
||
examples\windows_smoke\main.cpp
|
||
```
|
||
|
||
编译命令：
|
||
|
||
```powershell
|
||
$env:PATH='C:\Program Files\CMake\bin;C:\Program Files\xmake;' + $env:PATH
|
||
|
||
& 'C:\Program Files\xmake\xmake.exe' f -c -p windows -a x64 -m release -y
|
||
& 'C:\Program Files\xmake\xmake.exe' build Frostbite2DWindowsSmoke
|
||
```
|
||
|
||
产物：
|
||
|
||
```text
|
||
build\windows\x64\release\Frostbite2DWindowsSmoke.exe
|
||
```
|
||
|
||
运行 EXE 时，需要把依赖 DLL 放在 EXE 同目录。当前已验证至少需要：
|
||
|
||
```text
|
||
SDL2.dll
|
||
SDL2_image.dll
|
||
SDL2_mixer.dll
|
||
SDL2_ttf.dll
|
||
FLAC.dll
|
||
```
|
||
|
||
如果重新清理构建目录后 DLL 丢失，可以从 XMake 包缓存复制。当前机器路径示例：
|
||
|
||
```powershell
|
||
$out='build\windows\x64\release'
|
||
|
||
Copy-Item 'C:\Users\11655\AppData\Local\.xmake\packages\l\libsdl2\2.32.10\9cf157962d784bab85f45cbb66d68046\bin\SDL2.dll' $out -Force
|
||
Copy-Item 'C:\Users\11655\AppData\Local\.xmake\packages\l\libsdl2_image\2.8.8\026ef5efba044dc0824fc0125a4307c9\bin\SDL2_image.dll' $out -Force
|
||
Copy-Item 'C:\Users\11655\AppData\Local\.xmake\packages\l\libsdl2_mixer\2.8.1\03da77434a3f43dfa9c6e52b7ea5dafd\bin\SDL2_mixer.dll' $out -Force
|
||
Copy-Item 'C:\Users\11655\AppData\Local\.xmake\packages\l\libsdl2_ttf\2.24.0\56f7684f28e04a3eb194f8f4a4ed4c2b\bin\SDL2_ttf.dll' $out -Force
|
||
Copy-Item 'C:\Users\11655\AppData\Local\.xmake\packages\l\libflac\1.5.0\96b3cdc9f5834a3c9ac2a033627c794b\bin\FLAC.dll' $out -Force
|
||
```
|
||
|
||
运行测试：
|
||
|
||
```powershell
|
||
& build\windows\x64\release\Frostbite2DWindowsSmoke.exe
|
||
```
|
||
|
||
正常输出中应包含：
|
||
|
||
```text
|
||
Frostbite2D Windows smoke init ok.
|
||
Renderer initialized
|
||
TaskSystem initialized
|
||
Application stopped
|
||
```
|
||
|
||
## 2. Nintendo Switch 编译
|
||
|
||
### 2.1 前置环境
|
||
|
||
当前机器已验证可用：
|
||
|
||
- devkitPro：`C:\devkitPro`
|
||
- devkitA64：`C:\devkitPro\devkitA64`
|
||
- libnx：`C:\devkitPro\libnx`
|
||
- Switch portlibs：`C:\devkitPro\portlibs\switch`
|
||
- XMake：`C:\Program Files\xmake\xmake.exe`
|
||
|
||
Switch 版依赖不走 XMake 的桌面包，而是使用 devkitPro 的 portlibs：
|
||
|
||
- SDL2
|
||
- SDL2_image
|
||
- SDL2_mixer
|
||
- SDL2_ttf
|
||
- GLM
|
||
- zlib
|
||
- libnx
|
||
|
||
### 2.2 编译 Switch 引擎静态库
|
||
|
||
```powershell
|
||
$env:PATH='C:\devkitPro\devkitA64\bin;C:\devkitPro\tools\bin;C:\devkitPro\msys2\usr\bin;C:\Program Files\CMake\bin;C:\Program Files\xmake;' + $env:PATH
|
||
$env:DEVKITPRO='C:\devkitPro'
|
||
$env:DEVKITA64='C:\devkitPro\devkitA64'
|
||
|
||
& 'C:\Program Files\xmake\xmake.exe' f -c -p switch -a aarch64 -m release --toolchain=cross --sdk='C:\devkitPro\devkitA64' --bin='C:\devkitPro\devkitA64\bin' --cross='aarch64-none-elf-' -y
|
||
& 'C:\Program Files\xmake\xmake.exe' build Frostbite2D
|
||
```
|
||
|
||
产物：
|
||
|
||
```text
|
||
build\switch\aarch64\release\libFrostbite2D.a
|
||
```
|
||
|
||
### 2.3 编译 Switch NRO 测试程序
|
||
|
||
项目内有一个最小 Switch 测试程序：
|
||
|
||
```text
|
||
examples\switch_smoke\main.cpp
|
||
```
|
||
|
||
它会调用：
|
||
|
||
```cpp
|
||
frostbite2D::switchInit();
|
||
frostbite2D::switchShutdown();
|
||
```
|
||
|
||
先确保 `libFrostbite2D.a` 已经生成，然后执行：
|
||
|
||
```powershell
|
||
$env:PATH='C:\devkitPro\devkitA64\bin;C:\devkitPro\tools\bin;C:\devkitPro\msys2\usr\bin;' + $env:PATH
|
||
$env:DEVKITPRO='C:\devkitPro'
|
||
$env:DEVKITA64='C:\devkitPro\devkitA64'
|
||
|
||
$out='build\switch\aarch64\release\switch_smoke'
|
||
New-Item -ItemType Directory -Force -Path $out | Out-Null
|
||
|
||
$common=@(
|
||
'-g',
|
||
'-O2',
|
||
'-D__SWITCH__',
|
||
'-march=armv8-a+crc+crypto',
|
||
'-mtune=cortex-a57',
|
||
'-mtp=soft',
|
||
'-ffunction-sections',
|
||
'-fdata-sections',
|
||
'-fPIE',
|
||
'-IFrostbite2D\include',
|
||
'-IFrostbite2D\third_party\quickjspp',
|
||
'-IC:\devkitPro\libnx\include',
|
||
'-IC:\devkitPro\portlibs\switch\include',
|
||
'-IC:\devkitPro\portlibs\switch\include\SDL2',
|
||
'-specs=C:\devkitPro\libnx\switch.specs'
|
||
)
|
||
|
||
$compileArgs=@('-c','-std=c++17') + $common + @(
|
||
'-o', "$out\main.o",
|
||
'examples\switch_smoke\main.cpp'
|
||
)
|
||
& C:\devkitPro\devkitA64\bin\aarch64-none-elf-g++.exe @compileArgs
|
||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||
|
||
$linkArgs=@(
|
||
'-specs=C:\devkitPro\libnx\switch.specs',
|
||
'-g',
|
||
'-march=armv8-a+crc+crypto',
|
||
'-mtune=cortex-a57',
|
||
'-mtp=soft',
|
||
'-fPIE',
|
||
'-Lbuild\switch\aarch64\release',
|
||
'-LC:\devkitPro\libnx\lib',
|
||
'-o', "$out\Frostbite2D_smoke.elf",
|
||
"$out\main.o",
|
||
'-lFrostbite2D',
|
||
'-lnx'
|
||
)
|
||
& C:\devkitPro\devkitA64\bin\aarch64-none-elf-g++.exe @linkArgs
|
||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||
|
||
& C:\devkitPro\tools\bin\nacptool.exe --create 'Frostbite2D Smoke' 'Frostbite2D' '1.0.0' "$out\control.nacp"
|
||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||
|
||
& C:\devkitPro\tools\bin\elf2nro.exe "$out\Frostbite2D_smoke.elf" "$out\Frostbite2D_smoke_meta.nro" --nacp="$out\control.nacp" --icon=C:\devkitPro\libnx\default_icon.jpg
|
||
if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
|
||
```
|
||
|
||
产物：
|
||
|
||
```text
|
||
build\switch\aarch64\release\switch_smoke\Frostbite2D_smoke.elf
|
||
build\switch\aarch64\release\switch_smoke\Frostbite2D_smoke_meta.nro
|
||
build\switch\aarch64\release\switch_smoke\control.nacp
|
||
```
|
||
|
||
推荐运行带元数据的版本：
|
||
|
||
```text
|
||
Frostbite2D_smoke_meta.nro
|
||
```
|
||
|
||
不带 NACP/icon 的 NRO 在 Ryujinx 1.3.3 中可能触发 `OpenNroAssetSection` 相关加载错误。
|
||
|
||
正常运行后屏幕显示：
|
||
|
||
```text
|
||
Frostbite2D Switch smoke test
|
||
Press PLUS to exit.
|
||
```
|
||
|
||
## 3. 常见问题
|
||
|
||
### 3.1 切换平台后编译异常
|
||
|
||
XMake 会缓存当前平台配置。Windows 和 Switch 来回切换时，建议使用 `f -c` 重新配置：
|
||
|
||
```powershell
|
||
& 'C:\Program Files\xmake\xmake.exe' f -c -p windows -a x64 -m release -y
|
||
```
|
||
|
||
或：
|
||
|
||
```powershell
|
||
& 'C:\Program Files\xmake\xmake.exe' f -c -p switch -a aarch64 -m release --toolchain=cross --sdk='C:\devkitPro\devkitA64' --bin='C:\devkitPro\devkitA64\bin' --cross='aarch64-none-elf-' -y
|
||
```
|
||
|
||
### 3.2 Windows EXE 启动时报 `0xC0000135`
|
||
|
||
这是缺 DLL。把 SDL 相关 DLL 复制到 EXE 同目录即可。
|
||
|
||
### 3.3 Switch NRO 在 Ryujinx 中加载失败
|
||
|
||
优先使用带 NACP/icon 的：
|
||
|
||
```text
|
||
Frostbite2D_smoke_meta.nro
|
||
```
|
||
|
||
不要优先使用裸的 `Frostbite2D_smoke.nro`。
|
||
|