Screenshots

Captured on an Anbernic RG35XX H (640x480 screen).

Bot Match: Slayer against bots, offline

MULTIPLAYER > BOT MATCH sets how many bots join (1 to 15), how well they play (Easy to Legendary) and, in Team Slayer, whose side they are on. Then you pick the map and the game type, as in the Xbox's split screen, and play them on the handheld, with no network (Install: Bot Match).

The spawn menu

Hold SELECT and press D-pad Down in a game: the level's vehicles, weapons, equipment and characters, placed in front of you, a character on your side or against you, and a page of the game's cheats (Install: the spawn menu).

Updates on the handheld

When a new release is out, the launcher offers it before the game starts. START downloads it from this repository's releases, checks it against the SHA-256 GitHub gives for it and installs it: your maps, saves and settings stay. Any other button plays the version you have, and that release isn't offered again (Install: Updating).

Online and the campaign

Features

• Native AArch64 code for the game and the host. The CPU runs the game's own logic compiled for ARM64; nothing is translated or emulated.
• Uses the firmware's own SDL2 and Arm's Mali-G31 OpenGL ES driver on the framebuffer, so it runs on stock Knulli with no extra libraries.
• A dedicated GL thread takes the Mali driver's per-draw CPU cost (about 17 µs a draw call) off the game's core.
• Renderer changes for a tile-based mobile GPU: program binary cache, fp16 shaders, 16-bit textures, asynchronous occlusion readback, quad batching and decal ordering, model LOD scaling, and shadows restructured to avoid render-target switches.
• Adjustable render scale (default 0.75, 480x360 scaled to 640x480).
• CPU and GPU clocks pinned while the game runs and restored on exit.
• First launch extracts maps/ from your Xbox disc image on the handheld.
• The handheld's own controls, read from EmulationStation's configuration.
• Quit with the hotkey: hold MENU (or SELECT) and press START.
• Bot Match (MULTIPLAYER > BOT MATCH): Slayer and Team Slayer against up to 15 bots on the handheld, offline, their skill (Easy to Legendary) and teams set in the menu (Install: Bot Match). The bots are BirchWoodGod's, from the PS Vita port, contributed to upstream.
• Updates from the handheld: the launcher offers a new release before the game starts, and START installs it (Install: Updating).
• A spawn menu, after AlphaRing's: the map's vehicles, weapons, equipment and AI characters, placed in front of you, and the game's cheats (god mode, infinite ammo, one-hit kills and more), and Teleport everyone to me, which brings every other player beside you (for a big online game where someone is stuck). In single player and for the host of a co-op or multiplayer game, never for a player who joined: hold SELECT and press D-pad Down (Install: the spawn menu).
• Upstream's online play: the campaign in co-op and multiplayer, over the internet (a server browser of public games) or the local network, with the PC version's menus (Install: playing online). Network version 39, with OpenCE's own gametypes: SWAT, Infection, Gun Game and Hardcore, in Select Gametype's OPENCE bank, and upstream's dedicated servers, which it joins as any other host.
• Upstream's Halo Custom Edition maps, beside the Xbox game's: the community's multiplayer and campaign maps in halo/custom_maps/. Joining a game on one you don't have downloads it from the game's players (Install: Custom Edition maps).

Performance

Frames per second on an Anbernic RG35XX H, Knulli Gladiator II, stock thermal limits: the typical value and the range of HALO_FPS_LOG's 5-second averages over the first minute of each level after it has loaded, with the level already in the game's cache (the first time a level is entered, its loading screen decompresses it there: Install). Dynamic resolution is on, as it is by default. c10's opening holds 60 after its first 45 seconds. The b30 battle varies from run to run by 2 or 3 fps.

Last updated: 2026-10-06 (release v2026.10.06).

At 0.75 the limits are the game's own thread and the Mali driver's CPU time for each draw call on the GL thread. Where the GPU is the limit, as in c10, dynamic resolution lowers the render scale, down to 0.5, until it keeps up. At 640x480 the GPU is the limit in the a30 opening and the b30 battle too. The b30 battle steps down to 480x360 to 520x390 for much of the fight. In a30 the driver waits for the GPU where dynamic resolution does not yet see, so after its intro a30 stays at 640x480 (Roadmap). The kernel's thermal governor lowers the clocks at 70 °C. The history of the optimisations and the measurements behind them are in docs/PERFORMANCE.md.

Supported devices

The port is made for the Allwinner H700 (4x Cortex-A53 at 1.5 GHz, Mali-G31 MP2, 1 GB RAM), with Knulli or another firmware that has PortMaster. Halo moves and aims with two analog sticks; on a handheld with one or none, the D-pad takes the missing stick's place (Install: controls).

The port is made and tested for the H700's Mali-G31. Handhelds with other Mali GPUs and Arm's driver can work too: users report the Rockchip ones above working. TrimUI handhelds and other devices without a Mali GPU are not supported. If you try another device or firmware, please open an issue with the result and your halo/log.txt.

Requirements

• An H700 handheld with Knulli (tested with Gladiator II).
• Your own disc image of Halo: Combat Evolved for the original Xbox (.iso or .xiso), North American or European. The Xbox version's maps are required; the PC version's files do not work.
• About 3 GB free on the card: the extracted maps/ (1.8 GB) and the cache the game sets up at its first start (0.8 GB), plus room for the disc image until the maps are copied.
• The latest release (halo-ce-knulli-<version>.zip, or halo-ce-portmaster-<version>.zip for PortMaster), or the files built as described in Build from source.

Install

1. Download halo-ce-knulli-<version>.zip from the latest release.
2. Unzip it onto the SD card, into the partition that holds the roms folder (over the network, \\KNULLI\share). It adds roms/ports/Halo.sh and the folder roms/ports/halo/.
3. Copy your Xbox Halo disc image (.iso) into roms/ports/halo/.
4. On the handheld, start Halo from Ports. If it is not listed, update the game lists in EmulationStation's menu, or restart the handheld.

The first start copies maps/ out of the disc image, with its progress on the screen (about four minutes); the image can be deleted afterwards. The game's own first start then takes about a minute more with a black screen while it sets up its cache (the screen says so first); later starts take seconds. Instead of a disc image you can also copy an extracted Xbox maps/ folder into halo/. To quit, hold the hotkey (MENU, or SELECT) and press START. New releases are offered by the launcher before the game starts (START installs one); a newer release unzipped over the old files works too: maps/, save/ and config.toml stay.

With PortMaster (on Knulli or another firmware) instead: put halo-ce-portmaster-<version>.zip in PortMaster's autoinstall folder and start PortMaster, then copy the disc image into ports/halo/ (Install).

On a Batocera PC (x86-64) instead: unzip halo-ce-batocera-pc-<version>.zip into /userdata (over the network, \\BATOCERA\share), put the disc image, or the Xbox game's maps/ folder, in roms/ports/halo-pc/, and start Halo CE (PC build) from Ports. It is the decompilation's own 32-bit Linux build with this port's additions (Bot Match, the spawn menu), and it installs each new release by itself before it starts (Batocera PCs).

The resulting layout:

/userdata/roms/ports/
├── Halo.sh
└── halo/
    ├── halo
    ├── halo_guest.elf
    ├── halo_extract.py
    ├── halo_screen.py
    ├── sdl_mapping.py
    ├── halo_update.py   the updater the launcher runs
    ├── config.default.toml
    ├── VERSION          the release installed
    ├── brokers.txt      internet play's signalling brokers
    ├── config.toml      written at the first launch
    ├── log.txt          the log of the last launch
    ├── maps/            extracted from your disc image
    └── save/            saved games and the shader cache

The first time each shader combination is used, the driver compiles it, on a thread of its own: what it draws appears a moment late, rather than the game stopping for it. The compiled programs are kept in halo/save/shaders, so later launches load them instead.

Build from source

The build runs on Linux x86-64. It was done on Ubuntu 24.04 under WSL.

Tools

• Ubuntu 24.04 (WSL works), python3, ninja-build, git, curl.
• clang 22 from apt.llvm.org: the guest is compiled for the arm64_32 (ILP32 AArch64) target.
• Android NDK r28c: it builds the guest and provides the GLES and EGL headers.
• gcc-aarch64-linux-gnu (13.x): the host, an ordinary aarch64 glibc program.
• SDL2 headers from the SDL release-2.30.12 tag. build.sh downloads them.
• glibc 2.31 and libglvnd's EGL and OpenGL ES, Debian 11's, which the host is built against so that it runs on firmware with an older C library than Knulli's. build.sh downloads them (port/knulli/glibc_sysroot.sh, which checks the packages' checksums) and unpacks them with dpkg-deb.

sudo apt install python3 ninja-build git curl gcc-aarch64-linux-gnu
wget https://apt.llvm.org/llvm.sh && sudo bash llvm.sh 22
curl -LO https://dl.google.com/android/repository/android-ndk-r28c-linux.zip
unzip -q android-ndk-r28c-linux.zip

The device's libraries

The host links against the handheld's own libSDL2-2.0.so.0. Copy it from the handheld's /usr/lib into a sysroot/ folder. It is used only at link time and must not be committed. EGL and OpenGL ES are linked by their usual names (libEGL.so.1, libGLESv2.so.2), against Debian 11's libglvnd.

mkdir -p sysroot
scp 'root@<handheld>:/usr/lib/libSDL2-2.0.so.0*' sysroot/
# or: adb pull /usr/lib/libSDL2-2.0.so.0 sysroot/

Build

ANDROID_NDK=$PWD/android-ndk-r28c SYSROOT_LIB=$PWD/sysroot ./build.sh

build.sh:

1. clones halo-ce-universal into work/halo-ce-universal and checks out the commit in UPSTREAM_COMMIT;
2. applies patches/halo-ce-universal-knulli.patch and copies port/knulli into the upstream tree;
3. downloads the SDL2 2.30.12 headers, and glibc 2.31 and libglvnd, into work/;
4. runs python3 configure.py --release --android-ndk <ndk> --android-guest-cc clang-22 (the first time, and again for another upstream commit; it downloads musl and SDL3 for the guest), then port/knulli/build.sh;
5. copies halo, halo_guest.elf, Halo.sh, halo_extract.py, halo_screen.py and sdl_mapping.py into dist/.

The first build takes 10 to 30 minutes; later builds are incremental. Optional variables: GUEST_CC (default clang-22), HOST_CC (default aarch64-linux-gnu-gcc), WORK, DIST, JOBS.

How it works

The upstream project decompiled Halo CE's Xbox build to C and ported it to Linux, Windows and Android. Its Android port compiles the game as an ILP32 AArch64 "guest image" (32-bit pointers, as on the Xbox, in 64-bit ARM code) that a small host program loads and serves.

This port reuses that guest image and adds a new host for Knulli in port/knulli/: an aarch64 glibc Linux program instead of an Android app. It answers the guest's SDL3 calls with the firmware's SDL2, the only SDL with the Mali framebuffer video driver, and runs the guest's OpenGL ES calls on a GL thread. The renderer changes for the Mali-G31 are in the patch against upstream (port/linux/src and source/).

Details: docs/HOW-IT-WORKS.md and port/knulli/README.md.

Documentation

The documentation index describes each document and suggests a reading order for players, builders and developers.

• Install: the player's guide, from copying the files to the controls, the saves and what the launcher does to the clocks.
• Configuration: every setting and HALO_* variable, with its default and effect.
• Building: building from source, step by step, with the common build errors.
• How it works: the architecture in brief.
• Architecture: the guest and the host, the GL thread, the renderer and the rasterizer changes in depth.
• Performance: the optimisation history and its measurements.
• Profiling: the measuring tools and how to read them.
• Mali-G31 notes: lessons for porting a Direct3D-era renderer to this GPU.
• Contributing: how to change the code and benchmark a change.
• Roadmap: current limits and planned work.
• FAQ and legal notice.

Configuration

The settings are in halo/config.toml, written at the first launch. The launcher's defaults for the handheld:

Environment variables such as HALO_RENDER_SCALE=0.6 override a setting for one run. Every setting is described in docs/CONFIGURATION.md, and the debug.* settings and the profiling variables also in port/knulli/README.md.

A file halo/init.txt runs console commands at start-up, for example map_name levels\b30\b30 to start a level directly.

Troubleshooting

• Halo returns to the menu at once. The screen says why first (no disc image, not an Xbox disc image, an incomplete one, not enough free space); halo/log.txt has the details. A start while the game runs already is refused, and the log notes it.
• The first start seems stuck. Copying maps/ out of the disc image takes about four minutes, with its progress on the screen; then the game sets up its cache for about a minute with a black screen. A copy that was stopped goes on where it stopped at the next start.
• The maps do not load. The PC version's files do not work; use an Xbox disc image or an Xbox maps/ folder.
• The buttons are wrong. sdl_mapping.py builds the SDL mapping from EmulationStation's controller configuration. Check that the handheld's controls are configured in EmulationStation.
• Objects appear late the first time. Each new shader combination is compiled once, beside the game, and cached in halo/save/shaders; what it draws is skipped until it is ready. Deleting that folder is safe; the programs are compiled again.
• The frame rate drops after a while. At 70 °C the kernel lowers the CPU and GPU clocks. Lower display.render_scale for more headroom.
• The clocks stay high after a crash. Halo.sh restores the CPU governor and the GPU's minimum clock on exit; the next start, or a reboot, restores them too.

FAQ

Can the Anbernic RG35XX H run Halo: Combat Evolved?

Yes. This port runs Halo CE natively on the RG35XX H under Knulli, as AArch64 code on the H700's Cortex-A53 cores with the Mali-G31 GPU. It is built from the halo-ce-universal decompilation; you supply the Xbox game's data.

What frame rate does Halo CE get on the RG35XX H?

At the default render scale of 0.75: 60 fps in the menus, about 57 fps on 343 Guilty Spark (c10), about 43 in the beach battle of The Silent Cartographer (b30) and about 59 at the opening of Halo (a30). At the full 640x480 it is about 38 to 56 fps. The ranges are in the performance table.

Does it work with the Xbox version or the PC version of Halo?

The Xbox version. The decompilation is of the Xbox build, and it reads the Xbox maps. The PC version (Gearbox's port) has different map files that this code cannot load. Use a disc image of the original Xbox game. Halo Custom Edition's maps run beside it (Install: Custom Edition maps).

Is this legal?

The repository contains only source code and documentation, and its releases only the port's programs built from that source: the upstream decompilation's authors released their code under CC0, and so does this port. Neither contains game files, disc images or maps. You need your own copy of the Xbox game. Whether decompilation projects are lawful depends on where you live; this is not legal advice. See the legal notice.

Does it need PortMaster?

Not on Knulli: the Knulli zip is a plain port, a launcher script in roms/ports and a folder. Each release also has a PortMaster zip, for PortMaster on Knulli or on other firmware (Install). Both use the firmware's own SDL2 and graphics driver and none of PortMaster's runtimes.

Does it work on muOS or ROCKNIX?

muOS works with the PortMaster zip from v2026.10.07, tested on an RG35XX H with muOS 2601 Jacaranda, in the campaign and online. Earlier releases crashed there in menus, at respawn and in the pause menu: muOS's SDL takes over the crash handler the port uses to notice the game writing to its textures. ROCKNIX is reported working on an RG353M with Arm's Mali driver, once ROCKNIX was up to date: an older version (20260601) left parts of the picture frozen unless debug.instance_models = false (#5). It can also use the open Panfrost driver, which the port has not been tried with. dArkOSen on an R36S is reported working from v2026.10.07 (#4). The host is built on glibc 2.31 and links EGL and OpenGL ES by their usual names, so that it loads on firmware older than Knulli. Reports are welcome.

Why not run the PC version with Box64 and Wine?

The PC version is a 32-bit x86 Windows program that draws with Direct3D 9. Running it on the H700 would need x86 translation, Wine, and a Direct3D to OpenGL ES translation layer, all on four Cortex-A53 cores and 1 GB of RAM. Each layer costs CPU time the device does not have. The native port runs the game's own logic as ARM64 code and draws with OpenGL ES directly.

Why not use xemu?

xemu emulates the whole original Xbox, its Pentium III CPU and its NV2A GPU, and needs a fast desktop CPU and a desktop OpenGL or Vulkan GPU. The H700's Cortex-A53 cores and its OpenGL ES-only Mali driver are far below that. A native port of the decompiled code avoids the emulation entirely.

Which other handhelds does it work on?

It should run on the other Allwinner H700 handhelds that run Knulli: the Anbernic RG35XX Plus, SP and 2024, RG40XX H and V, RG CubeXX and RG34XX. Halo moves and aims with two analog sticks. The Plus, SP, 2024 and RG34XX have none and the RG40XX V one: from v2026.10.21 the D-pad takes their place, not yet tried on those handhelds (#9). The RG35XX H is the one it is developed on, and a user reported the RG34XX SP working, its 3:2 screen filled with screen_width = 0 (#1). TrimUI handhelds and other SoCs are not supported.

Can I play against bots?

Yes, offline: MULTIPLAYER > BOT MATCH plays Slayer or Team Slayer against up to 15 computer players on the handheld alone, at Easy, Normal, Heroic or Legendary (Install: Bot Match). The bots are BirchWoodGod's, from the PS Vita port, contributed to upstream OpenCE (in review there). They play in Bot Match only: not online, not on a LAN, and not in other game types.

Legal notice

This is an unofficial fan project. It is not affiliated with, endorsed by or sponsored by Microsoft, Xbox Game Studios, Halo Studios or Bungie. Halo, Halo: Combat Evolved and Xbox are trademarks of Microsoft Corporation.

The repository and its releases contain no Halo game files: no disc images, maps, XBE or extracted assets. They contain no Arm Mali driver binaries and no device libraries; the releases hold only the port's own programs, built from this source. To play, you need your own copy of the original Xbox game. Details: docs/LEGAL.md.

Credits

• halo-ce-universal and its contributors: the decompilation's Linux, Windows and Android ports, on which this port is built. It starts from bnunu/halo-1, a fork of punpckhdq/halo.
• BirchWoodGod: the bots, from the PS Vita port, contributed to upstream under CC0 (OpenCE #367).
• AlphaRing: the spawn menu's design, after its menu for The Master Chief Collection.
• Bungie, who made Halo: Combat Evolved. Halo is a trademark of Microsoft Corporation.
• SDL (zlib licence): the headers are used at build time, and the firmware's SDL2 at run time.
• Knulli, the firmware for these handhelds, based on Batocera.
• The upstream build also uses musl, tomlc17 and miniupnpc, under their own licences.

Licence

CC0 1.0 Universal, like upstream. Contributions are welcome; see CONTRIBUTING.md.