RailEmpire

An approachable railway tycoon about autonomous trains in an alternate-history Slavic engineering fairy tale. An exiled heir to the Pearl Throne is building the Great Eastern Railway across a wild frontier. Players connect cities, construct depots and industries, and dispatch trains that find their own routes and move cargo. Objectives arrive as imperial decrees, the world changes with terrain and seasons, and only the rolling stock attached to the prince's personal train can move between regions.

Status: early development / technical MVP. The end-to-end gameplay loop is playable and the public release-smoke suite is green. The broader terrain and save-system acceptance suite still has open gates. This is a solo project.

• Engine: Godot 4.7 using the GL Compatibility renderer
• Language: GDScript with a data-oriented simulation (SoA PackedArrays, fixed 1/60 step)
• Target: Steam on PC, with touch controls and Steam Deck support in scope

---

Quick start

# Open the project in Godot and press F5:
godot --path .
# Main scene: res://scenes/shell/boot.tscn

Editor and debug builds open the Dev Menu (scenes/debug/dev_menu.tscn). Press F1 to open it from anywhere and F2 to reload the current scene. The two primary entries are Play — Region 1 and Demo Scene — Train and Stations. Rail Lab, terrain and style previews, and the main menu are grouped under Debug ▸.

Tests

The project uses Godot 4.7 headless checks. Each scene test prints NAME:PASS/FAIL and calls get_tree().quit().

Run the public release gates:

pwsh tools/verify_open_source.ps1
pwsh tools/run_release_smoke.ps1  # Auto-detects Godot; also accepts -Godot <path>

Run the complete acceptance suite with pwsh tools/run_tests.ps1. It prints a summary and returns a non-zero exit code if any check fails. The equivalent manual sequence is:

$godot = $env:GODOT_BIN  # Or the full path to the Godot 4.7 console executable

# 1) Refresh the global class cache after adding class_name scripts:
& $godot --headless --editor --path . --quit
# 2) Compile and check for SCRIPT ERROR / Parse Error:
& $godot --headless --path . --quit
# 3) Run every scene test:
Get-ChildItem src/tests -Filter *.tscn | % { & $godot --headless --path . ("res://src/tests/" + $_.Name) }
# 4) Run the two script checks:
& $godot --headless --path . -s res://src/tests/zarnik_model_check.gd
& $godot --headless --path . -s res://src/tests/lot_grid_check.gd

Current release-smoke result: 8 scenes + 2 script checks pass, with no compilation errors. The full run on 2026-07-19 reported 166/211 scene checks passing and 45 failing, while both script checks passed. The open TC3/TC6 gates are recorded in docs/HANDOFF.md. Godot's dummy RenderingServer does not retain every per-instance MultiMesh transform in headless mode, so renderer tests use debug accessors.

Repository structure

src/              GDScript sources
  core/             autoloads: EventBus, GameState, Economy, ContentDB, SimClock, …
  construction/     BuildManager, placement, snapping, LotGrid, building assembly
  rail/             rail graph and custom A*
  sim/              data-oriented train simulation
  world/            terrain, world grid, and ports
  view/             read-only rail and train renderers
  ui/ and hud/      Magophonee, toasts, toolbars, and inspectors
  data/             content resource types
  debug/            Dev Menu, Rail Lab, and debug shortcuts
  tests/            211 headless scene checks plus script checks
scenes/           Godot scenes
assets/           data resources, models, materials, shaders, UI, and audio
tools/            Blender/Godot asset generators, probes, and screenshot tools
docs/             project documentation

Five architectural principles guide the project:

1. Simulation state is data, not a scene-node hierarchy.
2. A fixed simulation step plus render interpolation provides determinism.
3. Systems communicate through EventBus and GameState.
4. Content lives in .tres data indexed by ContentDB, not in hard-coded tables.
5. Saves serialize registries into flat, versioned dictionaries with explicit migrations.

Documentation

Start with the canonical docs/GDD.md. It consolidates the project vision, resolves known contradictions, and identifies the authoritative specialist document for each area.

Area	Document
Canonical vision, mechanics, and roadmap	docs/GDD.md
Architecture and data schemas	docs/PLAN.md
Core sandbox and active terrain work	docs/CORE_SLICE.md, docs/TERRAIN_CORE_PRODUCTION_V1.md
Rails, trains, and development tools	docs/RAIL_SYSTEM.md
Station construction and anchor ports	docs/CONSTRUCTION_STATIONS.md
World, plot, and characters	docs/NARRATIVE.md, docs/OPENING.md, docs/DIALOGUE_PERSONAS.md
The Sovereign's Train meta-campaign	docs/META_LAYER.md
Art direction and UI	docs/ART_STYLE.md
Market research and release phases	docs/ROADMAP_2026.md
Consolidated Early Access release plan	docs/RELEASE_PLAN.md
Steam page, assets, operations, and readiness	docs/steam/
Current implementation status	docs/HANDOFF.md

Detailed normative specifications live in docs/superpowers/specs/. Dated council audits, completed plans, and one-off studies live in docs/archive/ as a record of decisions rather than a source of current truth.

Project assessment

Strengths: strict simulation/render separation, event-driven system boundaries, deterministic simulation, data-driven content, and unusually broad automated coverage for a solo project. The design canon is consolidated in one GDD with explicit conflict resolution.

Known risks:

• The project-owned Zarnik_* train roster is intentionally small and must grow with the vertical slice.
• This remains a technical MVP. Tutorial presentation, the S9 art pass, M10 meta layer, M11 dialogue, and the Region 1 vertical slice are still ahead.
• The solo scope and a single Next Fest window make feature creep a serious risk; the GDD contains explicit do-not-build lists.
• Steam payout residency/banking and the final product name remain business blockers.

Contributing

Bug reports, documentation improvements, and small, well-isolated pull requests are welcome. Read CONTRIBUTING.md before making changes. Report vulnerabilities through SECURITY.md, not through a public issue.

Project code and original assets are licensed under the MIT License; see LICENSE. Bundled fonts remain under SIL OFL 1.1. Attribution and full license paths are listed in THIRD_PARTY_NOTICES.md.