rrt/docs/control-loop-atlas.md

# Control-Loop Atlas

This atlas is the high-level map for RT3 1.06. It is intentionally broader than the function map:
each section explains who owns a loop, where it starts, what dispatches it, which state blocks
anchor it, and where control is handed to neighboring subsystems.

## CRT and Process Startup

- Roots: `entry` at `0x005a313b`, CRT helpers in the `0x005a2d..0x005ad4..` range, and `app_bootstrap_main` at `0x00484440`.
- Trigger/Cadence: single process startup path before shell or engine services exist.
- Key Dispatchers: `startup_init_tls_state`, `startup_init_file_handle_table`, `startup_run_init_callback_table`, `__setenvp`, `startup_build_argv`, `___crtGetEnvironmentStringsA`, then `app_bootstrap_main`.
- State Anchors: CRT heap and file-handle tables; process environment and argv storage.
- Subsystem Handoffs: exits the generic CRT path at `app_bootstrap_main`, which becomes the first RT3-owned coordinator.
- Evidence: `artifacts/exports/rt3-1.06/startup-call-chain.md`, `artifacts/exports/rt3-1.06/function-map.csv`.
- Open Questions: exact ownership boundary between compiler CRT shims and the first game-owned bootstrap helper; whether any nontrivial startup callbacks seed game globals before `app_bootstrap_main`.

## Bootstrap and Shell Service Bring-Up

- Roots: `app_bootstrap_main` at `0x00484440`, `bootstrap_init_shell_window_services` at `0x004840e0`, and `shell_install_global_controller` at `0x0051ff90`.
- Trigger/Cadence: one-time bootstrap handoff immediately after CRT completion.
- Key Dispatchers: `app_bootstrap_main`, `bootstrap_init_shell_window_services`, `shell_install_global_controller`, `shell_service_pump_iteration`, graphics config load or default-init helpers, runtime capability probes, and early shell service initializers under the `0x004610..0x0053f0..` branch.
- State Anchors: global shell controller pointer `0x006d4024`, sibling display/runtime globals under `0x006d402c` and `0x006d4030`, and host capability flags gathered by `bootstrap_probe_system_profile`.
- Subsystem Handoffs: after the global shell controller has been installed the bootstrap path enters the repeating `shell_service_pump_iteration` loop, which services shell-state work and hands each iteration down into the controller frame path.
- Evidence: `startup-call-chain.md`, function-map rows for `app_bootstrap_main`, `bootstrap_init_shell_window_services`, `shell_install_global_controller`, `shell_service_pump_iteration`, `shell_load_graphics_config_or_init_defaults`, `shell_reset_display_runtime_defaults`, and related graphics setup helpers.
- Open Questions: whether `bootstrap_init_shell_window_services` remains the long-lived shell main loop for all shell modes or later hands control to another outer coordinator after certain transitions.

## Shell UI Command and Deferred Work Flow

- Roots: shell callback paths that converge on `shell_dispatch_ui_command` at `0x00464410`.
- Trigger/Cadence: event-driven UI command dispatch plus deferred-message queue flushing during shell activity.
- Key Dispatchers: `shell_dispatch_ui_command`, `shell_enqueue_deferred_work_message`, `shell_post_deferred_message_type5`, `shell_post_deferred_message_type6`, `shell_enqueue_deferred_message_type4`, `shell_enqueue_deferred_message_type1`.
- State Anchors: shell object at `0x0062be68`, queue roots around `[this+0x11369d]`, `[this+0x1136a1]`, and `[this+0x1136a5]`, plus global routing gates at `0x006d4034`.
- Subsystem Handoffs: routes into graphics config, scenario-text export, overlay generation, multiplayer UI, and presentation-facing deferred work later drained by `shell_service_frame_cycle`.
- Evidence: function-map shell rows around `0x00464410` and `0x0051f1d0..0x0051f460`.
- Open Questions: whether the shell command dispatcher is also used by hotkeys or only by UI callback tables.

## Presentation, Overlay, and Frame Timing

- Roots: the bootstrap-owned `shell_service_pump_iteration` at `0x00483f70`, the shell-state service pass `shell_state_service_active_mode_frame` at `0x00482160`, the installed global shell controller at `0x006d4024`, the pending frame-cycle owner `shell_service_frame_cycle` at `0x00520620`, and the frame-time history path under `shell_update_frame_time_history` at `0x0051fd70`.
- Trigger/Cadence: recurring bootstrap-owned shell service work once the active mode, controller window, and display runtime are live; special modal or content-building paths can also force immediate frame servicing inside that broader cadence.
- Key Dispatchers: `shell_service_pump_iteration`, `shell_state_service_active_mode_frame`, `shell_service_frame_cycle`, `shell_refresh_presentation_frame`, `shell_update_frame_time_history`, `shell_get_smoothed_frame_scalar`, `shell_set_gamma_ramp_scalar`, and overlay builders such as `shell_queue_single_world_anchor_overlay`, `shell_queue_world_anchor_overlay_list`, and `shell_queue_indexed_world_anchor_marker`.
- State Anchors: shell state at `0x006cec74`, active mode pointer `0x006cec78`, shell frame history ring at `0x006d403c`, display/runtime state inside the controller block near `[this+0x114282]` and `[this+0x11428a]`, presentation service pointer at `[this+0x0c]`, and the native controller window handle at `[this+0x00]`.
- Subsystem Handoffs: the bootstrap-owned pump runs shell-bundle polling and shell-state maintenance before the shell-state pass synchronizes active-mode helpers and modal-status work and dispatches the controller frame cycle, which then consumes world/object state for overlays and presentation refresh, uses the controller window handle for one-time `ShowWindow` and related UI interaction, and drains the deferred work queues at the end of the cycle.
- Evidence: function-map rows for `shell_service_pump_iteration`, `shell_state_service_active_mode_frame`, `shell_service_frame_cycle`, `shell_flush_deferred_work_queues`, frame history, gamma ramp, world-anchor overlay builders, and graphics runtime helpers.
- Open Questions: whether this bootstrap-owned shell pump also remains the steady-state owner for later shell modes and how simulation cadence rendezvous with the shell presentation cadence once gameplay takes over.

## Map and Scenario Content Load

- Roots: reference-database setup via `map_bundle_open_reference_databases` at `0x00444dd0`, followed by narrower loaders such as `map_load_geographic_label_database` and `map_load_city_database`.
- Trigger/Cadence: map or scenario open paths and scenario-text export commands.
- Key Dispatchers: `map_bundle_open_reference_databases`, `map_load_geographic_label_database`, `map_load_city_database`, `scenario_text_export_build_language_file`, `scenario_text_export_report_language_file`, `scenario_text_export_batch_process_maps`.
- State Anchors: map bundle state allocated through `0x00530c80`, geography tables rooted at `0x0062b2fc` and `0x0062b268`, shell-side map-selection context.
- Subsystem Handoffs: feeds shell preview panels, scenario export tooling, and later gameplay map state.
- Evidence: function-map map/scenario rows, analysis-context exports for geographic-label and city database strings.
- Open Questions: the main gameplay map-load entrypoint is still broader than the currently grounded reference-database loaders; scenario load versus scenario-text export remain only partially overlapped.

## Multiplayer Session and Transport Flow

- Roots: Multiplayer.win session-event callback table around `0x00468de0..0x004691d0`, plus the transport object and pending-template paths around `0x00597880..0x0059caf0`.
- Trigger/Cadence: event-driven session callbacks, registered-name updates, and repeated socket I/O service steps.
- Key Dispatchers: session-event wrappers for actions `1`, `2`, `4`, `7`, `8`; `multiplayer_transport_text_stream_service_io`; `multiplayer_transport_dispatch_pending_template_node`; `multiplayer_transport_service_pending_template_dispatch_store`.
- State Anchors: live session globals at `0x006d40d0`, status latch at `0x006cd974`, pending-template list at `[this+0x550]`, dispatch store at `[this+0x55c]`, text-stream buffers at `[this+0x108]` and `[this+0x114]`.
- Subsystem Handoffs: bridges shell/UI status presentation, transport text streams, session state changes, and pending-template completion callbacks.
- Evidence: `function-map.csv`, `pending-template-store-management.md`, `pending-template-store-functions.csv`.
- Open Questions: unresolved request-id semantics for `1`, `2`, `4`, and `7`; the exact owner loop that repeatedly services transport I/O; and how multiplayer preview data ties back into the shell flow.

## Input, Save/Load, and Simulation

- Roots: not yet cleanly named in the current ledger.
- Trigger/Cadence: expected recurring gameplay or shell-driven loops, but the current evidence is still indirect.
- Key Dispatchers: currently unresolved; nearest grounded hints are `bootstrap_capture_keyboard_state`, filesystem-related strings, and shell pathways that save graphics config rather than gameplay state.
- State Anchors: input DLL import `DINPUT8.dll`, save/load path strings under `.\Saved Games\`, and map/scenario globals already observed elsewhere.
- Subsystem Handoffs: likely connect shell/UI into gameplay state, but not yet strongly evidenced in committed exports.
- Evidence: `binary-summary.json`, `imported-dlls.txt`, `subsystem-inventory.md`, and broad strings in `interesting-strings.txt`.
- Open Questions: first real input pump, first gameplay save/load dispatcher, first simulation tick owner, and the exact boundary between shell frame work and gameplay world stepping.

## Next Mapping Passes

- Determine whether `bootstrap_init_shell_window_services` and `shell_service_pump_iteration` remain the long-lived shell main loop after early shell transitions or later hand off to another outer coordinator.
- Connect the map bundle open path to the broader map/scenario load coordinator instead of only the database leaves.
- Identify the owner loop that repeatedly services multiplayer transport I/O and dispatch-store work.
- Ground the first real input ingest path and the first gameplay save/load dispatcher.
- Keep detailed pending-template or transport work scoped to the specific atlas edges that remain unresolved.