Gen1Recomp Xbox UWP build notes

This is the Xbox Dev Mode package for Gen1Recomp.

The rough shape is:

Gen1RecompUWP.exe starts LÖVE through SDL's WinRT wrapper
the bundled LÖVE 11.5 UWP backend provides LuaJIT and the Xbox file picker
the bundled SDL2 runtime contains the Xbox controller mapping
ANGLE provides OpenGL ES over D3D11
the bundled runtime contains the audio, font, video, and compression libraries

What You Need

The tested toolchain is:

Visual Studio 2022 17.14
MSVC v143 x64/x86 build tools
C++ Universal Windows Platform tools
Windows 11 SDK 10.0.26100.0
CMake 3.24 or newer
Git for Windows
Info-ZIP zip and unzip

Use Visual Studio Installer to add Universal Windows Platform development, the v143 C++ tools, CMake tools for Windows, and Windows SDK 10.0.26100.0.

The x64 UWP dependencies are committed under third_party. Their versions, source revisions, licences, and hashes are recorded in third_party/manifest.json. No additional checkout or environment variable is required for a normal game build.

Rebuild the Dependencies

Run the dependency rebuild from the repository root:

.\scripts\xbox-uwp\rebuild_dependencies.ps1

The script clones the pinned SDL2, LÖVE, LuaJIT, vcpkg, depot_tools, and ANGLE sources when they are missing. It applies the Xbox SDL2 patch, builds the x64 UWP Release libraries, stages the required DLLs, import libraries, headers, and licences under third_party, updates every SHA-256 entry in the manifest, then builds the Release MSIX.

The generated source checkouts are ignored by Git. A fresh ANGLE sync is about 10 GB, so allow at least 20 GB of free disk space for all sources and build outputs. Use -SkipAngle to retain the existing pinned ANGLE runtime while rebuilding SDL2, LÖVE, LuaJIT, and the vcpkg libraries. Use -SkipPackage when only the dependency bundle needs to be refreshed. The rebuild stops if a source checkout has local changes. Remove that generated source directory to restore the pinned revision.

Build the MSIX

Run the Xbox build from Git Bash at the repository root:

scripts/build_xbox_uwp.sh --release --version 1.2.3

The build uses scripts/pack_love.sh to create and verify the same ROM-free game.love payload used by the other release targets. It then links the UWP host and stages LÖVE, LuaJIT, SDL2, ANGLE, and the vcpkg runtime DLLs.

Use --relwithdebinfo for a package with symbols. To package a .love produced by another build or downloaded from CI, pass --game-love path/to/game.love. The upstream X.Y.Z release becomes X.Y.Z.0 in the generated MSIX manifest. Neither the manifest template nor src/core/Version.lua is edited in place.

The manifest publisher must match the signing certificate subject. Pass it when preparing a signed package:

scripts/build_xbox_uwp.sh --release --version 1.2.3 \
  --publisher "CN=Gen1Recomp"

The normal build is unsigned. Release CI supplies the private PFX and password from XBOX_UWP_SIGNING_CERTIFICATE and XBOX_UWP_SIGNING_PASSWORD; neither may be committed. The public certificate is safe to include with the release.

Run the offline packaging checks from Git Bash:

bash scripts/xbox-uwp/selftest_build_xbox_uwp.sh

Build Output

Visual Studio package output lands under:

ports\uwp\build\release\AppPackages\Gen1RecompUWP

The build also stages the distributable archive and checksum under:

dist\xbox-uwp\gen1recomp-X.Y.Z-xbox-uwp.zip
dist\xbox-uwp\gen1recomp-X.Y.Z-xbox-uwp.zip.sha256

The archive contains the MSIX, framework dependencies, build provenance and, for a signed release, the public certificate. The third-party notices are packaged inside the MSIX. Install the MSIX and dependency packages through Xbox Device Portal.

Runtime Data

The package contains no ROM, generated cache, save or mod data. The Xbox file picker copies user-selected files into LocalState and the launcher imports them from there. Saves, ROM cache and installed mods remain under the LÖVE save directory in LocalState.

LuaJIT requires the codeGeneration capability. removableStorage exposes external media to the Xbox picker. The network capabilities support relay play and direct hosting. The package does not request full trust or broad filesystem access.

4.3 KiB Raw Blame History