@funpixel/tools 0.0.0-stage → 0.1.0

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 | Game |
+|---|---|---|
+| Split GLBs, ASTC for model textures | data 315 → 61 MB (app 386 → 106 MB with the size settings) | Noodle Nights |
+| Size settings (stripping High, engine stripping, IL2CPP OptimizeSize) | engine 66–69 → 40–42 MB | all |
+| LZ4HC player data (about 25 minutes of work) | 126 → 94 MB installed | The Hot Gates |
+| Shaders, pipeline states and the Vase grab warmed on the first frames | worst frame of the tide 249 → 18.6 ms | The Hot Gates |
+| A throwaway run prewarmed behind the title | Play tap 87 → 1.9 ms | The Hot Gates |
+| Glyph warm-up | 183–266 ms (Dawg Ball), 50–270 ms (Pocket Crew) → 17–20 ms first use | Dawg Ball, Pocket Crew |
+| 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 | Dawg Ball |
+| A blur that stopped re-rendering the world (it did 20 times a second) | about a third of all draws gone | Pocket Crew |
+| Instanced sets culled, cheap shadow proxies, far LODs | World 1 376–448k → 116–224k triangles | Pocket Crew |
+| The next level built while a menu is up; every level warmed | 82–99 ms (and 398 ms) → under 34 ms | Pocket Crew |
+| A quality governor that judges the median of 90 frames, not the mean | one hitch no longer drops a resolution rung | The Hot Gates |
+
+## The phone pipeline the games used
+
+- No light probes or lightmaps in any game; mostly unlit or emissive materials.
+- The Hot Gates' phone pipeline: no realtime shadows, MSAA 4×, HDR off, SRP Batcher on.
+  Post-processing is off on The Hot Gates and Dawg Ball.
+- Noodle Nights 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.
+- Scrap Riot'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.
+- Pocket Crew 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 (The Hot Gates); title interactive in 0.22 s and floor 1 playable 3.0 s after
+launch (Scrap Riot). About 14 MB of textures still load synchronously at boot in Scrap Riot, which
+uses no Addressables (Gallery Heist'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. The Hot Gates and Pocket Crew
+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. Scrap Riot 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":
+   Dead Letter grew from 1 letter to 5 in about 7 hours, Pocket Crew 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: Dead Letter, Scrap Riot, Hot Gates and Dawg Ball are Gamma. Pocket
+   Crew, 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 (Scrap Riot 98 of 98
+   cases), and load the web's level JSON from `Resources/Data`. Dead Letter'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. Particle Rush (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 (Pocket Crew: 1,515 numbers bit-identical), save formats (33 Scrap Riot fixtures 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, Dawg Ball (branch `dawg-ball/online`), 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
+
+The Hot Gates, 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: Scrap Riot'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" Dawg Ball's goal sill, which held the
+  balance up.
+- Linear colour space on a Pixi game: overlays about 2× too strong in Dead Letter 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; Dawg Ball's 12
+  heads "did not import at all".
+- A UI with its own catch-up loop: Dead Letter's seal pick never reached audio or FX.
+- An ignored `.csproj`: Dead Letter'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 (Pocket Crew's Worlds 3 and 4). Then on taste: it adds decoration the owner
+removes (5 reverts in 24 hours on Dawg Ball) 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 |
+| "add joydle splash to dawg ball as we did for other games" | carry every studio standard from the start (the studio's packages, `funpixel-unity-game`) and check parity with the sibling games: splash, 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. Pocket Crew'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,63 @@
+# 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
+
+- The studio's `com.joydle.core` (`funpixel-unity-game`, `studio-packages.md`): every
+  `BuildTools` build applies the size settings (stripping High, engine stripping, IL2CPP OptimizeSize);
+  `ProjectSettings/JoydleLz4hc.txt` turns on LZ4HC; `JoydleSplash` holds on black until the first
+  scene has loaded and 10 smooth frames pass.
+- `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 (Pocket Crew, 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; Dead Letter, 2D, 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 (Particle Rush), 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; `JoydleSplash` does). Async-preload each screen's textures while loading, and prewarm a throwaway run behind the title: The Hot Gates' 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 Pocket Crew (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
+
+The Hot Gates, 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. Pocket Crew warmed World 1 only, so World 2 started with a 398 ms hitch.
+- A warm-up that leaves global state changed. Pocket Crew'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 Hot Gates it was the Xcode project.
+- Test files in `Resources/`. Pocket Crew'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: Knockout Lap's `HitchProbe`, Particle Rush's `PerfProbe`, The Hot Gates' `PerfRecorder`, Pocket Crew's `PerfProbe` and `Hitch`, and Gallery Heist's. Pocket Crew 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 the studio's games reference `com.joydle.core`. 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 Pocket Crew's per view; SetPass and memory are Particle Rush'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 Floe Jam'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 Joydle.Core.Editor.BuildTools.SimulatorDev
+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/studio-packages.md

@@ -0,0 +1,127 @@
+# The studio's Unity packages
+
+The studio's two packages, `com.joydle.core` (0.1.0) and `com.joydle.firebase`, are optional: the
+games inside its repository use both, Knockout Lap, Gallery Heist and Particle Rush the core only,
+and Floe Jam neither. They live in that repository, `joydle/joydle-games` (private: the person needs
+read access), under `packages/`. A game that uses them never writes their pieces again. The field report's starter
+is "the SDK wired, switched off" (Starter project), and a fix made in the package reached every game at
+once (§1). Read as of 9 Oct 2026, from the packages' own code; what changes there wins over this page.
+
+## Adding them
+
+Every project lists them by `file:` path. Inside the repository that is `file:../../../packages/…`;
+the three outside it (Knockout Lap, Gallery Heist, Particle Rush) use `file:../../joydle-games/packages/…`
+(Knockout Lap, one folder deeper, `../../../`), so `joydle-games` must be cloned beside them, and
+`funtools doctor` warns when the path is missing. A git URL pinned to a commit needs no sibling
+clone (`#main` moves under a store build); no project uses one yet. Run `git lfs install` first: the splash's pictures and sounds are LFS files, and without it they arrive as
+pointer files. Inside the repository the same holds for a checkout whose LFS files were never pulled.
+`funtools doctor` in the game finds pointer files in Assets, Packages, every local package and the
+package cache, and names the repository to run `git lfs pull` in; run it before a build.
+
+```json
+"dependencies": {
+  "com.joydle.core": "file:../../joydle-games/packages/com.joydle.core",
+  "com.joydle.firebase": "file:../../joydle-games/packages/com.joydle.firebase",
+  "com.unity.inputsystem": "1.20.0",
+  "com.unity.render-pipelines.universal": "17.6.0",
+  "com.unity.test-framework": "1.8.0",
+  "com.unity.ugui": "2.6.0"
+}
+```
+
+The pinned form is `https://github.com/joydle/joydle-games.git?path=/packages/com.joydle.core#<commit>`.
+
+- `com.unity.inputsystem` goes in the game's own manifest: the core's assembly references it and its
+  `package.json` does not pull it in. Set the player to the new Input System only.
+- `com.unity.purchasing` 5.4.3 comes with the core (StoreKit 2 on iOS, Play Billing on Android).
+- The Firebase package needs Google's packages at 13.17.0 (app, analytics, crashlytics) and the External
+  Dependency Manager 1.2.189. The games repository keeps their `.tgz` files in `packages/vendor/` (LFS)
+  and lists them by `file:` path; another project keeps the same versions in its own folder, in LFS.
+  Each game has its own Firebase project, with its config file under `Assets/`.
+- Take out what no game uses: collab-proxy, learn, visual scripting, the Aseprite and PSD importers
+  (Scrap Riot also dropped 2D animation, sprite shape, tilemap extras and timeline: 88 → 78 MiB). Keep
+  what a game uses: Gallery Heist loads its rooms through Addressables 4.1 (built into the app, no
+  remote catalog) and aims its camera with Cinemachine 6.6, beside VFX Graph, Splines and Timeline.
+  No game uses DOTween (`Juice` tweens).
+
+## What each piece gives, and the rule it settles
+
+Editor side of `com.joydle.core`:
+
+| Piece | What it does | Settles |
+|---|---|---|
+| `ProjectConfig.ApplyIOS(name, bundleId, version, landscape)` | Company name, bundle id, IL2CPP, iOS 16, iPhone only, a fixed orientation, status bar hidden, Unity splash off; switches the build target to iOS | settings by script, not a copied file (`funpixel-unity-game` step 6). It does not set colour space, 48 kHz, render scale, ProMotion, the accelerometer or physics: `Setup.Configure` sets those after it |
+| `ProjectConfig.ApplyAndroid(packageName)` | API 26 to 36 (pinned), ARM64, IL2CPP, App Category game, GameActivity, full screen under cutouts, R8 off (it strips Firebase and purchase classes reached by reflection) | the Android half of the same rule |
+| `BuildTools.Simulator`, `SimulatorDev`, `SimulatorMuted`, `Device`, `TestFlight` | Headless iOS builds (`-executeMethod Joydle.Core.Editor.BuildTools.TestFlight`) into `Builds/iOS-sim` or `Builds/iOS`. Every build applies the size settings (stripping High, engine stripping, IL2CPP OptimizeSize, unused mesh channels off); LZ4HC when `ProjectSettings/JoydleLz4hc.txt` exists. `TestFlight` sets the studio's team and automatic signing, and the build number (`JOYDLE_BUILD_NUMBER`, else a `yyMMddHHmm` stamp) and refuses to build without `Assets/_Game/Art/Icon/app_icon.png`. `SimulatorMuted` turns audio off for that one build and restores it | size settings and LZ4HC ([performance](performance.md) step 8); the icon gate (Porcelain Panic shipped Unity's default icon); the CoreAudio wedge on a Simulator relaunched many times |
+| `BuildTools.Android`, `AndroidApk`, `AndroidDev`, `VersionCode()` | A signed `.aab` with its symbols (refuses without `JOYDLE_KEYSTORE` and `JOYDLE_KEYSTORE_PASS`); a release `.apk` for tests that reads launch args (never upload it); versionCode = minutes since 1 Jan 2026, because the iOS stamp is over Play's 2,100,000,000 cap | Android, planned in the report and built since (§15) |
+| `IosPostprocess` | Writes `ITSAppUsesNonExemptEncryption` false and stamps every embedded framework's minimum OS with the app's | ITMS-90208 (`funpixel-store`) |
+| `JoydleLaunch` | A black launch storyboard under its own name, for games that play the splash | iOS caches a launch screen by name across updates (§10) |
+| `SplashImport` | Splash parts scaled to a power of two, mipmapped, compressed | 10.3 MB of raw splash in every game, now about 2.6 MB |
+| `TextureBudget` | Textures named `model__basecolor.png` (and `__normal`, `__mr`, `__emissive`) under an `Art/` or `Models/` folder: ASTC 6×6, mipmaps, sRGB only for base colour and emissive, at most 512 under `Food/`, `Props/` or `Characters/`, else 1024 | glTFast's raw RGBA32 model textures (`funpixel-3d`, Unity page) |
+| `AndroidManifestPost` | Adds the vibrate permission the haptics need | |
+
+Runtime side of `com.joydle.core`:
+
+| Piece | What it does | Settles |
+|---|---|---|
+| `Sfx.Create(music)`, `Play(clip, volume)`, `Sfx.EnsureListener()` | 8 pooled one-shots with pitch jitter 0.06, one looping music source at 0.45, and exactly one AudioListener | the four silent TestFlight builds (`funpixel-audio`, Unity page, step 1) |
+| `Haptics.Light`, `Medium`, `Heavy`, `Success`, `Error` | iOS taptics through the package's native plugin, Android vibration effects; off when `Settings.Haptics` is | haptics by strength (`funpixel-game-feel`, Unity page). The 80–90 ms throttle and the 120 ms merge are the game's |
+| `Juice.Tween`, `Pop`, `Shake`, `EaseOutBack`, `EaseOutCubic`, `EaseInQuad`, `Ring`, `Dot`, `Rounded` | Coroutine tweens with the defaults the games used (pop 0.18 over 0.22 s, shake 0.08 over 0.25 s); a pop keeps the true rest scale | the compounding pop, fixed once for every game |
+| `UiKit` | A canvas scaled at 1170×2532 (match 0.5), a `Safe` rect from `Screen.safeArea`, rounded panels, text, buttons that pop, modal cards, a dim layer, `FitToContent`; text and images take no taps | the code-built UI and the Restore label that covered the shop card (`funpixel-mobile-ui`, Unity page). `Safe` is read once when the kit is made, and the landscape island-side rule is not in it |
+| `LaunchArgs.Get()` | Launch arguments: on iOS from the native process (Mono never sees `simctl launch` args), on Android from the intent extra `joydle_args`, in development builds and test APKs only | the basis of every automation flag. On iOS it is not gated: read it through the game's own wrapper that returns nothing unless `Debug.isDebugBuild` (Scrap Riot's), or a release build obeys an unlock flag (§1) |
+| `Settings.Music`, `Sound`, `Haptics` | The three player toggles, kept in PlayerPrefs | |
+| `Telemetry.Event`, `LevelStart`, `LevelEnd`, `TutorialComplete`, `ShopOpen`, `Log`; `Telemetry.Muted` | The one analytics and crash boundary; logs to the console in a development build with no sink | mute it under every dev flag: autoplay and capture runs must not reach analytics |
+| `IapService(catalog, grant)` with `Init`, `Buy`, `Restore(done)`, `Price`, `Refetch` | Unity IAP 5. Grants in the pending-order handler once per transaction, then confirms; non-consumables come back from confirmed orders on every fetch; `Restore(done)` asks StoreKit to sync on iOS and answers true or false; `Price` is the store's localised string | the double grant (fixed on main on 7 Oct; a game built before needs a new build), Restore that ends (`funpixel-store`) |
+| `Ads.CreateDefault(font)`, `Ads.Available`, `Ads.ShouldShowInterstitial(level, noAds)` | Test ads in development builds and the Editor, none in release; interstitials from level 15, every third level, never for a No Ads buyer | hide every ad button and No Ads while `Ads.Service` is null |
+| `JoydleSplash` | The studio splash, 4.25 s, tap to skip after 1 s. A game opts in with a text asset `Resources/JoydleSplashOn`; it holds the game's audio, waits for the first scene and 10 smooth frames (1 s floor, 3 s cap), and is skipped in the Editor and on any launch with a `-flag` (`-splash` forces it); `JoydleSplash.Playing` says when it is up | "add joydle splash … as we did for other games" (the owner, twice) |
+| `BackButton.PressedThisFrame`, `AndroidSystem.MoveToBack()`, `AndroidSystem.Density` | Android Back read from input events, since Back arrives pressed and released inside one frame and polling misses it; leave the app from the root screen; the dp scale | |
+
+`com.joydle.firebase` boots itself before the first scene and installs Analytics and Crashlytics as
+`Telemetry`'s sink (uncaught exceptions are fatal reports); the Editor keeps the console. It hands its
+`link.xml` to the linker and marks its assembly always linked, because High stripping removed it and
+Firebase never started in release builds (3 broken uploads). It pins the no-tracking setup: no
+advertising identifier and no ad personalisation in the iOS plist, the advertising-id and ad-services
+permissions removed on Android. That is what lets the privacy answers say nothing is used for
+tracking, with no tracking prompt.
+
+## A studio splash
+
+A game never makes its own splash or a "Funpixel presents" card, package or not: the opening belongs
+to the studio that makes the game, or to nothing. A studio's splash comes from its package, so one
+fix reaches every game. Today
+that is Joydle Core's `Joydle.Core.JoydleSplash` (read from its code on 10 Oct 2026; the code wins
+over this table). A project on another studio's package wires that package's splash the same way; a
+project with none ships no splash.
+
+| Day-one rule | How `JoydleSplash` does it |
+|---|---|
+| Opt in, once | A text asset that `Resources.Load<TextAsset>("JoydleSplashOn")` finds, such as `Assets/_Game/Resources/JoydleSplashOn.txt` (the games write one line: what it does and "Delete this file to turn it off"), with its `.meta` committed. Nothing else is called: the package boots it before the first scene loads (`RuntimeInitializeOnLoadMethod(BeforeSceneLoad)`) |
+| Before the first scene, on top | A `DontDestroyOnLoad` object with an overlay canvas at sorting order 32000. It waits for the first scene and 10 smooth frames (1 s floor, 3 s cap), then plays 4.25 s; a tap skips it after 1 s. On iOS `JoydleLaunch` makes the launch screen the black it opens on |
+| Holds the game's audio | `AudioListener.pause` is true until it ends; its own sounds ignore the pause and follow `Settings.Sound` |
+| Skipped in the Editor and on any flag | `Application.isEditor`, or any argument from `LaunchArgs.Get()` that starts with `-` (every automation, capture and test launch passes one); `-splash` forces it, to see it on the Simulator |
+| Title music waits | `JoydleSplash.Playing` is true from before the first scene until the fade ends (false when it was skipped): start the title music once it is false. Pocket Crew also hides its loading view while it is up |
+| The studio credit | Every credit line (Settings, About, an end card) names the studio, Joydle, and never Funpixel |
+
+Its pictures and sounds are LFS files under the package's `Runtime/Resources/JoydleSplash/`. On a Mac
+where the studio repository's LFS files were not pulled they are pointer text: the splash draws
+blank parts and stays silent, and Unity logs "FSBTool ERROR: Failed decoding audio clip" for each
+`JoydleSplash/*.wav` in every build. `funtools doctor` fails on them and says where to pull.
+
+## What they do not give
+
+What each game still writes by hand (§1): import rules (or `funtools gen --unity`'s, for what it
+makes), the `SceneBuilder`, the TMP font builder, capture tools, the launch-flag dev gate, a safe-area
+root off `UiKit`, the frame governor, saves, Firebase's Simulator stubs (its C++ SDK has no arm64
+Simulator slice), a smoke driver and a UI audit. The repository's scripts are not in the packages.
+
+## Rules for changing them
+
+- Fix a shared bug in the package, once, never in one game's copy. The pop and the AudioListener fixes
+  reached four games at once; the purchase double grant lived on one branch while four games still had
+  it (§1).
+- A change to the build pipeline every game shares (`BuildTools`) comes with a per-game opt-in marker,
+  as `JoydleLz4hc.txt` does, and a person looks before it lands (§10).
+- Additive only: a game built on 0.1.0 keeps building.
+- `BuildTools.TestFlight` signs automatically for the studio's own Apple team (KBAT76634X), and
+  `ApplyIOS` writes its company name. A game for another team needs its own build method until the
+  package takes a team per game.