A Civilization-style strategy game about governing Israel from 15 May 1948. Real ministers, real map, every fact sourced. Unity + deterministic C# sim.
Contributing to Statecraft: Israel
Thanks for helping. This file covers how to get set up, the rules every change follows, and how pull requests are reviewed.
Ways to help
- Code: the C# simulation (
sim/), the Unity client (unity/), and the Python map and data tools (tools/). - History: fact-checking, sourcing, and drafting new events, ministers and dates (
content/). - Art: 3D settlements, vegetation and units for the era-correct look. See the roadmap in the README.
- Design and writing: event choices, balance, and the text the player reads.
If you're unsure where to start, open an issue first and describe what you want to do.
Picking an issue. Start with an open good first issue. If you read Hebrew, you can take one of the native-speaker review slices. Comment "Taking this" before you start. Issues with the label ready for a contributor come from the Task issue form: a goal, the files likely touched, the commands that must pass, the agreed sources, what needs the maintainer's sign-off, and whether Unity is needed. When every field is filled, you can finish the work without asking the maintainer. If a field is missing or unclear, ask in the issue before you start. The label needs-unity marks an issue you cannot finish without Unity (see "Without Unity" in docs/dev-setup.md); area: unity only says the issue touches unity/.
Claims. Nobody is assigned on GitHub: your "Taking this" comment is the claim. When an issue has several parts (rows, files, a slice), say which part you take, so the rest stays open to others.
help wantedmeans nobody holds the issue. The label comes off while someone has an active claim (activity in the last 7 days, or an open pull request for it) and goes back on when the claim ends. A maintainer comment that says a part is free ("Free now", "Open to anyone") is current, even below an older claim.- At most 10 claims without a pull request. You can hold up to 10 claimed issues for which you haven't opened a pull request yet. Issues where you have opened a pull request for the issue don't count toward the 10, and there's no limit on those.
- 7 days. A claim with no activity from its claimant on the issue or its pull request for 7 days is freed with a comment, and the issue is open to anyone again.
- Issues paused until after the MVP, or waiting on an owner ruling, say so in the issue; start only the part a maintainer comment opens (for example the research part). Some research issues ask for "a person's check": a person opens each source. AI-assisted contributors may do these person-only steps too, such as source checks, device checks and native Hebrew reads (the owner, 4 November 2026: "allow ai assisted contributers"). Disclose the AI assistance in the pull request's "AI assistance" section, say what you checked and how (which source, which device, which strings), and you stay responsible for the check. Such a check also closes an item tagged "a person's check pending". Asked whether an item tagged "a person's check pending" counts as done once an AI-assisted contributor does and reports that check, the owner answered "Done if disclosed (Recommended)" (4 November 2026); the chosen option read: "Yes, when the PR discloses the AI help and says exactly what was opened and checked; the tag becomes 'checked by , AI-assisted'." The same holds for the
reviewed_bysign-off and the Hebrewagent-checkedflags (docs/CONTENT_POLICY.md, section 2, rules 6 and 7).
Licence of your contribution
There is no CLA and no sign-off. By opening a pull request you agree that your contribution is licensed as follows:
- code: to the project maintainer, Eyal Golan, under MIT, which lets him give permission for commercial use; everyone else gets it with the rest of the code, under PolyForm Noncommercial 1.0.0;
content/under CC BY-SA 4.0;- other original material under CC BY 4.0.
For content/ and the other original material this is "inbound = outbound", as GitHub's Terms of Service (section D.6) also say. For code it is not: code comes in under MIT to the maintainer and goes out under PolyForm Noncommercial 1.0.0 (the owner's decision of 22 October 2026). This wording is the owner's choice, not legal advice, and it should be checked by a lawyer.
LICENSING.md lists which licence covers each path. Only contribute work you have the right to license this way. If you add a third-party file, include its source and licence. Material from the Unity Asset Store is never accepted.
The licence line in the pull request. The template's last box, "I contribute this under the terms in CONTRIBUTING.md", is asked of everyone; please tick it.
- Docs only: the maintainer may merge without the tick, relying on GitHub's Terms of Service, section D.6 ("inbound = outbound"). That means every changed path is in
docs/(exceptdocs/sources/),research_notes/,reports/,changelog.d/or a root*.mdfile other thanLICENSING.mdandTHIRD-PARTY-NOTICES.md, or is one of the UI text and layout files of the CC BY 4.0 row:unity/Assets/UI/*.uxml,*.ussandstrings.en.yaml. No image, audio, video, 3D model, font, PDF or other binary file anywhere. - Everything else needs the tick, code included: code comes in under MIT to the maintainer, which is not the licence it goes out under, so GitHub's terms do not cover it. That means
sim/,tools/,scripts/,.github/,.gitignore,promo/*.pyand everyunity/Assets/file of the code row (scripts, tests, scenes, prefabs,.metafiles,strings.he.yaml,WebGLTemplates/and the rest), as well ascontent/,ASSETS.yaml, the licence and notice files, art, audio, video, models, fonts, materials, shaders,.assetfiles,unity/Assets/Settings/,unity/Assets/StreamingAssets/,unity/Assets/UI/Fonts/,unity/Assets/UI/Portraits/, Shader Graphs,spikes/,unity/Packages/,unity/ProjectSettings/and any other path. A pull request that mixes the two needs it too.
These are the owner's decisions of 22 October 2026 (D2 in docs/oss/DECISIONS.md).
Setup
Follow docs/dev-setup.md. In short:
- Sim and tools only: .NET SDK 10 and
uv. Unity is not needed. - Unity work: Unity 6000.3.25f1 (6.3 LTS) with Web Build Support, a free Unity account, and running
uv run tools/build_sim_for_unity.pybefore you openunity/.
Rules every change follows
- Game rules live in the sim, not in Unity. Unity draws, reads input and calls sim helpers. A rule written in a presenter is a bug.
- Determinism. The same seed and commands must give the same state hash.
- If your change alters the simulation on purpose, the golden hashes will change.
- Record the new values everywhere they are pinned (see docs/determinism.md), with a one-line reason in its history table.
- Tests first. Add or change a test that fails without your change, then make it pass. Run:
dotnet test sim/Statecraft.sln, which must pass with 0 warnings (warnings are errors);- the tools tests (they need the .NET SDK too: one runs the sim's release gate):
uv run --with pytest==9.1.1 --with rasterio==1.5.2 --with numpy==2.5.3 --with pyyaml==6.0.3 --with pillow==12.3.0 --with requests==2.32.5 --with pyproj==3.8.0 pytest tools/tests -q; - the repository policy checks:
uv run --with pytest==9.1.1 --with pyyaml==6.0.3 --with requests==2.32.5 pytest scripts/oss/tests -qanduv run scripts/oss/check_repo.py(the command CI runs); - Unity EditMode tests, if you touched
unity/(-buildTarget OSXUniversalkeeps an earlier WebGL build from leaving the editor on the wrong platform). First the Unity-MCP warm-up, every time (it exits by itself, so no-quit; it fetches the plugin's DLLs and adds its defines, which the tests need loaded and the post-build cleanup removes):"$UNITY" -batchmode -CI false -GITHUB_ACTIONS false -TF_BUILD false -projectPath unity -buildTarget OSXUniversal -executeMethod Statecraft.Game.EditorTools.UnityMcpGuard.WarmUp -logFile unity-warmup.log, then"$UNITY" -batchmode -CI false -GITHUB_ACTIONS false -TF_BUILD false -projectPath unity -buildTarget OSXUniversal -runTests -testPlatform EditMode -testResults "$PWD/unity-editmode.xml" -logFile unity-tests.log. There must be 0warning CSin the log.
- Text the player sees has no internal ids, gives dates as "15 May 1948", and shows money as "IL 1.2m" or "$1.2m". The tests enforce this.
- Keep the pull request focused: one change per PR, and no unrelated refactors.
- Changelog. If you change
sim/,content/,translations/,unity/Assets/,unity/ProjectSettings/orunity/Packages/(tests excepted, andtranslations/README.md), add a new filechangelog.d/<branch-or-issue>.mdwith your entry as a bullet (changelog.d/README.md); fragments never conflict with other pull requests. A line under## [Unreleased]in CHANGELOG.md still works. CI'sChangelogjob checks it; the maintainer can add theno-changeloglabel to a change no player would notice. - Rule IDs. A rule that has an ID (
R-ECON-014, defined indocs/rules/, see docs/rules/README.md) is cited by that ID in the test that checks it (// R-ECON-014), in YAML comments that depend on it, and in the PR body ("implements R-ECON-014").uv run scripts/oss/rule_ids.pyfails on a rule with no citing test (it counts citations only insim/Statecraft.Sim.Tests/) and on a citation of an ID that does not exist (it looks for cited IDs insim/**/*.cs,unity/Assets/**/*.csandcontent/**/*.yaml). It reads repository files only, so it cannot check the PR body. - Provenance. Every new image, video, font, audio, 3D-model, map-data, PDF or Unity-package file, and every file Git treats as binary, must be covered by a matching glob rule in ASSETS.yaml or ASSETS.portraits.yaml (the generated portrait records; the check reads the rules of both files together). CI's
Repo policyjob fails on a file with no matching rule. - Roadmap status. If your PR finishes a Phase 1 PR or a whole phase of #374, update the Roadmap table in README.md and the same table in README.he.md, and tick the item in #374 if you can (otherwise ask the maintainer in the PR). The Phase 1 count must match in both files;
test_readme.pychecks it.
History and content rules
- Adding an event? Follow docs/WRITING_EVENTS.md: every field, what the loader rejects, and how to run the tests.
- Adding a player-facing string? Follow docs/UX_GLOSSARY.md, docs/WRITING_UI.md and docs/WRITING_UI_HE.md. They bind new strings from 22 October 2026 (#622), and reviewers check against them. An existing string that doesn't match them changes one PR at a time, never in a sweep: name the guide rule, change
strings.en.yamlandstrings.he.yamltogether, and send the Hebrew to the native read on #564. - Every historical fact needs a source. Every event, minister, office term, historical date and number in
content/carriessources:with a URL and the date you checked it. A claim without a source can't be merged. Game-balance values (for exampleattention_per_turn) are design choices, not facts, and need no source. Mark them with aDESIGN VALUEcomment orstatus: design, or keep them in a file whose note says its values are game balance, ascontent/rules.yamldoes. - No invented quotes. Paraphrase, and never put words in a real person's mouth.
- Framing. The project tells the story from the Israeli perspective. Contested narratives are not shown as parallel accounts.
- Sensitive events. Events tagged
holocaust,terror,massacre,war-casualtiesordisplacementneed the maintainer's sensitivity review before they can ship. A release build refuses to package until that review is done. - Reporting a mistake. Use the Historical accuracy issue form; it asks for the source that shows the correct fact.
AI-assisted contributions
AI-assisted work is welcome. Say so in the pull request: which parts, and how you checked them. You are responsible for every line you submit. For content, check every fact against its source yourself, and never take one from an AI tool unchecked.
Working with an AI agent in Unity (Unity-MCP)
Unity-MCP (Apache-2.0) is the project's standard way to let an AI agent (Claude Code, Cursor, Copilot and others) work in the Unity editor: read the Console, inspect scenes, run tests. It runs locally, with no account and no cloud.
- Install: nothing to do. The package (
com.ivanmurzak.unity.mcp0.93.3) and the OpenUPM registry it needs are already inunity/Packages/manifest.json. On the first open, the plugin downloads its NuGet DLLs from nuget.org intoAssets/Plugins/NuGet/(git-ignored) and its local server,gamedev-mcp-server, from the plugin's GitHub releases intoLibrary/. Then Unity compiles once more. - Open Window → AI Game Developer — MCP.
- Connection: Custom, held by the project.
UnityMcpGuardkeeps the plugin in Custom (local) mode in every editor, so Cloud is disabled. If you pick Cloud in the window, the setting goes back to Custom when the plugin saves and nothing connects to the cloud, but the window can keep showing Cloud (with its sign-in section) and the local server stops: reopen the window and click Start. Never sign in: nothing in this project needs an ai-game.dev account. The plugin's ownUNITY_MCP_CONNECTION_MODEvariable would override this; the project doesn't support that. Your settings file,unity/UserSettings/AI-Game-Developer-Config.json(per user, git-ignored, holds your local token), may still say Cloud: the project's choice is applied in memory and never written there, so don't edit the file by hand. - Server URL: leave it as the window shows it, with the transport
http. The port is derived from your project's path, so every clone and worktree gets its own server. A second editor finds an already-running server on its port and attaches to it, so two projects never share one as long as their ports differ. - Authorization: token, held by the project. The local server checks a Bearer token (your local token). Never choose "Account sign-in" (oauth): it makes the local server validate tokens online against ai-game.dev.
- The local server starts with the editor. If you don't use an agent, turn off Keep server running in the window.
- Choose your agent and click Configure, or click Generate to write skill files instead. Configure writes the server URL and the Bearer header into
unity/.mcp.json(for Claude Code). Start your agent inunity/, or point it at that file. The files these steps write (.mcp.json,unity/.claude/and the other agent folders) are git-ignored; don't commit them. - The rules still apply: no game rules in Unity (they live in the sim), tests first, sources for every fact in
content/, and disclose the AI assistance in your pull request (see "Rules every change follows" and "AI-assisted contributions" above). - Security: the local server lets the agent run editor actions, including editing files and executing code in the editor. It listens on loopback only and rejects browser pages from other sites, and the token keeps other local programs out. Keep it local: never expose the server's port (no port forwarding, tunnels or
0.0.0.0binds), and stop the server when you're done. - Not connecting? Connect only works in an interactive editor: in batch mode (tests and builds) the plugin is held offline on purpose, and its windows don't open. Check that the server shows Running on the port in the Server URL, then click Connect. The first attempt can fail while the server is still starting; the plugin retries. If the editor is stopped without quitting,
gamedev-mcp-servercan stay behind on the port: stop it with the window's Stop button or by its PID. - Batch mode and builds:
UnityMcpGuard(unity/Assets/Editor/UnityMcpGuard.cs) keeps the plugin from connecting, starting its server or opening a window in batch mode (tests and builds), and drops its assemblies from every player build. The browser build's golden hashes don't change. Run batch Unity with-CI false -GITHUB_ACTIONS false -TF_BUILD false(as every command in these docs does): the plugin treatsCI,GITHUB_ACTIONSorTF_BUILDset totruein the environment as CI (every CI runner sets at least one of them, and so do some agent shells), and then it skips its NuGet download but still adds its defines, and a fresh clone fails to compile. The update popup is off for the team (unity/ProjectSettings/AI-Game-Developer-UpdateSettings.asset); version bumps come by pull request. On every Unity-MCP version bump, run the Unity EditMode tests in batch mode and paste theUnityMcpGuardTestsresult in the pull request. - Leave one change uncommitted: the plugin adds
UNITY_MCP_READY;UNITY_MCP_DEPS_7to the scripting defines inunity/ProjectSettings/ProjectSettings.assetonce its DLLs are in place. Don't commit that change: on a fresh clone the defines would arrive before the DLLs, and the plugin wouldn't compile. A policy test refuses it. The post-build cleanup (git checkout -- unity/Assets/Settings unity/ProjectSettings/ProjectSettings.asset) drops the defines too; the plugin adds them back on the next open, at the cost of one extra compile. A batch test run that starts without them runs its tests before the plugin loads, and theUnityMcpGuardTestsfail ("its editor assembly must be loaded"): run the warm-up above first. - Per-user state the plugin keeps: besides the settings file, it stores
Unity-MCP.MainWindow.InitializedandUnity_MCP_SelectedAiAgentin this project's editor PlayerPrefs, and the server's PID and update-check state in EditorPrefs.
Pull requests
- Base your branch on
main. History onmainis protected, so no force-pushes. - In the description, say what changed and why. Paste the test commands you ran and their output; a description of the output doesn't count.
- Visual changes: matched before/after screenshots are required in the PR description for any change a player can see (models, the map, characters, the UI or the website). Keep the game state, camera and zoom the same; match resolution and lighting when relevant. Label the changed area and show important visual side effects. For changes with no visible effect, explain why screenshots are not applicable, and add a short video when motion helps review. Prefer GitHub PR attachments that reviewers can open over private Library links or committing review-only captures to the repository.
- The maintainer reviews every PR (
.github/CODEOWNERS). Once the maintainer approves your latest commit and the required checks on it have passed (Sim (dotnet test),Tools (pytest),Repo policy,Changelog),.github/workflows/merge-approved.ymlsquash-merges it within about ten minutes, as long as the PR is not a draft, has no merge conflict and, unless the maintainer opened it, has the licence line ticked ("[x] I contribute this under the terms in"). A new push needs a new approval.
What CI runs
Every pull request and every push to main runs Sim (dotnet test), Tools (pytest), Repo policy, and, on pull requests, Changelog. The exception is a squash merge made by .github/workflows/merge-approved.yml: GitHub starts no workflow for a merge made with that workflow's token, so the already-checked pull request head is not checked again on main. The Changelog job also runs scripts/oss/reviewed_by_guard.py: a commit with an AI co-author trailer may not remove a reviewed_by or reviewed_on line in content/, and may add or change one only when the pull request's "AI assistance" section discloses the AI help and names the check (a person signs a row off, #375; asked whether an AI-assisted contributor's source check counts as the reviewed_by sign-off, the owner answered "Yes, it counts" (4 November 2026)). The guard reads that section from the event that started the run, so push again after you edit it. The jobs use no secrets, call no paid API, run no AI agent and push nothing.
The policy checks also refuse:
- a
docs/gdd/*.mdfeature file other thanTEMPLATE.mdorREADME.mdthat does not follow the template: all seven sections must be present and non-empty,Done whenneeds a bullet, and placeholders and unfinished markers are forbidden. Numbers inRulesandDone whenneed a recognised unit or(unitless); years and dates inPlayer story,Rules,Data touchedandDone whenneed a defined[S<n>]source on the same line, and linked source entries need a checked date; - any tracked file larger than 10 MiB;
- an absolute user-home path in text, or a user-home, temporary or agent-session path embedded in a binary, unless a reviewed row in
scripts/oss/allow.yamlexempts it; - a
secrets.*reference in a.github/workflows/*.ymlfile other thansteam-upload.yml; - an
owner/repo@refaction reference in.github/workflows/*.ymlthat is not pinned to a full commit SHA (local./anddocker://actions are not checked); action pins inci.yml,player-golden.ymlandsteam-upload.ymlalso need an exact# vX.Y.Zcomment; - a tracked file stored with CRLF instead of LF;
- a broken relative link in a Markdown file; or
- an absolute symlink or a relative symlink that resolves outside the repository.
Unity EditMode tests are not in CI. Running Unity in CI needs the maintainer's Unity account credentials stored as repository secrets. GitHub never gives secrets to pull requests from forks, so the job could not run on the pull requests that most need it, and those credentials would sit on machines that run outside code. So the Unity tests are a local gate: paste their result in your PR, and the maintainer re-runs them before merging any change under unity/. A future Unity job must run Unity with -CI false -GITHUB_ACTIONS false -TF_BUILD false (runners set CI=true, and GitHub Actions and Azure Pipelines also set GITHUB_ACTIONS=true or TF_BUILD=true; the Unity-MCP plugin treats any of them as CI, then skips its NuGet download and fails to compile), or commit the plugin's DLLs.
Security
Never commit keys, tokens or .env files. Secret scanning and push protection are on. To report a vulnerability, use Security → Report a vulnerability on the repository page (GitHub private reporting); don't open a public issue. What is in scope and what to expect: SECURITY.md. How the maintainer reviews outside pull requests without running their code: docs/UNTRUSTED_PR_REVIEW.md.
Conduct
Be respectful. Argue about facts with sources, not with people. Political or personal attacks are not tolerated. The full CODE_OF_CONDUCT.md applies in every project space, including its section on historical and political discussion. The content rules, and how to dispute a fact, are in docs/CONTENT_POLICY.md. A short sourcing checklist, including what to do when a source cannot be reached, is in docs/SOURCING_FOR_CONTRIBUTORS.md.