A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.
Releasing
A release is a tagged commit on main with a CHANGELOG section and, from the first shared build on, a WebGL zip on the
GitHub Releases page (and, from M4, on itch.io). Steps 1–3 are a normal pull request. Steps 4–7 happen on the merged main, and steps 5–7 are owner steps.
The MVP release is web only (owner ruling, 20 Oct 2026 (#814)). Desktop players move after the MVP (#905), and the
macOS IL2CPP parity check is not an MVP release gate.
Choose the version (Semantic Versioning, pre-1.0 while the game is pre-release).
Bump every version site in one pull request:
sim/Statecraft.Sim/SimInfo.cs(Version) andunity/ProjectSettings/ProjectSettings.asset(bundleVersion). Fold the changelog fragments withuv run scripts/oss/changelog_fold.py: it moves eachchangelog.d/*.mdentry into## [Unreleased], in filename order, and deletes the fragments (it refuses, changing nothing, if one has no entry). Then move the## [Unreleased]entries inCHANGELOG.mdunder## [X.Y.Z] - YYYY-MM-DDand leave an empty## [Unreleased]above it.scripts/oss/tests/test_release.py::test_versions_agreefails if the three disagree.Merge the pull request (squash).
Run the release gate on the merged
main(it refuses to run elsewhere):bash scripts/oss/release_gate.sh. It must printRELEASE GATE OK. It refuses while an owner decision is open (including D10, history acknowledgement, and D11, the sensitivity review), while an asset row isowner-verifyor haslicence: unknown(scripts/oss/check_repo.py --release), while the sim's sensitivity gate refusescontent/(including acontent/settlement_targets.yamlrow that is notsensitivity-reviewed, Q-TGT-3 (b)), or while the history scan (scripts/oss/scan_history.py) shows an open secret-shape row.Build and package on the owner's machine, from the merged
main:Build both web zips from the merged release commit, never from a pre-merge candidate. The .NET SDK includes the source commit in
Statecraft.Sim.dll's informational version, so a candidate build cannot be reproduced from the tag after a squash merge. Before building, check that the disk has several GB free forunity/Library/Bee.uv run tools/machine_lock.py --shared --wait-unity -- "$UNITY" -batchmode -CI false -GITHUB_ACTIONS false -TF_BUILD false -quit -projectPath unity -buildTarget WebGL -executeMethod Statecraft.Game.EditorTools.Build.Web -compression gzip -shareable -logFile "$PWD/unity-build-web-gz.log" git checkout -- unity/Assets/Settings unity/ProjectSettings/ProjectSettings.asset golden_expect=(); while read -r name hash; do [[ -z "$name" || "$name" == \#* ]] || golden_expect+=(--expect "GOLDEN OK $name $hash"); done < sim/Statecraft.Sim.Tests/golden/manifest.txt # one GOLDEN OK line per manifest golden (#394), e.g. "GOLDEN OK hash1950 832e8ccc38e3fb36228826816b452477fbbd6ab667ee30cdaef40e5b1b2fe869" # and "GOLDEN OK hash1952 841f05536a49b68cd10d3f1ca548e559098415119284d483620f14bb6a4bb44e" uv run tools/web_check.py unity/Builds/Web-gzip --query "golden&smoke=5" "${golden_expect[@]}" \ --expect "SMOKE OK 5 turns 1948-10-15 12f088f62bd0694ae59b5f6472751579ad96c2198308d0869a8cf795f1aad051" uv run tools/web_check.py unity/Builds/Web-gzip --startscreen new --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-gzip --startscreen recording --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-gzip --startscreen new --query lang=he --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-gzip --startscreen recording --query lang=he --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-gzip --persistence --timeout 300 --stall 90 bash scripts/oss/package_web.sh unity/Builds/Web-gzip unity/Builds/statecraft-israel-vX.Y.Z-web.zipThe release build is gzip, not Brotli (owner decision on #879, 17 October 2026: "gzip for both", one zip for GitHub Releases and itch.io). itch.io's CDN decodes a
.brfile and re-encodes it by content type, and it sends Unity's.data(application/octet-stream) to the player uncompressed; a gzip.datastays gzip. Estimated from the 15 October build's files, that is about 34 MB to download per player instead of about 46 MB. Both load in a browser with Decompression Fallback off, asBuild.Websets it, andweb_check.pyserves*.gzwithContent-Encoding: gzip.The four
--startscreenpasses (owner decision on #967, 17 October 2026) open the start screen every player sees first, which the golden and smoke run skips: New game, and Play the recording then New game, in English and in Hebrew. Each must printPASS. A console exception,RECORDING failedorBOOT FAILfails it (#908). So does a map without Israeli and enemy unit tokens on turn 1 (the new game) or turn 2 (after End turn):UNITS FAIL, read from theunits drawnline the unit layer logs under?navlog; a build that logs no such line fails too (owner ruling on #2056, 1 November 2026).The English-only
--persistencepass waits for each save's matching IndexedDB commit and checks that both reloads restore its date, turn and state hash.For the playable demo on GitHub Pages (
/demo/), build a second web variant with Unity's Decompression Fallback - GitHub Pages cannot set response headers, so the loader must decompress the files itself (Unity manual: deploying a Web application). For the same reason it stays single-threaded (webGLThreadsSupport: 0; threads need the COOP and COEP headers), and only a-shareablebuild may be published. Check it and package it the same way:uv run tools/machine_lock.py --shared --wait-unity -- "$UNITY" -batchmode -CI false -GITHUB_ACTIONS false -TF_BUILD false -quit -projectPath unity -buildTarget WebGL -executeMethod Statecraft.Game.EditorTools.Build.Web -compression gzip -decompressionFallback -shareable -out Builds/Web-pages -logFile "$PWD/unity-build-web-pages.log" git checkout -- unity/Assets/Settings unity/ProjectSettings/ProjectSettings.asset uv run tools/web_check.py unity/Builds/Web-pages --query "golden&smoke=5" "${golden_expect[@]}" \ --expect "SMOKE OK 5 turns 1948-10-15 12f088f62bd0694ae59b5f6472751579ad96c2198308d0869a8cf795f1aad051" uv run tools/web_check.py unity/Builds/Web-pages --startscreen new --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-pages --startscreen recording --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-pages --startscreen new --query lang=he --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-pages --startscreen recording --query lang=he --timeout 300 --stall 90 uv run tools/web_check.py unity/Builds/Web-pages --persistence --timeout 300 --stall 90 bash scripts/oss/package_web.sh unity/Builds/Web-pages unity/Builds/statecraft-israel-vX.Y.Z-web-pages.zipPublishing a release starts the Pages deploy (
.github/workflows/site.yml, onmain;gh workflow run site.ymlstarts one on demand). It unpacks the Latest release'sstatecraft-israel-vX.Y.Z-web-pages.zipat/demo/(https://eyalgolan.github.io/statecraft-israel/demo/) and the root page redirects there. It fails, and Pages keeps the last deploy, when that release has no such zip, the zip has noindex.html, or itsevent-photos.jsonis notshareable. The demo is never in git (no file in the repository may pass 10 MB).package_web.shcopies the licence and attribution files into the build folder, then runstools/package_release.py, M3's sensitivity gate, which zips the folder and printsPACKAGED …orPACKAGE REFUSED …. It refuses a build that was not made with-shareable(the build'sevent-photos.jsonsays so) or that carries an unreviewed sensitive event photograph. It then checks the zip's file list (without printing it) for the notices andindex.html, and printsMISSING in zip: …and deletes the zip if one is absent. A good run prints the content gate'sRELEASE GATE OKline,PACKAGED …, the SHA-256 line andOK: notices inside …, and exits 0. If it printsPACKAGE REFUSED,MISSING in zipor exits non-zero, stop. This one zip is the file for GitHub Releases and for the M4 itch.io upload (docs/m3-release.md); never zip a build by hand.The files under
Build/are named by their content hash (webGLNameFilesAsHashes: 1, set byProjectSetup.Apply; issue #437), so their names change with every build that changes them. Only the build'sindex.htmlsays which ones belong to it: never refer to them by a fixed name. Unity emptiesBuild/on each build;package_release.pyzips only theBuild/filesindex.htmlnames (it printsLEFT OUT Build/<name>for any other) and refuses the folder when one of them is missing.With
webGLDataCaching: 1, Unity's loader also keeps each build's.datain the browser's IndexedDB (UnityCache), keyed by its URL. Its clean-up drops entries made under anotherproductVersion(bundleVersion), and otherwise trims the least recently used above 1 GiB (MaximumCacheSize=1073741824in the 6000.3 loader). With hashed names, every build with the samebundleVersionadds one more.datathere until that cap; the version bump in step 2 clears them at each release.Desktop builds after the MVP (macOS, Linux, Windows; #905). Desktop players are built on the owner's Mac (decisions O7 and O8 in
docs/oss/DECISIONS.md; plan indocs/superpowers/specs/2026-10-14-desktop-builds-and-release-pipeline.md). On the mergedmain, tagHEADfirst (git tag -a vX.Y.Z -m "Statecraft: Israel vX.Y.Z"; step 6 pushes it), then:uv run tools/release_build.py --platform all --tag vX.Y.Z # or mac, linux, windows; --dry-run prints the commandsBefore building anything it refuses: a dirty tree; a branch other than
main, or aHEADthat your lastgit fetch origindid not show onorigin/main(the script never fetches); a tag that is notvplusbundleVersion(--tagdefaults tov<bundleVersion>; an optional-suffixis allowed) or does not point atHEAD; an editor whose version is not the one inProjectVersion.txt; an--outinside any checkout or worktree of the repository (ignored folders too: a build emptiesStreamingAssets/content), or one that is not empty. It also stops if Unity Hub lacks a module the platforms need: Mac Build Support (IL2CPP), Linux Build Support (Mono) or Windows Build Support (Mono); the message names them and gives the Hub command.--devmakes a test build from any branch: not-shareable, no--tag, and archives namedvX.Y.Z-dev.<commit>so they cannot pass for a release.Each build runs under
tools/machine_lock.py --shared --wait-unity. The script runs the-goldencheck on the macOS player, the only one the Mac can run; the Linux and Windows players are recorded as unchecked until the CI player check runs them. It archives each player under the names that check expects (statecraft-israel-vX.Y.Z-macos-universal.zip, made withditto;-linux-x64.tar.gz;-windows-x64.zip), each withLICENSE,NOTICE,THIRD-PARTY-NOTICES.md, the two font licences (OFL-EBGaramond.txt,OFL-FrankRuhlLibre.txt) andLICENSES/beside the player (it lists the archive to check), and writesbuild-record.json,build-record.md, afiles-<platform>.sha256list of each archive's files and the build'sevent-photos-<platform>.jsonto~/statecraft-release/v<version>-<commit>-<UTC time>/(or--out), and prints the path. It never commits, pushes or uploads: copy the record files to the build records repository by hand. Signing (#905) is a later step, not yet scripted; the Steam upload is below.Steam builds (#2155, #2156; owner answers Q3, Q7 and Q8 in #2150). After the GitHub archives above, and only once
steam/steam.jsonhas the app and depot IDs (docs/steam/README.md, section 1), build the Steam players from the same tagged commit into a new folder:uv run tools/release_build.py --platform all --tag vX.Y.Z --steam --out ~/statecraft-release/vX.Y.Z-steam uv run tools/steam_upload.py stage --out ~/statecraft-release/vX.Y.Z-steam --tag vX.Y.Z--steampasses-steamto every build (only those players carry Valve's library) and writessteam/windows/,steam/mac/andsteam/linux/(the player and the notices, no archive) with a record that says"steam": trueand"channel": "beta"; it refuses a folder holdingsteam_appid.txt. The GitHub archives, for their part, are refused if they list any Valve file. The macOS Steam player passes the same-goldencheck as above. Thenstagezips each folder (keeping the executable bits), writessteam-record.jsonwith each zip's SHA-256, attaches them to a draft releasesteam-vX.Y.Zthat is never published, and starts.github/workflows/steam-upload.ymlfor thebetabranch. That job (dispatch only, environmentsteam, the owner's two secrets) checks the draft against its record and the commit againstmain, uploads with steamcmd, sets the build live onbetaand deletes the draft. A login failure there means the owner re-provisions the secret (docs/steam/README.md, section 2); nobody else touches it. A--dev --steambuild is for local tests only:stagerefuses its record. Testers then rundocs/steam/test-checklist.md, and only the owner sets abetabuild live ondefault, in App Admin. Nightlies go to thenightlybranch by themselves ("Nightly builds", thesteamstage).Tag and publish (owner), in one
gh release create. The MVP release carries only the web zips (owner ruling, 20 Oct 2026 (#814)). Desktop players ship after the MVP under #905. For a later release with desktop players, include all three desktop archives from "Desktop builds after the MVP" above, as a pre-release with "unchecked" in its notes. Never publish first and upload the players afterwards:git tag -a vX.Y.Z -m "Statecraft: Israel vX.Y.Z" # skip if "Desktop builds" already made it git push origin vX.Y.Z notes="$(mktemp)" awk '/^## \[X.Y.Z\]/{f=1;next} /^## \[/{f=0} f' CHANGELOG.md > "$notes" (cd unity/Builds && shasum -a 256 statecraft-israel-vX.Y.Z-web.zip statecraft-israel-vX.Y.Z-web-pages.zip) >> "$notes" gh release create vX.Y.Z --prerelease --title "vX.Y.Z" --notes-file "$notes" \ unity/Builds/statecraft-israel-vX.Y.Z-web.zip unity/Builds/statecraft-israel-vX.Y.Z-web-pages.zipThe notes are the version's CHANGELOG section and the SHA-256 of each zip, the same hashes step 5 printed. Read
"$notes"before publishing.After the MVP, a release with desktop players appends all three archives from the
<out>folder thattools/release_build.pyprinted. Its notes also say "unchecked" until the player checks below pass:<out>/statecraft-israel-vX.Y.Z-windows-x64.zip <out>/statecraft-israel-vX.Y.Z-linux-x64.tar.gz <out>/statecraft-israel-vX.Y.Z-macos-universal.zipPublishing starts the
Player goldenworkflow (.github/workflows/player-golden.yml). For the web-only MVP this workflow is not a release gate, and no "unchecked" marker is required (owner ruling, 20 Oct 2026 (#814)). When a release has desktop players, the workflow downloads each player, checks it against the SHA-256 GitHub records for the asset, and runs-batchmode -nographics -goldenon GitHub's Windows and Linux machines (the Linux player underxvfb-run -a: with no display at all it crashes, issue #533), and the Mac app twice on Apple silicon (macos-15): its arm64 slice, and its x86_64 slice under Rosetta (arch -x86_64; GitHub retires its last Intel image,macos-15-intel, in August 2027, issue #548). It fails when only one or two of the three archives are attached. A release with none (a web-only release, before desktop players ship) passes, but its run summary says UNCHECKED.- A release with desktop players stays a pre-release marked "unchecked" until that run is green. Testers can download a pre-release as soon as it is published, so do not announce it before then. Then remove "unchecked" from the notes.
- Uploading or replacing an archive later (
gh release upload, with or without--clobber) starts no run. After any such upload, rungh workflow run player-golden.yml -f tag=vX.Y.Zand wait for it to pass (gh run watch <run-id> --exit-status, with the run id fromgh run list --workflow player-golden.yml). A run that started before the replacement fails on the digest; run it again.
Check every published artefact: download each uploaded archive (GitHub Releases, and itch.io once used) into an empty folder, then list it and look for the notices: for a
.zip(the web zip, the macOS and Windows players),unzip -Z1 <zip> | grep -E '^(LICENSE|NOTICE|THIRD-PARTY-NOTICES.md|OFL-EBGaramond.txt|OFL-FrankRuhlLibre.txt)$'; for the Linux.tar.gz,tar -tzf <archive> | grep -E '^(\./)?(LICENSE|NOTICE|THIRD-PARTY-NOTICES.md|OFL-EBGaramond.txt|OFL-FrankRuhlLibre.txt)$'. It must print five lines for each archive.
Nightly builds
site.yml selects GitHub Latest for /demo/, matching the release chosen by nightly recovery. Only when the Latest lookup returns HTTP 404 does it fall back to the newest published prerelease, and with neither it deploys nothing. Other lookup failures stop deployment. A post-publication site failure leaves the served demo unverified; it must not be reported as unchanged without readback.
Every night at 03:00 (Israel time) the newest main is built and, only if every gate passes, becomes the public web
game: a normal GitHub release marked Latest, tagged vX.Y.Z, which GitHub Pages' /demo/ serves, and, once itch
pushes are enabled, the itch.io page. X.Y.Z is one patch above the numerically highest published release tag matching
^v[0-9]+\.[0-9]+\.[0-9]+$; drafts, -nightly tags and other names do not choose the version. With v0.3.1 and
v0.3.1-nightly.20261028 published, the next nightly is v0.3.2. A by-hand run can choose a higher version instead
(--manual --version X.Y.Z, tools/README.md, "Nightly release"); the 03:00 night never does. The job is
tools/nightly.py under launchd; the install steps are in tools/README.md, "Nightly release". Nothing here changes
the owner-run release steps above (steps 1-7). Published nightlies are never deleted.
Owner rulings, 28 Oct 2026: "the nighttly release needs to be vx.y.z +0.0.1 every time";
"Mark each Latest (Recommended)"; "Stamp the build only (Recommended)". The build's bundleVersion and in-game label
are X.Y.Z, stamped only in the nightly worktree after the gates pass and never committed.
The gates, in order. The first one that fails ends the night as REFUSED, and nothing public changes:
- Preflight:
origin/maindiffers from the last published nightly (otherwise the night is SKIPPED), at least 40 GB free, noEXCLUSIVE-WINDOWfile, the Unity licence, editor and slot script present, and no release already holding tonight's tag, and no local or remote git tag of that name. First delete a stranded draft only when its tag matches this job's savedopen_draftand its release ID matchesopen_draft_id, then check availability. Foreign drafts and published releases refuse. Old state with anopen_draftbut no ID still loads; a same-tag draft refuses with "check by hand" and is never deleted without an ID match. With--no-publish, leave the draft and state alone and refuse the collision. build-sim, thenscripts/check.sh origin/main(check) andscripts/oss/release_gate.sh(release-gate), the same bar as a release.- The sim tests under
he_ILanden_US(sim-he_IL,sim-en_US). - The Unity warm-up and the full EditMode run (
editmode), with at least one test and no failure. - The two WebGL builds, the gzip one (
build-web-gz) and the Pages one (build-web-pages), with the nightly version stamped in after the gates; the tree must be clean afterwards, and the stamp is never committed. Then the gzip zip (package-gz) and the Pages zip (package-pages). web_check.pyon both builds (web-check).- Download size (
sizes): compare the combined total of the data, wasm and framework files with this job's last published night (state.json'slast_published), even if that release is now a draft. On a first night with no saved publication, use the newest non-draft release carrying a*-web.zip. The total may grow at most 2%, plus the size budget below. - Headless boot time (
boot): the median of three boots. The first 5 published nights set the baseline; after that a boot slower than the slowest baseline night plus the spread of the baseline is refused. Before the first boot the machine settles: the job waits until the 1-minute load average is under 2.0, at most 5 minutes, and measures anyway if it never gets there. Eachboot-N.logstarts with the machine's load averages,vm.swapusage,memory_pressure's free percentage andpmset -g therm, andboot-1.logalso says how long the wait took. A median over the bound is measured once more: the machine settles again, three more boots run (boot-4.logtoboot-6.log), and the night is refused only if that second median is also over the bound, naming both. The log records both medians when the second one passes (#2921).
A nightly never moves a golden: golden moves arrive through reviewed pull requests, and the nightly only needs the golden tests of the full run to pass.
Size budget. A pull request that adds download size on purpose puts this line in its body, with the megabytes (1 MB = 1,000,000 bytes) it adds:
Nightly size budget: +N MB
The next nightly allows the growth of the 2% plus the lines of every pull request merged since the last published nightly; without the line, an increase beyond 2% refuses the night. After a night is published, its new total becomes this job's baseline for the next night.
Publishing (only after every gate): a normal draft release with both zips and notes listing the commits since the
last nightly (the tag points at the commit the night started from, even if main moves during the build), the assets
checked against the local zips, the itch push when enabled (checked by build id and a fetch of the live files, and
rolled back to the previous build if publication or its verification fails), the release made public with --latest and checked for
isPrerelease: false and Latest, then site.yml started and the demo checked for the new version. Creation uses
gh api through the same job runner, with draft: true, prerelease: false and make_latest: "true".
Right before create, the tag is checked again (no release, no local or remote git tag), so a release made during the
build is refused and not touched. The create response's numeric release ID is saved as open_draft_id alongside
open_draft before gh release upload starts. A failed upload can therefore clean its own draft. Cleanup and
rollback first check that the tag still resolves to that ID and is still a draft, then delete through
gh api repos/<repo>/releases/<id> --method DELETE, preserving git tags. A different or unknown ID refuses with
"check by hand"; a replacement with the same tag is never the deletion target. If creation fails without returning
a usable ID, ownership is not guessed and any stranded draft requires a check by hand. A saved draft with a matching
ID is cleaned before the next attempt; it never reaches /demo/, because site.yml skips drafts. These ID ownership
and persisted recovery guarantees complete the two hardening steps deferred from #1916 to #1917.
Before publishing, read the current Latest separately from the previous nightly asset baseline and record it in
latest-before-publish.txt. On any later failure, including publication verification or both site attempts, and only
while the failed release is still Latest, restore that previous tag with gh release edit <previous> --latest and
verify it; a Latest someone else set in the meantime is left alone and reported. The REFUSED line and
latest-rollback.log name the previous Latest and the recovery result. With no previous Latest, explicitly report
that fact and remove the failed release's Latest mark. Before attempting recovery, save
latest_recovery_pending: {"failed": "<tag>", "previous": "<previous Latest>"} in state.json; previous is null
when there was no Latest. A failed or unverified recovery keeps this record and reports "check by hand". At the
start of the next publishing run, before preflight, the no-change skip or a pending site deploy, retry through the
same guarded restore_latest. Only while the failed tag is still Latest may it edit Latest. A different Latest,
including no Latest, is left alone and the record is cleared; a verified recovery also clears it. A failed retry
keeps the record and refuses the run before anything publishes. Each outcome is logged and notified, including
success and leaving Latest alone. --no-publish leaves pending recovery and state untouched and refuses until a
publishing run can handle it. Old state files without the pending field load with no recovery pending. Published
releases and tags are preserved. A site-only failure retains the new itch build and the public release, records
the site deploy as pending, and restores the previous Latest after the second attempt.
If the ownership checkpoint cannot be saved, refuse before upload and attempt only guarded cleanup of the known draft ID. If recovery state cannot be saved, still attempt the guarded Latest repair, then refuse before site dispatch or publication and report "check by hand". An unwritable state file cannot promise a durable retry record; preserve the saved file and report the unsaved-state error.
Numeric tag components accept leading zeros: v0.03.1 ties with v0.3.1 and yields the normalized next tag v0.3.2.
The no-change skip compares state.json's last published SHA with origin/main, regardless of its saved tag name.
The record. One line per night in ~/israel-game/.superpowers/nightly/LOG.md (and a NIGHTLY: line in ~/israel-game/.superpowers/HANDOFF.md),
<date time> <OUTCOME> tag=... sha=... gate=... log=<run folder>:
PUBLISHED: every gate passed and the stores serve the new build.SKIPPED:mainhas not moved since the last published nightly (an unfinished site deploy is retried).REFUSED:gate=names the step that stopped it, andlog=the folder holding every step's log. A desktop notification is shown too.MISSED: no run started on that date (the Mac was asleep or logged out); the next run adds the line.
A night that starts after 03:30 is MISSED unless it was started by hand with --manual.
Steam (the steam stage, #2155). Only after the web nightly is published (publish_night returned), the nightly
fetches tonight's tag into its clone, runs uv run tools/release_build.py --platform all --steam --tag <tag> --nightly-version <X.Y.Z> --out <run folder>/steam-release (each Unity build stamped with tonight's version, as the web
builds are) and then uv run tools/steam_upload.py stage --out <run folder>/steam-release --tag <tag>, which attaches
the Steam content to a never-published draft release steam-<tag> and starts steam-upload.yml for the nightly
branch. A failure there never refuses, unpublishes or rolls back the web nightly: the night stays PUBLISHED, its
line ends with steam=failed (the steam-build.log and steam-stage.log are in the run folder) and a notification
is shown. The stage is skipped while steam/steam.json still has a null ID (until the owner has created the app,
#2151), and with uv run tools/nightly.py run --no-steam.
itch.io. Pushes stay off until the owner or an agent (owner, 2 Nov 2026, "2 (a)") runs
uv run tools/nightly.py savetest --tag <a published nightly> once
and it prints PASS (the two-upload save test of docs/m3-release.md, "Upload to itch.io"); until then each night
logs itch: skipped (<reason>), naming the missing config key or the problem, and pushes nothing to itch. Once the test has run, the command prints the line it records in the job's LOG.md (SAVETEST <result> tag=<tag> <why>), then the path of the run's evidence.json when it wrote one, then the result word; a run refused before the test starts prints only the refusal, on stderr. The save test pushes only to a separate test page, named in the job's config.json as
savetest_itch_target (user/project:channel), and refuses to run without it or if it names the public project:
each upload hides the game while itch unpacks it, which took up to an hour on 28 October 2026. It never reads the
test page: it loads each upload's game frame from the upload and build ids butler status shows, so the test page
can stay Restricted (#2056).
Refreshing the README screenshots
The README's screenshots are claims about the current build. Re-take them whenever the build looks different, and always in the pull request that merges a visual change (visual-v1 included), never as a follow-up:
- Build the web player (
docs/dev-setup.md) and serve it. After visual-v1 has merged, capture with itsuv run tools/machine_lock.py --shared -- uv run tools/web_check.py <build> --query "golden&shot" --expect "SHOT done" --shots <dir>(the formtools/art_checkpoint.shuses), so the capture does not disturb profiling. The player only sends shots when the URL hasshot; it saves one PNG per map pose inPromoPose, and views those poses do not cover are still captured by hand. Before that, capture by hand at 1640×920 in Chrome. - Replace
docs/images/build-m3-map.jpg,build-m3-start.jpg,build-m3-city.jpg,build-m3-cabinet.jpgandbuild-m3-why.jpg(or addbuild-<milestone>-*and update the README to the new names). Each must show a non-sensitive moment: no unreviewed sensitive event card. - Update the visible caption "Real screenshots, main at abc1234, YYYY-MM-DD." in
README.md, and the "Is this any good?" and "Roadmap" text the change made stale. - Rebuild
docs/images/social-preview.jpg(1280×640) from the new map shot:sips --resampleWidth 1280 <shot> --out /tmp/sp.jpgthensips --padToHeightWidth 640 1280 --padColor 0B1220 /tmp/sp.jpg --out docs/images/social-preview.jpg(padded, not cropped, so no text is cut off). The owner re-uploads it under Settings → General → Social preview. Never use concept art for the social preview.
The README's hero, concept art and screenshots
What README.md shows at the top, and what scripts/oss/tests/test_readme.py checks:
- The hero is the cinematic trailer. It is a
https://github.com/user-attachments/assets/<id>URL on its own line above the# Statecraft: Israelheading, which GitHub plays in its video player, with a caption saying it was made with AI video tools and is not in-game footage (test_hero_is_the_trailer_in_githubs_player_disclosed_as_ai). - The concept art opens "What is this?" (
CONCEPT,docs/images/hero-concept-1936.jpg). Its alt text says it is AI-generated concept art and not the current build, and the caption under it says "Concept art (AI-generated)", "set in 1936" and "not the current build" (test_concept_art_opens_what_is_this_captioned_as_concept_art). - Real gameplay comes next: the clip (
CLIP) and the five screenshots (GRID, one wide over two pairs), with the captions "Real gameplay, main at abc1234, YYYY-MM-DD." and "Real screenshots, main at abc1234, YYYY-MM-DD." (test_real_dated_screenshots_in_a_one_plus_two_plus_two_grid; refreshing them is the section above).
To change any of these, edit README.md and README.he.md together (the Hebrew README's tests keep the same facts),
give a new image an ASSETS.yaml row, change CONCEPT, CLIP or GRID in test_readme.py if a file name changes,
and land it as a normal pull request. Whether a real build screenshot later replaces the concept art in "What is
this?" is not decided.
Capturing trailer footage (issue #45)
The trailer's map shots come from the real build: the editor renders the map frame by frame, so a capture can be run
again and gives the same camera, state and water on every frame. The pixels match too, except the unit badges' glyphs
at the whole-country zoom: two runs on the build server differed only there (1,288 of 6.2 million bytes per frame;
the 60 km frames were byte-identical), where a glyph and its plate draw at almost the same depth. Build the sim DLLs
first (python3 tools/build_sim_for_unity.py), run Unity with graphics (not -nographics; on Linux under
xvfb-run -a), then encode the frames with ffmpeg:
uv run tools/machine_lock.py --shared --wait-unity -- "$UNITY" -batchmode -CI false -GITHUB_ACTIONS false -TF_BUILD false -quit -projectPath unity \
-executeMethod MapCapture.Trailer -captureDir "$PWD/captures/<name>" -seed 1948 -logFile "$PWD/unity-trailer.log"
ffmpeg -framerate 60 -i captures/<name>/frame-%05d.png -vf scale=out_color_matrix=bt709 \
-c:v libx264 -preset slow -crf 16 -pix_fmt yuv420p -colorspace bt709 -color_primaries bt709 -color_trc bt709 \
-movflags +faststart captures/<name>/trailer-map.mp4
Give -captureDir an absolute path (a relative one resolves against Unity's working directory) under the ignored
captures/ or outside the repo: frames anywhere else in the tree would mark the recorded commit -dirty. The capture
deletes any frame-*.png already in it first, so an older, longer run cannot leak into the encode.
- What it renders: the camera moves in
TrailerShot.Default(unity/Assets/Scripts/Map/TrailerShot.cs), built only from the promo poses the art checkpoint already compares (PromoPose): the whole country held for 2 s, down to the Jaffa-Tel Aviv-Lydda ground of promo 03 (6 s), and back up to the whole country (6 s). 840 frames, 14 s, each move eased in and out. That order is a placeholder; the shots are the owner's call. Change the list to change it. - Settings: 1920 x 1080 on the desktop (PC) tier, 60 fps, the water's clock pinned to each frame's time, the 1948
sub-districts and the units of turn 1 of a new historical game started with
-seed(default the golden seed, 1948, so the command above may leave it out; turn 1's units do not depend on the seed today, it is recorded so a later moment can be repeated). The frames areframe-00000.pngonwards, one sequence across the shots.trailer.txtbeside them records the commit, Unity version, seed, size, fps, tier and each shot's frame range. - Not in it: the UI (editor renders draw no UI Toolkit, so UI shots still come from the player), sound, and the cut. The .mp4 has no audio track; Steam prefers AAC audio, which the cut adds.
- Why PNG frames: a frame is written only when it is fully rendered, so a slow machine gives the same footage as a fast one, and the Linux editor needs no video codec. On the software-rendered Linux build server (llvmpipe) the default 840 frames took 15 to 25 minutes (907 s alone, 1,459 s beside another Unity run) and 2.3 GB of PNG; the encode took under a minute. Delete the frames after encoding.
- Check the encode before it goes anywhere:
ffprobe -v error -show_entries stream=codec_name,width,height,r_frame_rate,bit_rate captures/<name>/trailer-map.mp4must say h264, 1920 x 1080, 60/1, and a bit rate above Steam's 5,000 Kbps. If it is under (long still holds compress well), encode again with-b:v 8M -maxrate 12M -bufsize 16Min place of-crf 16.
Store-page checklist (issue #45; OWNER STEP)
This is preparation, not a published store page or an answered content survey. The checklist does not clear the name, assets or content for commercial use. Finish the release gates above first; the owner reviews and submits the page. Exception (owner, 21 October 2026, in the coordinator session): the Coming Soon page may open before the MVP, since it ships no build; the gates still apply to the first build uploaded to Steam.
Resolve D8 in
docs/oss/DECISIONS.mdbefore using "Statecraft: Israel" as the commercial name. Do not treat the repository name as trademark clearance. Review the description against the actual release build: distinguish features that are playable now from roadmap plans, and do not promise a platform or language not verified in it.Prepare the Steam store capsules at the current upload sizes below, with a readable game logo and artwork. Capsule text is the game title only, not quotes, awards or marketing copy. Check the small capsule at its generated 120 x 45 and 184 x 69 display sizes before approval. Use the current official templates, not older dimensions.
Store asset Upload pixels Header capsule 920 x 430 Small capsule 462 x 174 Main capsule 1232 x 706 Vertical capsule 748 x 896 Capture at least five gameplay screenshots, minimum 1920 x 1080, 16:9, from the real release build, not concept art, pre-rendered cinematic stills or marketing images. Record the build commit and zip SHA-256 with the capture date. The README build shots (
docs/images/build-m3-*.jpg, 1568 x 882) are smaller than this minimum. Show the actual UI when useful; do not pass offpromo/final/03-gameplay-1936.pngor the AI likenesses in promo/final/04 and 08 as gameplay. Review each screenshot's age-suitability flag individually; never mark a sensitive scene suitable for all ages just to gain placement. If at least four genuinely qualify, mark them suitable for all ages; with fewer flagged, the game may not appear in some placements. Check the set's count and sizes withuv run tools/store_screenshots.py <shot1> … <shotN>(it must printDIMENSIONS OK).Prepare a trailer from the real build, not the M2 recruiting flythrough or concept-art target. Capture the map footage with "Capturing trailer footage" above (1920 x 1080, 60 fps, deterministic); the draft cut is still pending (#45), so this checklist does not provide a finished trailer. Keep the capture's
trailer.txt(build commit, seed and capture settings) with the cut. Steam requires a trailer and recommends that the first one be mostly gameplay; this project's rule (real build only) is stricter. Upload the highest resolution available, up to 1920 x 1080, at 30/29.97 or 60/59.94 fps and 5,000+ Kbps, in a .mov, .wmv or .mp4 container; H.264 video with AAC audio is preferred (Steamworks: Trailers). The game cannot be released while a trailer is still encoding.Complete all Steam Content Survey sections against the build and store page (OWNER STEP): general content, mature content and generative AI. Review war, terror and the Holocaust in both playable and bundled content; disclose all adult content uploaded in the build, even if it cannot be reached during play. Prepare honest answers and access instructions from what actually ships, not ratings guessed from the project's subject.
Regenerate
docs/ai-disclosure.mdwithuv run scripts/oss/ai_disclosure.py --output docs/ai-disclosure.mdand review its diff against both manifests. It lists explicitai_generated: trueasset rows only and does not answer the survey. Steam's current AI section concerns player-consumed content such as artwork, sound, narrative and localization, not efficiency tools alone. Check shipped content outside the manifest's media rows too; do not infer a complete survey from an empty media group. Keep the no-live-generation statement only while it remains true. Anowner-verifyasset is not cleared by appearing in generated disclosure text; do not change flags merely to make an answer convenient.Have the owner inspect the final previews, descriptions, media and survey answers together before submission. For itch.io, use
docs/m3-release.md's separate upload and save test; Steam image sizes are not itch.io requirements.
Official Steam sources checked 11 October 2026; re-check them before submission: