home · subsystems · world map

World Map

The overworld traversal mode. Two overlay variants share a code window at 0x801C0000..0x801EFFFF: the normal walk view and a debug top-down camera. The main controller is FUN_801E76D4 (9320 bytes); the per-entity tick is FUN_801DA51C (260 bytes). Sources: overlay_world_map.bin (mc4/mc7) and overlay_world_map_top.bin (mc8) mednafen captures.

Overlay structure

Both variants load into the same address window. The top-view variant starts its first prologue ~0x1400 bytes earlier in the window to fit extra sprite-rendering code.

VariantFirst prologueLoaded when
Normal walk (overlay_world_map)0x801CFC40Standard world-map mode
Top-view debug (overlay_world_map_top)0x801CE850Debug toggle combo (see below)

Both variants share the core field VM (FUN_801DE840), the move-VM overlay extension (FUN_801D362C), and all rendering helpers. The view-mode toggle flag is at DAT_801F2B94 (outside the 192 KB extraction window; not in the binary dump).

World map controller — FUN_801E76D4

Entry: (ctx_ptr). Three top-level paths based on DAT_801F2B94:

  • Debug top-view toggle — fires when _DAT_8007B98C != 0 (debug flag) AND pad mask _DAT_8007B850 == 0x4A AND held mask _DAT_8007B874 == 0x40. On trigger: DAT_801F2B94 ^= 1, captures current actor camera position into _DAT_801F35A8/AA/AC, clears ctx[+0x54] and ctx[+0x50], calls FUN_80035C10.
  • Top-view camera controls (DAT_801F2B94 != 0) — D-pad adjusts scroll globals; L/R buttons adjust azimuth and zoom:
    • Left/Right → _DAT_80089120 ±= 8 (X scroll)
    • Up/Down → _DAT_80089118 ±= 8 (Z scroll)
    • Circle/Square → _DAT_8007B794 ±= 0x14 (azimuth)
    • R1/L1 → _DAT_8007B6F4 ±= 4 (zoom/height)
  • Normal-walk path (DAT_801F2B94 == 0) — standard per-frame world-map update: field VM tick, actor step, camera follow via the motion VM.

World map entity tick — FUN_801DA51C

Entry: (entity_ptr). A 5-state dispatcher on entity[+0x8A] (jump table at 0x801CEC28). Called once per world-map entity per frame by the entity pool tick loop.

  • State 0 (Idle) — when _DAT_80083808 == 0: calls FUN_800243F0 (BGM/asset resolver) to look up the scene associated with the entity's location; checks _DAT_8007BB38 pad buttons for entity interaction.
  • States 1–4 — Activating, Transitioning, and Terminal states for encounter and location-entry sequences.

Debug menu renderer — FUN_801EAD98

Entry: (ctx_ptr, x, y, scroll_idx, max_visible). Renders a vertically scrolling menu list for the world map developer menu. String table at 0x801CF344; at least 24 entries (bounds check local_40 > 0x17). Known entries: MAP_CHANGE, CARD_OPTION (both show as CLOSED when _DAT_8007B868 != 0), PLAYER_STATUS, CAMERA, ENCOUNT, OTHER_SETTINGS, BGM_CALL, DEBUG.

Called by FUN_801ECA08 when the debug panel is active (ctx[+0x54] mod-6 dispatch, cases 1 or 3).

Engine port

Two modules in the clean-room port cover this subsystem:

  • engine-vm::world_map — clean-room port of FUN_801DA51C: EntityState enum (Idle / Activating / Transitioning / Terminal), WorldMapEntityHost trait (callbacks for BGM resolution and pad input), step(host, entity) -> StepResult. 10 unit tests.
  • engine-core::world_map::WorldMapController — models the camera globals (scroll_x, scroll_z, azimuth, zoom) and the top_view debug toggle flag; exposes tick(pad_input) matching FUN_801E76D4's control logic. Attached to World as world_map_ctrl: Option<WorldMapController> and ticked when SceneMode::WorldMap is active.

The legaia-engine play-window --world-map flag activates WorldMap mode and shows camera state (scroll, azimuth, zoom) in the HUD overlay.

Full reference

The complete function-level reference with Ghidra provenance lives at docs/subsystems/world-map.md in the repo. Function dumps: ghidra/scripts/funcs/overlay_dialog_801e76d4.txt, overlay_dialog_801ead98.txt, and 801cfc40.txt.