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.

10 KiB Raw Blame History