Paul Hontz
8e9ee175a9
The network test's per-second line (debug.network_test) now ends with "| drift <ticks> <apart> <mean> <largest>": on the host, the ticks in which it moved a client's player one tick on from where it took the client's last prediction, with the client's input of that tick, as the client did, and how far apart the two moves were. Builds that simulate alike move the player alike to the last bit, so this is what shows a build that simulates otherwise; the positions the machines log agree either way, as the netcode corrects every copy toward the host's. tools/net_compare.py (next commit) judges two builds by it. Only counters and the test's log line change: nothing sent between machines, nothing a game does with them, so the network version stays. Checked with i686 builds against themselves (0 to 13% of such ticks apart, up to 42% on a loaded computer) and against one whose players run 0.5% or 2% faster (77 to 93%). (cherry picked from commit 95b2ddf86d4abc279c4ed462789e0ff7a75a7881)
Halo: Combat Evolved for Linux, Windows, Android and the web
This project is a port of the Halo: Combat Evolved decompilation to Linux,
Windows, Android and web browsers. The decompilation is of the Xbox build 2342
(cachebeta.exe, SHA-256
4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520).
The port starts from the decompilation of bnunu/halo-1. That project is a fork of punpckhdq/halo.
Download
GitHub Actions builds the game for each commit. These links download the builds of the latest release:
| Platform | Release | Debug |
|---|---|---|
| Linux | halo-linux-release.zip | halo-linux-debug.zip |
| Windows | halo-windows-release.zip | halo-windows-debug.zip |
| Android | halo-android-release.zip | halo-android-debug.zip |
| Web | halocombatevolved.com (or halo-web-release.zip for your own server) | halo-web-debug.zip |
Use the release build to play. The debug build stops at the first failed assertion and writes it to the log. Use the debug build to find and report problems.
The game updates itself. At start-up it looks for a newer release, and asks if you want to install it. Refer to "Updates" in port/linux/README.md. The web site offers each new build when it is out.
Each build of the main branch that passes on all four platforms is a new
release, and the web site then plays it. The Releases
page keeps the last five releases. If the latest build has a problem, get
an older build from that page.
Arch-based Linux Distributions
The above Linux binary release is available on the AUR.
Game data
The port does not include the game data. Download an Xbox disc image
(.xiso or .iso) of Halo: Combat Evolved. All versions of the game
operate. The maps of the European (PAL) version were made for a slower
console. The port changes them to play as the North American (NTSC) maps do,
so players of the two versions can play together.
- Start the game.
- At the first start, the game asks for the disc image. Select it in the
file picker. On Linux and Windows, a disc image (
.isoor.xiso) next to the executable is used without the file picker. Where no file picker can be shown (on Linux, without the desktop portal orzenity), the game says to put the disc image next to the executable, and stops. - The game extracts the
maps/folder. Then the game starts.
The maps/ folder holds the Xbox maps only. If it holds Halo PC's maps
instead (a Halo PC or Custom Edition install's maps folder), the game says
so and stops: Custom Edition maps go in custom_maps/, beside maps/.
On Linux and Windows, the game puts maps/ next to the executable. On
Android, copy the disc image to the phone first. The app puts maps/ in its
data folder. Refer to port/android/README.md. On
the web, the page copies maps/ out of the disc image into the browser's
storage for the site; nothing is uploaded. Refer to
port/web/README.md.
Mods
Mods are folders of Halo PC tag files, as the Halo Editing Kit and Invader
write them, in mods/ next to maps/: texture, sound, text and model packs
that play over the maps' on your machine only, in any game. Each has a
mod.toml. Every mod in the folder is on; the main menu's Mods turns them
off and on and sets the order they load in.
Refer to docs/mods.md.
Platforms
Each platform has its own instructions:
| Platform | Instructions |
|---|---|
| Linux (32-bit x86 executable, OpenGL 4.5, SDL3) | port/linux/README.md |
| Windows (32-bit x86 executable, OpenGL 4.5, SDL3) | port/windows/README.md |
| Android (arm64 app, OpenGL ES 3, SDL3) | port/android/README.md |
| Web (WebAssembly, WebGL 2, SDL3; desktop Chrome, Edge and Firefox) | port/web/README.md |
The Linux README also gives the controls, the settings and the multiplayer functions. These are almost the same on all platforms.
Multiplayer
The game can play system link games on a local network and on the internet:
- A system link game can have up to 128 players on up to 128 machines.
- Linux, Windows and Android machines and browsers can play in the same game. On a local network, the native builds play system link; browsers play each other in rooms, over WebRTC (port/web/README.md).
- An invite link, or the server browser, lets a machine join a game on the internet, browsers too: a native build takes a browser's WebRTC (port/linux/README.md, "Browsers"). No server of this project is necessary.
- The netcode is new. Each machine moves its own player at once, and the host makes the decisions for the game. Refer to port/linux/NETCODE.md.
Build the game
You do not need the Xbox SDK. The port supplies the SDK declarations that the game uses. Refer to port/include/xdk.
To build the game:
- Install Python and ninja.
- Install the tools for your platform. Refer to the README for the platform.
- In the root folder of the repository, enter
python configure.py. - Enter
ninjawith the target for the platform:
| Target | Result |
|---|---|
ninja linux |
build/linux/halo |
ninja windows (on Windows, or on Linux after configure.py --windows-cross) |
build/windows/halo.exe and SDL3.dll |
ninja android_apk |
port/android/app/build/outputs/apk/debug/app-debug.apk |
ninja web |
build/web/site/, the web site (python tools/web_serve.py serves it) |
If you enter ninja without a target, ninja builds the game for the
computer that you use.
tools/ci_build.py makes the same builds as GitHub Actions. For example,
enter python tools/ci_build.py linux release.
Build options
Give these options to configure.py:
| Option | Result |
|---|---|
| (none) | A debug build. A failed assertion stops the game. |
--release |
A release build. The game does not examine assertions, as in the retail game. |
--portable |
The Linux and Windows builds operate on all x86-64 processors. The Linux build also operates on older distributions and on SteamOS: refer to "Portable build" in port/linux/README.md. Use this option for builds that you give to other persons. |
--lto=thin, --lto=off |
Less link-time optimization. The link is faster. |
--pgo=off |
No profile-guided optimization. |
--pgo=train |
Records a new optimization profile. Refer to "Optimization profiles". |
--profile |
A profiling build. It records CPU times. Refer to "Profiling builds". |
--web-emcc PATH |
The Emscripten emcc for ninja web (else the one on the PATH, or ~/emsdk's). |
Without --portable, the Linux and Windows builds use all the instructions
of the processor that builds them (-march=native). Such a build does not
always start on a different computer.
Optimization profiles
The builds use profiles of the game to optimize the code:
pgo/halo_linux.profdatafor Linux and Android.pgo/halo_windows.profdatafor Windows.
The profiles need clang 22 or later. With an older clang, the builds do not use the profiles.
To record a new profile:
- Delete the profile.
- Enter
python configure.py --pgo=train. - Enter
ninja linuxorninja windows.
The build then plays the main menu and the first minute of each campaign
level. This procedure continues for approximately 15 minutes. The game
data must be in assets/.
Profiling builds
A profiling build records where the game spends its time.
- Enter
python configure.py --profile, then build as usual. - Start a recording. Enter
profile_recordin the console (or the telnet console), or setdebug.profile_record = trueinconfig.toml. To record each game of a session, also setdebug.profile_record_when = "game". - Stop the recording. Enter
profile_stop, load another map, or quit.
The game writes numbered .part<n>.json files under profiles/ in its data root
and logs their paths. Parts are retained after the recording stops. Logs go to
standard error; a Windows release build without standard error writes them to
halo.log next to halo.exe.
tools/net_report.py is a helper for developers. Enter
python tools/net_report.py <recording.part1.json> to read a recording
as tables. The command also writes <recording>.summary.txt, a short text
file.
| Command | Result |
|---|---|
profile_record [seconds] |
Starts a recording. With a number of seconds, the recording stops after that time. |
profile_stop |
Stops the recording. |
debug.profile_memory sets the memory of a recording in MB (default 256,
from 4 to 1024). A recording has no length limit:
the game writes a part each time the memory is full. Refer to "Settings" in
port/linux/README.md.
On Android, the files are in /sdcard/Android/data/com.halo.decomp/files/profiles/.
Enter adb pull to copy the recording parts to a computer.
A profiling build plays with normal builds. It does not use
--pgo=train.
Licence
OpenCE is free software: you can give it to others and change it under the
terms of the GNU Affero General Public License as published by the Free
Software Foundation, version 3 of the License or (at your option) any later
version (AGPL-3.0-or-later). It comes with no warranty. The full text is in
LICENSE.
- From the change. The AGPL applies from the commit that made the change, and to each release built from that commit or a later one. Earlier releases, and the source at every earlier commit, were released under CC0 1.0 and stay that way.
- What OpenCE builds on. The decompilation of punpckhdq/halo is under the AGPL 3.0 from 17 October 2026, and under CC0 1.0 before that date. bnunu/halo-1 is under CC0 1.0.
- Contributions are under
AGPL-3.0-or-later. A change taken from a project under GPL 3.0 keeps that licence and its notices; the GPL 3.0 and the AGPL 3.0 let the two be combined (section 13 of each). - Hosts and servers. If you change the game and let other persons play
with your version over a network (for example, as the host of an internet
game, or on a web site), the AGPL asks you to offer them the source of
your version (section 13). The game as released has its source here, and
each release's source is its tag (
build-<n>). - Third-party code, fonts and art keep their own licences, which are
next to them (
port/third_party,port/assets/fonts,port/assets/icons,port/assets/text_filter). The release downloads and the web site'slicenses.txtcarry their notices. - Halo is not covered. The licence covers the work of OpenCE's authors. It gives no rights in Halo, its maps or anything else that Microsoft owns.