unity-cross-platform-local-build-orchestrator: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents (Codex, Cursor, GitHub Copilot, Claude Code, Windsurf, Aider, Zed, and others) working in this repository or running it from a Unity project that consumes it. Humans: this is a fast, accurate map. Deeper docs are linked at the bottom.

What this project is

A local (no-CI) cross-platform build-and-ship orchestrator for Unity games. One PowerShell command on a Windows PC bumps the version, builds Windows + Android, uploads to Steam + Google Play, commits and pushes, then drives a Mac on the same LAN over SSH to build and ship iOS (TestFlight) and macOS (Steam). It also has a WebGL-only submodule mode that OSS Unity demos vendor at Tools/.orchestrator to build → serve → force-push to GitHub Pages. It is not a UPM package and not a Unity runtime library: it is PowerShell 5.1 + macOS bash + Python scripts plus one Unity Editor C# CLI (Assets/Editor/BuildCli.cs, namespace BuildOrchestrator.Cli). License: MIT. It builds and ships Leap of Legends every week.

Golden rules (do not violate)

1. The platform split is hard. *.ps1 (Build-All, Build-WebGL, Deploy-GhPages, Tools/Steam/deploy.ps1) run on Windows PowerShell 5.1 only — not PowerShell 7, not bash. build_mac.sh and Tools/Steam/deploy_mac.sh run on macOS bash only. The Windows orchestrator drives the Mac over ssh -t; the Mac half never runs on Windows. Do not "port" a .ps1 to pwsh-isms or a .sh to Windows.
2. PowerShell 5.1 string discipline is load-bearing. Never put a non-ASCII character — especially an em-dash (—) — inside a double-quoted PowerShell string literal. PS 5.1 reads .ps1 as CP-1252, and the 3-byte UTF-8 em-dash derails quote matching into a misleading Missing '}' parse error. Keep .ps1 string literals ASCII (em-dashes in # comments are harmless). Use "${Var}:", never "$Var:" (the latter parses as a scoped-variable reference).
3. Secrets never live in the repo. All credentials go in the gitignored Tools/Build/config.local.json (each machine keeps its own copy), and the Play service-account JSON and Apple .p8 live outside the repo entirely. Windows-only fields (Steam, Play) can be blank on the Mac and vice-versa (mac.keychainPassword and all testFlight.* are Mac-only). Never echo -cliKeystorePass, -cliKeyaliasPass, or keychainPassword — the orchestrator masks them; keep it that way.
4. The defensive scar tissue is not boilerplate — it is documented production fixes. Do not "tidy away" $null = $proc.Handle (PS 5.1 drops the process handle → null ExitCode), the always-on Temp/UnityLockfile scrub, the Clean-Dir <8-char / bare-drive-root guard, the Burst-AOT cache-corruption auto-retry, the git fetch && git reset --hard @{u} && git clean -fd Mac-slave reset, the Mask-Sensitive redaction, or the JSON-report exit-code fallback. Each is in the CHANGELOG's "Known tool quirks worked around". Read docs/TROUBLESHOOTING.md before changing one.
5. Config is config.local.json, copied from config.example.json, and gitignored. Both machines need their own copy. Read the _comment fields in config.example.json before adding keys.
6. The WebGL -UnityMethod points at the CONSUMER's BuildCli.cs, not this repo's — e.g. SpriteBakerDemo.BuildTools.BuildCli.BuildWebGL. This repo's BuildCli.cs implements only Windows / MacOS / iOS / Android / BumpVersion / PrintVersion; there is no BuildWebGL here.