Repository Layout

Repository Layout

This page maps every directory and every hand-written file in the master-chef source tree at commit 9f915af (version 1.0.3). Use it to find where a piece of behavior lives. The subsystem pages linked from each section explain how the files work.

The tracked tree holds 377 files and about 7.8 MB. These numbers are recorded in SOURCE_MANIFEST.json. About 64,500 lines of that are vendored third-party code (MojoShader including its GL/SPIR-V headers, stb_vorbis, xxHash, and the XWA lifter). The rest is original project code.

Some things are deliberately absent from Git. They are produced or supplied locally:

Absent item	Where it comes from	Where it ends up
game/halo.exe and the game data (maps, Strings.dll, movies, configs)	You supply it from your own retail Halo PC 1.10 installation	game/ (git-ignored). Setup stages a verified copy in .setup/GamePayload plus .setup/GamePayloadManifest.json, which project.yml bundles as optional resources
Generated whole-executable C (the translated engine)	tools/generate_engine_reuse.py	native/build/engine-reuse/whole-exe/ (chunk_*.c, engine_bundle.c), git-ignored
Import/TLS tables as C	tools/export_engine_imports.py	native/build/engine-reuse/whole-exe/engine_imports.c
Xcode project	XcodeGen from native/EngineVision/project.yml	native/EngineVision/*.xcodeproj (git-ignored)
Built app	tools/build_engine_vision.py	native/EngineVision/.build/DirectXROS/HaloVision.app
Visual packs TextureMods.hvt, ShaderMods.hvs, CEnshineSources.zip	Downloaded and verified by tools/visual_assets.py, or reused from the Complete bundle	.setup/VisualMods/ (git-ignored), then bundled as app resources
Private registry export (*.reg, halo-vision-registry.txt)	Your own registered install	Local only; .gitignore blocks both patterns
Signing identities and provisioning profiles	Your Apple account	Local only; .gitignore blocks *.p12, *.mobileprovision, etc.

See Static Translation Pipeline and Build System for how these items are produced.

---

Top level

master-chef/
├── .github/                    CI workflow and issue templates
├── decompilation/c9acf0c46954/ Numeric function-entry lists for the supported halo.exe
├── docs/                       User and release documentation (+ header artwork)
├── mods/                       Records of the shipped runtime settings and visual packs
├── native/
│   ├── EngineHost/             Native runtime: Win32/D3D9/DSound/DInput shims, Metal, panorama
│   ├── EngineReuse/            Guest CPU model shared with generated code
│   ├── EngineVision/           visionOS SwiftUI/CompositorServices app + validation tests
│   └── Tests/                  Runtime contract test
├── third_party/
│   ├── mojoshader/             D3D shader bytecode -> Metal Shading Language
│   └── xwa/                    Pinned x86 decoder/lifter (sp00nznet XWA toolchain)
├── tools/                      Generation, build, setup, packaging, diagnostics, checks
├── AGENTS.md                   Rules for coding agents working in the repo
├── CHANGELOG.md                Release notes 1.0.0 – 1.0.3
├── CONTRIBUTING.md             Contribution rules
├── LICENSE                     MIT (original project code only)
├── README.md                   Landing page
├── SOURCE_MANIFEST.json        Byte count + SHA-256 for every tracked file
├── THIRD_PARTY.md              Vendored component licenses
├── VERSION                     "1.0.3"
├── requirements-development.txt  capstone, pefile, numpy, Pillow, unicorn (pinned)
└── setup.sh                    Guided setup entry point (execs tools/setup_halo.py)

File	Purpose
README.md	Project summary, download link for the v1.0.3 Complete bundle, requirements, quick start for the bundle and the ISO routes, status, and a repository table.
AGENTS.md	Rules for coding agents. Drive setup.sh and run --stage check --json first. Never handle product keys. Never publish generated engine source, registrations, saves or signing material. Keep preparation, generation, compilation, signing, installation, launch and gameplay validation separate when reporting.
CHANGELOG.md	Version history. Summarized in Release Process and Hygiene.
CONTRIBUTING.md	Keep changes focused. Separate source tests, desktop Metal checks and headset measurements. Run the strict hygiene audit before distributing.
SOURCE_MANIFEST.json	{version, formatVersion, license, scope, fileCount: 377, totalBytes, files:[{path, bytes, sha256}]}.
THIRD_PARTY.md	MojoShader (zlib), stb_vorbis (MIT/public domain), xxHash 0.8.3 (BSD-2), XWA tools (MIT).
setup.sh	POSIX shim. Finds python3.12 or python3 (version 3.10 or later) and execs tools/setup_halo.py "$@". See Setup Wizard.
.gitignore	Blocks build products, game/, .setup/, Release/, .build/, Xcode projects, binaries (*.exe, *.dll, *.app, *.ipa), signing material (*.p12, *.mobileprovision, …), packs (*.hvt, *.hvs, *.tpf), and halo-vision-registry.txt.
.gitleaks.toml	Default gitleaks rules plus one narrow allowlist: two AVX-512 shift lines in xxhash.h that look like key assignments.

---

.github/

Path	Purpose
workflows/source-checks.yml	Runs on push, pull request and manual dispatch, on macos-15. It runs the strict hygiene audit, then run_source_checks.py --portable-only, then the same with --sanitize. macOS is required because the host fixtures use Mach APIs and Apple's linker.
ISSUE_TEMPLATE/bug_report.yml	Structured bug form: area, release/build, environment, steps (mission or checkpoint, and whether it happens stationary, while turning the stick, or while moving the head), expected vs actual, and a privacy checkbox.
ISSUE_TEMPLATE/config.yml	Links to the setup guide, the agent setup guide and the latest release.

See Testing and Source Checks.

---

decompilation/c9acf0c46954/

The directory is named after the first 12 hex digits of the supported executable's SHA-256 digest. The same identifier appears in host comments such as "halo.exe c9acf0c46954".

File	Lines	Purpose
function-addresses.txt	6,495	Known function entry virtual addresses, one per line.
extra-function-entries.txt	1,627	More entries found by discovery and indirect-call analysis.

The generator takes both lists as @file arguments. See Function Address Lists.

---

docs/

File	Audience	Content
SETUP.md	Players	Prerequisites, the ISO route, the existing-install route, the Windows fallback and troubleshooting.
AGENT_SETUP.md	Players using a coding agent	A copy-and-paste prompt and the procedure the agent must follow.
COMPLETE_RELEASE.md	Players	How to verify, extract and prepare the Complete ZIP.
BUILDING.md	Developers	Manual generation, build, payload staging, signing and install.
ARCHITECTURE.md	Developers	A one-page summary. Architecture Overview expands it.
FEATURES.md	Everyone	A capability-by-capability table: where each feature lives and what has been verified.
CONTROLS.md	Players	Controller mapping.
KNOWN_ISSUES.md	Everyone	Open performance, seam, audio and qualification gaps.
VALIDATION.md	Maintainers	Which checks were actually run for each release.
RELEASING.md	Maintainers	The release checklist and privacy rules.
ASSET_NOTICES.md	Everyone	Rights for game content, the HD texture inputs (Delta117), CEnshine (GPL-3.0) and the header art.
assets/master-chef-header.png, assets/README.md	—	The generated README banner and its provenance.

---

mods/

File	Purpose
runtime-settings.json	A record, not a loader. It lists the compiled defaults the app ships with: 2048×1536 render, 30 fps target, 105° panorama vertical FOV, 63 mm IPD, audio at 48 kHz with 1536-frame buffers ×3, and the HALO_* defaults the app sets at launch. See Runtime Settings.
visual-assets.json	Pinned sizes and SHA-256 digests of TextureMods.hvt (1,068 entries), ShaderMods.hvs (13 entries) and CEnshineSources.zip, plus the release archive URL and digest. tools/visual_assets.py consumes it. See Visual Mods Pipeline.

---

native/EngineReuse/ — guest CPU model

This code is shared by the generated translation units and the host. See EngineReuse Runtime and x87 Floating Point.

File	Role
engine_cpu.h	Guest CPU state (registers, x87 stack, FP control), memory access macros, the flat-memory base and ENGINE_* build switches.
engine_flags.h	IA-32 EFLAGS computation helpers. All widening happens before arithmetic.
engine_registers.h	Register aliases that generated code uses. Include it after engine_cpu.h.
engine_hooks.h	The table of guest function entries the host intercepts, and direct calls to the rest. It explains why direct calls replace the dispatch binary search.
engine_runtime.c/.h	Dispatch: function lookup, the override filter, the crash call record and the unsupported-entry trap.
engine_arm64_fenv_prototype.h	An isolated, default-off prototype that maps x87 rounding control onto the ARM64 FPCR.
module.modulemap	Clang module map so Swift and Obj-C can import the runtime headers.

native/EngineHost/ — native runtime

This is the largest directory: 80 C, header, Obj-C and .inc source files, plus 111 files under tests/. It replaces every Windows API the game imports and owns rendering, audio, input and panorama production. EngineHost Overview has the per-file map. The table below groups the files by subsystem.

Area	Files	Wiki page
Loader, dispatch, entry	host.c, host.h, main.c, host_path.inc, host_snapshot.h	EngineHost Overview
Win32 shims	shims_kernel32.c (process, memory, files, time, sync), shims_misc.c (USER32, GDI32, ADVAPI32 registry, OLE32, WINMM, VERSION, WINSOCK), resources.c (RT_STRING)	Win32 Compatibility Layer
Threads	threading.c/.h	Threading and Synchronization
Engine function overrides	overrides.c, campaign_unlock.h, hsc_trace.inc, a10_control.inc	Engine Overrides and Hooks
Settings	halo_settings.c/.h	Runtime Settings
Direct3D 9	d3d9.c, d3d9_render.inc, d3d9_capture.inc, d3d9_process_vertices.inc, stateblock.h, rhw_declaration.h, ddraw.c	Direct3D9 Bridge
Metal	metalrenderer.h/.m, metalshader.c/.h, metalwin.h/.m	Metal Renderer, Shader Translation
Textures	texture_decode.c/.h, texture_mips.h, texture_content_hash.h, texture_mod_pack.h, texture_mod_runtime.inc, shader_mod_pack.h, shader_mod_runtime.inc	Textures and Texture Packs
Geometry fast paths	native_gather.h, native_gather_tree.h, native_leaves.h, visible_surfaces.h, gather_diagnostics.h, process_vertices*.h, vertex_shader_cpu.h, fp_vertex_capture.inc, model_capture_*, model_vertex_capture.inc	Geometry Fast Paths
Fog	radial_fog.h	Radial Fog
Panorama	panorama.h, panorama_hooks.inc, panorama_render.inc, panorama_budget.h, panorama_lod.h, panorama_overlay_scope.h	Panorama System, Panorama Budget and LOD
Pacing	frame_pacer.h, frame_pacing_hooks.inc	Frame Pacing
Audio	directsound.c/.h, directsound_mixer.c/.h, directsound_engine_state.inc, audio_ownership_trace.inc, audio_source_identity.h, vorbis_shim.c/.h, third_party/stb_vorbis.c	Audio System
Input	dinput8.c, gamecontroller.h/.m, gamecontroller_guard.h, a10_gamepad.inc, pointer.c/.h, pointer_step.inc	Input and Controllers
Haptics	haptics.c/.h	Haptics
Telemetry	core_telemetry.h, gather_diagnostics.h	Diagnostics and Telemetry
Vendored	third_party/stb_vorbis.c, third_party/xxhash/	—
Build	Makefile (desktop halo-host and host objects)	Build System
Tests	tests/ (C, Obj-C and Python fixtures; x87 translation fixtures)	Testing and Source Checks

The .inc convention

Many subsystems are written as .inc files that are #included into one translation unit, most often d3d9.c. This lets them share file-static state (the device object table and the draw state) without exporting symbols, and lets tests include exactly the same code. EngineHost Overview documents which .inc is included where.

native/EngineVision/ — visionOS app

Path	Role
project.yml	XcodeGen spec. Defines the EngineVision target, which produces HaloVision.app (display name "Halo Vision"). Sets visionOS 26.0, MARKETING_VERSION 1.0.3 and build 103, and the placeholder bundle ID org.example.halovision. It also lists the exact EngineHost/MojoShader sources compiled into the app, the generated chunk_*.c, the frameworks, and -frounding-math -ffp-contract=off -DENGINE_FLAT_MEMORY=1 -DHALO_ARM64_FENV_FAST=1.
Info.plist	Game-controller keys (GCSupportedGameControllers = ExtendedGamepad, GCRequiresControllerUserInteraction) plus Files-app sharing (UIFileSharingEnabled, LSSupportsOpeningDocumentsInPlace). Other keys, such as the immersive-space default scene role and the hand and world-sensing usage strings, are generated from project.yml.
Resources/PrivacyInfo.xcprivacy, Resources/ThirdPartyNotices.txt	Privacy manifest and the bundled license notices.
Sources/HaloEngineVisionApp.swift	SwiftUI App: windows, the immersive space and lifecycle.
Sources/EngineVisionRuntime.m, EngineVisionBridge.h	Obj-C runtime that starts host_run on the engine worker thread, sets the launch defaults, and bridges frames, panorama leases, status and input.
Sources/EngineImmersive*.swift	The immersive presenter: CompositorServices renderer, curved-panel geometry, render targets, the loading card, ownership generations and the startup trace.
Sources/EnginePanoramaTexture.swift, EnginePanoramaLayerArray.swift, EngineWorldCadence.swift	Consumption of panorama layers and cadence measurement.
Sources/EngineLayerAlignment.swift	Experimental per-layer camera re-alignment.
Sources/EngineFrameTexture.swift, EngineFrameView.swift	Flat-window frame display.
Sources/EngineAssets.swift	Imports and validates game files, stores saves, preserves mutable assets.
Sources/EngineSettingsView.swift, EngineRuntimeModel.swift	Settings UI and the observable runtime state.
Sources/EngineMenuInput.swift, EngineHaptics.swift, audio_session.inc	Spatial menu input, controller haptics, and AVAudioSession coordination.
Sources/EngineDiagnostics*.swift/.h/.m, EngineCoreTelemetry.swift, EngineDeepTelemetry.swift, EngineGatherDiagnostics.swift	report.json, the timeline, history, and deep telemetry journals.
Tests/	32 validation sources: Swift mains, Obj-C probes, a C probe and real-GPU tests. See Testing and Source Checks for which checks build them.

See visionOS App, Immersive Presenter, Layer Alignment and Diagnostics and Telemetry.

native/Tests/

File	Role
EngineRuntimeContract.c	Compiles the canonical CPU with ENGINE_STEP_FULL and checks the dispatch and runtime contract.

---

third_party/

Path	Role	License
mojoshader/	Converts D3D9 vertex and pixel shader bytecode to MSL through its Metal profile. The GL, SPIR-V, HLSL and other profiles are present but unused by the app.	zlib
xwa/recomp_types.h, xwa/tools/*.py	The pinned XWA static-recompilation toolchain: pe_analyze, disasm (Capstone), lifter, translator, generate. tools/engine_reuse/ adapts it.	MIT

native/EngineHost/third_party/ holds stb_vorbis.c and xxHash 0.8.3, which includes an UPSTREAM.json pin.

---

tools/

Script	Purpose	Page
setup_halo.py	The guided setup wizard behind setup.sh. Covers the ISO route, existing-install import, the registry, generation and the Xcode handoff.	Setup Wizard
halo_setup_registry.py	Reads Halo installation values from a registry export or a Wine prefix. Never prints product information.	Setup Wizard
halo-vision-registry.template.txt	Template for the private registry values file.	Device Preparation and Signing
generate_engine_reuse.py	Generates the translated original-engine closure from the entry lists and reports every unresolved boundary.	Static Translation Pipeline
export_engine_imports.py	Emits the executable's import table and TLS directory as C for the host loader.	Static Translation Pipeline
engine_reuse/ (decode, lift, flags, fpu, extra, upstream)	The project's strict lifter on top of XWA: bounded decoding, EFLAGS, binary64 x87, and string and system instructions.	XWA Decoder and Lifter
build_engine_vision.py	Generates and builds the whole-engine visionOS app.	Build System
prepare_engine_vision_device.py	Stages the owned game files into a signed .app and verifies them. Never contacts a device.	Device Preparation and Signing
visual_assets.py	Fetches and verifies the exact release texture and shader packs.	Visual Mods Pipeline
import_texmod_pack.py	Converts a TexMod TPF or ZIP to a native .hvt pack.	Visual Mods Pipeline
merge_hd_texture_pack.py	Merges reviewed PNGs into an HVTEX001 pack.	Visual Mods Pipeline
import_censhine_pack.py	Adapts CEnshine 1.0.0 shaders to the retail shader ABI.	Visual Mods Pipeline
run_source_checks.py	The source-only regression suite (portable, native, Metal and Swift).	Testing and Source Checks
check_repository_hygiene.py	Path and secret audit for distribution trees.	Release Process and Hygiene
watch_engine_vision_telemetry.py	Pulls a build's live.json from a paired headset about every 5 seconds.	Diagnostics and Telemetry
engine_vision_report_summary.py	Summarizes a headset diagnostics run: fps, passes, CPU, audio and layer alignment.	Diagnostics and Telemetry
check_core_telemetry_xros.py	Compiles and links the telemetry APIs for xrOS without running them.	Diagnostics and Telemetry
check_probe_runner_exit.py	Exercises the probe runner's reporting tail.	Testing and Source Checks
probe_engine_menu_input.py	Builds and runs a bounded Mac menu-input probe against cloned owned data.	Input and Controllers
benchmark_x87_rotating_stack.py	Compares rotating and shifting x87 stack layouts on real translated leaves.	x87 Floating Point
test_*.py	Python regressions for the tools above.	Testing and Source Checks

---

Related pages

• Architecture Overview
• EngineHost Overview
• Build System
• Testing and Source Checks
• Glossary