GearsUE3

GearsUE3 is an in-progress clean-code engine port for the Xbox 360 Gears of War games. Its target product combines native subsystem overrides with Xenia's existing x64/A64 Xenon dynarecs for every guest path that remains emulated. A bounded Xenia interpreter fallback is allowed only after a reason-labelled dynarec failure; it is counted and cannot satisfy gameplay or performance evidence. The product has no generated guest C++ or offline translation step.

Gears of War 1 is the active and only conformance target. Gears 2, Gears 3, and Judgment remain product scope, not compatibility claims. See docs/project-state.md for factual coverage and docs/gearsue3-engine.md for the architecture.

Running

./run.sh [--iso <path>]

The launcher finds your disc (--iso, then GEARS_ISO in the environment or a gitignored .env, then the one image or 7z archive in roms/), refuses any disc whose default.xex is not the supported retail revision, builds build/product/gears1, and starts it. Missing build tools or libraries are refused by name with the exact install command. --prepare checks and builds without starting.

The product hosts the authenticated executable on x360port's system session: Xenia's kernel, file system, GPU, audio, and input services, with the guest CPU on Xenia's x64 dynarec and title-owned native overrides called from the guest's own call slots. It currently reaches Act 1 at the title's 30 Hz cap; gamepads are the only Linux input. docs/project-state.md lists what is verified and what is not.

Maintainers observe the product headless and silent with uv run --locked python tools/run_offscreen.py --seconds 150 --walk menu, which writes a log, captures, and a contact sheet under scratch/offscreen/.

Preserved evidence

The retired path previously demonstrated exact-revision Gears 1 boot, menus, Act 1 gameplay, guest threading and memory, SDL-backed input, working XMA audio, and a bounded Vulkan renderer driven by the title's PM4/Xenos stream. It also grounded a growing set of title-owned native seams, including resource lifetime leaf 0x8222E868. Those observations remain useful as migration targets, but they are not evidence that the x360port product exists or passes gameplay.

The compatibility renderer's in-game world is still not fully faithful, saves do not complete, networking/user services are absent, and no title has passed a complete exact-revision conformance report. The native RHI is partial and no representative gameplay run has met the native 8.33 ms / 120 fps goal.

User-owned game input

No game or UE3 source is included or fetched. The eventual product accepts a legally owned disc image (or one bounded nested archive), validates its exact revision, maps the authenticated XEX at runtime, and launches without emitting or compiling guest code. Explicit CLI input, GEARS_ISO/gitignored .env, and one unambiguous ignored roms/ drop-in remain the intended discovery order.

The current ./run.sh refuses explicitly because the authenticated full-image adapter and runtime-service composition are not yet wired over x360port. It cannot generate, build, or select the removed product.

Ownership

Area	Owner
Xenon CPU execution, typed imports, and authenticated image mapping	shared/x360port; the pinned-Xenia executor is consumed and synthetically exercised here
Device callbacks, overrides, original calls, and executable-write invalidation	shared/x360port; synthetic runtime evidence covers title-reported, automatic virtual-write, and mid-call invalidation paths
Bounded exits and fallback accounting	future shared/x360port contracts, added only with executing evidence
Reusable UE3-on-Xbox-360 ABI, RHI semantics, and engine lifetimes	shared/x360ue3, consuming only public x360port interfaces
Cross-framework executable-memory helpers	shared/jit-common, only after two integrations prove the same missing contract
Exact Gears identity, addresses, policies, navigation, and native bindings	title adapters in this repository
Shared Gears-family engine behavior	GearsUE3: cohesive runtime/render/audio/input/storage modules in this repository
Authenticated image/import validation	shared/x360port; exercised against Xenia RawModule by both its own runtime test and the Gears-addressed discriminator
Independent comparison	Xenia oracle/hardware/binary evidence, never the old generated product

The local shared/ue3 checkout is developer reference material, not one of these runtime layers. No product may compile, link, package, copy, or require it.

docs/codemap.md maps existing and target locations. docs/re-frontier.md records what has and has not been reverse-engineered. Atomic work is in docs/issues/.

Third-party code and licence

extern/xenia is a pinned fork of Xenia Canary, BSD 3-Clause. The migration reuses its Xenon CPU dynarecs as well as its separately integrated Xenos shader and hardware code. The XMA decoder is built from an LGPL-2.1-or-later FFmpeg fork. First-party code is intended to be MIT licensed. Gears of War is copyright Epic Games / Microsoft; this project ships none of it. See LICENSE and THIRD_PARTY_NOTICES for the complete notices.