Map world entry simulation and shell input flow

docs/control-loop-atlas.md

@@ -20,19 +20,19 @@ anchor it, and where control is handed to neighboring subsystems.
 - 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.
+- 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 `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.
+- 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]`, 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.
+- 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
 
@@ -42,17 +42,17 @@ anchor it, and where control is handed to neighboring subsystems.
 - 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.
+- 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: 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.
+- 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
 
@@ -66,18 +66,18 @@ anchor it, and where control is handed to neighboring subsystems.
 
 ## 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.
+- 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
 
-- 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.
+- 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.
-- Ground the first real input ingest path and the first gameplay save/load dispatcher.
+- 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.