sots-engine/README.md

sots-engine

A from-scratch, functional reimplementation of the engine behind Sword of the Stars (2006). Not a byte-for-byte decompilation: behavior-equivalent code, built up one verified piece at a time (OpenRCT2-style) until the tree can build the whole application on its own.

Bring your own game. This repository contains engine code only. Game data, assets, saves, and the original binaries are never included; tests and tools read an owner-supplied copy via $SOTS_DATA_DIR. See CONTRIBUTING.md for the clean-room rules.

Status

Phase 2. M0 done — the shim frontend (src/shim/, a proxy binkw32.dll the original game loads) builds, deploys, hooks, and logs from a real game launch. Engine code accrues under src/mars/ and src/game/; each module is oracle-verified against the owner's game data before merge:

• mars/parse — brace-block + .effect readers (1,531/1,531 files agree with the reference)
• mars/text — flat key/value tables, id manifests, CSV (64/64 files agree)

Build: cmake --preset host && cmake --build --preset host && ctest --preset host (Linux); tools/sync-build.sh cross-builds the shim on the lab box and stages it for deployment.

Layout (grows with the work)

• src/shim/ — binkw32 proxy + hooks + old-vs-new compare harness (frontend #1)
• src/mars/, src/game/ — the engine and game reimplementation (accruing)
• include/generated/sots_addresses.h — binary facts (RVAs/prototypes), generated from the RE repo
• tests/ — host tests; real-data tests skip unless $SOTS_DATA_DIR is set
• tools/ — build (MinGW i686 cross) and deploy scripts

Planning, findings, and verification evidence are tracked in the private RE repo (sots-re).