SC2 strategic-structure investigation

This repository is a reproducible empirical investigation of strategy and policy in real StarCraft II play. It uses 3,649 professional human trajectories from SC2EGSet and 360 raw AlphaStar Battle.net replays. The conclusions and concrete thesis/bot recommendation are in REPORT.md.

Reproduce

PowerShell, from the repository root:

py -3.13 -m venv .venv
.venv\Scripts\python -m pip install -e .[dev]
.venv\Scripts\python scripts\download_data.py
.venv\Scripts\python scripts\extract_data.py
.venv\Scripts\python scripts\build_dataset.py --workers 8
.venv\Scripts\python scripts\run_analysis.py
.venv\Scripts\python -m pytest
.venv\Scripts\ruff check .

The extraction expands to roughly 34 GiB. Downloads, extraction, and shard construction are idempotent. The final analysis takes about four minutes on the development machine after the compact Parquet shards exist. StarCraft II itself is not required: SC2EGSet supplies normalized tracker events and the raw AlphaStar files are decoded with Blizzard's s2protocol package.

Exact source URLs and SHA-256 digests are in data/SOURCES.json. Large raw, intermediate, and processed files are intentionally ignored by git. Final evidence is retained as CSV in outputs/tables/ and as report figures in outputs/figures/.

Pipeline

• src/sc2_strategy/replay.py: normalized SC2EGSet and raw SC2Replay loaders.
• src/sc2_strategy/features.py: replay events to 30-second player snapshots and milestones.
• src/sc2_strategy/analysis.py: shared representations, PCA, cluster/null diagnostics.
• scripts/run_analysis.py: grouped validation, cross-era tests, signatures, and figures.
• tests/: canonicalization and trajectory-state regression tests.

All strategic forecasts use game-grouped folds. The report distinguishes omniscient replay features from information that would actually be available to a bot under fog of war.