@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/codex/skills/funpixel-unity-game/references/fixes.md

@@ -0,0 +1,40 @@
+# The fixes that gave the most, and the phone pipeline
+
+From the Unity field report, sections 3 (lighting and materials), 6 (post-processing) and 8
+(performance). Every figure is from the Simulator or batch mode; none was measured on a real iPhone.
+
+## Fixes, before and after
+
+| Fix | Before → after |
+|---|---|
+| Split GLBs, ASTC for model textures | data 315 → 61 MB (app 386 → 106 MB with the size settings) |
+| Size settings (stripping High, engine stripping, IL2CPP OptimizeSize, every game) | engine 66–69 → 40–42 MB |
+| LZ4HC player data (about 25 minutes of work) | 126 → 94 MB installed |
+| Shaders, pipeline states and the Vase grab warmed on the first frames | worst frame of the tide 249 → 18.6 ms |
+| A throwaway run prewarmed behind the title | Play tap 87 → 1.9 ms |
+| Glyph warm-up | 183–266 ms (one game), 50–270 ms (another) → 17–20 ms first use |
+| No world drawn behind opaque menus; menus at 30 fps | 759 M → 0 3D px/s; CPU 94 → 32 ms/s; GC 52 → 2.4 KB/s |
+| A blur that stopped re-rendering the world (it did 20 times a second) | about a third of all draws gone |
+| Instanced sets culled, cheap shadow proxies, far LODs | World 1 376–448k → 116–224k triangles |
+| The next level built while a menu is up; every level warmed | 82–99 ms (and 398 ms) → under 34 ms |
+| A quality governor that judges the median of 90 frames, not the mean | one hitch no longer drops a resolution rung |
+
+## The phone pipeline the games used
+
+- No light probes or lightmaps in any game; mostly unlit or emissive materials.
+- One game's phone pipeline: no realtime shadows, MSAA 4×, HDR off, SRP Batcher on.
+  Post-processing is off on it and on another.
+- One game keeps bloom and ACES tone mapping in a night volume: an emissive strength of 3.5 blew
+  the bloom out (down to 2.2), and the HDR glow washed out the price text.
+- One game's URP bloom and depth-of-field shaders were found stripped from its builds: check a
+  post effect in the player build, not the Editor.
+- One port carries three.js's physical shading over in HLSL with quality tiers that drop shadows and
+  render scale on a hot or Low Power phone. Shed load through render scale, never MSAA (step 7).
+- No millisecond cost of any post effect was measured on a device.
+
+## Load
+
+Boot to title 0.32 s (one game); title interactive in 0.22 s and floor 1 playable 3.0 s after
+launch (another). About 14 MB of textures still load synchronously at boot in the second, which
+uses no Addressables (a third game's views branch loads each room through them). A lobby frame of 50 ms went once each screen's textures were preloaded
+while loading. Memory measured 117–174 MB in use; there is no memory budget yet.

package/plugins/codex/skills/funpixel-unity-game/references/from-a-web-game.md

@@ -0,0 +1,108 @@
+# A Unity game from a web game
+
+Five of the nine Unity games started as Funpixel web games (Pixi or three.js) and were rebuilt in
+Unity. That rebuild is hours of work when it has a fixed contract. Two of them
+each had a bit-exact C# core checked against golden traces recorded from the web sim, and both
+played end to end on the Simulator about 2 hours after kickoff. A third had a moving spec: it
+logged 85 entries in its iOS phase, agents built seven fixes from one-line descriptions, and their
+versions were torn out when the web game's author shipped different code. This page keeps the
+rebuild on the contract: shipped web code, goldens and `parity.md`. Field report sections 0, 1, 2
+and 10, and its dead ends.
+
+## What it takes
+
+- `CoreTests~/CoreTests.csproj` of your own (net8.0, NUnit) compiles the Core and its tests by link
+  and runs them outside Unity: `dotnet test CoreTests~` (Unity's bundled SDK lives under
+  `Unity.app/Contents/Resources/Scripting/DotNetSdk/`). A `CoreNetStandard/` project compiles Core
+  alone against netstandard2.1 to catch APIs Unity lacks.
+- Goldens: a short node script in the web game that runs its sim with fixed seeds and writes each
+  step's state as JSON; a C# test replays the same inputs and compares. The recorder and the trace
+  format are not in the report; this is the shape that worked.
+- `Rules.WebParity` and `Rules.Mobile`: rule sets in the Core. Mobile fixes and experiments are
+  default-off `Rules` flags; with its fix flags off, `Rules.Mobile` must equal `Rules.WebParity`
+  (a test of your own until the proposed `rules_guard` exists).
+- `parity.md`: the list of deviations from the shipped web build, one row each.
+- JS-math shims in the Core (`Js.Round`, `Js.Hypot`, fdlibm trig); until the proposed
+  `determinism_lint` exists, search the Core for `Math.Pow` and `float` by hand.
+- `npx @funpixel/tools capture --all --viewport phone` in the web game: its reference frames.
+- `dwebp` (WebP to PNG) and gltf-transform (decodes meshopt and WebP GLBs).
+- `CORE_API.md`, `WORLD_API.md`, `UI_API.md`: API docs written before the code, so parallel agents
+  compile against each other.
+
+## Procedure
+
+1. Freeze the reference. Take the shipped web code, not the design doc. Record golden traces from
+   the web sim under node, and capture reference frames of the web game at phone sizes. The
+   project adds `design/web-ref` and `parity.md`.
+2. Fix the content minimum before the rebuild. The owner asked for "at least 5 different levels":
+   one game grew from 1 letter to 5 in about 7 hours, another from 4 levels to 26.
+3. Fix colour space on day one to match the source renderer. Pixi and three.js without a linear
+   composer blend in gamma: four of the ports are Gamma. The one whose web build used a linear
+   composer stays Linear.
+4. Rebuild the Core first, in an asmdef with `noEngineReferences: true`. Copy web numbers verbatim
+   into `Scripts/Core/Config.cs`, carry every web test over 1:1 to NUnit (one port: 98 of 98
+   cases), and load the web's level JSON from `Resources/Data`. One port's core had 229 tests
+   about 50 minutes after kickoff.
+5. Apply the determinism kit while writing it, because C# and V8 disagree silently:
+
+   | In the web sim | C# trap | Use |
+   |---|---|---|
+   | JS numbers | not in the report | doubles |
+   | `Math.round` | `Math.Round` is banker's rounding | `Js.Round` |
+   | Array sort | `List.Sort` is unstable | a stable sort |
+   | `Math.sin` and other trig | `Math.Sin` differs from V8 on about 6% of inputs | fdlibm trig |
+   | `Math.hypot` | naive hypot differs on about 40% | `Js.Hypot` |
+   | `Math.pow` | not in the report | no `Math.Pow` in Core |
+
+   The proposed `determinism_lint` would also flag `Math.Exp`, `Math.Atan2`, `Mathf.*` and
+   `DateTime.Now` outside the shims; until it exists, search for them.
+6. Replay the goldens. Pass is 0 diffs at zero tolerance, and the same hash under IL2CPP. Where the
+   web's own math is not reproducible, bit-exact is not the rule: V8's libm (fdlibm `sin`, `log10`) is
+   compiled with fused multiply-adds on arm64, which C# cannot match bit for bit. One port (Oct 2026)
+   compares at a relative tolerance of 1e-9 with identical events, frames and results (80 runs), and
+   records it as a `parity.md` row.
+7. Record every deviation as a `parity.md` row and a default-off `Rules` flag, then check that
+   `Rules.Mobile` with its fix flags off gives digests identical to `Rules.WebParity`. This lets a
+   web bug be fixed without breaking parity.
+8. Reuse by this table:
+
+   | Reuse | What |
+   |---|---|
+   | As it is | sim rules, tests, tuning, level JSON (one port: 1,515 numbers bit-identical), save formats (33 fixtures of one port loaded byte-identical), sprite art, audio clips, key art |
+   | After conversion | WebP to PNG; WOFF2 to TTF with full fonts; meshopt and WebP GLBs decoded; loops rebuilt as OGG at exact sample counts; Web Audio synths re-rendered offline in C# |
+   | Redo | every view, HUD and menu (UGUI in code), input, haptics, app lifecycle, shaders, store art, icon, the IAP and economy layer |
+   | No path yet | online play: the kit's relay client is the JavaScript SDK (`funpixel-game-spine`), with no C# client. The one online Unity game vendors LiteNetLib with its own `Server~` and `Api~` matchmaker |
+
+9. Build the views in parallel behind the written APIs. One frame owner, `GameDriver`, runs
+   input, `sim.Update(dt)`, each `SimEvent` to every presenter, then `Render(alpha)`, so every
+   event is delivered exactly once. Content plugs in through a registry.
+10. Do not build a change from a one-line description. Rebuild what the web game shipped; anything
+    else is a deviation under step 7. The owner's direction: "make it same with what author
+    shipped on web".
+
+## Worked example
+
+A port from three.js (about 20,000 lines) to URP 3D, Gamma, portrait:
+1. A bit-exact core checked against goldens: seed 1 ended on the web's hash 1936916133.
+2. 358 core tests run with `dotnet test`.
+3. The web's 41 procedural audio cues were re-rendered offline in C#, correlation 0.999998
+   against Chromium.
+4. Played end to end on the Simulator 2h20 after kickoff.
+5. First TestFlight on day 4, submitted on day 5 (days counted from 25 Sep 2026).
+
+## Common mistakes
+
+- Improvising fixes: one port's agents built 8 props, a chain shockwave, a countdown, a
+  recolour and a 4 s PA delay that were torn out, and 3 of 6 earlier fixes were never re-audited
+  and still differed from the web.
+- `Math.Round` in the Core: banker's rounding drew 2 sparks where the web drew 3 (game not in the
+  report).
+- Tidying art that encodes a rule: an agent "cleaned up" one game's goal sill, which held the
+  balance up.
+- Linear colour space on a Pixi game: overlays about 2× too strong in one game until it
+  switched to Gamma.
+- Web MP3s as loops: they ran 1,245–1,997 samples long.
+- Importing a web GLB undecoded: glTFast imports it as nothing with no error; one game's 12
+  heads "did not import at all".
+- A UI with its own catch-up loop: One game's seal pick never reached audio or FX.
+- An ignored `.csproj`: One game's tests could not run from a fresh clone.

package/plugins/codex/skills/funpixel-unity-game/references/handing-off.md

@@ -0,0 +1,42 @@
+# What to hand an agent, and what earns trust
+
+From the Unity field report, section 14 (agents making Unity games) and the owner's direction table.
+
+## What to hand an agent
+
+| Today | Never alone |
+|---|---|
+| Rebuilding rules against golden traces; view layers behind written APIs | Art direction, icon and name |
+| Level generation with solvers; balance and economy sweeps | Judging audio or feel |
+| Size and performance passes with before/after numbers | Deciding prices |
+| Capture tooling; store listing pushes | Creating accounts or credentials |
+| TestFlight uploads, with approval | App Privacy; pressing Submit |
+| Audits by fresh read-only agents (one found 27 bugs, 5 high) | Editing `.claude/settings.json` or hooks |
+
+## Where an agent goes wrong first
+
+On what looks fine in its own captures: no sound (captures are silent), settings inherited from a
+cloned project, UI that overflows only at the owner's phone shape, keyboard wording, a level that
+breaks only when reached from the one before, and art that passes every gameplay gate while looking
+like grey blockout (one game's Worlds 3 and 4). Then on taste: it adds decoration the owner
+removes (5 reverts in 24 hours on one game) and grades its own art favourably. The answer to both is
+evidence a person can judge: the real frame at full size against the target and the competitors.
+
+## What the owner asked for again and again
+
+| The owner said | What the agent does without being asked |
+|---|---|
+| "where we are? what's left? how long?" | a tracker updated by tools (step, status, who, clock time), with the session id on every entry |
+| "did you sync to remote?" | push after green checks; rewrite status sections from repo state; a docs-freshness check at the end of each task |
+| "…as we did for other games" | carry every studio standard from the start and check parity with the sibling games: store fields, Restore placement |
+| "no workarounds, remove all leftovers" | a leftover sweep and a comment lint after each change |
+| "What actually you're asking me now?" | a report that ends with at most 3 numbered decisions, each with options, a default and a picture when it is visual |
+| "go do it by yourself" (website, Firebase) | the list of what an agent may do (bundle id, profile, Firebase, an upload with approval) against what only a person does (app record, App Privacy, agreements, the first purchase tick, Submit) |
+
+## What earns trust in a build an agent made
+
+The checks green, the launch with no flags clean, the smoke run reaching an ending on a stripped
+build, the archive pre-flight passed, and the owner's own 15-minute session on a phone. One game's
+build 1 was "mostly liked" and still unshippable: a production gate (fresh install, every level
+through the real flows, 7 kill-and-relaunch cycles, every setting persisted) found 4 more bugs behind
+1,377 green tests. A hand-off with a dirty worktree is refused: commit by path first.

package/plugins/codex/skills/funpixel-unity-game/references/performance.md

@@ -0,0 +1,59 @@
+# Frame time, memory, battery and size
+
+This skill turns a performance worry into a number measured in the player, before and after a fix. The failure it prevents is tuning against a figure that was never the game's: the Simulator's "16.7 ms average" was vsync while the real problem was a 240 ms first frame, and a "1.08 GB" build was the generated Xcode project around a 123 MB archive. No number here was measured on a real iPhone; all come from the Simulator or batch mode.
+
+## Tools
+
+- `npx @funpixel/tools unity probe --target mac|sim --path path.json`: the kit's in-player probe
+  (`com.funpixel.probe`, added by `unity probe install`; development builds only). It builds or reuses
+  the player through the Unity queue, plays the path, reads `ProfilerRecorder` per frame (frame, main,
+  render and work time, draws, SetPass, triangles, GC, memory), leaves capture and load frames out,
+  flags host spikes and judges the tier's budgets. Don't write a probe of your own:
+  `probe.md`.
+- Allocation tests under `dotnet test`: `GC.GetAllocatedBytesForCurrentThread()` inside
+  `#if NETCOREAPP`, because Mono has no per-thread counter.
+- `FunpixelProbe.WorkBegin/WorkEnd` around the game's own work, to tell its hitches from the host's.
+- Size: unzip the exported `.ipa` (or open the `.xcarchive`) and `du -sh` the `.app` and its `Data/`.
+- Not in the kit: the studio's size scripts, and the checks `alloc_quiet` (in a release player),
+  `size_budget`, `invisible_work`, `look_leak`, `resources_hygiene` (the Budgets table says what each
+  passes at). More measured fixes, light and post-processing: `fixes.md`.
+
+## Budgets
+
+| What | Budget | Check |
+|---|---|---|
+| Frame rate | 60 fps locked on iPhone 11 (A13); 120 Hz on ProMotion only when cool; menus 30 fps | |
+| Frames | first entry to a screen or level under 34 ms; none over 20 ms after warm-up; p99 at most 17.5 ms | `unity probe` |
+| GC | 0 B per warm sim step or quiet frame | `alloc_quiet` |
+| Draws, triangles | 120 and 250k per view (a 3D platformer) | |
+| Behind a full-screen menu | 0 world cameras or passes; 1 pass in play | `invisible_work` |
+| Look | `RenderSettings` and shared materials identical before and after each level and warm-up | `look_leak` |
+| Unpacked `.app` | 2D 80 MB, 3D 100 MB, engine 45 MB, at most 2 MiB unexplained growth per build (proposed; one 2D game is 133 MB) | `size_budget` |
+| `Resources/` | 0 bytes of test-only or Editor-only files | `resources_hygiene` |
+| Memory | 117–174 MB was measured; a budget is not in the report | |
+
+Per tier (phone, tablet, Mac): `unity probe --tier`, from `probe.md`.
+
+## Procedure
+
+1. Measure in a player build, with `unity probe`. Editor draws read 134–151 against 74–114 in the player. Under URP draws read 0 in some players, so read SetPass calls too.
+2. Attribute each slow frame before fixing it: game work, GC, the host Mac, or your own screenshot. A `ScreenCapture` costs 100–130 ms, and it and a Mac at load 36 were blamed on the game twice; game work in those frames was 0.4–0.7 ms. The probe reports hitches with their own work and skips 4 frames after each capture.
+3. Fix first-use stutters. Put every level id in the warm queue; warm glyphs, the first level's shaders (a ShaderVariantCollection, never `Shader.WarmupAllShaders`) and sounds behind the title; build the next level while a menu is up. Then run `look_leak`, since a warm-up can leave global state changed.
+4. Turn off invisible work: no world drawn behind opaque menus, and menus at 30 fps.
+5. Take allocations to 0 B. Use flat `struct` events in a reused list, no LINQ, closures or string building per frame, and rebuild text only on change. Measure in a release player, since 30–200 B per frame in the dev player is engine-side.
+6. Load: hold the splash on black until the scene is loaded and 10 smooth frames pass (1 s minimum, 3 s cap). Async-preload each screen's textures while loading, and prewarm a throwaway run behind the title: one game's Play tap went from 87 to 1.9 ms.
+7. Heat and battery: poll thermal state and Low Power Mode every 2 s. Hot or Low Power drops render scale from 0.83 to 0.66; critical caps matches at 30 fps; 120 Hz only when cool, falling back with a doubling back-off. Keep MSAA fixed, because changing it at runtime recompiled every pipeline state in one game (a 1.5 s frame). Turn off Unity's own thermal frame-rate adjust: two controllers on one knob.
+8. Size: measure the unpacked `.app` from the archive, with a delta against the last build. Apply the size settings (stripping High, engine stripping, IL2CPP OptimizeSize), then LZ4HC. Keep test files out of `Resources/`: the Unity test runner drops `PerformanceTestRun*.json` there, and it ships.
+9. Report every claim as before and after. The owner's direction ("ensure the performance is top") became `frame_budget` and `invisible_work` in every round.
+   The fixes that gave the most, each with its before and after: `fixes.md`.
+
+## Worked example
+
+A port from three.js, the whole seed-7 run. Over 17,246 frames, frames over 34 ms went from 17 to 2 and the worst frame from 98.4 to 19.0 ms; p99 was 18.2 ms. Warming shaders, pipeline states and the Vase grab on the first frames took the worst frame of the "tide" (a moment the report does not define) from 249 to 18.6 ms. The last 48 ms hitch was a missing glyph, and the last allocation was a "+N" badge string; the game holds 0 B over 600 frames. The quality governor now judges the median of 90 frames, so one hitch no longer drops a resolution rung.
+
+## Common mistakes
+
+- A short warm list. One game warmed World 1 only, so World 2 started with a 398 ms hitch.
+- A warm-up that leaves global state changed. One game's left fog and sky altered and every launch flashed violet for about 1 s; another kept references, so movers drew frozen.
+- Reading "Complete build size": in one game it was the Xcode project.
+- Test files in `Resources/`. One game's release export carried about 1 MB of test reference meshes.

package/plugins/codex/skills/funpixel-unity-game/references/probe.md

@@ -0,0 +1,80 @@
+# Measuring the player: com.funpixel.probe and funtools unity probe
+
+Five games each wrote a probe of their own (`HitchProbe`, `PerfProbe`, `PerfRecorder`, `PerfProbe` and `Hitch`, and one more). One of them also wrote a 661-line `RemotePlay.cs` for input over TCP. The kit now ships one package with both halves. Don't write another probe; give the package your game's facts instead.
+
+## Getting it into a project
+
+`npx @funpixel/tools unity probe install --project <dir>` adds one line to `Packages/manifest.json` and prints it. The line is a `file:` path to the kit's copy, relative to `Packages/`, the way a game references a local package. Pass `--git <url> --ref <tag>` for a pinned git URL; an unpinned one is refused. `--tests` also lists the package under `testables`; leave it off on a game whose test count is a baseline. `unity probe uninstall` takes the line out. Nothing is installed silently: `probe`, `play` and `capture` refuse a project without the line and say how to add it.
+
+What reaches a store build: nothing. The player assembly (`Funpixel.Probe.Player`) has define constraints `DEVELOPMENT_BUILD || UNITY_EDITOR || FUNPIXEL_PROBE` and `!FUNPIXEL_NO_PROBE`. The game calls `FunpixelProbe`, whose methods are `[Conditional]`, so in a release build the calls and their arguments are compiled away. `FUNPIXEL_PROBE` exists only for the capture build (below), and the package's build guard fails any build whose Player Settings carry it.
+
+## The game's side (optional, a few lines)
+
+| Call | What it gives |
+|---|---|
+| `FunpixelProbe.State("lives", () => lives)` | a fact `state` and a path's `expect` read |
+| `FunpixelProbe.View("shop", () => OpenShop())` | a view `capture --all` enters and shoots, in order |
+| `FunpixelProbe.Target("jump", () => jumpRect)` | a named tap target the EventSystem does not own (a HUD button) |
+| `FunpixelProbe.Command("level", a => …)` | a command of the game's own, e.g. `{"cmd": "level", "id": "3"}` |
+| `FunpixelProbe.WorkBegin()` / `WorkEnd()` | the game's own work per frame, which tells its hitches from the host's |
+| `FunpixelProbe.MarkCapture()` | the game took its own screenshot: that frame and the 4 after are left out |
+
+Without any of them the probe still measures, taps still reach UGUI buttons by name or text, and `capture --all` shoots the build's scenes.
+
+## A run
+
+`npx @funpixel/tools unity probe --project <dir> --target mac|sim --path path.json --seconds 20`:
+1. Builds a development player through the Unity queue, or reuses one when nothing under `Assets/`, `ProjectSettings/` or the package manifest changed since (`Builds/FunpixelProbe/<target>/`). The build changes no ProjectSettings and switches the active build target back.
+2. Launches it. A Mac player opens hidden, unfocused and muted, in a window of the tier's shape, so nothing lands on the owner's screen or speakers (`--visible`, `--sound`). A Simulator player goes on a fresh lease that is released at the end, or on `--udid` of a lease you hold.
+3. Plays the path, then keeps measuring until `--seconds`. A path is JSON: `{"steps": [{"tap": "Play"}, {"wait": 1500}, {"segment": "race"}, {"drag": [[100, 600], [300, 600]], "ms": 400}, {"key": "Space"}, {"scene": "Level2"}, {"shot": "level2"}, {"expect": {"game.lives": 3}}]}`. Coordinates are pixels of the game's own upright still (`"space": "pt"` for points).
+4. Reads the probe, judges it, stops the player, and writes `.funtools/unity/probe.json` (the verdict) beside `probe-<when>.frames.json` (every frame).
+
+Exit 0 within budget, 1 over budget or a step failed, 2 not observed, 3 error. `--port N` attaches to a running player instead, for example one a `unity play` session drove to a level.
+
+## What it measures and leaves out
+
+Per frame, from `ProfilerRecorder`, which works in development players where `UnityStats` reads 0 in batch mode:
+- the frame's wall time;
+- main and render thread time;
+- work: the player loop minus `WaitForTargetFPS` and the wait for present;
+- GPU time, when Player Settings "Frame Timing Stats" is on;
+- draws (Unity 6's standard plus null-geometry counters);
+- SetPass calls, batches and triangles;
+- GC allocated in the frame;
+- total, system and GC memory.
+
+Left out, and counted: the first 30 frames of the path, every capture frame and the 4 after it, and each scene load plus 2 frames. The longest load frame is judged as the first entry.
+
+## The budgets
+
+| Tier | p99 | longest frame | first entry | draws | SetPass | triangles | GC per frame | memory |
+|---|---|---|---|---|---|---|---|---|
+| phone | 17.5 ms | 20 ms | 34 ms | 120 | 150 | 250k | 256 B | 1024 MB |
+| tablet | 17.5 ms | 20 ms | 34 ms | 160 | 200 | 400k | 256 B | 1536 MB |
+| mac | 17.5 ms | 20 ms | 34 ms | 400 | 400 | 4M | 256 B | 3072 MB |
+
+The frame numbers are `frame_budget`; draws and triangles are one game's per view; SetPass and memory are another's tiers. The GC line allows the 30–200 B a development player allocates in the engine. Judge 0 B (`alloc_quiet`) in a release player or in tests. A Mac target is judged as `mac`, and a Simulator as `phone` or `tablet` by its device name. `--tier` and `--budget '{"draws": 200}'` (or a file, one budget per tier) override this.
+
+Three states, as on the web: a number the player did not report is "not observed", never a pass. A run under 120 measured frames does not judge frame time.
+
+## Host spikes
+
+A Simulator, or a Mac at load 36 or more, adds single long frames the game did not cause. Field report 1 saw 95–217 ms spikes with under 2 ms of game work. The probe flags a hitch as the host's when its own work is at most max(2 ms, 25% of the frame) and the render thread and GPU each took under half of it. "Own work" is `WorkBegin/WorkEnd` when the game uses them, else the player loop's work. The judged longest frame leaves flagged frames out; the raw maximum is printed beside it. The run also records the Mac's load and the Unity runs beside it. Work is wall time, so a host stall in the middle of the game's code still counts against the game: the flag only removes what clearly was not the game.
+
+## Remote play and pictures
+
+`unity play start` keeps one player running. Then:
+- `play tap 540 1600`, `play tap "Play"` (a target, a UI name, a path or its text) and `play drag x1 y1 x2 y2 400`;
+- `play key Space`, `play pad south` and `play act "stick 1 0 800"`;
+- `play state`, `play ui` (every pressable thing with its rect), `play views` and `play scene Level2`;
+- `play shot --out f.png`, upright at full resolution;
+- `play record --seconds 10`: frames plus a WAV of the game's own mix, through Unity's offline `AudioRenderer` after one game's `Recorder.cs`, joined into an MP4 when ffmpeg is there;
+- `play end`.
+
+Input goes in as Input System device state (touch, mouse with `--mouse`, keyboard, pad), so it takes the path a finger takes.
+
+`unity capture --all` shoots one still of each registered view, else each build scene. It uses a capture build without the development watermark, which a development build stamps into every frame, or an open play session, or `--dev`.
+
+## Not measured yet
+
+No phone has been measured. The package is built and its EditMode tests pass, but no run on a real project or Simulator is on record yet. Device runs (`devicectl`, the same environment flags) come later.

package/plugins/codex/skills/funpixel-unity-game/references/shared-mac.md

@@ -0,0 +1,121 @@
+# The shared Mac: Unity queue, Simulator leases, disk guard
+
+Agents in different sessions and repos built one Unity project at once, quit each other's
+Simulators and filled the disk to 99% (field reports, 10 Oct 2026). Each repo had grown its own
+lock (one in `tools/unity-run.sh`, one in `tools/unity_run.sh`), and no lock saw another. The kit
+now has one of each, shared by every session of this user on the Mac.
+
+## Unity: `funtools unity run`
+
+```
+funtools unity run -- -nographics -buildTarget iOS -executeMethod Setup.BuildSimulator
+funtools unity run --project ../my-game -- -nographics -runTests -testPlatform EditMode -testResults results.xml
+funtools unity jobs
+```
+
+- Everything after `--` goes to Unity. Added for you: `-batchmode`, `-quit` (never with `-runTests`:
+  the test runner exits by itself), `-projectPath` (the folder you are in, or `--project`) and
+  `-logFile Logs/funtools-unity-<when>-<id>.log` (or `--log`). The Editor is the one
+  `ProjectSettings/ProjectVersion.txt` names, from Unity Hub (`--unity` for another).
+- One job per project path at a time, across all repos, waiters in the order they came. While you
+  wait it prints who holds the project: session, pid, command and since when.
+- At most two Unity batch runs on the Mac (`--max`; `FUNTOOLS_UNITY_MAX`). A Unity batch run that no
+  funtools job started (a repo script, a terminal) counts too, and it is waited for, never stopped.
+- Liveness is progress, not time: the holder's log grows, or its processes (Unity, and the clang
+  and il2cpp under it during an IL2CPP build) use CPU. A holder that is gone, or made no progress for
+  20 minutes (`--stale-minutes`), is reclaimed with a message naming it. A fixed timer reclaimed
+  live builds and kept dead ones.
+- An Editor with the project open refuses the run: batch mode cannot open a project an Editor
+  holds. Save and quit it yourself, or work in your own worktree. funtools never quits or kills a Unity it did not open.
+- Exit code: Unity's own. 125 means nothing ran (refused, or `--max-wait` minutes passed). The log's
+  compile errors and exceptions are printed at the end; read the whole log before trusting a build.
+- Run it in the background for anything over a minute, and judge it by `funtools unity jobs`.
+
+## A live Editor: `funtools unity editor`
+
+```
+funtools unity bridge install                 # one line in Packages/manifest.json, printed
+funtools unity editor compile --open          # opens an Editor with the bridge, then compiles
+funtools unity editor console --since last    # what the console said since your last read
+funtools unity editor play; funtools unity editor shot --game --out shots/play.png; funtools unity editor stop
+funtools unity editor menu "Tools/Build Main Scene"
+funtools unity editor call Game.EditorTools.Setup.Configure
+funtools unity editor hierarchy
+funtools unity editor close                   # only the Editor funtools opened
+```
+
+- A batch launch costs 30–90 s and waits behind the project's lock; a call through the bridge takes
+  about a second, so an Editor that stays open while you work beats a launch per check. The rule
+  that kept every Editor closed is why the bridge went unused for 29 sessions.
+- One Editor per project. The agent that needs one opens it with `--open` (through the queue, with
+  MCP for Unity pinned to stdio for that session), keeps it while it works and closes it with
+  `funtools unity editor close`, which ends only the pid funtools recorded. An open Editor holds the
+  project, so batch runs on it are refused until it closes; work in your own worktree when another
+  agent's Editor is there.
+- The bridge is MCP for Unity 10.3.0 (CoplayDev/unity-mcp, MIT): the package in the project
+  (`funtools unity bridge install`, never added silently) and its server, which uv fetches once
+  (`brew install uv`). Each command starts its own server, routes it to the Editor whose status file
+  names this project and checks that Editor's project root before sending anything, so a call never
+  reaches the owner's Editor.
+- With no Editor open, `compile`, `call` and a `[MenuItem]` from the project's own scripts run as a
+  queued batch job and `console` reads the newest funtools log, each said as a fallback. `play`,
+  `stop`, `shot`, `hierarchy`, `add` and `save` need an Editor and say so; add `--open`.
+- An Editor someone else opened without the bridge is refused, never relaunched or quit: add the
+  package in its Package Manager, or wait until it is closed. `funtools unity bridge status` says
+  what is there. A Safe Mode, licence or sign-in dialog holds a fresh Editor; `--open` reports it.
+- Exit codes: 0 done, 1 failed (compile errors, Unity said no), 2 not observed (needs an Editor),
+  3 refused.
+
+## Simulators: `funtools sim lease`
+
+```
+udid=$(funtools sim lease --device "iPhone 17 Pro")   # the udid alone on stdout
+xcrun simctl install "$udid" Builds/dd/Build/Products/Release-iphonesimulator/Game.app
+xcrun simctl launch "$udid" com.studio.game -smoke
+funtools sim shot "$udid" --out shots/title.png
+funtools sim tap "$udid" 1311 603
+funtools sim release "$udid"
+```
+
+- A lease is a fresh simulator named `ft-lease-<id>`, created and booted headless for you, recorded
+  with its owner: the agent host's process. Use its udid in every call. `booted` picks whichever
+  device booted first, which may be another agent's.
+- `funtools sim release <udid>` shuts down and deletes that device and nothing else. Another live
+  agent's lease is refused without `--force`. `funtools sim list` shows the leases and owners.
+- `funtools sim gc` deletes leases whose owner has ended, and only `ft-lease-*` devices.
+- Never quit Simulator.app, never `xcrun simctl shutdown all`, never erase or delete a device you did
+  not lease. Each of those ended other agents' runs.
+
+## Landscape shots and taps
+
+The Simulator's screen stays portrait whatever the game does, so a landscape game comes back
+sideways and a point read off it lands elsewhere.
+
+- `funtools sim shot <udid>` turns the picture upright by the game's orientation: `--orientation`,
+  else the installed app's Info.plist (`--app <bundle id>`, or the one app running), else what the
+  lease last used. Unity's "Landscape Left" is iOS's landscape-right; the plist is the truth.
+- `funtools sim tap <udid> x y` presses that point of the upright picture (pixels; `--points` for
+  points), mapped onto the device, on a lease only. simctl cannot tap; the tap goes through
+  baguette, else idb (`--tool`). On the home screen a baguette tap reads as a long press; in an app
+  it is a tap. With neither installed: `brew install baguette`.
+
+## Disk: `funtools unity gc`
+
+```
+funtools unity gc ~/Documents/github --days 14
+funtools unity gc ~/Documents/github --days 14 --yes
+```
+
+Lists `Library/`, `Builds/`, `Temp/` and `Logs/` that nothing touched for `--days` (default 14),
+largest first. It is a dry run unless `--yes`, and skips any project Unity has open, whose queue lock
+is held or waited for, or whose `Temp/UnityLockfile` is fresh; each project is checked again just
+before deleting. Unity rebuilds `Library/` on the next open (minutes for a big project), so keep the
+one you are about to build.
+
+When the disk itself is low, look wider: `funtools unity gc --disk ~/Documents/github` reports free
+space against 20 GB (`--below`) and ranks what is safe to reclaim across this repo's finished
+worktrees, cargo `target/`, Xcode DerivedData, Unity folders and `.funtools/unity` scratch, each with
+its size, why it is safe and the one command. It deletes nothing unless you name a kind:
+`--apply --only worktrees` (or `derived-data`, `unity`, `scratch`). A worktree with uncommitted
+changes or a process in it is "in use" and never touched; `target/` is reclaimed only by
+`scripts/target-gc.sh`. Exit 1 below the threshold is advice, not a failure.

package/plugins/codex/skills/funpixel-unity-game/references/traps.md

@@ -0,0 +1,108 @@
+# Unity traps, one line each
+
+Unity 6000.6.0f1 on iOS, from the field report §10 (and §9 for the batch runs). Each one failed
+silently or cost a build in one of the nine games. The skill that owns the fix is named where there
+is one.
+
+## Checked by `funtools doctor`
+
+Run it at project start and before every build: it reads the project's files and this Mac, never
+starts Unity, and prints each finding with its fix. One line per trap it catches:
+
+- Git LFS pointer files where binaries belong (FSBTool "Failed decoding audio clip", blank textures): fails, names the repository to pull in.
+- `activeInputHandler: 0`, the old Input Manager alone, on an iOS or Android project (no touch in a player build): fails.
+- `UnityEngine.Input` calls on a project set to the Input System only (each throws): fails.
+- The Input System hooked at `AfterAssembliesLoaded` (throws on iOS; hook on first read): warns.
+- TextMesh Pro used with no Essential Resources (`CreateFontAsset` returns null): fails; a batch-mode ImportPackage of them (hangs): warns.
+- A camera in a scene or made in code with nothing adding an AudioListener (a silent build): warns.
+- `Shader.WarmupAllShaders` (segfaults with URP keyword spaces; warm a ShaderVariantCollection): fails on URP.
+- A GLB glTFast cannot decode (meshopt, Draco or Basis without its decoder package, WebP ever): fails, because it imports as nothing.
+- `Shader.Find` of a project shader nothing references (null in a build): warns.
+- `enableWordWrapping`, a bare `new RenderParams{}`, runtime `QualitySettings.antiAliasing`, `-quit` with `-runTests`: warn.
+- ProjectSettings drifted from the project's setup method (one game's iOS graphics APIs went back to automatic three times): warns; build through `Setup.Configure`.
+- A build module a target needs (Mac IL2CPP and Windows were missing): warns with the Unity Hub line.
+- No distribution certificate, Xcode account or App Store Connect key on an iOS project (each blocks TestFlight): warns.
+
+## Build and import
+
+- A mipmapped texture that is not a power of two ships as RGBA32 even with an ASTC override, and Unity
+  says nothing about it (`funpixel-art`, Unity page).
+- glTFast decodes textures embedded in a GLB to RGBA32; its "latest" tag pointed at an experimental
+  7.0, so pin 6.20 (`funpixel-3d`, Unity page).
+- `UnityRuntime.framework`'s plist says iOS 15.0 and its binary 16.0: ITMS-90208: stamp each embedded framework's minimum OS with the app's in a post-process step.
+- High stripping removes an assembly reached only through `RuntimeInitializeOnLoadMethod`, and Unity
+  ignores a package's own `link.xml` (hand that file to the linker yourself).
+- TMP outline and underlay variants of materials made at runtime are stripped, and so are
+  `shader_feature` variants: use `multi_compile_local`.
+- TMP lives in uGUI 2.x, not a package of its own; its Essential Resources still go in `Assets/TextMesh Pro`.
+- Burst can time out under heavy host load; never ship that export.
+- Re-importing an atlas regenerates sprite ids, and a PNG of a new size keeps the old sprite rect, so
+  Unity drops the sprite.
+- iOS caches launch storyboards by name across updates: rename the storyboard.
+- A project can be URP with `GraphicsSettings` saying none: the monorepo games assign the URP asset only
+  in `QualitySettings` (`m_CustomRenderPipeline: {fileID: 0}`), while others set it in
+  `GraphicsSettings`. Read both before calling a project built-in.
+- A WebGL build compressed with Brotli fails on a phone over the Mac's LAN address
+  (`ERR_CONTENT_DECODING_FAILED`: Brotli needs https or localhost): serve it with `funtools serve`,
+  which falls back to gzip there.
+- Addressables bundles built uncompressed (for a CDN to Brotli) weigh about twice as much from a
+  server that sends them raw (one game's Room 1: 99.7 MB against 47.3 MB). `funtools serve`
+  compresses them on the fly as a CDN would, so its sizes and load times are what a player gets;
+  `--no-compress` shows the raw weight.
+
+## Runtime
+
+- Mono never sees `simctl launch` arguments: read them natively.
+- PlayerPrefs reads the launch-argument domain first: a flag `-coins` shadows the save key `coins`.
+- A Unity API call in a field initializer throws: move it to `Start`.
+- `OnApplicationPause(true)` also fires on resign-active (Control Center, Siri, call banners, Face ID).
+- `StopCoroutine` does not dispose the iterator, so a `finally` in a stopped coroutine never runs.
+- Static initialisation order: a cache declared after the colours it used threw
+  TypeInitializationException, and no build booted for about 7 hours.
+- Glyphs added at runtime cost a frame (48 ms): warm them behind the title.
+- `Screen.cutouts` allocates on every call: read it when the screen changes.
+- `preserveAspect` fits around the pivot; a `Slider` stretches to the row height; stretch anchors
+  plus a non-zero `sizeDelta` double the width.
+- The first scene load can eat about 1 s of a startup animation (wait for it before one starts).
+- Unity 6 renamed the draw-call profiler counter, so an old probe reads 0.
+- C# `Math.Round` is banker's rounding, `List.Sort` is unstable, `Math.Sin` differs from V8 on about
+  6% of inputs and a naive hypot on about 40% (`references/from-a-web-game.md`).
+
+## Captures, logs and the Editor
+
+- `Debug.Log` on iOS goes to stdout, not the system log: launch with `--console-pty`.
+- `Object.Destroy` does nothing in edit-mode captures: use `DestroyImmediate`.
+- `CaptureScreenshotIntoRenderTexture` is upside down on Metal, and `ScreenCapture` stalls the next
+  frames.
+- Frames a judge scores come from a capture rig, not the Editor (Oct 2026):
+  - a player build with a scripting define that turns the launch flags on and is not a development
+    build, because a development build stamps its watermark and console into every frame;
+  - `-shotscale 2` (passed to `ScreenCapture.CaptureScreenshot`'s supersize) for a full-resolution phone
+    frame from a half-size window (1172×2532 from 586×1266);
+  - a driver that plays like a person (holds, eases, misses a little), not a perfect line;
+  - a separate development build for measuring (`funtools unity probe`: SetPass calls, triangles, GC
+    per frame), whose watermark is fine because no one judges those frames; `funtools unity capture
+    --all` builds the no-watermark variant itself (`FUNPIXEL_PROBE` for that build only).
+- Unity wipes `Temp/` on launch, so a lock goes in `Logs/`; one Editor per project.
+- Every headless run rewrites ProjectSettings, AudioManager and TMP font assets, and leaves
+  `Assets/Resources/PerformanceTestRun*.json`, which ships.
+- Never pass `-quit` with a play-mode `-executeMethod` either (§9): the run ends Unity itself.
+- Never pipe a build or a check through `| tail`: it hid a failing compile and a commit went through.
+- Unity's NUnit is old: no `Assert.Multiple`, no `Does.Contain` on an enum.
+
+## Git
+
+- A file written outside Unity needs its `.meta` committed, or its GUID changes per checkout.
+- TMP dynamic font assets are rewritten by every batch run and conflict on every merge: keep shipped
+  fonts static, or clear them after captures.
+- The root `.gitignore`'s `*.csproj` silently drops hand-written test and server projects.
+- A copied project keeps its source's identity: one game's `.gitattributes` names its source's
+  paths, its Android id is still Unity's template `com.UnityTechnologies…urpblank`, and standalone ids
+  are left as `com.DefaultCompany.2D-URP`. Check the ids and `.gitattributes` against the game's name.
+
+## Never changed by a script without a person looking
+
+Signing identity and team; the bundle id; `ITSAppUsesNonExemptEncryption` (the owner: "do not flip");
+App Privacy answers; the App Store Connect submission and the first purchase tick; the agent's own
+settings and hooks; anything in a build pipeline every game shares without a per-game opt-in marker;
+deleting "unused" assets: an agent deleted 20 files the game loads by name.