OpenCE

OpenCE is a port of Halo: Combat Evolved to Windows, Linux and Android that supports multiplayer across all platforms.

README

OpenCE - Halo: Combat Evolved for Linux, Windows, Android and the web

OpenCE

Download Play in browser Discord Deploy with Zenith

OpenCE (Open Community Edition) is an open source port of the Halo: Combat Evolved decompilation (Halo CE) based on an early Xbox development build (2342) and forked from bnunu/halo-1. The project aims to enhance the existing game and adds many features, such as 128-player multiplayer, online campaign co-op, mod packs, field-of-view settings, a server browser, peer-to-peer hosting, automatic map downloads, voice chat, support for Custom Edition maps and much more!

The game runs natively on Windows, Linux, Android and in the web browser with nothing to install. A macOS port is in progress. Worth noting that it is not an emulator, the game's own code is compiled for each platform with a new layer in place of the Xbox's hardware. Runs on OpenGL (Android is on OpenGL ES and WebGL 2 in the browser). Sound, input, gamepads are all handled through SDL3. The game currently draws a frame every refresh of your display with Smooth Motion enabled, while the simulation runs at 30 ticks just like the original Xbox.

The game running on Windows

OpenCE running on Windows (release build)

A copy of Halo: Combat Evolved is required

OpenCE does not include the game data. You must provide your own Xbox disc image (.xiso or .iso) of Halo: Combat Evolved. Every version of the game works. The maps of the European (PAL) version were made for a slower console - the game changes them to play as the North American (NTSC) maps do, so players of the two versions can play together.

  1. Start the game (halo.exe on Windows and halo on Linux).
  2. At the first start you will get a pop up message asking for the disc image. Select it in the file picker. On Linux and Windows, a disc image (.iso or .xiso) next to the executable is used without the file picker. Where no file picker can be shown (on Linux, without the desktop portal or zenity), the game says to put the disc image next to the executable, and stops.
  3. 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 folder, beside maps folder.

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 (port/web/README.md).

Download

GitHub Actions builds the game for each commit.

Builds for latest release:

PlatformReleaseDebugGuide
Linuxhalo-linux-release.ziphalo-linux-debug.zipLinux
Windowshalo-windows-release.ziphalo-windows-debug.zipWindows
Androidhalo-android-release.ziphalo-android-debug.zipAndroid
Webhalocombatevolved.com (or halo-web-release.zip for your own server)halo-web-debug.zipWeb

Release build is recommended for regular play.

The debug build stops at the first failed check (assertion) and writes it to the log, so use it when you want 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.

Each release also has SHA256SUMS, the SHA-256 of each of its files, and SHA256SUMS.sig, that file's Ed25519 signature by the project's release key, whose public key is deploy/release-key.pub. sha256sum -c --ignore-missing SHA256SUMS checks the downloads, and tools/release_sign.sh verify SHA256SUMS (OpenSSL 3) the signature.

The Linux README also covers the controls, every setting and the multiplayer features. These are almost the same on all platforms. The settings are in config.toml next to the game, and many are in the menus too.

The Arch-based distribution release is available on the AUR.

Multiplayer

  • Supports up to 128 players on up to 128 machines and up to 4 players on each device in split screen.
  • Every platform plays together: Windows, Linux, Android and the browser all support cross-play! On a local network, the native builds can play LAN. Browser players can play each other in rooms over WebRTC (port/web/README.md).
  • Peer-to-peer internet hosting: join through the server browser or an invite link. A host lists a game as public in the server browser, or keeps it private for players with the invite link. With the Discord integration, the host can also send the invite through Discord.
  • Online co-op campaign: with settings for friendly fire, player collisions and the number of enemies as a multiplier based on per player or static.
  • New gametypes: SWAT, Infection, Gun Game and Hardcore (Slayer, CTF, Oddball and King), in Select Gametype's OPENCE bank; Edit Gametypes' OPENCE OPTIONS gives any gametype their rules (port/linux/README.md, "OpenCE gametypes").
  • Voice Chat: push to talk (V) or an open microphone (can be changed in the menu's audio settings)
  • Map sharing: a player who does not have the game's Custom Edition map downloads it from the other players.
  • Moderation: the host can kick and ban players from the scoreboard menu or the kick and ban console commands. Players can vote to kick.
  • Scrollable Scoreboard: the mouse wheel or PageUp / PageDown scrolls through list of players in large multiplayer lobbies.
  • A new netcode: each machine moves its own player at once, and the host makes the decision for the game. Refer to port/linux/NETCODE.md.
  • Official dedicated server hosting: Zenith Hosting is the official host for OpenCE Fleet. Get your own dedicated servers in one click, managed from one dashboard.

Deploy with Zenith

Custom Edition Maps

Halo Custom Edition maps are placed in custom_maps folder, not in the maps folder itself. It requires bitmaps.map, sounds.map, and loc.map in the custom_maps folder, which you must copy over from your existing installed copy of Halo Custom Edition. The maps folder is only for Xbox maps that's extracted from your disc image, not Halo Custom Edition.

Halo PC Gearbox exclusive maps (Ice Fields, Death Island, Danger Canyon, Infinity, Timberland and Gephyrophobia) are not included by default. They would need to be copied over from your existing Halo Custom Edition install's maps folder into custom_maps folder too.

Once that's setup, the maps will appear on CUSTOM SINGLEPLAYER and CUSTOM MULTIPLAYER in the map list in Campaign's New Game, and on the Map screen of Create Game (Internet or LAN). A CUSTOM SINGLEPLAYER map plays as a campaign level, alone or as online co-op.

Maps that require OpenSauce are not compatible.

Both the server browser and the LAN browser support automatic map downloads - when you join a game it will download the custom maps from other players, with any of bitmaps.map, sounds.map and loc.map you are missing. This works on a LAN and on the Internet, when the host has map sharing enabled (on by default). Refer to docs/custom_edition_caches.md.

MCC maps

OpenCE supports Halo 1 MCC maps through Steam discovery on Windows/Linux, package imports on Android, and local installation. You still need the Xbox game data to run OpenCE. Obtain required MCC resources from your own installed copy of Halo 1 in MCC.

Windows and Linux

Subscribe to a Halo 1 MCC Workshop mod and let Steam finish downloading it. OpenCE reads the installed package directly; Steam can be closed while playing. Steam discovery, campaign mission ordering and package collections are enabled by default. Their controls are under Settings > Network Setup > Map Sharing > MCC Packages. Reopen the map list after changing them or restart OpenCE after installing a new package.

If your Steam library is not detected, set steam = 'C:\Steam' under [paths] in config.toml to point to your Steam installation or library.

Local installation

Copy the complete folder from steamapps/workshop/content/976730/<workshop ID> into mcc_maps, beside maps and custom_maps. Keep its maps, JSON files, resources and artwork together. OpenCE reads the mod's name and supported PNG previews from its metadata, even with Steam discovery disabled.

You can also make your own folder, such as mcc_maps/MyMod, and place .map files directly inside it. Keep package-supplied bitmaps.map and sounds.map with that package; do not mix resources from different mods. Metadata is optional for map-only installs, but needed for authored titles, previews and campaign ordering. See the package layout guide.

Android

Copy the complete Workshop folder or a ZIP of it to your phone. Quit OpenCE, long-press its launcher icon, choose Import MCC maps > Workshop package, and select the folder or ZIP. Import required shared resources separately. See the Android import guide.

Shared MCC resources

With Steam discovery enabled, desktop builds can read required base resources from your installed Halo 1 MCC files. They are not copied into the mod. For manual setup, or when that installation is unavailable, use these locations:

File in your MCC installationDestination in OpenCE
halo1/maps/bitmaps.mapmcc_maps/_shared/singleplayer/bitmaps.map
halo1/maps/custom_edition/bitmaps.mapmcc_maps/_shared/multiplayer/bitmaps.map
halo1/maps/custom_edition/sounds.mapmcc_maps/_shared/multiplayer/sounds.map

Use MCC's files, not standalone Custom Edition resources. Package-supplied resources take priority. On Android, use the shared-resource import options. Self-contained maps need no shared files; missing or incompatible resources produce a diagnostic.

Hosting and sharing

Share Maps in Server Setup > Map Sharing covers CE maps and eligible MCC packages automatically. MCC downloads ask for the joining player's consent and install separately, preserving their existing copy. Actual base resources are never sent: each player must provide matching local copies when required. A Workshop link opens Steam on desktop, with an explicit browser fallback. OpenCE does not update manually installed or host-downloaded packages for you.

Dedicated servers use the same sharing setting and can host MCC multiplayer maps and co-op campaigns. See the dedicated-server guide. MCC loading remains separate from Xbox and Custom Edition loading; see MCC support and limits for details.

Mods

Mods go in a mods folder next to maps. Each mod is a folder of Halo PC tag files, as the Halo Editing Kit and Invader make them, with a mod.toml describing it. Every mod in the folder is on by default. Mods in the main menu turns them on and off and sets their order. Think of it like a resource pack list, the mod at the top plays over the ones below it. The game also refuses mods that say they cannot be played together.

Refer to docs/mods.md to make your own.

Graphics

The game retains the original look and feel as it did on the Xbox by default. The video settings menus have additional options that go beyond it.

Display

OptionWhat it doesDefault
DISPLAY MODE, RESOLUTION, WINDOW SIZEFullscreen, borderless or windowed, at any resolution (F11 switches)Borderless, at the display's resolution
RESOLUTION SCALINGDraw at the window's resolution, or at the Xbox's 640x480 and scale it upNative resolution
V-SYNC, FRAME RATE LIMITWait for the display, or run free up to a frame cap; works with G-Sync and FreeSyncV-sync on
SMOOTH MOTIONA frame for every refresh of the display (60, 120, 240 Hz and more), blended between the game's 30 ticks a secondOn
INSTANT AIMIn first person, the view turns the frame the mouse moves, not up to two ticks laterOn
FOV, VIEWMODEL FOVField of view of the view and of the weapon and hands, from 80 to 150 degreesStock

Image quality

OptionWhat it doesDefault
ANTI-ALIASINGFXAA, SMAA, MSAA or SSAAOff, as on the Xbox
TEXTURE FILTERINGAnisotropic filtering, from 2 to 16 - provides sharper floors, walls and terrain at an angleOff, as on the Xbox
SHADOW RESOLUTIONObject shadows at 128 (the Xbox's), 256, 512 or 1024 pixels128
PER-PIXEL LIGHTINGLights models for each pixel, without the facets of the Xbox's per-vertex lightingOff
MODEL DETAILKeep more model detail at a distance at high resolutions, or always the most detailedStock
HDR, HDR DISPLAYKeeps explosions, plasma and the sun's glare past white and tone maps them; on an HDR monitor, shows them brighter than whiteOff
HIGH-RES HUD, HIGH-RES TEXTThe HUD from hand-drawn redraws at 8x the size, and text in the Overpass font, sharp at any resolutionOn

Extras

OptionWhat it doesDefault
LEGSSee your own legs when you look down in first personOff
ARM SHIELDSThe energy shield's flare on your first-person arms tooOff
SHIELD GLOW, GLOW INTENSITYEnergy shields light up what is around them as they flareOff
SHIELD COLORYour own shield in a multiplayer armor color, as your machine draws itDefault
OVERSHIELDThe overshield's own color, rising up the body as it chargesOff
PASSENGER THIRD PERSONThird-person view for Warthog and Scorpion passengers (Campaign-only)Off

How to 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:

  1. Install Python and ninja.
  2. Install the tools for your platform. Refer to the README for the platform.
  3. In the root folder of the repository, enter python configure.py.
  4. Enter ninja with the target for the platform:
TargetResult
ninja linuxbuild/linux/halo
ninja windows (on Windows, or on Linux after configure.py --windows-cross)build/windows/halo.exe and SDL3.dll
ninja android_apkport/android/app/build/outputs/apk/debug/app-debug.apk
ninja webbuild/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:

OptionResult
(none)A debug build. A failed assertion stops the game.
--releaseA release build. The game does not examine assertions, as in the retail game.
--portableThe 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=offLess link-time optimization. The link is faster.
--pgo=offNo profile-guided optimization.
--pgo=trainRecords a new optimization profile. Refer to "Optimization profiles".
--profileA profiling build. It records CPU times. Refer to "Profiling builds".
--web-emcc PATHThe 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.

For developers

Testing

The tests are listed in AGENTS.md ("Testing"). Most run without the game data, in GitHub Actions too.

One check needs the retail maps, so it runs on your own computer (or on a self-hosted runner), not in GitHub Actions: tools/net_compare.py plays two builds together in a network game on one computer and checks that they stay in step. Run it when a change can alter how a build calculates the game, as a change to the simulation, the compiler or the maths does, before it is merged. For example, to check a build with such a change against a build without it:

python tools/net_compare.py --a build/linux/halo --b <other checkout>/build/linux/halo \
    --data <folder with maps/> --maps bloodgulch,beavercreek,hangemhigh --swap

Each game prints PASS or FAIL. A FAIL names the first player, tick and value that differ. Refer to "Comparing two builds" in port/linux/NETCODE.md.

Optimization profiles

The builds use profiles of the game to optimize the code:

  • pgo/halo_linux.profdata for Linux and Android.
  • pgo/halo_windows.profdata for Windows.

The profiles need clang 22 or later. With an older clang, the builds do not use the profiles.

To record a new profile:

  1. Delete the profile.
  2. Enter `python config