# sots-re

Reverse-engineering worklog for **Sword of the Stars (2006, SOTS1)** — the 32-bit DX9
original + expansions. The nitty-gritty: static/dynamic analysis notes, Ghidra & ReVa
scripts, function/struct maps, D3D9 call traces, decomp progress, findings.

## Where this runs
Analysis lab on **spicy** (PVE, 192.168.3.201):
- **CT111 `sots-re`** — Linux workspace: Ghidra + headless ReVa server, radare2/rizin/cutter,
  binwalk. Hosts the Samba share and this repo's working tree at `/srv/re-lab/notes`.
- **VM140 `sots-re-win10`** — Win10 runtime + dynamic analysis (x64dbg, Cheat Engine,
  RenderDoc/apitrace, DXVK→CPU-Vulkan for GPU-less rendering).

Infra (guests, storage, network, share, ReVa endpoint) is documented from the
system-maintainer POV in **trikilli** → `services/re-lab.md`. This repo is everything else.

## Layout
- `findings/`   — the running findings log (append-only), one file per subsystem.
- `ghidra/`     — exported scripts, data-type archives, struct definitions.
- `traces/`     — D3D9 / Win32 API call captures + analysis.
- `scripts/`    — helper tooling (loaders, extractors, parsers).
- `notes/`      — session notes, scratch, hypotheses.

## Ownership / legality
Game binaries come from the owner's own GOG/Steam copy. RE is for personal
interoperability, bug-fixing, and preservation. Binaries themselves are **not** committed
here (see `.gitignore`) — they live on the lab's Samba share `/srv/re-lab/samples`.

## Campaign (how this repo is run)

A 4-agent crew (defined in `~/.claude/agents/re-*.md`) runs the exploration:
**re-quartermaster** (backlog + board) → **re-analyst** (maps via ReVa) →
**re-verifier** (proves vs real data; old-vs-new differential once reimpl starts) →
**re-scribe** (files the note, links it, commits).

- `campaign/board.md` — live status board (start here).
- **Live tracking = Forgejo issues** on `alex/sots-re` (labels `status/*` are the kanban
  columns; `type/*`, `conf/*`). `campaign/board.md` is the editable mirror — publish with
  `scripts/forgejo_campaign.py bootstrap` (needs `FORGEJO_TOKEN`).
- `campaign/backlog.md` — prioritized target queue.
- `campaign/open-questions.md` — unresolved threads.
- `findings/_template.md` — the record format every finding follows.
- `findings/{objects,control-flow,subsystems}/` — the growing engine map.
- `verify/{parsers,traces,harness,results}/` — validation: struct parsers now, golden-trace
  replay + shim compare-mode for reimplementation.
- `ghidra/` — exported scripts + datatype archives.

Approach & north star: `findings/00-strategy.md`. Binary facts: `findings/01-fingerprint.md`.

## Sibling repo
`alex/sots-engine` — the from-scratch engine source (clean-room, public-capable). This repo keeps the
evidence + planning for both; binary facts cross over only via `ghidra/addresses.json` → `tools/gen_addresses.py`.
- `guides/re-windows-2000s-howto.md` — annotated bibliography + how-to for RE of mid-2000s MSVC/DX9 Windows games, with our-experience call-outs.