83 lines
8.4 KiB
Markdown
83 lines
8.4 KiB
Markdown
# 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` and `bootstrap_init_shell_window_services` at `0x004840e0`.
|
|
- Trigger/Cadence: one-time bootstrap handoff immediately after CRT completion.
|
|
- Key Dispatchers: `app_bootstrap_main`, `bootstrap_init_shell_window_services`, graphics config load or default-init helpers, runtime capability probes, and early shell service initializers under the `0x004610..0x0053f0..` branch.
|
|
- State Anchors: shell service bundle rooted at `0x006d4024`, display/runtime globals under `0x006d4024` and `0x006d4030`, host capability flags gathered by `bootstrap_probe_system_profile`.
|
|
- Subsystem Handoffs: hands control into shell/UI configuration, presentation defaults, and later per-frame shell work.
|
|
- Evidence: `startup-call-chain.md`, function-map rows for `app_bootstrap_main`, `bootstrap_init_shell_window_services`, `shell_load_graphics_config_or_init_defaults`, `shell_reset_display_runtime_defaults`, and related graphics setup helpers.
|
|
- Open Questions: where the first persistent main-loop owner object becomes stable; whether `0x0046c230` or one of the unnamed bootstrap children is the shell's first long-lived coordinator.
|
|
|
|
## 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.
|
|
- Evidence: function-map shell rows around `0x00464410` and `0x0051f1d0..0x0051f460`.
|
|
- Open Questions: where the deferred queues are drained in the wider frame loop; whether the shell command dispatcher is also used by hotkeys or only by UI callback tables.
|
|
|
|
## Presentation, Overlay, and Frame Timing
|
|
|
|
- Roots: shell display runtime setup and the frame-time history path under `shell_update_frame_time_history` at `0x0051fd70`.
|
|
- Trigger/Cadence: recurring shell or presentation update loop once the window and display runtime are live.
|
|
- Key Dispatchers: `shell_update_frame_time_history`, `shell_set_gamma_ramp_scalar`, 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 frame history ring at `0x006d403c`, display/runtime state inside the shell block near `[this+0x114282]` and `[this+0x11428a]`, presentation service pointer at `[this+0x0c]`.
|
|
- Subsystem Handoffs: consumes world/object state for overlays and pushes deferred presentation messages back through shell queues.
|
|
- Evidence: function-map rows for shell frame history, gamma ramp, world-anchor overlay builders, and graphics runtime helpers.
|
|
- Open Questions: the exact outer frame pump is still unnamed; simulation cadence and shell presentation cadence may be separate loops that only rendezvous through shared shell state.
|
|
|
|
## 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
|
|
|
|
- Name the first stable owner of the outer shell or presentation loop above the existing frame-history helpers.
|
|
- 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.
|