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; when the shell lifetime ends this same bootstrap path tears the shell bundle down and returns to app_bootstrap_main.
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 gameplay or in-engine world stepping later escapes this bootstrap-owned shell loop entirely, or whether gameplay entry still rendezvous with the same outer coordinator before the shell bundle is destroyed.

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], global routing gates at 0x006d4034, and the separate detail-panel controller rooted at 0x006d0818.
Subsystem Handoffs: routes into graphics config, scenario-text export, overlay generation, multiplayer UI, shell detail windows such as EditorPanel.win and TrainDetail.win, and presentation-facing deferred work later drained by shell_service_frame_cycle.
Evidence: function-map shell rows around 0x00464410, 0x004d4500, 0x004ddbd0, and 0x0051f1d0..0x0051f460.
Open Questions: whether the shell command dispatcher is also used by hotkeys or only by UI callback tables; the current 0x006d0818 detail-panel path looks shell-only and does not yet explain gameplay world entry.

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: how simulation cadence rendezvous with the shell presentation cadence once gameplay takes over and whether gameplay stepping exits this shell-owned controller path entirely.

Map and Scenario Content Load

Roots: shell_map_file_entry_coordinator at 0x00445ac0, the first grounded world-entry branch world_entry_transition_and_runtime_bringup at 0x00443a50, shell_map_file_world_bundle_coordinator at 0x00445de0, reference-database setup via map_bundle_open_reference_databases at 0x00444dd0, and narrower loaders such as map_load_geographic_label_database and map_load_city_database.
Trigger/Cadence: shell tutorial launch, editor or detail-panel file actions, map-scenario open paths, and scenario-text export batch commands.
Key Dispatchers: shell_map_file_entry_coordinator, world_entry_transition_and_runtime_bringup, world_runtime_release_global_services, shell_map_file_world_bundle_coordinator, 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: shell-side file staging buffers at 0x0062bee0 and 0x0062bec4, shell and mode globals at 0x006cec74 and 0x006cec78, world object root 0x0062c120, map bundle state allocated through 0x00530c80, and geography tables rooted at 0x0062b2fc and 0x0062b268.
Subsystem Handoffs: the broad shell entry coordinator chooses between a full shell mode-transition and world bring-up path versus a sibling .smp world-state path. The heavier branch now appears to be the first true shell-to-gameplay handoff: it resets the prior world bundle, allocates the new 0x0062c120 world root from the staged filename, initializes multiple world-facing managers, and only then leaves later map content and runtime stepping to narrower helpers. The lower coordinator still fans into the live-world packaging branch at 0x00446240 or the reference-database bundle load at map_bundle_open_reference_databases, which in turn feeds shell preview panels scenario export tooling and later gameplay map state.
Evidence: function-map map/scenario rows, analysis-context exports for 0x00445ac0, 0x00445de0, 0x00443a50, 0x00434300, and 0x00444dd0, plus objdump string evidence for .gmp, .gmx, .gmc, .gms, .smp, and Quicksave.
Open Questions: the exact user-facing verb split between the .smp branch and the .gmp/.gmx/.gmc/.gms branch still needs tightening, but the remaining high-value question is no longer whether 0x00443a50 is world entry. It is where the long-lived simulation cadence takes over after this bring-up and whether that cadence still rendezvous with the shell-owned frame path or escapes into a separate gameplay loop.

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: the shell controller window-message ingress shell_controller_window_message_dispatch at 0x0054e3a0, the shell input-state object initialized at 0x006d4018 through shell_input_state_init 0x0054e710, world_entry_transition_and_runtime_bringup at 0x00443a50, the frame-owned cadence simulation_frame_accumulate_and_step_world at 0x00439140, and the lower step family rooted at simulation_advance_to_target_calendar_point 0x0040ab50 with periodic branches through simulation_service_periodic_boundary_work 0x0040a590.
Trigger/Cadence: shell-side input is event-driven by controller-window WM_* traffic while post-bring-up gameplay service becomes recurring once a world root exists at 0x0062c120; elapsed wall-clock time is then accumulated and converted into one or more simulation-step quanta.
Key Dispatchers: shell_controller_window_message_dispatch, shell_input_apply_window_key_transition, shell_input_snapshot_dispatch_state, simulation_frame_accumulate_and_step_world, simulation_advance_to_target_calendar_point, the smaller single-step helper at 0x00409e80, 0x0040a9c0, 0x0040a910, and simulation_service_periodic_boundary_work.
State Anchors: shell input object 0x006d4018, per-key state table starting at [input+0x100], packed shell input flags at [input+0xa8c], nested dispatch counter [input+0xa90], global shell controller 0x006d4024, active world root 0x0062c120, accumulated leftover simulation time at [this+0x4c80], shell and mode globals at 0x006cec74, 0x006cec78, and 0x006cec7c, world manager collections at 0x0062be10, 0x006ceb9c, 0x006cfcbc, 0x006cec20, and 0x0062bae0, plus the packed calendar-like tuple fields around [this+0x0d], [this+0x0f], [this+0x11], and [this+0x14].
Subsystem Handoffs: the controller window dispatcher now looks like the first grounded input ingress. It translates keyboard and mouse WM_* traffic into shell controller state and the separate input object at 0x006d4018; read-side cursor and shell consumers later snapshot that object through shell_input_snapshot_dispatch_state. After world entry the frame-owned cadence computes how much simulation time should elapse and repeatedly hands that budget into simulation_advance_to_target_calendar_point; the step helper then advances the world in coarse or fine increments, enters the periodic maintenance family when boundary conditions hit, notifies the live world root through 0x00450030, and returns to the frame owner for later shell-facing and world-facing follow-up work.
Evidence: function-map rows for shell_controller_window_message_dispatch, shell_drain_pending_window_messages, shell_input_state_init, shell_input_apply_window_key_transition, shell_input_snapshot_dispatch_state, world_entry_transition_and_runtime_bringup, simulation_frame_accumulate_and_step_world, simulation_advance_to_target_calendar_point, and simulation_service_periodic_boundary_work, plus analysis-context exports for the shell input cluster and the simulation cluster around 0x00439140, 0x0040ab50, and 0x0040a590.
Open Questions: whether gameplay continues to reuse this shell controller and input object path or hands off to a deeper world-mode input branch; the exact public semantics of the packed simulation tuple fields need tightening; and the save/load family still needs a cleaner user-facing split between autosave or package work and regular simulation stepping.

Next Mapping Passes

Clarify the user-facing split between the .smp branch and the .gmp/.gmx/.gmc/.gms branch under shell_map_file_entry_coordinator.
Identify the owner loop that repeatedly services multiplayer transport I/O and dispatch-store work.
Determine whether gameplay keeps using shell_controller_window_message_dispatch and the 0x006d4018 input object or hands off to a deeper world-mode input branch after world entry.
Ground the first gameplay save/load dispatcher and tie it back to the already-mapped .smp and live-world packaging branch.
Keep detailed pending-template or transport work scoped to the specific atlas edges that remain unresolved.

14 KiB Raw Blame History