rrt/docs/control-loop-atlas.md

82 lines
82 KiB
Markdown
Raw Normal View History

# 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
2026-04-02 23:24:19 -07:00
- 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.
2026-04-02 23:24:19 -07:00
- 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`.
2026-04-02 23:24:19 -07:00
- 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
2026-04-02 23:24:19 -07:00
- 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 through `fileopt.win`, 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 shared `fileopt.win` dialog rooted at `0x004dc670` now looks like the shell-side selector above the two broad file coordinators. Its message handler sets `0x006d07f8` for the load or restore side or `0x006d07ec` for the save or package side before the detail-panel transition manager routes into `shell_map_file_entry_coordinator` or `shell_map_file_world_bundle_coordinator`. The former unresolved third flag at `0x006d07f0` is now accounted for too: it escapes into the standalone `SettingsWindow.win` path through `shell_open_settings_window` rather than another map or save verb. The broad coordinators now hand their interactive work through the shared `filerqst.win` helper at `0x004dd010`, and that helper gives the extension split a firmer shape. The paired editor-map path is now grounded as `.gmp` through load mode `4` and save mode `3`. The remaining non-editor families are no longer anonymous either: `.gmc` is the campaign-scenario branch, backed both by the campaign-screen resignation prompt on `0x006cec7c+0xc5` and by the numbered `%s%02d.gmc` save helper at `0x00517c70`; `.gmx` is the sandbox branch, backed by the shell-side `The briefing is not available in sandbox games.` restriction on `0x006cec7c+0x82`; and the default `.gms` branch is therefore the standalone scenario family. When a live runtime world is already active the same helper bypasses those non-runtime extensions and forces the `.smp` runtime-state branch instead. The auxiliary save-side mode `11` is tighter now too: it still maps to `.gmt`, but instead of looking like another gameplay save family it conditionally diverts into the same `.gmt` preview-surface pipeline owned by the Multiplayer preview dataset object at `0x006cd8d8`, and only falls back to the normal reference-bundle path when that dataset object is absent.
- Evidence: function-map map/scenario rows, analysis-context exports for `0x00445ac0`, `0x00445de0`, `0x00443a50`, `0x00434300`, and `0x00444dd0`, plus objdump string and mode-table evidence for `.gmp`, `.gmx`, `.gmc`, `.gms`, `.gmt`, `.smp`, `Quicksave`, the `0x004dd010` mode table at `0x005f3d58`, the auxiliary-owner presence check at `0x00434050`, and the `.gmt` handoff through `0x00469d30`, together with localized string evidence from ids `3018` and `3898`.
- Open Questions: bit `0x1` on both broad coordinators now grounds the Quicksave name seed and the former third `fileopt.win` flag has been ruled out as a file-flow question because it just opens `SettingsWindow.win`. The old broad extension question is mostly resolved: `.gmp` is the editor-map pair, `.gms` is the standalone scenario family, `.gmc` is the campaign-scenario family, `.gmx` is the sandbox family, and `.gmt` is at least bounded as an auxiliary preview-surface branch rather than another gameplay save family. The higher-value global 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_window_init_globals` at `0x004efe80`, `multiplayer_window_service_loop` at `0x004f03f0`, the Multiplayer.win session-event callback table built by `multiplayer_register_session_event_callbacks` at `0x0046a900`, the active session-event transport object at `0x006cd970`, the Multiplayer preview dataset object at `0x006cd8d8`, and the lower pending-template and text-stream helpers around `0x00597880..0x0059caf0`.
- Trigger/Cadence: shell-owned Multiplayer.win frame service plus event-driven session callbacks and repeated transport pump steps.
- Key Dispatchers: session-event wrappers for actions `1`, `2`, `4`, `7`, `8`; `multiplayer_register_session_event_callbacks`; `multiplayer_dispatch_requested_action`; `multiplayer_reset_preview_dataset_and_request_action`; `multiplayer_preview_dataset_service_frame`; `multiplayer_load_selected_map_preview_surface`; `multiplayer_flush_session_event_transport`; `multiplayer_transport_service_frame`; `multiplayer_transport_service_worker_once`; `multiplayer_transport_service_route_callback_tables`; `multiplayer_transport_service_status_and_live_routes`; `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`, active session-event transport object at `0x006cd970`, status latch at `0x006cd974`, session-event mode latch at `0x006cd978`, retry counter at `0x006cd984`, preview dataset object at `0x006cd8d8`, preview-valid flag at `0x006ce9bc`, staged preview strings at `0x006ce670` and `[0x006cd8d8+0x8f48]`, Multiplayer.win backing block at `0x006d1270`, selector-view store root at `[transport+0xab4]`, selector-view generation counters at `[transport+0xab8]..[transport+0xac0]`, selector-view backing arrays around `[transport+0xad0]..[transport+0xae4]`, selector-view entry probe-request id at `[entry+0x50]`, live-state gate at `[entry+0x58]`, third-slot flag word at `[entry+0x64]`, probe-schedule tick at `[entry+0x68]`, last-success tick at `[entry+0x6c]`, pending-probe latch at `[entry+0x74]`, success generation at `[entry+0x78]`, consecutive-failure counter at `[entry+0x7c]`, rolling average at `[entry+0x80]`, recent sample window at `[entry+0x84..]`, bounded sample-count at `[entry+0x94]`, total-success count at `[entry+0x98]`, pending-template list at `[transport+0x550]`, dispatch store at `[worker+0x54c]`, and text-stream buffers rooted under `[worker+0x1c]`.
- Subsystem Handoffs: the Multiplayer.win initializer seeds the backing block at `0x006d1270`, later reset paths construct the separate preview dataset at `0x006cd8d8`, and the shell-owned active-mode frame services that dataset every frame through `multiplayer_preview_dataset_service_frame`. That preview side publishes roster and status controls through the Multiplayer window control paths, loads `.gmt` preview surfaces through `multiplayer_load_selected_map_preview_surface`, and is even reused by the map/save coordinators mode-`11` `.gmt` path when the dataset already exists. In parallel, `multiplayer_register_session_event_callbacks` allocates and registers the separate session-event transport object at `0x006cd970`. The shell-side bridge into that deeper transport cadence is now tighter: `multiplayer_window_service_loop` and neighboring reset or initializer branches call `multiplayer_flush_session_event_transport`, which forces one status flush and then drops into `multiplayer_transport_flush_and_maybe_shutdown`. That wrapper in turn runs `multiplayer_transport_service_frame`, the recurring pump that services one worker step through `multiplayer_transport_service_worker_once`, sweeps the transport-owned callback tables and field caches through `multiplayer_transport_service_route_callback_tables`, services both the auxiliary status route and the current live route through `multiplayer_transport_service_status_and_live_routes`, and then descends one layer farther into the shared GameSpy route helper `multiplayer_gamespy_route_service_frame` at `0x58d040`. The transport also owns a separate selector-view sidecar beneath that route cadence. `multiplayer_transport_ensure_selector_view_store` allocates the keyed selector-view store at `[transport+0xab4]`, `multiplayer_transport_find_selector_view_entry_by_name` resolves entries from that store, `multiplayer_transport_upsert_selector_name_entry` marks per-slot activity and flags inside each entry, and `multiplayer_transport_mark_selector_slot_views_dirty` plus `multiplayer_transport_reset_selector_view_entry_runtime_state` manage the dirty or refresh fields at `+0xa0`, `+0xa4`, and `+0xa8`. That selector-view maintenance path is now split more cleanly too. The recurring owner is `multiplayer_transport_service_selector_view_refresh_cycle`, which first runs the fast deferred-probe lane: `multiplayer_transport_collect_refreshable_selector_view_entries` walks the store through `multiplayer_transport_filter_insert_refreshable_selector_view_entry`, which now shows that `[entry+0x64]` is not a generic flag bucket but the third selector-slot flag word, parallel to `[entry+0x5c]` and `[entry+0x60]`. In that collector, the `g` and `a` mode-letter bits produced by `multiplayer_transport_parse_selector_mode_letters` become mask `0x0c` in the slot-local flag words, and any third-slot entry carrying those bits at `[entry+0x64]` is excluded from the refreshable set. Eligible entries then pass slot-aware retry timing on `[entry+0x68]`, `[entry+0x6c]`, `[entry+0x78]`, and `[entry+0x7c]`, after which the service loop schedules refresh probes through `multiplayer_transport_schedule_selector_view_entry_refresh_probe`. That fast lane is narrower now too: the entry-side match key `[entry+0x50]` is no longer just an opaque request field. The profile-key callback lanes feed `multiplayer_transport_parse_selector_view_probe_marker`, which decodes one local `X%sX|%d` marker into a request id plus companion value, and `multiplayer_transport_arm_selector_view_probe_tracking` stores those into `[entry+0x50]` and `[entry+0x54]` before arming the live probe gate at `[entry+0x58]`. The current-selector callback root at `0x59f8b0` is now bounded as well: it resolves and upserts the active selector name, optionally reuses a cached `username` marker to arm probe tracking immediately, then submits the same profile-key bundle with selector context and forwards that selector through callback slot `17`, with the status-route side able to force route-mode transitions `2 -> 3 -> 4` afterward. One layer lower,
- Evidence: `function-map.csv`, `pending-template-store-management.md`, `pending-template-store-functions.csv`, plus objdump caller traces showing `multiplayer_window_service_loop` reaching `multiplayer_flush_session_event_transport` and the transport pump chain `multiplayer_flush_session_event_transport -> multiplayer_transport_flush_and_maybe_shutdown -> multiplayer_transport_service_frame -> multiplayer_transport_service_worker_once -> multiplayer_transport_drain_request_text_queue`.
- Open Questions: unresolved request-id semantics for `1`, `2`, `4`, and `7`; whether any non-mode-path helper outside the currently grounded release-and-rebuild flow ever patches `[route+0xa4]` and `[route+0xd4]` for the transport-owned status/live routes, or whether those packet families are simply unused in this stack; and how far the Multiplayer preview-dataset machinery is reused outside `Multiplayer.win` beyond the currently grounded `.gmt` save-mode hook.
## 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`, the saved-world restore path `world_load_saved_runtime_state_bundle` at `0x00446d40`, the live-world save path `world_runtime_serialize_smp_bundle` at `0x00446240`, `world_entry_transition_and_runtime_bringup` at `0x00443a50`, the frame-owned cadence `simulation_frame_accumulate_and_step_world` at `0x00439140`, the recurring `GameMessage.win` service branch through `game_message_window_service_if_present` `0x004e0720`, the world-facing `GameUppermost.win` overlay branch ensured by `shell_ensure_game_uppermost_window` `0x004e0e40` and serviced through `game_uppermost_window_service_world_hotspot_band` `0x004e0780`, 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 save or load work is triggered either directly from shell commands or through the `fileopt.win` branch flags into the `.smp` runtime-state family; post-bring-up world service becomes recurring once a world root exists at `0x0062c120`, but the current grounded top-level cadence still remains the shell-owned `shell_service_pump_iteration` path, which calls `simulation_frame_accumulate_and_step_world` directly and lets it accumulate elapsed wall-clock time into one or more simulation-step quanta. A second ingress is now bounded too: `simulation_run_chunked_fast_forward_burst` at `0x00437b20` repeatedly calls the same lower stepper `simulation_advance_to_target_calendar_point`, but current grounded callers put that helper inside the larger post-load generation pipeline `world_run_post_load_generation_pipeline` at `0x004384d0` under the `Seeding Economy...` phase rather than under the ordinary player-facing speed buttons. That setup pipeline is now clearer at the progress-banner level too: localized id `318` `Computing Transportation and Pricing...` stays visible while the pipeline runs `world_compute_transport_and_pricing_grid` `0x0044fb70`, the early collection-owned staging pass `world_setup_building_collection_phase` `0x0041ea50`, and the conditional region pair `world_region_collection_seed_default_regions` `0x00421b60` plus `world_region_border_overlay_rebuild` `0x004882e0`; only then does the code post id `319` `Setting up Players and Companies...`. That `319` lane is no longer just a shell-state placeholder: its primary grounded work is still the chairman-profile pair `world_seed_default_chairman_profile_slots` `0x004377a0` plus `world_build_chairman_profile_slot_records` `0x00437220`, which seed the 16 selector bytes at `[0x006cec7c+0x87]`, materialize the per-slot chairman records from the scenario selectors, campaign override flag `[0x006cec7c+0xc5]`, and the static persona table at `0x005f2d28`, and then publish the selected chairman-profile and linked company summary pair through `[state+0x25]` and `[state+0x21]`. The local slot-record shape is tighter too because the shell editor panel around `0x004cc2d0` now surfaces it directly: `[slot+0x00]` is the staged chairman profile id, `[slot+0x01]` is the Optional-versus-Mandatory byte with nonzero=`Optional` and zero=`Mandatory`, `[slot+0x02]` combines with the separate per-slot gate at `[world+0x0bc3+slot*9]` to surface `Human`, `Computer`, and `Human or Computer`, `[slot+0x03]` is the special occupied-seat byte, and `[slot+0x04]` is the numeric tuning field. Both the selector seeder and the record materializer treat either `[slot+0x02]` or `[slot+0x03]` as enough to keep a slot live, but current grounded writes only seed `[slot+0x03]` on slot zero and later move it solely by whole-record compaction. That makes `[slot+0x03]` the strongest current anchor for the distinguished primary-human-seat flag rather than a generic role byte. The summary fields are tighter too: current direct accessors now show `[state+0x25]` as the selected chairman profile id in `0x006ceb9c`, while `[state+0x21]` is the linked owning company id copied from `[profile+0x1dd]` through `scenario_state_set_selected_chairman_profile` `0x00434890`. The editor-side scenario setup surface beside that chairman panel is clearer now too. `map_editor_scenario_metadata_panel_refresh_controls` `0x004ca790` republishes the scenario description from `[0x006cec78+0x672e]`, the start-year trio `[+0x66ca]`, `[+0x66d2]`, and `[+0x66ce]`, and the paired boolean toggles `[+0x66de]` plus inverse `[+0x66f3]` across control band `0x5b69..0x5b74`, while `map_editor_scenario_metadata_panel_refresh_briefing_mode` `0x004ca670` now bounds the single-player versus multiplayer briefing switch by flipping selector `0x621f50`, publishing localized headings `1491` and `3586`, and refreshing the two briefing texts from `[state+0x4f30]` and `[+0x5ae9]`. The companion dispatcher `map_editor_scenario_metadata_panel_handle_message` `0x004c
- Key Dispatchers: `shell_controller_window_message_dispatch`, `shell_input_apply_window_key_transition`, `shell_input_snapshot_dispatch_state`, `shell_input_cursor_inside_active_view`, `world_load_saved_runtime_state_bundle`, `world_runtime_serialize_smp_bundle`, `simulation_frame_accumulate_and_step_world`, `game_message_window_service_if_present`, `game_message_window_service_frame`, `game_uppermost_window_handle_message`, `game_uppermost_window_service_world_hotspot_band`, `game_uppermost_window_refresh_controls`, `world_view_service_keyboard_turn_pan_and_zoom_bindings`, `world_view_step_heading_quadrant`, `world_view_step_zoom_bucket`, `world_seed_default_chairman_profile_slots`, `world_build_chairman_profile_slot_records`, `world_conditionally_seed_named_starting_railroad_companies`, `scenario_state_set_selected_chairman_profile`, `scenario_state_get_selected_chairman_profile_record`, `scenario_state_get_selected_chairman_company_record`, `shell_company_list_window_construct`, `shell_company_list_window_refresh_rows`, `shell_company_list_window_handle_message`, `start_new_company_dialog_open`, `start_new_company_dialog_commit_create_company`, `start_new_company_request_create_company`, `shell_station_detail_window_construct`, `shell_station_list_window_construct`, `shell_station_list_window_handle_message`, `shell_station_pick_window_construct`, `shell_station_pick_window_populate_station_rows`, `map_editor_chairman_slot_panel_construct`, `map_editor_chairman_slot_panel_handle_message`, `map_editor_chairman_slot_panel_refresh_selected_slot`, `map_editor_chairman_slot_panel_cycle_selected_slot_profile`, `map_editor_available_chairman_panel_construct`, `map_editor_available_chairman_panel_handle_message`, `map_editor_scenario_metadata_panel_refresh_briefing_mode`, `map_editor_scenario_metadata_panel_refresh_controls`, `map_editor_scenario_metadata_panel_handle_message`, `map_editor_scenario_special_conditions_panel_construct`, `map_editor_scenario_special_conditions_panel_handle_message`, `map_editor_economic_cost_slider_panel_construct`, `map_editor_economic_cost_slider_dispatch`, `station_place_world_surface_sync_and_dispatch`, `station_place_window_handle_message`, `track_lay_window_refresh_controls`, `track_lay_window_service_frame`, `track_lay_window_handle_message`, `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]` now grounded as Right Shift `0x1`, Left Shift `0x2`, Control `0x4`, and Alt `0x20`, nested dispatch counter `[input+0xa90]`, global shell controller `0x006d4024`, active world root `0x0062c120`, `GameMessage.win` object `0x006d081c`, `GameUppermost.win` overlay object `0x006d0820`, `StationPlace.win` tool object `0x006d1720`, `TrackLay.win` tool object `0x006d1a8c`, accumulated leftover simulation time at `[this+0x4c80]`, shell and mode globals at `0x006cec74`, `0x006cec78`, and `0x006cec7c`, world manager collections at `0x0062be10`, `0x006ceb9c`, `0x006cfcbc`, `0x006cec20`, `0x0062bae0`, and `0x006acd34`, 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 camera helpers later snapshot that object through `shell_input_snapshot_dispatch_state` and gate world-relative interaction through `shell_input_cursor_inside_active_view`. Current grounded consumers around `0x00478cb0`, `0x004e0780`, `0x0053f450`, and `0x0053fe90` still sit on the shell controller path and consult `0x006d4024` or the world owner at `0x0062be68`, so there is still no evidence for a distinct gameplay-only input object after world entry. Instead, the first deeper world-mode interaction branch now looks like a shared world-view coordinator layered on top of the same shell-fed input state. Shell_transition_mode ensures the `GameUppermost.win` object at `0x006d0820`; its message dispatcher `game_uppermost_window_handle_message` owns the narrow action band `0x7918` through `0x7921`; and the recurring service helper `game_uppermost_window_service_world_hotspot_band` rate-limits those hotspot actions, rechecks `shell_input_cursor_inside_active_view`, and then pans the live world view through `world_view_pan_relative_offset_in_camera_plane` `0x0043d130`. The same lower setter family is also reached from the cursor-drag path through `world_view_apply_screen_delta_to_focus_position` `0x0043d0c0`. Above both of those sits the larger recurring service `world_view_service_shell_input_pan_and_hover` `0x0043db00`, which now has one grounded keyboard branch beneath it: `world_view_service_keyboard_turn_pan_and_zoom_bindings` `0x0043d740`. That helper resolves four binding-pair families from the shell input table via `0x0054e7d0`, and the localized labels are now grounded from `Data/Language/RT3.lng`: `Camera Forward` and `Camera Backward` feed the first signed pan channel, `Camera Left` and `Camera Right` feed the second signed pan channel, `Camera Zoom In` and `Camera Zoom Out` feed the signed zoom-step channel that `0x0043db00` smooths into `world_view_step_zoom_bucket` `0x0043cc30`, and `Camera Rotate Left` plus `Camera Rotate Right` feed the continuous heading-turn branch through `0x0043c810`. The setup side is now better bounded too: `world_view_seed_keyboard_binding_slot_pairs` at `0x00439e40` seeds the eight slot pairs at `[this+0x0a6]` through `[this+0x0e2]` from the global action-binding registry through `0x0045f370` using the distinct registry keys `0x0043d2a0` through `0x0043d310`, and the registration block at `0x00460769` through `0x004608e7` shows those roots are defaulted to the expected Up Down Left and Right virtual keys before runtime polling begins. Beneath that camera stack, the enclosing frame path now has one grounded non-view sidecar: after `0x0043db00` it reads the active controller-view object pointer at `[0x006d4024+0x18]+0x366e`, compares it against the latched target at `[frame_owner+0x66a2]`, fires exit and enter-style vtable callbacks on pointer changes through slots `+0x64` and `+0x60`, and only latches the new object when the object passes its own slot `+0x1c` availability test and shell detail control id `0x07d6` on `0x006d0818` has flag bit `0x4`. That `0x07d6` gate is now more bounded than before: the dedicated `TrackLay.win` tool family rooted at `0x006d1a8c` special-cases the same control id in both `track_lay_window_service_frame` and `track_lay_window_handle_message`, uses world hit tests through `0x00448ac0` to arm and release a drag latch on that surface, and routes the resulting command work through the shared track-lay mode state at `0x00622b0c`. The surrounding `track_lay_window_refresh_controls` pass now shows that this is not just one isolated drag handler: the same tool family owns three mutually exclusive primary mode buttons at `0x985e` `0x985f` and `0x9860`, and current primary evidence now bounds those values as `Lay single track.` `0x1`, `Lay double track.` `0x4`, and `Bulldoze` `0x40` from the localized strings 2054 2055 and
- 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`, `shell_input_cursor_inside_active_view`, `world_load_saved_runtime_state_bundle`, `world_runtime_serialize_smp_bundle`, `world_entry_transition_and_runtime_bringup`, `simulation_frame_accumulate_and_step_world`, `game_message_window_service_if_present`, `game_message_window_service_frame`, `shell_ensure_game_uppermost_window`, `game_uppermost_window_construct`, `game_uppermost_window_handle_message`, `game_uppermost_window_service_world_hotspot_band`, `world_view_set_focus_position_xyz`, `world_view_apply_screen_delta_to_focus_position`, `world_view_pan_relative_offset_in_camera_plane`, `world_view_seed_keyboard_binding_slot_pairs`, `world_view_service_keyboard_turn_pan_and_zoom_bindings`, `world_view_step_heading_quadrant`, `world_view_step_zoom_bucket`, `world_view_should_drive_primary_pan_channel`, `world_view_should_drive_secondary_pan_channel`, `world_view_service_shell_input_pan_and_hover`, `world_seed_default_chairman_profile_slots`, `world_build_chairman_profile_slot_records`, `world_conditionally_seed_named_starting_railroad_companies`, `profile_collection_count_active_chairman_records`, `profile_collection_get_nth_active_chairman_record`, `scenario_state_set_selected_chairman_profile`, `scenario_state_get_selected_chairman_profile_record`, `scenario_state_get_selected_chairman_company_record`, `start_new_company_dialog_open`, `start_new_company_dialog_commit_create_company`, `start_new_company_request_create_company`, `shell_company_list_format_company_or_start_row`, `shell_company_list_activate_or_shift_center_company`, `shell_company_list_window_refresh_rows`, `shell_company_list_window_handle_message`, `shell_company_list_window_construct`, `shell_company_detail_window_refresh_controls`, `shell_company_detail_window_construct`, `shell_company_detail_window_handle_message`, `shell_station_detail_window_construct`, `shell_station_list_window_construct`, `shell_station_list_window_handle_message`, `shell_station_pick_window_construct`, `shell_station_pick_window_populate_station_rows`, `map_editor_chairman_slot_panel_construct`, `map_editor_chairman_slot_panel_refresh_slot_list`, `map_editor_chairman_slot_panel_refresh_selected_slot`, `map_editor_chairman_slot_panel_refresh_slot_counters`, `map_editor_chairman_slot_panel_cycle_selected_slot_profile`, `map_editor_chairman_slot_panel_handle_message`, `map_editor_available_chairman_panel_construct`, `map_editor_available_chairman_panel_handle_message`, `map_editor_scenario_metadata_panel_refresh_briefing_mode`, `map_editor_scenario_metadata_panel_refresh_controls`, `map_editor_scenario_metadata_panel_handle_message`, `map_editor_scenario_special_conditions_panel_construct`, `map_editor_scenario_special_conditions_panel_handle_message`, `map_editor_economic_cost_slider_panel_construct`, `map_editor_economic_cost_slider_dispatch`, `station_place_refresh_category_controls`, `station_place_format_selected_site_summary`, `station_place_format_preview_panel`, `station_place_select_category_and_refresh`, `station_place_world_surface_sync_and_dispatch`, `station_place_window_handle_message`, `station_place_window_construct`, `station_place_window_service_frame`, `track_lay_window_refresh_controls`, `track_lay_window_construct`, `track_lay_window_service_frame`, `track_lay_window_handle_message`, and `simulation_service_periodic_boundary_work`, plus the shell-input disassembly around `0x0054f290`, the world-view setup and service branches around `0x00439e40`, `0x0043d740`, `0x0043db00`, `0x0043cb00`, and `0x0043cc30`, the `319` setup-side branches around `0x004377a0`, `0x00437220`, `0x00477820`, `0x00477860`, `0x0047d440`, `0x004c6c30`, `0x004c6f30`, `0x0047d080`, `0x0047d120`, `0x0047d320`, `0x004c2ca0`, `0x004c5540`, `0x004c56a0`, `0x005068c0`, `0x005071e0`, `0x005074c0`, and `0x005076c0`, the direct summary-field helpers around `0x00434870` `0x0043
- Open Questions: no separate outer gameplay loop is grounded above `simulation_frame_accumulate_and_step_world` yet and no deeper gameplay-only input object is grounded either. The new setup-pipeline evidence narrows that question in one direction: the currently grounded chunked burst path at `0x00437b20` now looks subordinate to `world_run_post_load_generation_pipeline` rather than to the ordinary speed controls, and even there it still reuses the same lower stepper and pumps shell work between chunks instead of revealing a detached gameplay loop owner. The player-facing speed-control family is now cleaner too: `world_set_game_speed_mode` owns the bounded `Paused` through `Very Fast` ladder plus the hidden `Ultra Fast 6..9` extension, `world_toggle_pause_or_restore_game_speed` uses `[this+0x1d]` as the resume slot, and the multiplayer host restriction now looks attached to that same setter family rather than to the setup-side burst helper. The first deeper world-mode interaction branch is now better bounded: `GameUppermost.win` hotspots, cursor drag, held Shift state, discrete shell view-step commands, direct keyboard turn/pan/zoom bindings, the `TrackLay.win` and `StationPlace.win` world-command surfaces, and a frame-owned hover or focus-target transition branch all feed the same shell-controller-backed path. The remaining uncertainty has moved farther from basic ownership: the hover-target branch clearly exists, and `0x07d6` now looks like the shared main-world interaction surface rather than a generic detail button for one tool family only. The next unresolved layer is narrower and more semantic: the setup side now has one grounded owner, `world_run_post_load_generation_pipeline`, and its building-side branch is no longer just one opaque block. We now have a region family, a region-border overlay rebuild, a region-owned structure-demand and placement dispatcher, and a deeper per-region worker that computes category demand, subtracts existing coverage, and tries candidate placements. The category map is tighter too: category `0` falls back to `House`, category `2` is the year-gated weighted region-profile family that also feeds the localized `Industry Weightings` stats panel, and category `3` now reaches a separate pool-driven picker whose fallback label is `Commercial` but whose aligned player-facing stats bucket is `City Support`. The remaining setup-side uncertainty has therefore narrowed again: the region seed and border-overlay pair clearly complete before the `Setting up Players and Companies...` banner is posted; `[0x006cec74+0x174]` now looks like the direct building-population gate; `[0x006cec74+0x178]` now looks like the direct seeding-burst gate; and `[0x006cec74+0x68]` now aligns with editor-map mode because the same flag forces the `.gmp` family in the shell file coordinators while suppressing the later building and seeding branches and diverting the deeper region worker into alternate logic. The `319` lane itself is no longer the open structural gap; it now clearly owns chairman-profile slot seeding, profile-record materialization, a shell editor surface over the same local record family, and a separate live-company presentation path through the company-list window. The remaining gaps on this lane are therefore narrower than before: the local slot records are rooted at `[world+0x69d8]`, `[slot+0x01]` polarity and the external role gate at `[world+0x0bc3+slot*9]` are now grounded, and `[slot+0x03]` now looks like the distinguished primary-human-seat marker because current grounded writes seed it only on slot zero and later logic moves it solely by whole-record compaction. The open question is no longer whether the seeded trio lands in the visible shell company roster; current evidence says it does, and ordinary `Start New Company` now looks like a fresh-company allocator through `start_new_company_dialog_commit_create_company` and `start_new_company_request_create_company`, not like the path that claims one of the seeded named railroads. The immediate post-roster station branch is now clearly separate:
- Editor breadth: the broader map-editor page owner is now bounded through `map_editor_panel_select_active_section` `0x004ce070` and `map_editor_panel_dispatch_active_section_message` `0x004cf700`, which switch among the grounded setup pages, `Cities/Regions`, `Territories`, the `Players` and `Player Pool` setup slices, the now-grounded `Building Density` page, the locomotives-available and industry-availability pages, the economic and special-condition pages, the `Port/Warehouse Cargos` page, and the later report pages. The mid-editor ownership is materially clearer now too: the chairman-slot editor is the `Players` page, the available-chairman editor is the `Player Pool` page, and the former unnamed dual tri-state page now lines up with localized page text `997` `Building Density` plus help text `1017` and the direct field captions `1642` `Starting Building Density Level:` and `1644` `Building Density Growth:`. Both controls are now bounded as stored ordinal bytes `0/1/2` rather than loose labels: the first three-choice control is the map-wide starting-density selector, with its default middle state `1` matching the documented `100%` baseline from `1643`; the second is the paired overall growth selector whose effects later appear in the city-growth side of the simulation. `map_editor_city_region_panel_construct` and `map_editor_city_region_panel_handle_message` own the city-or-region editing lane with rename and copy-industry-data flows; `map_editor_territory_panel_construct` and `map_editor_territory_panel_handle_message` own the territory rename and border-remap lane; `map_editor_locomotive_availability_panel_construct` plus `map_editor_locomotive_availability_panel_handle_message` now bound the locomotive policy page over `0x006ada84`; `map_editor_industry_availability_panel_construct` plus `map_editor_industry_availability_panel_handle_message` do the same for the industry candidate pool at `0x0062b268`; and `map_editor_port_warehouse_cargo_panel_construct` plus `map_editor_port_warehouse_cargo_panel_handle_message` now ground the recipe-book page that edits port or warehouse cargo policies through twelve per-book state blocks at `[0x006cec78+0x0fe7+index*0x4e1]`. Each book now has a shared maximum annual production float at `book+0x3ed` and five fixed cargo-line entries starting at `book+0x3f1` with stride `0x30`; each line is bounded as a mode dword, annual amount, a supplied-cargo token at `+0x08`, and a demanded-cargo token at `+0x1c`. The constructor and handler now make those fields materially tighter too: the row pair shown in `Supply Only` and `Production Demand->Supply` is the `+0x08` supplied-cargo selector, the row pair shown in `Demand Only` and `Production Demand->Supply` is the `+0x1c` demanded-cargo selector, and the single amount field at `+0x04` is labeled `Annual Demand:` only in mode `1` but `Annual Supply:` in modes `2/3`. The stronger new runtime-side result is now a full chain rather than only the importer: `scenario_state_rebuild_port_warehouse_cargo_recipe_runtime_tables` first imports those same five lines into one repeated array of identical `0xbc`-byte runtime descriptors with no row-index special casing, and the candidate-side rebuild pass at `structure_candidate_collection_rebuild_runtime_records_from_scenario_state` `0x00412d70` then projects those descriptors into the live structure collection at `0x0062ba8c` before `structure_candidate_rebuild_cargo_membership_and_scaled_rate_tables` `0x00411ee0` rebuilds the per-cargo runtime summary tables. The player-facing line modes remain `Disabled`, `Demand Only`, `Supply Only`, and `Production Demand->Supply`, and the fourth mode is tighter now too: current wording around `1674`, `1675`, and `504` plus the downstream scaling path says it is the production-line mode governed by the shared annual production cap, where the entered annual amount stays on the supply side while the demanded side becomes the normalized input branch. The candidate-side accumulator pass reinforces that split by applying the shared production cap only to the supply-ha
## Next Mapping Passes
- Resolve the owner-side callback roles behind the validated GameSpy packet branches, especially `[route+0x9c]`, `[route+0xa0]`, `[route+0xa4]`, and `[route+0xd4]`.
- Determine whether any later world-mode branch beneath the frame owner bypasses the shell controller input path for non-cursor gameplay input, since the current grounded overlay and cursor helpers still reuse `0x006d4018`.
- Keep detailed pending-template or transport work scoped to the specific atlas edges that remain unresolved.