squarehole360

squarehole360

Xbox 360 games, statically recompiled to native x86-64 and drawn by a native Vulkan renderer: a square peg for a round hole.

The first target is Gears of War 3, which is playable on Linux. It has been played through Act 1, including the boss fight. The framework is being prepared for Gears of War 2 and Gears of War: Judgment next.

No game content is included. You need your own legally obtained disc image. Everything derived from it is generated locally during the build: assets, the recompiled game code, and the XDK functions the renderer copies.

How it works

• CPU. The game's PowerPC executable is recompiled ahead of time to C++ and then native x86-64 with the ReXGlue SDK. There is no JIT and no interpreter. The SDK also provides the Xbox 360 runtime around the game: memory, threads, kernel and XAM services, audio and input.
• GPU. A new renderer intercepts the game's Direct3D calls instead of emulating the Xenos GPU's command stream. It renders with real Vulkan render targets and fixed-function blending and depth, and models EDRAM only where the game depends on it. Shaders are translated from Xenos microcode to SPIR-V and cached; pipelines build in the background.
• Threading. The game's render thread only captures each draw. Planning, command recording and driver submission run on their own threads.
• Presentation. Native Wayland with HDR10 and VRR; X11 fallback.
• Upscaling. FSR 1, plus temporal FSR 3.1, DLSS and XeSS fed with the renderer's depth, motion vectors and jitter; a low-latency mode and AMD Anti-Lag. See the guide.

docs/renderer-vs-xenia.md compares this approach with Xenia. docs/direct-renderer-plan.md covers the renderer's stages and what remains emulated.

Performance

Gears of War 3 at its native 720p, upscaled to 4K, on an RX 9070 XT (frame-rate cap off):

Scene	Frame time
Act 1 Tickers fight, about 1,600 draws and queries per frame	about 7.3 ms (about 137 fps)
Heaviest camera-pan frames, 2,500 or more operations	about 12 ms
Typical frames, under 500 operations	about 2.6 ms

The GPU's command processor, not its shaders, is now the limit. STATUS.md has every measurement and the options behind it.

Requirements

• Linux to build. The game runs on Linux, on Windows from a cross-compiled build, and on Apple silicon Macs (see below)
• Clang, CMake 3.25+, Ninja, Python 3.11+
• A modern Vulkan GPU and driver (developed and tested on an AMD RX 9070 XT with RADV)
• Wine, to compile the FidelityFX (FSR 3.1) shaders; without it FSR 3.1 is left out of the build
• Optional: jemalloc and OpenSSL development packages (used automatically); PySide6 and tomli-w for the standalone settings editor; the NVIDIA DLSS and Intel XeSS SDKs, downloaded from their official releases by tools/fetch-vendor-sdks.sh --accept-licenses (not redistributed here)
• Your own Gears of War 3 disc image and its Title Update 6 package. The supported executable is default.xex with SHA-256 4e5d00b8…f8f790 (disc media ID 58122AD6), recompiled with Title Update 6 (TU_16L625B_000001C000000.00000000001GB) applied; the importer and the setup wizard check both. RAAM's Shadow needs the update.

Build and run

git clone https://github.com/GloriousEggroll/squarehole360.git
cd squarehole360
tools/setup-dependencies.sh            # pinned submodules (our forks), recursive

python3 tools/import-assets.py import "/path/to/Gears of War 3.iso"
python3 tools/import-assets.py update ~/Downloads   # Title Update 6 (file, folder or archive)
tools/build-linux.sh                   # recompiles the game, then builds it
tools/run-linux.sh

The first start compiles every pixel shader in the game into user/cache behind a progress bar (about 20 minutes, 7.4 GB), so new areas don't stall on their first visit; see docs/gears3.md.

tools/build-linux.sh runs rexglue codegen on your executable with the title update's patch (user/update/default.xexp) applied. It then generates the XDK-derived inputs (tools/porting/generate_getdata.py) and builds build/bin/gow3. Saves and caches live in user/, and logs in logs/.

Windows build

Code generation runs on Linux, so the Windows build is cross-compiled there with clang-cl and an xwin sysroot (creating it accepts Microsoft's license):

xwin --accept-license --arch x86_64 splat --use-winsysroot-style \
  --preserve-ms-arch-notation --output ~/.xwin
tools/build-linux.sh                   # generates the recompiled sources
tools/build-windows.sh                 # builds build-windows/bin/gow3.exe

To run it on Windows, package it (tools/fetch-runtime-deps.sh windows once, then tools/package-windows.sh) and double-click gears3launcher.exe in the extracted zip; the settings editor is Settings.exe (from a command prompt, tools\run-windows.bat and tools\settings-windows.bat). The package carries the Visual C++ runtime and a Python with PySide6 for the setup wizard and settings, so Windows needs only a Vulkan 1.3 driver. The same build also runs under Wine and Proton.

macOS build

The Mac version (Apple silicon, macOS 14 or newer) runs on Vulkan through MoltenVK. It builds on the Mac from the sources generated on Linux, with the Xcode command-line tools and Homebrew (cmake ninja llvm molten-vk vulkan-loader openssl glslang):

tools/build-linux.sh                   # on Linux: generates the recompiled sources
# copy the checkout, including generated/, to the Mac, then on the Mac:
tools/build-macos.sh                   # builds build/bin/gow3
tools/fetch-runtime-deps.sh macos      # once: Python with PySide6 for the package
tools/package-macos.sh                 # dist/squarehole360-macos-arm64.tar.gz

The package carries MoltenVK, the Vulkan loader, OpenSSL and its own Python, so players need no Homebrew. Run tools/run-macos.sh; the settings editor is tools/settings-macos.sh. FSR 3.1, DLSS and XeSS are not available on macOS.

Settings live in config/gow3.toml. You can change them in the standalone editor (tools/settings.sh) or in game (L3+R3, or F4). The Gears of War 3 guide covers controls, display, HDR, the frame-rate cap, the renderer choice (native or Xenia) and troubleshooting.

Multiplayer

Co-op Campaign, Horde, Beast and private Versus work through the game's System Link mode: on a local network, or over the internet through gears3-lobby, a small lobby and relay server anyone can host. Players connect directly when their routers allow it. See docs/multiplayer.md.

Repository layout

Path	Contents
src/	Game glue, settings, Direct3D bridge
src/renderer/native/	Native renderer: capture planner, scene executor, resolve memory, GPU work queue
src/renderer/profiles/	Per-game executable profiles (D3D entry points, device offsets)
config/	Game settings and recompiler hook definitions
vendor/rexglue-sdk/	Submodule: our ReXGlue SDK fork (v0.8.0 + port changes)
vendor/plume, vendor/xenos-recomp, vendor/fidelityfx-sdk	Submodules: our forks, squarehole360 branch
tools/assets/, tools/import-assets.py	Disc import and verification
tools/porting/	XEX image dump, XDK signature scanner, GetData generator
tools/rendering/	Renderer tests, replay tools, the benchmark harness
docs/	Design notes, porting guide, Gears 3 guide

Porting other games

The renderer's dependence on one executable is collected in a compile-time profile (src/renderer/profiles/gears3.h). tools/porting/xdk_signatures.py locates the XDK Direct3D functions and hook sites in another executable. It also reports how the D3D device structure moved between XDK versions.

First scans:

• Judgment: 34 of 39 functions and 30 of 31 hook sites located automatically.
• Gears 2: built against an older XDK; needs manual work.

See docs/porting.md.

Testing

• Planner parity on captured frames: gow3-native-live-plan-test in the tools/rendering/native test project.
• Memory, constant-upload, cache and GPU fixture tests: tools/rendering/native/CMakeLists.txt and the gow3-*-test targets.
• Live automated runs: tools/rendering/verify-native-boot.py and tools/rendering/bench/.

License

BSD 3-Clause; see LICENSE. Bundled and submodule components keep their own licenses; see THIRD_PARTY_NOTICES.md.

Gears of War, Xbox and Xbox 360 are trademarks of Microsoft Corporation. This project is not affiliated with or endorsed by Microsoft, The Coalition or Epic Games.