A player who joins a server on a map they don't have, or whose host or post-game vote picks one, gets a prompt with the map's hub screenshot and details. DOWNLOAD installs the map and loads it into the running game, and the join (or the lobby) carries on. There is no restart. The same screenshots now appear on the map select, the lobby card, FIND GAMES and the post-game vote.
Verified on CU4, 2026-10-09:
- Wizard was uninstalled (launcher state, cache, Paks,
MJOLNIRMaps, and the registration container rebuilt without it). From the running game's download screen it then downloaded, verified, installed, mounted and registered in under six seconds, and hosted and played. - Reactor, a halomaps.org conversion that was never in the registration container or in Paks at boot, was registered and mounted by hand while the game ran, then hosted and played. The game exited cleanly afterwards.
Then on two PCs (PC 2 without Wizard: launcher uninstall, so its registration container lacked it too):
- FIND GAMES: PC 2 used DOWNLOAD AND JOIN on PC 1's Wizard game. It downloaded, mounted and registered the map, joined the lobby, and both played it.
- The host's pick: PC 1 changed the lobby to Hang 'em High. PC 2 got the prompt, PC 1's lobby showed "WAITING FOR 1 PLAYER TO DOWNLOAD", PC 2 downloaded it, and both played.
- The vote: the post-game vote chose The Longest. PC 2's option read
/ DOWNLOAD, it got the prompt, PC 1 held its countdown until PC 2 was ready, and both played.
Two things only a second PC could show, both fixed:
- The map's index in the campaign list must match on every machine (next section).
- The live row's MapGuid has to match the cooked one. The C copy of
map_guidupper-cased all of "MJOLNIR map CODE", not just the code. A host alone never notices: it only has to agree with itself. A client whose row disagrees with the host's loads the world, and the game never starts.
Every machine needs the same index for the map
SetAndBeginCampaign (0x7B446E0) finds the map by a linear scan of
DA_FirstPlayableCampaign.ScenarioList and keeps its index
(BlamCampaignFlowGameSubsystem+0x38). A fireteam only starts when every
machine's index agrees:
- PC 1 has two local maps (CSN, YOY) that PC 2 lacks. Danger Canyon is index 15 on PC 1 and 14 on PC 2, and both loaded the world and stayed "not in a game".
- Blood Gulch sits before both local maps, at 12 on each, and started.
Installed map sets differ from player to player, and a live install appends at the end, so this has to be handled:
- The host sends its index with the map: field 4 of the lobby message, field 6 of the vote message.
- A guest joining a match under way asks for it (
where/mapindex). - Clients call
MapLive.follow, which usesmjolnir_scenario_place(native/map_registry) to swap the handle to that index. When the list is shorter, it pads with copies of B40's handle; the scan finds the real B40 first, so a filler never answers for anything.
The map registry logs the move, e.g. place DCN: index 14 -> 15.
What a converted map needs, and when each step happens
| Step | At boot (the launcher's install) | While the game runs |
|---|---|---|
| Containers in Paks | hub::materialize copies them; the engine mounts them at startup | the launcher's live install copies them under the same names; mjolnir_mount_paks mounts them |
| Short world name resolves | mjolnir_map_registry indexes Paks/*.utoc at load | the mount re-reads the indexes |
DT_Scenarios row and campaign ScenarioList handle | cooked into pakchunk996-MJOLNIRREG_P | mjolnir_scenario_add clones the B40 row in memory |
| Frontend levels cache entry | built at boot from every DT_Scenarios row | the same insert, called by mjolnir_scenario_add |
| Level data and the menu list | maps::sync writes MJOLNIRMaps/<CODE>/ and maps.json | maps::add_live writes the same; the lobby re-reads it every time |
The frontend levels cache was the missing piece. The 2026-09 notes put the
boot-time gate in the simulation's own levels registry. That registry is the
data arrays campaign levels (64) and multiplayer levels (50) in
HaloSimulation_tag_release.dll at 0xbd5738 and 0xbd5748, and on CU4 they are
empty. Nothing reads them, and their caps limit nothing.
The real boot-time step is in the exe:
UBlamFrontendLevelsEngineGlueSubsystem::BuildRuntimeCachesFromBuiltInMapInfoDataAsset
(0x7B7D180). It passes every row of the tables BuiltInMapInfoData names to
a per-row insert (0x7BAC140). That insert builds the subsystem's per-map
entries: 0x14c bytes each, keyed by MapGuid, in a sparse array at
subsystem+0x138. It then stamps each campaign map's entry with its
campaign's id (+0x120).
A row added without that entry loads the world, but the simulation stays "not
in a game" (mjolnir live arrays). With the entry, the map plays. So there is
no limit on how many hub maps a player can install. Only maps registered at
boot or added this session can start, and every start path adds the map
first.
The pieces
Launcher, --install-map <CODE> [--release <id>] --progress <file> (hub::run_live_install).
This is the ordinary install (install_one), run with no window:
- It checks the hub's sha256, the platform signature when there is one, and the author signature.
- It writes the same cache,
hub_state.jsonand active profile, and uses the same Paks file names. The next launch therefore copies nothing and rebuilds the registration container, because its record lacks the new code. - Since launcher 0.14.0 it writes every file under the pack's
map/(a remastered map's foliage file anddecals/). Since 0.14.1 a map that is installed but missing one of the files its level names is fetched again at the release it has, and its containers in Paks are left as they are.
What it leaves out, because the game is running:
- It never rewrites a container the game holds open: an update of a mounted map is written beside it under a patch name, and the game swaps them (below).
- It doesn't install or update code mods: their DLLs are loaded.
- It treats a missing dependency (the CE runtime pack) as an error, and since launcher 0.14.0 one older than the floor of the pack's range too, naming the range and the installed version.
- It doesn't rebuild the registration container: it is mounted.
It decides everything that can stop it before it writes a container, so a refusal leaves Paks as it was, and a write that fails takes back what it wrote. A map that downloaded but cannot be loaded into the running game (a pack it needs is already loaded in another version, or Paks written for another profile holds another mod's shader library under its number) stays installed and enabled. The message then says to quit and start the game again from the launcher, and that launch writes the map with everything else. A container that only shares a chunk number with one already mounted is not such a case (docs/chunk_numbering.md).
Progress goes to <file> as one JSON object, replaced as it changes:
{"stage":"start","code":...}first.{"stage":"download","received":n,"total":n}, where the total comes from the hub listing, since the archive is streamed without a length.- Then
{"stage":"done","mount":[...],...}or{"stage":"error","message":...}.
The launcher records its own path in launcher_exe.txt in its config folder
each time it starts. A launcher from before live installs records nothing, so
the game says to update it instead of opening it.
MJOLNIRLobby's native half (native/lobby):
mjolnir_map_installstarts the launcher for a code ([A-Z0-9]{3}only).mjolnir_map_install_statussays whether the launcher is still running.mjolnir_hub_callgained aFILEmethod that saves a hub response toMJOLNIRMaps\_covers\<name>; the name is a plain file name.
MJOLNIRLevelLoader's native half (native/map_registry):
-
mjolnir_mount_pakscallsFCoreDelegates::MountPak. The storage is at exe 0xD349040; the bound instance holds theFPakPlatformFileat +0x18 andHandleMountPakDelegate(0x4694C00) at +0x20, and the method is checked before the call. It mounts each.pak, then its IoStore sibling with the IoDispatcher and the package store, and firesOnPakFileMounted. Then it re-reads the world index. -
mjolnir_scenario_adddoes the following:- clones a template row (B40, as the cooked rows do) with the codename's
world,
ScenarioNameand MapGuid (blam_pack::scenario::map_guid); - adds it to
DT_Scenarios'RowMap; - appends the
ScenarioListhandle; - calls the frontend levels insert and copies the campaign id from the template's entry.
Every allocation goes through
GMalloc(exe 0xD4B7428: Malloc at vtable +0x28, Free at +0x48), so the engine frees them at shutdown like its own. An FText copied by value takes a reference (+8of its text data). - clones a template row (B40, as the cooked rows do) with the codename's
world,
Both are CU4-only, with one set of exe addresses per build picked by the
exe's PE timestamp (exe_profiles). The exe RVAs in this note are the Steam
exe's; the Xbox app's CU4 exe has its own set (PR #179,
game_pass.md).
MJOLNIRLobby (Scripts/maplive.lua, wired into main.lua):
MapLive.refresh/inforead the hub listings (GET /maps,/maps/{code}).MapLive.cover/texturekeep each map's cover on disk and read it withKismetRenderingLibrary.ImportFileAsTexture2D. Textures are kept by name and found again withStaticFindObject, never kept by reference: a transient texture no brush holds any more is collected.MapLive.installstarts the launcher, polls its progress, mounts, then registers.MapLive.registeradds a map's scenario records unless they are there already. It runs before every start (startGame), before a join from FIND GAMES, and when a client hears the host's map.
The flows
- FIND GAMES:
- A game on a map you lack offers DOWNLOAD AND JOIN. The download screen explains why, and once the map is in, the join runs as usual.
- The details panel shows the map's screenshot and download size.
- QUICK JOIN still only picks maps you have.
- The host picks a map a client lacks:
- The client's lobby offers the download once; after that, the lobby's START button reads DOWNLOAD MAP.
- The client reports
mapstate <code> prompt|download <pct>|ready|declined|errorto the host. - While someone is deciding or downloading, the host's lobby footer says so. A first START warns; a second START within ten seconds starts without them.
- The post-game vote picks a map a client lacks:
- Vote options on maps you lack read
/ DOWNLOAD. - When the vote ends on one, the client gets the download screen.
- The host's countdown waits while anyone is deciding (up to 25 s
without word) or downloading (
Live.DOWNLOAD_WAIT, 180 s), and the post-game footer says who it is waiting for.
- Vote options on maps you lack read
- Test verbs:
mjolnir_auto download <CODE>opens the screen.mjolnir_auto install <CODE>installs with no screen.mjolnir_auto joindownloads the listed game's map first.
Versions, and updating a map the game has loaded
Every player has to run the host's release of the map. The host sends it,
as its hub release id and version (read from the launcher's
hub_state.json, MapLive.release):
- in the lobby message (fields 5–6);
- in the vote message (fields 7–8);
- in
starting; - in the hub listing (
map_release_id/map_version, migration 0016).
A guest with another release, older or newer, gets the download screen as
an update: "ANOTHER VERSION OF THIS MAP — The host runs WIZARD 1.4.0; you
have 1.1.0", with UPDATE (or UPDATE AND JOIN in FIND GAMES). It installs the
host's exact release (--install-map <CODE> --release <id>), even one older
than the newest. A guest that won't update is treated like one without the
map: named on the host's first START, sent back on the second.
The swap happens in the running game.
- The engine holds a mounted
.ucasopen, so the launcher writes the new release beside it as<name>_2_P,_3_P, and so on.FPakPlatformFile::Mountgives a_<n>_Ppak 100·n more order than a plain_Pone, so the update wins even where a later Steam launch mounts both. The next launch from the launcher removes the patch files (paks_strays) and writes the release under its usual name. - The launcher also removes, or lists for unmounting, any other copy of the map in Paks: an earlier patch, or a load-order number the profile no longer uses. Two releases mounted together mix their packages.
- The game unmounts the old containers through
FCoreDelegates::OnUnmountPak(exe 0xD349248 → 0x4694CC0,mjolnir_unmount_paks). That drops each pak and its IoStore container from the package store and the IoDispatcher. The game then collects garbage, mounts the new release, and rescans. - Verified on one PC: Wizard 1.1.0 was played, then updated to 1.4.0 from
the frontend.
- Before the update, a texture only 1.4.0 has (
…_sunshare) didn't load; after it, it did. - The updated map then played with its baked lighting.
- Before the update, a texture only 1.4.0 has (
- Verified on two PCs: PC 2 downgraded live to 1.1.0, joined PC 1's 1.4.0
lobby, got the update prompt and updated.
- A 1.1.0-only texture no longer resolved there, and the 1.4.0 one did.
- Both played.
Not tested yet: FIND GAMES comparing releases before the join. The listing fields need the hub deploy and migration 0016. Until then a joiner compares once the host's lobby message arrives, which the two-PC test used.
Joining from a link
A website links a listed game as mjolnir://join/<lobby id> (the hub's
lobby id). The launcher registers the mjolnir scheme (its src/links.rs
also takes mjolnir://mod/<slug> and mjolnir://map/<CODE>, which only
open the launcher's pages, and mjolnir://update, the game's out-of-date
prompt, update_check.md). A join that has to start the
game runs the launcher's launch check first, as Launch does.
-
The launcher (
hub_join_lobby) checks multiplayer is installed: the four map code mods present and on, and the CE runtime pack installed and on. If not, it offers Install multiplayer instead. Otherwise it writesMJOLNIRLobby\native\pending_join.txt(a temporary file renamed over it) and starts the game if no game process is running:lobby=<lobby id> at=<unix seconds> -
MJOLNIRLobby reads the file from the main menu's poll (every 1.5 s), only once the player is signed in (a main menu has been up) and in the frontend. During a match the file waits. It deletes the file on reading, and drops a join older than ten minutes or one it can't read. It then opens FIND GAMES and, when the list arrives, chooses the game with that id and joins it as JOIN does, so DOWNLOAD AND JOIN, a full game and another version are handled as usual. A game that is not listed reads "That game has ended or is no longer listed."
Not tested yet: all of it in game. The launcher side is unit-tested.
What was still open on 2026-10-09
Update 2026-10-21: both items below are done; they were verified on two PCs on 2026-10-09 (eced8a14).
- A guest that can't get the map. One left in the fireteam holds
everyone's start. Two PCs showed the host waiting forever on Gephyrophobia
because the guest had declined it. So:
- The host's first START names who doesn't have the map. A second START sends them back to their own menu, and the post-game vote does the same once its wait is over.
- A guest told
starting <code>for a map it lacks leaves by itself. - In the lobby the leave is
MeteoritePlayerViewModel.LeaveFireteam.BlamCampaignFlowGameSubsystem.LeaveGame, which the kick used, only leaves a match. - Verified: the guest left before the countdown, and the host's match started alone.
- Joining a match under way on a map this PC lacks works. On two PCs, PC
2 used DOWNLOAD AND JOIN on PC 1's running Gephyrophobia game. Its held
join asked
where, gotmapindexback at once, moved the map from index 18 to 19, and joined: the host's game had 2 players. A match started private with the host alone used to play offline and could never be listed later. Since MJOLNIRLobby 0.24.0 a host stays online alone, and the match can be made public mid-match (multiplayer_servers.md).