Play it: halo.damian.lol. Halo: Combat Evolved multiplayer in the browser, against other browser players, on dedicated servers.
This repository is the game side of that site:
- a WebAssembly client that runs the game in the browser (WebGL 2);
- a headless Linux dedicated server that hosts games from a rotation, controlled over its pipes;
- halo-gateway, a small Go daemon that carries the browsers' traffic (WebSocket, with a WebRTC data channel for datagrams) to the dedicated servers.
It is a fork of
cybersecurity/halo-ce-universal,
the port of the Halo: Combat Evolved decompilation to Linux, Windows and
Android. That port starts from bnunu/halo-1,
a fork of punpckhdq/halo, the
decompilation of the Xbox build 2342 (cachebeta.exe, SHA-256
4cc87b45f721270392a96f1674ed2b5cd4a7bb4355faeab4531d1cf1884d9520).
No game data is included or provided. You need your own legitimately obtained copy of Halo: Combat Evolved for the Xbox. Refer to "Game data". Halo is a trademark of Microsoft; this project is not affiliated with or endorsed by Microsoft or Bungie.
The upstream project is a port for players: a game that you download, point at a disc image and play, on a local network or over the internet. This fork is for hosting Halo multiplayer as a service, with the browser as the client:
| Part | What it is | Where |
|---|---|---|
| Dedicated server | The Linux build, started headless: no window, GPU, audio or player of its own. It hosts system link games forever from a map and game type rotation, and a supervising process controls it through JSON over its pipes. | port/linux/README.md, "Dedicated server" |
| WebAssembly client | The game compiled with Emscripten (ninja web) for the browser, WebGL 2. By default it is multiplayer only, with no menus: the page that embeds it picks the player's name, colour, team and server, and the game loads straight into that server's game (the dedicated server runs its rotation back to back, with no lobby countdown). |
docs/gateway.md, docs/wasm-spike.md |
Gateway (halo-gateway) |
A small Go daemon that runs next to the dedicated servers. A browser has no UDP or TCP sockets, so the web client's sockets are framed onto one WebSocket to the gateway, which owns the real sockets. The game's datagrams move to a WebRTC data channel (unordered, no retransmits, as UDP) when one can open, with the WebSocket as the fallback. Access is by short-lived signed join tokens. | port/gateway, docs/gateway.md |
The fork uses upstream's distributed netcode (the lockstep netcode is removed, as upstream did) and takes upstream changes selectively; see docs/upstream-lockstep-removal-plan.md for an example of how a change is reviewed and ported.
This fork builds and supports only:
- the dedicated server:
ninja linux, a release build, started withHALO_DEDICATED=1; - the web client:
ninja web(multiplayer only); - the gateway:
go build ./port/gateway.
The Windows and Android code comes from the original repository. It stays in
the tree, so that changes from the original repository merge cleanly, but
this fork does not build, test or publish it. The Linux build also starts as
a normal windowed (or debug.hidden_window) game, which the end-to-end tests
use as a native client; it is for development and testing, not a product.
The self-updater of the native game is off in every build (it looks for the
original repository's releases).
The fork also changes the game where multiplayer with a dedicated server
needs it: joining games in progress and after a game's end, team balance
(with a team preference from the web client), per-player colours reported
by the server, a client datagram queue that holds several ticks against
rubber-banding, and larger map cache slots for community multiplayer maps.
Most changes are behind #ifdef (HALO_LINUX, HALO_WEB,
HALO_MULTIPLAYER_ONLY), so the byte-matching build is unchanged.
The intended user is an application, for example a web site that lets its users play Halo multiplayer in the browser. It needs no Halo code of its own; it runs these pieces and glues them together:
browser page ── halo.js / halo.wasm (the web client)
│ WebSocket (+ WebRTC data channel for datagrams)
▼
halo-gateway ── system link over loopback ──► dedicated servers (build/linux/halo)
▲ ▲
│ control API (register servers) │ JSON events / commands on pipes
└────────────── the application's supervisor ──┘
- Run dedicated servers. The application starts one
build/linux/haloprocess per server withHALO_DEDICATED=1, a name, a rotation (for examplebloodgulch:slayer,sidewinder:ctf) and its own loopback address (HALO_NET_ADDRESS=127.0.1.N,HALO_NET_BROADCAST=127.64.0.1). It reads the server's events (server_started,player_joined,game_started,status, ...) from stdout to show a live server list and player counts, and writes commands (kick,change_map,set_rotation, ...) to stdin. Refer to "Dedicated server control" in port/linux/README.md. - Run the gateway beside the servers, with a shared secret. The
supervisor registers each server with the gateway's loopback control API
(
PUT /servers/{id}) when it is up, and removes it when it stops. The site's reverse proxy forwardswss://<site>/gatewayto it; for WebRTC, one UDP port (3478 by default) must reach it. - Issue join tokens. When a signed-in user clicks "play" on a server, the application signs a token (HMAC-SHA256 over a small JSON claim set: user, one-time session id, expiry, the servers the user may join, and the session's address) and answers token refreshes from a URL of its own. The token format is in docs/gateway.md.
- Serve the client. The page serves
port/web/shell/play.html(or its own page withhalo-loader.js) andbuild/web/halo.{js,wasm}with the cross-origin isolation headers (Cross-Origin-Opener-Policy: same-origin,Cross-Origin-Embedder-Policy: require-corp), and the maps under/maps/with Range requests. It passes the settings asHALO_WEB_*values: the gateway URL, the token, the player's name, colour and team, and where to go when the player leaves. The client downloadsui.mapfirst and each multiplayer map when a game needs it. - Handle leaving. When the player quits, is refused or loses the
connection, the page gets a cancelable
halo:leaveevent, or the client goes toHALO_WEB_EXIT_URL, so the site can take the player back to its server list.
A native Linux client (for development and tests) can join the same dedicated servers over system link, next to the browser players.
docs/gateway.md has the details: addressing, the frame format, WebRTC, the gateway's settings, an example reverse proxy configuration, and the multiplayer-only build.
This repository does not include the game data, and none is provided
anywhere by this project. Use your own 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 the two versions can play together.
- Native Linux client (development): at the first start, the game asks
for the disc image and extracts the
maps/folder next to the executable. - Dedicated server: needs a
maps/folder in its data root (HALO_DATA_ROOT) withui.mapand the maps of its rotation. It needs no display, GPU or audio device. - Web client: the site serves
ui.mapand the multiplayer maps. The multiplayer-only build refuses campaign levels, so they are not needed.
You do not need the Xbox SDK. The port supplies the SDK declarations that the game uses. Refer to port/include/xdk.
- Install Python and ninja, and 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 a target:
| Target | Result | Instructions |
|---|---|---|
ninja linux |
build/linux/halo: the dedicated server, and the native client for development and tests (32-bit x86, OpenGL 4.5, SDL3) |
port/linux/README.md |
ninja web |
build/web/halo.js and halo.wasm (wasm32, WebGL 2, SDL3). Needs Emscripten (source emsdk_env.sh first). |
docs/wasm-spike.md, docs/gateway.md |
The windows and android_apk targets of the original repository are
still defined, but this fork does not build or maintain them.
The gateway is a separate Go program:
go build ./port/gateway (a static binary; tests:
cd port/gateway && go test -race ./...).
To try the web client locally, run a dedicated server and the gateway, then
python3 port/web/serve.py --maps /path/to/maps serves the page with the
right headers. The web client uses threads (SharedArrayBuffer) and JSPI;
it runs in current Chrome and Firefox. Safari would need an ASYNCIFY build,
which is not made yet.
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 build operates on all x86-64 processors. Use this option for builds that you deploy to servers. |
--web-campaign |
ninja web with the campaign and the menus, instead of the multiplayer-only build. |
--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". |
Without --portable, the Linux build uses all the instructions of the
processor that builds it (-march=native). Such a build does not always
start on a different computer.
The dedicated server is deployed as
python configure.py --portable --release --pgo=off then ninja linux,
and the web client as python configure.py --pgo=off then ninja web, as
in CI.
The Linux build can use a profile of the game to optimize the code
(pgo/halo_linux.profdata, inherited from the original repository). The
profile needs clang 22 or later; with an older clang, the build does not use
it. The deployment and CI build with --pgo=off.
To record a new profile, delete the profile, enter
python configure.py --pgo=train, then ninja linux. The build then plays
the main menu and the first minute of each campaign level (approximately 15
minutes). The game data must be in assets/.
GitHub Actions (.github/workflows/build.yml)
checks each pull request and each push to main:
- server:
ninja linux(release, portable, as deployed; Debian, clang 19), thentools/test_linux_port.pyand the dedicated server's control test (tools/dedicated_control_test.py), which need no game data; - web:
ninja webwith Emscripten 6.0.10 (the build is kept for three days as thehalo-webartifact); - gateway:
go vet,go test -raceandgo buildinport/gateway.
The workflow publishes no releases. Windows and Android are not built.
- System link games on a local network or over the internet. The port
raises the Xbox's limits to 128 players on up to 128 machines; a
dedicated server's games take up to 16 players (
server.max_players). - Browser and native clients can play in the same game.
- 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.
- Players can join a game in progress; a dedicated server keeps the game on when only one player is left.
- Without a dedicated server, one player's machine hosts, and an invite link lets a machine join it over the internet, as in the original project.
The Linux README also gives the controls, the settings and the multiplayer functions of the native game. These are almost the same on all platforms.
The decompilation also has a byte-matching build. That build compiles the
game with the compiler of the Xbox SDK and compares the result with
cachebeta.exe. This project does not generate that build, because the
Xbox SDK is not free to distribute. The sources of that build are not
changed. To use it again, set SolutionConfig.matching in
tools/project_x86.py. You must also have the Xbox SDK in xbox/ and
cachebeta.exe in the root folder.
- punpckhdq/halo: the Halo: Combat Evolved decompilation and its byte-matching build (AGPL-3.0 from 17 October 2026; CC0-1.0 before).
- bnunu/halo-1: the fork of the decompilation that the port starts from (CC0-1.0).
- OpenCommunityEdition/OpenCE (formerly cybersecurity/halo-ce-universal): the port to Linux, Windows and Android (Direct3D 8 on OpenGL, SDL3 input and sound, the system link netcode), which this repository forks (AGPL-3.0-or-later from 4b09168e; CC0-1.0 before).
- Everyone credited in those projects, and the third-party code in port/third_party (each directory has its license).
- Tools and libraries: Emscripten, SDL, Ninja, Pion WebRTC and coder/websocket (the gateway).
- The community multiplayer maps that halo.damian.lol hosts are credited on its credits page.
The game as built from this repository is under the
GNU Affero General Public License, version 3 or later
(AGPL-3.0-or-later), because it includes fixes ported from upstream OpenCE
after upstream switched from CC0 1.0 to the AGPL at its commit 4b09168e
(19 October 2026). Code from before that switch, upstream's and this fork's
own up to main 2d7c2077, was released under CC0 1.0
and stays so. NOTICE.md lists what was ported from after the
switch. The source is this repository,
https://github.com/damiantw/halo-ce-web-multiplayer. Third-party code keeps
its own license (see each directory under port/third_party).