rrt/README.md

Analysis and reimplementation of Railroad Tycoon 3

The old executable is at ./rt3_wineprefix/drive_c/rt3/RT3.exe

Our first task is to understand the executable's high-level control loops and subsystem boundaries well enough to choose good rewrite targets. As we go, we document evidence, keep a curated function map, and stand up Rust tooling that can validate artifacts and later host replacement code.

The long-term direction is still a DLL we can inject into the original executable, patching in individual functions as we build them out. The active implementation milestone is now a headless runtime rehost layer that can execute deterministic world work, compare normalized state, and grow subsystem breadth without depending on the shell or presentation path. The current packed-event frontier is real grouped-descriptor semantic mapping on top of the existing save-slice, snapshot, overlay-import, compact-control, and symbolic company-target workflows. The runtime already carries selected-company and controller-role context through overlay imports so synthetic packed records can execute selected_company, human_companies, and ai_companies scopes without a parallel packed executor, while condition-relative company scopes remain explicitly blocked. The PE32 hook remains useful as capture and integration tooling, but it is no longer the main execution milestone.

Project Docs

Bootstrap design and workflow documents live in docs/.

• docs/README.md: handbook index and target hashes
• docs/control-loop-atlas.md: compatibility index for the split atlas
• docs/control-loop-atlas/: canonical atlas section files
• docs/setup-workstation.md: toolchain baseline and local setup
• docs/re-workflow.md: repeatable reverse-engineering workflow
• docs/function-map.md: canonical function-map schema and conventions

The first committed exports for the canonical 1.06 executable live in artifacts/exports/rt3-1.06/.

Rust Workspace

The Rust workspace is split into focused crates:

• rrt-model: shared types for addresses, function-map rows, and control-loop concepts
• rrt-runtime: headless runtime state, stepping, normalized event service, and persistence-facing runtime types
• rrt-fixtures: fixture schemas, loading, normalization, and diff helpers for rehost validation
• rrt-cli: validation, runtime fixture execution, state-diff tools, and repo-health checks
• rrt-hook: minimal Windows DLL scaffold for low-risk in-process loading, capture, and later integration experiments under Wine

For the current headless runtime smoke path, use cargo run -p rrt-cli -- runtime summarize-fixture fixtures/runtime/minimal-world-step-smoke.json or one of the broader runtime fixtures under fixtures/runtime/.

For the current hook smoke test, run tools/run_hook_smoke_test.sh. It builds the PE32 proxy, copies it into the local RT3 install, launches the game briefly under Wine with WINEDLLOVERRIDES=dinput8=n,b, and expects rrt_hook_attach.log to appear.