rrt/docs

RT3 Reverse-Engineering Handbook

This handbook is the project bootstrap for reverse-engineering and rewriting Railroad Tycoon 3. It is written for future us first: enough structure to resume work quickly, without pretending the project is already mature.

Canonical Target

• Canonical executable: rt3_wineprefix/drive_c/rt3/RT3.exe (patch 1.06)
• Reference executable: rt3_wineprefix/drive_c/rt3_105/RT3.exe (patch 1.05)
• Canonical SHA-256: 01b0d2496cddefd80e7e8678930e00b13eb8607dd4960096f527564f02af36d4
• Reference SHA-256: 9e96b0695cb722a700f99c8dce498d34da7235e562b1e275bcc1764f8c9b7eb1

Documents

• setup-workstation.md: toolchain baseline and local environment setup.
• re-workflow.md: how to analyze the binary, record findings, and export reusable artifacts.
• function-map.md: canonical schema and conventions for function-by-function mapping.
• control-loop-atlas.md: compatibility index for the split atlas, preserving legacy anchors.
• control-loop-atlas/: canonical section files for the atlas narrative.
• runtime-rehost-plan.md: bottom-up runtime replacement plan and milestone breakdown.

Repo Conventions

• docs/: stable project guidance and durable design notes.
• tools/py/: committed Python helpers for analysis and validation.
• artifacts/exports/: committed derived outputs that can be regenerated.
• Local-only state stays untracked: .venv/, Ghidra projects, Rizin databases, crash dumps, and other bulky/generated working files.

Current Baseline

The current technical milestone is a repeatable loop-mapping workflow for the 1.06 executable. Before injection work or deep file-format work, we capture:

• executable hashes and PE metadata
• section layout, imports, and notable strings
• a starter subsystem inventory plus a control-loop atlas
• focused address and string context exports for branch-deepening passes
• a reusable CLI RE kit for branch dossiers where the atlas needs deeper grounding
• a stable curated function ledger in artifacts/exports/rt3-1.06/function-map.csv

Current coverage is broad enough to support future sessions without rediscovery, especially in:

• CRT startup and bootstrap handoff
• shell frame, layout, presentation, deferred-message, and frontend overlay flow
• Multiplayer.win UI, chat, session-event, and transport ownership
• map/scenario load and text-export paths
• shared support layers such as intrusive queues, vectors, hashed stores, and tracked heaps

README maintenance rule:

• Keep this section at subsystem level only.
• Do not mirror per-pass function additions here.
• Detailed mapping progress belongs in artifacts/exports/rt3-1.06/function-map.csv and the derived branch artifacts under artifacts/exports/rt3-1.06/.

Current local tool status:

• Ghidra is installed at ~/software/ghidra
• ~/software/ghidra/ghidraRun launches successfully in an interactive shell
• Rizin is installed and available on PATH
• winedbg works with rt3_wineprefix
• RT3 launches under /opt/wine-stable/bin/wine when started from rt3_wineprefix/drive_c/rt3

Next Focus

The atlas milestone is broad enough that the next implementation focus shifts downward into runtime rehosting. The highest-value next passes are:

• preserve the atlas and function map as the source of subsystem boundaries while avoiding further shell-first implementation bets
• stand up a bottom-up runtime core that can load state, execute deterministic world work, and dump normalized diffs without depending on the shell controller or presentation path
• use rrt-hook primarily as an optional capture tool for fixtures and state probes, not as the first execution environment
• choose early rewrite targets from the lower simulation, event-service, and persistence boundaries before attempting shell, input, or presentation replacement
• write milestone-scoped implementation notes in docs/runtime-rehost-plan.md before expanding the workspace crates

Regenerate the initial exports with:

python3 tools/py/collect_pe_artifacts.py \
  rt3_wineprefix/drive_c/rt3/RT3.exe \
  artifacts/exports/rt3-1.06

Regenerate the startup-focused Ghidra exports with:

python3 tools/py/export_startup_map.py \
  rt3_wineprefix/drive_c/rt3/RT3.exe \
  artifacts/exports/rt3-1.06

That default export now walks two roots:

• entry:0x005a313b
• bootstrap:0x00484440

For a focused branch-deepening pass, regenerate the analysis context exports with:

python3 tools/py/export_analysis_context.py \
  rt3_wineprefix/drive_c/rt3/RT3.exe \
  artifacts/exports/rt3-1.06 \
  --addr 0x00444dd0 \
  --addr 0x00508730 \
  --addr 0x00508880 \
  --string gpdLabelDB \
  --string gpdCityDB \
  --string 2DLabel.imb \
  --string 2DCity.imb \
  --string "Geographic Labels"

For the pending-template dispatch-store branch, regenerate the new branch dossier with:

python3 tools/py/rt3_rekit.py \
  pending-template-store \
  rt3_wineprefix/drive_c/rt3/RT3.exe \
  artifacts/exports/rt3-1.06

That dossier is now a targeted follow-up tool, not the default first pass.