{"id":42558207,"url":"https://github.com/halo-re/halo","last_synced_at":"2026-07-09T23:00:31.766Z","repository":{"id":45778400,"uuid":"514425049","full_name":"halo-re/halo","owner":"halo-re","description":"Halo: Combat Evolved (for original Xbox) Decompilation Research Project","archived":false,"fork":false,"pushed_at":"2023-10-09T15:36:16.000Z","size":1400,"stargazers_count":156,"open_issues_count":16,"forks_count":11,"subscribers_count":22,"default_branch":"main","last_synced_at":"2023-11-07T15:55:22.351Z","etag":null,"topics":["decompilation","hacktoberfest","halo","halo-ce","patching","xbox"],"latest_commit_sha":null,"homepage":"https://blam.info","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/halo-re.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-15T22:56:35.000Z","updated_at":"2023-10-21T14:13:20.000Z","dependencies_parsed_at":"2023-01-22T16:55:15.731Z","dependency_job_id":null,"html_url":"https://github.com/halo-re/halo","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/halo-re/halo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-re%2Fhalo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-re%2Fhalo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-re%2Fhalo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-re%2Fhalo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/halo-re","download_url":"https://codeload.github.com/halo-re/halo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/halo-re%2Fhalo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35314872,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-09T02:00:07.329Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["decompilation","hacktoberfest","halo","halo-ce","patching","xbox"],"created_at":"2026-01-28T20:00:26.605Z","updated_at":"2026-07-09T23:00:31.761Z","avatar_url":"https://github.com/halo-re.png","language":"C","funding_links":[],"categories":["Game \u0026 Studio Tools"],"sub_categories":["Microsoft Studios / Bungie / Turn 10"],"readme":"![Halo Decompilation Project](logo.png)\n\nThe goal of this project is to study and create a free, open-source re-implementation of the original Xbox launch title [Halo: Combat Evolved](https://en.wikipedia.org/wiki/Halo:_Combat_Evolved).\n\n**Disclaimer:** This project is intended only for educational and research purposes, and is not indended to promote piracy or violation of any copyright laws. This repository does not include original game executables, nor does it include required game assets. You will need to provide these files from your own copy of the game. Buy a copy. Heck, buy two!\n\n**Motivation:** Fans of Halo CE will be empowered to customize and enjoy this incredible classic in new ways, to understand the mechanics behind the game, and to eventually achieve interoperability of their copy of the game with more of their personal devices. Moreover, this project serves as an exciting vehicle to drive advancements in program analysis research and tooling.\n\n**Methodology:** Pieces of the game are slowly being re-implemented in C source code. These re-implemented pieces are then compiled and patched into the original executable, such that the re-implemented pieces are used instead of their original implementation counterparts. This approach enables incremental development, testing, and debugging.\n\nCommunity\n---------\nThe homepage for this project is: https://blam.info/\n\nThere is a Discord server for the project: https://discord.gg/wJFfe6c9UB\n\nCurrent State\n-------------\n* Able to patch and run existing game\n* Main loop of the game is re-implemented\n* Several more functions are implemented\n* Long way to go...\n\nThe [Progress Report](https://blam.info/progress/) details what functionality has been re-implemented.\n\nBuild\n-----\nThis project can be built with Visual Studio or Clang, on Windows, macOS, and Linux. Project tooling is developed with [Python 3](https://www.python.org/), so that will need to be installed, along with dependencies listed in requirements.txt. CMake will also need to be installed.\n\nBuild overview:\n* First prepare `halo-patched` directory with disc files and original executable\n  * Retail disc game files\n  * Original executable version `01.10.12.2276` (MD5: `c7869590a1c64ad034e49a5ee0c02465`) as file `cachebeta.xbe`\n* You can build in a Docker container, or outside of a container with system tools (e.g. Clang, MSVC).\n* If not using a container to build, install system deps:\n  * Ensure Python 3 is installed.\n  * Install Python requirements: `python -m pip install -r requirements.txt`\n  * On Windows you can use Visual Studio (MSVC).\n  * On Linux/macOS/WSL you can use Clang.\n\n### Build options\n\nBuild with the Docker container:\n```bash\ndocker build -t halo .\ndocker run -it --rm  -u $(id -u):$(id -g) -v $PWD:/work -w /work halo /bin/bash -c \"cmake -Bbuild -S. -DCMAKE_TOOLCHAIN_FILE=toolchains/llvm.cmake \u0026\u0026 cmake --build build\"\n```\n\nBuild on Windows with CMake and Visual Studio:\n```bash\npython3 -m pip install --user -r requirements.txt\ncmake -AWin32 -Bbuild -S.\ncmake --build build\n```\n\nBuild on Linux (Ubuntu) with CMake and Clang:\n```bash\nsudo apt install cmake clang lld python3-pip\npython3 -m pip install --user -r requirements.txt\ncmake -Bbuild -S. -DCMAKE_TOOLCHAIN_FILE=toolchains/llvm.cmake\ncmake --build build\n```\n\nBuild on macOS (works on both Intel and Apple Silicon macs) with CMake and Clang:\n```bash\nbrew install llvm cmake\npython3 -m pip install --user -r requirements.txt\nexport PATH=\"/opt/homebrew/opt/llvm/bin:/usr/local/opt/llvm/bin:$PATH\"\ncmake -Bbuild -S. -DCMAKE_TOOLCHAIN_FILE=$PWD/toolchains/llvm.cmake\ncmake --build build\n```\n\nWhen the build is complete, the original game with re-implementation patched in will be at `halo-patched/default.xbe`. Use `extract-xiso` to create an ISO from your `halo-patched` directory, then run `halo-patched.iso` in xemu, or on your Xbox.\n\nYou'll want to set up a debug environment.\n\n### GDB debugging\n\nTo create an executable with symbols when building with the LLVM toolchain, add `-DCMAKE_BUILD_TYPE=Debug` argument to CMake when configuring the project.\n\nDuring the build process, a `.gdbinit` script is generated. This script will help initialize a gdb session for debugging. It will be loaded automatically when `gdb` is invoked from the current directory. You can launch xemu with a GDB server by passing the `-s` flag.\n\nReversing\n---------\nInterested in reversing the game? PRs are welcome!\n\nThe process of adding re-implemented functions is mostly automated and relatively painless:\n* Add new function/data declarations to `kb.json` as they are discovered and confirmed. The definitions in `kb.json` are used to automatically generate header files and link the new implementation with the original XBE.\n* Implement new functions in the appropriate source file `src/halo/**/*.c`. Add new source files to `src/CMakeLists.txt`.\n* The build system will compile and patch the XBE with redirects from the original implementations to the re-implementations.\n* Naturally, your new code will call some function in the original binary that has not yet been re-implemented. These functions will also be automatically linked correctly, provided the definitions of data and called functions are in `kb.json`.\n\nSee the [Progress Report](https://blam.info/progress/) to interactively explore the call graph, familiarize yourself with the code base, and examine the project frontier.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalo-re%2Fhalo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhalo-re%2Fhalo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhalo-re%2Fhalo/lists"}