@funpixel/tools 0.0.0-stage → 0.1.1

package/plugins/claude/skills/publishing/references/server-build.md

@@ -0,0 +1,85 @@
+# The server build
+
+Funpixel builds every upload itself. It receives your source (never your `dist/`, which is
+excluded), installs dependencies with lifecycle scripts turned off, and runs a plain `vite build`.
+Plan for no network beyond the npm registry during install, and none at all during the build.
+Anything your machine supplies that the upload does not carry is missing there, and most of those
+gaps build green and fail only in the player's browser.
+
+## Refusals you can get back
+
+| Answer | Meaning | What to do |
+|---|---|---|
+| no key, or a plan without API access | the key is missing, lacks `games:publish`, or the plan is free | a paid plan's `fp_live_` key in `FUNPIXEL_API_KEY` |
+| `verify_missing`, `verify_stale`, `verify_failed` | the verify record gate (skill step 2) | verify again; fix a failure first |
+| `package_refused` | a banned or typosquatted package, or a `git+`, `file:` or tarball specifier | depend on registry packages by version |
+| `source_layout` | no `package.json` or no `index.html` at the upload's root (the server installs and runs `vite build` there) | put the game at the root; a game in a monorepo subfolder cannot be built there yet |
+| `build_failed` | the install or the build failed on the server | reproduce below; the message names the step |
+| a conflict | the game id belongs to another account | fix `game_id` in `funpixel.json`, or drop `--game-id` |
+| `publish_not_allowed` | an upload asked to be public in the same call | uploads are drafts; share from the game's page |
+| busy (service unavailable) | uploads are at capacity | retry in a minute; nothing was stored |
+
+## Reproduce the server build locally
+
+Build from a clean copy of what ships, not from your working folder: the working folder has
+`node_modules`, a warm Vite cache and files `.harnessignore` removes.
+
+1. Copy the game into an empty folder, leaving out `node_modules/`, `.git/`, `dist/`, `.vite/`
+   and everything your `.harnessignore` names.
+2. In that copy: `pnpm install --ignore-scripts`, then `pnpm exec vite build`, then
+   `pnpm exec vite preview`.
+3. `npx @funpixel/tools verify <the preview URL>`. A failure here is the failure the server will
+   have, found for free.
+
+## Traps that build green and break live
+
+**An environment-only value.** A flag or URL set in your shell or in a `.env` that does not ship is
+undefined on the server, so the published build takes the other branch: a feature missing, a debug
+path on. Bake the shipping value into the code (a constant in `src/`), not into `vite.config.ts`, which the
+platform replaces with its own; keep environment variables for local overrides only.
+
+**Decoders that were never vendored.** Draco (`/draco/`) and Basis (`/basis/`) files must be real
+files under `public/`, so they ship and are served from the game's own origin. A dev plugin or a
+`node_modules` path that serves them locally does not exist on the server, and a missing file is
+answered with the page's `index.html`: the loader receives HTML where it expected wasm and waits
+forever, with no error the player can see. Check in the published page's network log that each
+decoder request returns wasm or JavaScript, not HTML.
+
+**An externalized engine.** Loading Pixi or Three from a CDN or an import map, or splitting the
+engine into a named manual chunk, passes locally and gives a blank screen when published without
+the same map. Let Vite bundle the engine, and keep it in `dependencies`.
+
+**Native and heavy tooling in the game's manifest.** With lifecycle scripts off, packages that
+download a binary at install (`sharp`, Playwright, Puppeteer, native addons) break or balloon the
+install. Image processing and browser tests belong to your tools, outside the game's
+`package.json`.
+
+**Local links.** `file:` and `link:` dependencies, and workspace links to a folder that is not in
+the upload, cannot resolve on the server. Depend on published versions.
+
+**An unpinned SDK.** `@funpixel/sdk` is pinned exactly (`"0.7.0"`); a caret range can resolve to a
+different build on the server than on your machine.
+
+**Path case.** Your disk may treat `Hero.png` and `hero.png` as one file; the server and the
+storage behind the published game do not. Every import and asset URL must match the file's case
+exactly.
+
+**Files the dev server invents.** The dev server serves anything on disk, including files an
+ignore rule removes from the upload, and raw files outside `public/` through its module graph. Only
+the published copy tells you what really loads.
+
+**A size that surprises you.** Vite copies all of `public/` into the build, so raw sources, keyed
+intermediates or unused takes left there ship too. One game's build was 606 MB for 5 MB of real
+assets. Keep only what the game loads under `public/`, and move the rest out or into
+`.harnessignore`.
+
+## When the published page does not render
+
+Do not publish the same files again. In order:
+1. Open the play URL with the browser's network log and console. Any request answered with HTML
+   where a decoder, image, model or script belongs names the missing file.
+2. Compare with the local reproduction above; it fails the same way almost every time.
+3. If the reproduction works and the published page does not, run the platform's `build` tool
+   and read its output, then file the difference with `report_feedback`: it is a platform gap.
+4. Fix, `npm run build && npx @funpixel/tools verify`, publish again (the id in `funpixel.json`
+   updates the same draft) and smoke the URL again.

package/plugins/claude/skills/publishing/references/store-shots.md

@@ -0,0 +1,85 @@
+# Trailers, store and portal shots
+
+Detail for step 9 of `fp:publishing`: the method our studio used to get games through store
+review and in front of players, whether `store_shots` and `funtools reel` compose the set or you
+do. Concept art is refused by stores and distrusted by players, and an idle board sells nothing.
+
+## Moments make the footage
+
+Every automatic cut can only pick from what the game shows it. Call
+`window.__FPX_MOMENT__?.(name, weight)` at each payoff (a boss down at 1, a combo at 0.6, a clear at
+0.8): the capture tour shoots at the mark, and the published share video cuts on the marks before
+it falls back to motion. The share video plays the game's own music (`public/assets/music/`) and, on
+a scene whose mark names one of its sound files by a word (`boss_down` → `boss-defeat.mp3`), that
+effect on the cut; name the marks and the files alike. `store_shots` picks its peaks from input and measured motion, not marks.
+A game with no marks gets footage of whatever happened to move.
+
+## The reel
+
+- Hook first: the first seconds show play, not a menu. `funtools reel` holds the title for at
+  most two seconds, then films play driven by the game's own verbs, then the ending; declare verbs
+  that reach the payoff, or the reel shows the start of a level over and over.
+- A reel that reports mostly still frames means the verbs did not play; fix the verbs, not the
+  video.
+- No pause screen, settings or loading. Text only where the footage cannot say it, a few words,
+  never over the action. End on the game's name and where to play it.
+- It is silent; a trailer with sound uses the game's own music and effects, never a stock track.
+- Look at stills from the file before handing it over: a timeline cannot see framing, occlusion or
+  a HUD covering the payoff.
+
+## The arc
+
+Five or six shots, each with one job, in this order:
+
+| Shot | Its job | Typical frame |
+|---|---|---|
+| 1. Hook | stop the scroll | the single most spectacular real moment |
+| 2. Core mechanic | show what the player does | the main verb mid-action, input visible |
+| 3. Depth | show it grows | a later level, a new enemy or rule |
+| 4. Meta | show why to come back | upgrades, a map, a shop, progression |
+| 5. Collection | show variety | skins, characters, worlds side by side |
+| 6. Benefit | say what the player gets | a win, a big combo, a finished board |
+
+A game without a meta or a collection skips that shot; it does not invent one.
+
+## Real captures only
+
+- Every shot is a frame the game really rendered. You may move, scale or tilt the capture as a
+  whole inside a frame; you never redraw or retouch gameplay.
+- Capture peak moments: a combo mid-chain, a boss at low health, a near-fail save, the frame after
+  a big clear. Never an idle board, a menu, or the first second of a level.
+- Stage the state through the game's own hooks (`__FPX_VIEWS__`, `__FPX_VERBS__`, a fixed seed),
+  so the shot shows a player doing well: full lives, a healthy score, no lost hearts. A staged
+  capture that shows a struggling player reads as a hard or broken game.
+- Capture in bursts (several frames a few hundred milliseconds apart) and keep the liveliest one.
+- Use the `screenshot` tool at the store's aspect (a 390x844 phone frame for portrait stores),
+  or the dev server with device emulation. Check that no debug overlay, cursor or dev badge is in
+  frame.
+
+## Caption bands
+
+- Every shot carries a caption of two to four words on a saturated band ("Chain the sparks",
+  "Beat the tide"). One type size across the set, fitted to the longest caption; the band never
+  covers the action.
+- Captions are real type set over the capture, never words generated inside an image.
+- Give each game its own frame language (band shape, angle, ornament). Reusing another game's
+  frame makes two games read as one series. When you vary it, change geometry and ornament, and
+  keep the saturation, the chunky type and the mascot scale that worked.
+
+## Honest badges
+
+- Never show a mechanic, mode or label the game lacks: no "x3 combo" badge without a combo system,
+  no "HARD" tag except on a level the game really tags hard, no multiplayer art on a solo game.
+- Numbers shown (scores, levels, counts) are ones the game can actually reach.
+
+## The icon
+
+- Make three or four candidates and judge them at 60 px and at 120 px, side by side, on light and
+  dark backgrounds. What reads at 60 px is one big shape or one friendly face; detail disappears.
+- No words in the icon; the store shows the name beside it.
+
+## Checking the set
+
+Lay the shots out in order at the size a store list shows them. Read only the captions: they
+should tell the game's pitch in order. Then look only at the captures: each should show a
+different thing happening. Any shot that repeats another, or that you had to explain, is replaced.

package/plugins/claude/skills/publishing/references/trailer.md

@@ -0,0 +1,55 @@
+# A trailer from real play
+
+Stores and portals reject a preview whose "gameplay" is not the game: App Store app previews
+may only use screen captures of the app itself, and Steam asks that a trailer mostly show the
+game being played. A Funpixel trailer is therefore cut from the built game being played, and
+anything generated is a card, labelled as one.
+
+## Make one
+
+1. **Build, and let the game be filmed well.** `npm run build`. The trailer films the tour
+   `reel` films: the game's `__FPX_VIEWS__` (a title, the play view with `motion: true`, an
+   ending) driven by its own `__FPX_VERBS__`. A game with no verbs is filmed idle.
+2. **Mark the payoffs.** Call `window.__FPX_MOMENT__?.('boss_down', 1)` (or `markMoment` from
+   `@funpixel/sdk`) at each payoff, weight 0..1. Shots are placed to land on the heaviest ones;
+   unmarked, they are spread evenly over the take.
+3. **Give it the game's own material.** Key art at `design/key-art.png` (or `--key-art`), a logo
+   at `design/logo.png` if there is one, and the music bed in `public/assets/music/` (or
+   `--music`; with neither, the music the game loops while it is filmed). Never the target frame (`design/target.png`): it is a mock-up of play, and a card
+   on it would pass one off as the game.
+4. **Cut it.** `npx @funpixel/tools trailer --seconds 30`. It films the game, finds the beat of
+   the music bed, and writes `.funtools/trailer/trailer-16x9.mp4` (1920x1080),
+   `trailer-9x16.mp4` (1080x1920) and `trailer.json`. Every cut lands on a beat: a title card,
+   gameplay shots, an end card (`--cta "Play free"`). `--formats 9x16` for one shape only.
+5. **Listen to it too.** The sound is the music bed plus the game's OWN sound effects, each at the
+   moment it really played inside a kept shot (the trailer logs every sound start while it films).
+   Mixed like a finished trailer: music −4 dB, effects −3 dB, the music dipping ~5 dB while an
+   effect plays, a 2 s music fade-out, loudness-normalised to −16 LUFS under −1.5 dBTP. Sounds
+   come from FILES: an oscillator or a buffer the page fills itself cannot be played back, so it
+   is listed as skipped, never faked; if your game's key sounds are synthesised, it will sound
+   thin here — ship them as files (`gen sound`). `--no-sfx` leaves the effects out, `--no-music`
+   the bed. The effects only play if audio is unlocked by the game's first input.
+6. **Look at it before it goes anywhere.** Watch both files. `trailer.json` lists every segment
+   and its `source`: `gameplay` (this build, filmed), `card`, or `generated`; and under `sound`
+   every cue used (`at`, `name`, `source` file, `take_at`), every one skipped and why, and the
+   measured `lufs` / `true_peak`.
+
+## Generated clips
+
+`generate_video` (MCP) or `funtools gen video "prompt" --duration 5 --aspect 16:9` makes a 2–30 s
+clip (`--resolution 480p|720p|1080p`, priced per second) from a prompt, animates a still of yours
+(`--image-asset <id>`, cropped to the aspect asked) towards an end frame (`--end-image-asset`), or
+keeps the subjects of up to four `--references`; `--model kling-2.5` picks the other engine (5 or
+10 s). `edit_video` (`funtools gen edit-video "make it snow" --video-asset <id>`) edits a 2–10 s
+clip by an instruction. Camera words (`camera: {move, lens, aperture, speed}`, or `--camera-move dolly_in --lens tele --aperture shallow --camera-speed slow`) are for a shot with a set move or look: a slow dolly in on key art, a static title card, a character in shallow focus; leave them out when a still should only come alive, and a word the model does not take is refused, never dropped.
+`lip_sync` (`funtools gen lipsync --image-asset <portrait> --audio-asset <line.mp3> --duration <s>`) fits a story scene or a trailer beat where a character speaks a `voice_line` or `dialogue` line: up to 60 s, priced per second of speech, and the portrait is the game's own character or your own face, never a real person who has not agreed.
+All of these cost credits and ask you to confirm above the line; they are saved
+under `.funtools/video/`, never shipped. Pass it as `--intro` or `--outro`: the trailer uses at most 4 s of it (and at most
+a fifth of the trailer), places it only before the title card or before the end card, and shows
+"Generated video · not gameplay" on it for its whole length. Never cut a generated clip into the
+middle of play, never remove the label, and never describe a generated clip as footage.
+
+**Where it is posted.** `--for tiktok,reels,shorts,stories,feed,square,youtube,store,site` picks the
+formats (9:16, 4:5, 1:1, 16:9) and lays every card and the label inside that format's clear area: a
+tall feed's header, its right-hand action rail and its caption block never cover the title or the call
+to action. `--formats` names them directly.

package/plugins/claude/skills/publishing/references/what-ships.md

@@ -0,0 +1,30 @@
+# What ships, and the leak scan
+
+## The ignore rules
+
+What ships is the game folder minus `node_modules/`, `.git/`, `dist/`, `.vite/`, empty files and
+the rules in `.harnessignore`. The rules follow `.gitignore`'s shape, with one trap:
+
+- A rule without a leading `/` matches at any depth: `assets/` (meant for a root-level raw art
+  folder) also strips `public/assets/`, and the game ships with no art. Write `/assets/`.
+- A leading `/` anchors the rule to the game folder; a trailing `/` matches directories only; `!`
+  brings a path back.
+- Publish warns about each rule that matched nothing: a misspelt rule ships what it meant to hide.
+
+The dev server serves files that will not ship, so a missing asset 404s only after publish. An
+unexpected `files` count in `verify.json` means a rule is wrong; `funtools pack --dry-run` lists
+exactly what ships and which rule dropped each file.
+
+## The leak scan
+
+A name can look harmless while the contents are not. Search every file that ships, GLBs included:
+
+- keys and tokens: `fp_live_`, `sk-`, `API_KEY`, a `.env`;
+- paths from your machine (a home folder in a debug string);
+- internal words and private tooling;
+- vendor names inside binaries: `strings model.glb | grep -i` over bone and node names;
+- source maps;
+- a debug escape left live (`?debug=1` that enables god mode).
+
+Private scripts and docs go in `.harnessignore`. `funtools pack --dry-run` runs the same scan over
+the upload.

package/plugins/claude/skills/store/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: store
+description: Use when a game is headed for a store (Google Play, the App Store, Steam, itch.io, Poki, CrazyGames), to say whether it is ready and what is left, how it should make money (premium, ads, a pass), a Unity build for TestFlight and App Review (signing, stripping, archive checks), or its App Store screenshots, preview, icon, listing, purchases and privacy answers.
+---
+
+# Ready for a store
+
+"Can it go on the store?" is answered by an audit, not a guess, and most store failures are silent
+until a reviewer finds them: four of eight first Unity submissions were rejected, four games reached
+TestFlight with no sound, and a listing said "no analytics" while analytics shipped. This skill
+reads the game and the store's current rules, writes one readiness page, and moves each known
+rejection in front of the submission. It submits nothing: accounts, forms, prices and the Submit
+button are the person's.
+
+## Route by the job
+
+| The job | Read |
+|---|---|
+| Is it ready, what is left, in what order | [readiness](references/readiness.md), [readiness-page](references/readiness-page.md) |
+| How it should make money | [money](references/money.md) |
+| A store's own rules | [google-play](references/google-play.md), [app-store](references/app-store.md), [steam](references/steam.md), [web-portals](references/web-portals.md) |
+| A Unity build to TestFlight, App Review answers | [ios-release](references/ios-release.md) |
+| App Store screenshots, preview, icon, listing, purchases, privacy | [unity-store](references/unity-store.md), [purchases-and-review](references/purchases-and-review.md) |
+
+## Tools
+
+- `probe` and `screenshot`: the build played and captured at a phone viewport.
+- `store_shots`: store-size screenshots from the newest real capture run, never concept art.
+- `npx @funpixel/tools store init | doctor | lint | plan [--store play|ios|steam]`, read-only and
+  offline: `store/answers.json` (no secrets; both privacy forms from one `sdks` list), what this Mac
+  has for each store, the answers against each store's rules, and the steps marked Script, Console
+  or You.
+- `npx @funpixel/tools check`, `verify` and `capture --all`: the build measured; `funtools doctor`'s
+  iOS release block names a missing certificate, Xcode account or App Store Connect key.
+- Unity: `funtools unity run -- … -executeMethod Setup.BuildTestFlight`, the game's own build
+  method, then `xcodebuild archive` and `-exportArchive`; `funtools sim lease` and
+  `sim shot` for screenshots; `ffprobe` before any preview upload.
+
+## The audit, for any store
+
+For each game, each area is **Ready**, **Partial**, **Missing** or **Check** (not known until a build
+runs), with its evidence in one line: the build the store takes and its signing; the permanent
+bundle or package id (the owner confirms it); the store's own billing, restore and refunds; privacy,
+every SDK that collects anything declared truthfully; rating and audience; back and pause on every
+screen; every aspect ratio and the low end of its devices, measured; platform services; no other
+store's name anywhere; store art at that store's sizes from real play; the download size; and a
+build only from a clean main. Every policy fact carries the day it was read and its source.
+
+## The work, in order
+
+1. **The owner's decisions:** ids, what ships in 1.0, release order, the money model and prices.
+2. **A shared foundation** before any one game: the store's build, signing, one back handler, the
+   store's billing, the privacy declarations.
+3. **Per-game fixes,** each named with its file.
+4. **Device test** on a real low-to-mid device; purchases with test accounts (buy, reinstall, refund,
+   a slow payment). Products never load on the Simulator without a StoreKit configuration.
+5. **Store art:** a bake-off per asset type against the competitors' listings; icons judged at 60
+   and 40 px; captions true of their frame, the real HUD visible.
+6. **Before each Unity upload:** the pre-flight on the archive (sound, Firebase in release, stripping,
+   the build from main), Buy within two taps of the title, a real Restore, prices only from the
+   store's localised string ([ios-release](references/ios-release.md),
+   [unity-store](references/unity-store.md)).
+7. **The console and the release,** by the person: one game at a time, a staged rollout where the
+   store has one.
+
+## Worked example
+
+Four Unity games for Google Play (8 Oct 2026): no Android build ever made, Unity IAP already
+on Play Billing 9, analytics in all four while two listings said "no analytics". Verdict: none can
+upload today, none is blocked. A shared Android foundation first (an AAB pinned to API 36, one upload
+key, the AD_ID permission removed, one back handler), then 2–8 days per game; the screenshots
+re-composed for Play's 2:1; five questions for the owner end the page.
+
+## Common mistakes
+
+- Calling a game ready because the code compiles: a store rejects on forms, art and words.
+- A privacy form filled from a listing that is wrong about the SDKs.
+- "Free" or a price word in the name, subtitle, keywords or captions (guideline 2.3.7).
+- Resubmitting fast instead of linting first: each rejected game waited over a week again.
+- A launch-time Restore: it shows an Apple sign-in prompt; Restore runs only from a tap.
+- A policy number from memory, or an agent deciding an id, a price or a release date.

package/plugins/claude/skills/store/references/app-store.md

@@ -0,0 +1,73 @@
+# Apple App Store
+
+What a readiness page checks for iOS and iPadOS. Apple changes its requirements every spring; read
+the App Review Guidelines and App Store Connect Help on the day the page is written and date each
+fact. A Unity game's build, signing and review steps are in fp:store; its
+screenshots, previews, icon and purchases in fp:store.
+
+## Rules to read and date
+
+- **The SDK floor.** Uploads must be built with the Xcode and SDK Apple currently requires; it rises
+  each year. Name the version read.
+- **Minimum functionality (4.2).** A wrapped website is rejected; a game whose code and assets are in
+  the bundle and that plays offline is not a website. A web game ships in a native shell with its
+  `dist/` inside.
+- **Spam (4.3).** Several similar games from one account are reviewed as one; distinct mechanics,
+  art and listings, released apart.
+- **Payments (3.1.1).** Digital goods through In-App Purchase, with a way to restore non-consumable
+  purchases. The first in-app purchase is ticked onto a version by a person in App Store Connect.
+- **Privacy.** App Privacy answers for every SDK that collects data, and a privacy manifest
+  (`PrivacyInfo.xcprivacy`) for SDKs on Apple's list and for the required-reason APIs the app uses.
+- **Accounts.** An app that lets people make an account lets them delete it in the app; a
+  third-party sign-in comes with Sign in with Apple.
+- **Age rating.** The questionnaire, in Apple's current age tiers.
+
+## Store art and listing
+
+- Icon 1024×1024, no transparency.
+- Screenshots for the largest iPhone size Apple currently requires (and the largest iPad, if the
+  game runs on iPad), from real play with the real HUD.
+- App Previews: short real gameplay, encoded to Apple's rules (fp:store).
+- Name 30 characters, subtitle 30, promotional text 170, keywords 100, description 4,000.
+- No other platform's name, no price or "free" in the screenshots' words.
+
+## Who does each step (read 8 Oct 2026)
+
+**Script** = the App Store Connect CLI `asc` (rorkai, MIT; pinned to 5.13.0, run with `ASC_READ_ONLY=1`
+for a plan and `DO_NOT_TRACK=1` always); **Console** = the agent in the person's signed-in browser, from
+`store/answers.json`; **You** = agreements, money, 2FA and Submit. `asc web` (private endpoints, the
+person's Apple ID session) is the person's opt-in, never the agent's default. `funtools store plan --store ios`
+prints these steps in order with this column.
+
+| Step | Next time | Notes |
+|---|---|---|
+| Agreements, tax, banking | You | The Paid Apps agreement before any purchase can be sold. |
+| API key and sign-in | You: a Team API key (App Manager), its `.p8` outside the repo, `asc auth login` once | Admin only if cloud signing is wanted. |
+| Register the bundle id | Script: `asc bundle-ids` | Permanent once the app exists: the owner decides it. |
+| Create the app record | Console | Not in the public API (`asc web apps create` only on the person's own session). |
+| Certificates and profiles | Script: `asc signing` | |
+| Upload the build | Script: `asc builds upload --ipa` | |
+| TestFlight groups and testers | Script: `asc testflight` | |
+| Listing text | Script: `asc metadata apply` | `--dry-run` first. |
+| Screenshots and previews | Script: `asc screenshots plan`, then `upload` | |
+| Category, age rating, encryption | Script: `asc categories`, `asc age-rating`, `asc encryption` | |
+| App Privacy | Console | From the SDK list; not in the public API (`asc web privacy` only on the person's session). |
+| Price and availability | Script: `asc pricing` | |
+| In-app purchases, prices | Script: `asc iap` | |
+| The first in-app purchase on the version | Console | Ticked onto the version; whether `asc` can attach it was not verified (one game's was dropped when submitted by API alone). |
+| Review details | Script: `asc review` | Notes, contact, a way to the paid content. |
+| Validate | Script: `asc validate --strict`, `asc release stage --dry-run` | |
+| Submit for review | You | `--submit` only after the person's go-ahead. |
+| Status, reviews | Script: `asc status`, `asc reviews` | Read-only. |
+
+Screenshot sizes (Apple's screenshot specifications, read 8 Oct 2026; portrait, landscape is the same turned;
+1–10 per size; JPEG or PNG with no alpha): 6.9" iPhone 1320×2868, 1290×2796 or 1260×2736; 6.5" 1284×2778 or
+1242×2688; 6.3" 1206×2622 or 1179×2556; 13" iPad 2064×2752 or 2048×2732 (required when the game runs on iPad).
+
+## Matrix rows
+
+Developer account and agreements · SDK floor · bundle id · signing and provisioning · build number
+that only rises · IAP products and restore · App Privacy and privacy manifest · age rating · safe
+area and the notch in both landscape directions · haptics · Game Center (in 1.0 or later) · other
+stores' words · download size (cellular download limit) · screenshots per required size · previews ·
+listing text · TestFlight · branch.

package/plugins/claude/skills/store/references/google-play.md

@@ -0,0 +1,141 @@
+# Google Play
+
+From a Google Play readiness audit (8 Oct 2026, four Unity games), with what changes for a
+web game. Policy facts were read on that day from Google Play Console Help and developer.android.com;
+read them again before the page is final.
+
+## The rules that apply now (read 8 Oct 2026)
+
+| Rule | What it means |
+|---|---|
+| Target Android 16 (API 36) | Required for new apps since 31 Aug 2026; an extension to 1 Nov can be requested. Pin the API level: "highest installed" can pick a newer one. |
+| App Bundle + Play App Signing | Uploads are AAB. The base module can be up to 500 MB compressed; users on mobile data are warned above 200 MB. One upload keystore per studio, never in git; accept Play App Signing on the first upload. |
+| 16 KB memory pages | Native libraries must be 16 KB-aligned; hard enforcement on updates from 1 Feb 2027. Check every AAB with `zipalign -P 16` and a 16 KB emulator (it must report `PAGE_SIZE 16384`). |
+| Play Billing Library 8+ | Required since 31 Aug 2026 for digital goods. |
+| Edge-to-edge, predictive back | Targeting API 36, an app cannot opt out of edge-to-edge, and the old back key is no longer delivered on Android 16: back is handled through the system's callback. |
+| App category = Game | Exempts games from Android 16's forced resizing and rotation on tablets and foldables; set it when the game locks its orientation. |
+| Advertising ID | A game without ads declares No, and the `AD_ID` permission an analytics SDK merges in is removed. |
+| Products after the first upload | In-app products can be created only after an AAB with the billing permission is on a track. |
+| Testers | An organisation account skips the 12-testers-for-14-days rule that personal accounts have. |
+
+## The matrix rows
+
+Play account · toolchain · compiles for Android · package name · build pipeline · billing ·
+analytics and crash reporting · back · haptics · screen and DPI · performance · platform services
+(Play Games for achievements and leaderboards) · other stores' words · download size · icon 512 and
+adaptive layers · feature graphic · screenshots · short description · data safety · rating and
+audience · branch.
+
+## Store art and listing
+
+- Icon 512×512, plus adaptive foreground and background layers (432×432, the art inside the middle
+  66%), derived from the 1024 master.
+- Feature graphic 1024×500: required, new art per game.
+- 4–8 phone screenshots, at most 2:1; 1920×1080 (landscape) or 1080×1920 (portrait) also qualifies
+  for Play's game recommendation surfaces. iOS sets at 2.17:1 do not fit and are re-composed from
+  real captures. Optional: 4 tablet screenshots; a video as an unlisted YouTube link.
+- Title 30 characters, short description 80, full description 4,000.
+
+## A web game on Play
+
+- **Bundled, offline:** a Capacitor (or similar WebView) shell with the game's `dist/` inside; the
+  game works with no network. Billing through a Play Billing plugin, never a web checkout.
+- **A Trusted Web Activity** (Bubblewrap) opens a hosted address full screen; it needs Digital Asset
+  Links on the site and a working network. Digital goods still go through Play Billing.
+- Either way: back handled in the page (`popstate` or the shell's back event), the safe area through
+  `env(safe-area-inset-*)`, haptics through the shell, and the WebView's performance measured on a
+  real mid-range phone.
+
+## A Unity game on Play
+
+Unity's Android module (SDK, NDK, JDK), IL2CPP and ARM64, an AAB, target API pinned, min API 26,
+Vulkan with a GLES3 fallback, ASTC textures, stripping set for Android, a symbols file for crash
+reports. A versionCode under Play's 2,100,000,000 cap (iOS-style yyMMddHHmm numbers exceed it:
+count minutes since a fixed date). Unity IAP's Play Billing, restore on launch (no Restore button
+on Android), pending purchases granted only on confirmation. Analytics SDK assemblies include
+Android, with the platform's config file committed.
+
+## Device test
+
+Autoplay and smoke runs on a normal and a 16 KB emulator with no exceptions in Logcat; a real
+mid-range phone (Galaxy A or Redmi Note class) for frame rate, heat, touch and haptics; back on
+every screen; notch-left and notch-right landscape; 20:9 and taller; license-tester purchases (buy,
+reinstall, refund, the slow test card); the pre-launch report on a testing track.
+
+## The console (the person)
+
+A tester group and license testers; each app created by hand (name, language, Game, Free); the
+first AAB on internal testing; App content (privacy policy, ads, login, data safety, target audience
+13+, the IARC questionnaire, the government, financial, health and news questions); products reusing
+the iOS ids; the listing; a service account with testing-track and listing rights only.
+
+## Release (the person)
+
+Managed publishing on, so an approved release waits for a click. One game at a time: a new
+account's first review can take 7 days or more. A staged rollout of 10–20%, then 100%, watching
+crash rate (under 1.09%) and ANR rate (under 0.47%) in Android vitals.
+
+## Who does each step (one game, 8 Oct 2026)
+
+The first game went from its first Android build to Send for review in about 5 hours, but almost every
+console form was filled by an agent driving Chrome, because there was no Play API access. Set the API
+up once and the next game is mostly a script. **Script** = the Google Play Developer API v3 with a
+service account; **Console** = the agent in the person's signed-in browser, with the answers from the
+game's own answers file (`store/answers.json`); **You** = legal ticks and money, the person's alone.
+`funtools store plan --store play` prints these steps in order with this column, and what the game's files
+already settle.
+
+| Step | Next time | Notes |
+|---|---|---|
+| One-time setup | You: a Cloud project, a service account, its invite, a testers Google Group | See below; `funtools store doctor --store play` checks the key's path in `.env` (only that the file exists). |
+| Create the app | You: name, default language, Game, free or paid, and the declarations | A legal tick; the package name is permanent once the app exists. |
+| Upload the AAB | Script: `edits.bundles.upload` (resumable) | Chrome's upload stops at 10 MB: a browser upload is the person's drag and drop. |
+| Internal release, testers | Script: `edits.tracks.update` on internal, then `edits.commit` | Testers through the API only as a Google Group: make one per studio once. |
+| Listing text | Script: `edits.listings.update` | Keep it in the same answers file as the App Store's (short description 80 characters). |
+| Icon, feature graphic, screenshots | Script: `edits.images.upload` per type | Upload order is display order; to reorder, delete and upload again. |
+| Contact email, website | Script: `edits.details.update` | Category stays in the console. |
+| Data safety | Script: `applications.dataSafety` (Play's CSV) | Export it from the first game once and keep it as `store/play-data-safety.csv`; every game with the same SDKs reuses it. |
+| App content: privacy URL, ads, ad ID, target audience, government, finance, health, AI declaration | Console | From the answers file; the ad ID answer follows the SDK list. |
+| Content rating (IARC) | Console | The questionnaire from the rating answers; the IARC terms tick is yours. |
+| Category, countries | Console | Not in the API (country availability is read-only there). |
+| Sign in details, promo codes | Console | A reviewer's way to the paid content; the promo terms tick is yours. |
+| License testers, managed publishing | Console | Managed publishing on, so an approved release waits for a click. |
+| One-time product, prices | Script: `monetization.onetimeproducts` | Product ids from the code, the same as iOS. Creating products needs an AAB with the billing permission on a track first. |
+| Native crash symbols | Script: `edits.deobfuscationfiles.upload` (`nativeCode`) | Per version code. Unity's symbols zip is refused by Firebase's tool (it needs unstripped libraries). |
+| Production release | Script: `edits.tracks.update` on production (completed, or staged with `userFraction`) | Give the service account production rights only if the agent should release. |
+| Send for review | You: the Publishing overview button | `edits.commit` sends the API's changes; console-only changes (declarations, countries) still need the button. |
+| Status, reviews, vitals | Script: Reviews API, Play Developer Reporting API | Read-only: safe to automate fully. |
+
+About 15–20 minutes of console work per game with the answers ready.
+
+One-time setup (the person, about 20 minutes): a Google Cloud project with the Play Android Developer
+API and the Play Developer Reporting API on; a service account whose JSON key lives outside the repo
+(its path in `.env`); invite it in Play Console › Users and permissions with testing-track releases,
+store presence, monetization and app info (production and finances off unless wanted); a testers
+Google Group.
+
+## Found on the first run
+
+- **Back**: Android can deliver press and release in one frame; read Back from input events or the
+  first press is lost. Back on the title screen sends the app to the background.
+- **Launch arguments are an attack surface**: a store build that reads intent extras lets any app pass
+  a debug unlock (a paywall bypass was found this way). Read them only in dev and test builds, and
+  check the AAB itself.
+- **The privacy policy must be reachable inside the game**, not only on the listing: a Settings row
+  that opens it. Update the site's privacy and support pages for Android too.
+- **The App Store and Play answers must agree**: an App Store "Data Not Collected" beside an analytics
+  SDK that Play's Data safety declares is a mismatch to fix.
+- **Reviewers need a way to the paid content**: a promo code in Sign in details (codes are console
+  only). On iOS the one rejection (2.1(b)) was a reviewer who could not find the purchase.
+- **Emulator automation**: Android's one-time "Viewing full screen" notice blocks the first run for
+  minutes; mark it seen before each launch. A smoke run leaves its save behind: clear it before the
+  next.
+- **Screenshots**: Play caps them at 2:1; re-shoot the store moments at Pixel 8 (1920×1080) and 10"
+  tablet (2560×1440) sizes from real captures rather than cropping iOS sets.
+- **Version code**: minutes since a fixed date, restored to the committed value after each build.
+
+## Risks it named
+
+Spam and repetitive content on a new account (release a few days apart, distinct listings, real
+gameplay in every shot); an inaccurate data safety form; 3D performance tuned on iPhones; download
+size without Android texture overrides; the first Gradle build; pending purchases.

package/plugins/claude/skills/store/references/ios-release.md

@@ -0,0 +1,63 @@
+# iOS release for a Unity game
+
+A Unity iOS build can upload "successfully" and still be broken, because most release failures are silent. Across nine games, four reached TestFlight with no sound, Firebase never started in release builds (3 broken uploads), one upload drew ITMS-90208 by email afterwards, and one game was pulled from review twice. This skill orders the checks so each failure shows on the Mac first.
+
+## Tools
+
+- The game's own build method,
+  `funtools unity run -- -nographics -buildTarget iOS -executeMethod Setup.BuildTestFlight`: it
+  applies the size settings, signing and a unique build number, and refuses to build without
+  `Assets/_Game/Art/Icon/app_icon.png`; a device and a Simulator build beside it. A post-process
+  step stamps every framework's minimum OS and the encryption key, and the linker is handed what
+  High stripping would remove.
+- Xcode: `xcodebuild archive` (automatic signing), then `xcodebuild -exportArchive` (manual signing;
+  `destination: upload` uploads it): 15–25 minutes.
+- App Store Connect (ASC), on the web or its API: bundle ids, profiles, processing, listings.
+- `funtools doctor`: its "iOS release" block names a missing distribution certificate, Xcode account
+  or ASC key (its `.p8` in `~/.appstoreconnect/private_keys/`): each blocks TestFlight.
+- Not in the kit: the studio's upload script with its pre-flight (`testflight.sh` needs
+  `games/<game>` and `.venv-asc`), the ASC scripts, and
+  the checks named below (`build_from_main`, `export_log`, `il2cpp_preserve`, `tmp_variants`,
+  `archive_contents`, `resources_hygiene`, `size_budget`, `texture_audit`).
+
+## Who does what
+
+| An agent may, with approval | Only a person |
+|---|---|
+| Register bundle ids, create App Store profiles | Create the app record (no API) |
+| Create Firebase projects | App Privacy (no API); Google/Firebase terms |
+| Archive, upload to TestFlight, poll processing | Paid Apps agreement, tax and banking |
+| Push listings | The first IAP tick on the version page |
+| Build a draft review submission | The Submit button; anything with credentials |
+
+No script changes the signing identity, team, bundle id or `ITSAppUsesNonExemptEncryption` without a person looking; the owner pinned the last: "do not flip".
+
+## Procedure
+
+1. Build only when HEAD equals origin/main and the tree is clean. TestFlight builds came from an unmerged branch (one game's icon was missing on main), and two review builds from uncommitted reimports (190 `.wav.meta` files, 4 TMP font assets), so main was not what Apple reviewed. Until `build_from_main` exists, compare by hand.
+2. Keep the Simulator's churn out of commits. Simulator builds rewrite `iPhoneSdkVersion` to 988 and dirty AudioManager, TMP font assets and URP global settings; `git commit -a` swept them in on one game.
+3. Confirm the build settings: IL2CPP, managed stripping High, strip engine code, code generation OptimizeSize, iOS 16.0, iPhone only (the build method sets them), LZ4HC. Signing: the build method sets the team and automatic signing; archive with `-allowProvisioningUpdates` and the ASC key, export manually with the Apple Distribution certificate and the bundle's App Store profile (`asc_profiles.py`). Never cloud-managed signing: it needs an Admin API key.
+4. Preserve what High stripping removes. Anything reached only at runtime (collider types for `CreatePrimitive`, the game's own assemblies) needs the game's `link.xml`; Unity ignores a package's own, so an Editor step hands that file to the linker. Pass for `il2cpp_preserve`: every assembly with `RuntimeInitializeOnLoadMethod` is present in il2cppOutput. Pass for `tmp_variants`: TMP `OUTLINE_ON` and `UNDERLAY_ON` kept, no `shader_feature` in runtime materials.
+5. Empty `Resources/` of test files (`resources_hygiene`: 0 bytes). The Unity test runner drops `PerformanceTestRun*.json` into `Assets/Resources`, which ships.
+6. Close any Editor on the project, run `funtools doctor`, then build, export and archive. Read the whole output: `| tail` hid a failing compile check.
+7. Read the export log before archiving (`export_log`: 0 errors, Burst timeouts included). Burst can time out under heavy host load; that export does not ship.
+8. Pre-flight the archive (`ios_preflight`): framework plist minimum OS equals the binary's, app icon present, audio on. Before the first TestFlight of a release, a fresh read-only agent does a publisher and story-consistency review: 6 blockers in one game, 30 issues in another.
+9. Check what the archive holds (`archive_contents`): a known string per level in `.app/Data`, the plist, a new CFBundleVersion. One archive on disk held Letter 1 only.
+10. Measure the unpacked `.app` from the archive (`size_budget`), not Unity's "Complete build size". Proposed budget: 2D ≤ 80 MB, 3D ≤ 100 MB, engine ≤ 45 MB, unexplained change ≤ 2 MiB per build; one 2D game is over it at 133 MB. `texture_audit` passes at 0 unwhitelisted RGBA32 or non-power-of-two mipmapped textures and RGBA32 under 1 MB in total.
+11. Upload with approval, then watch processing in App Store Connect. An upload that reports success can still fail by email (ITMS-90208).
+12. Submit in two hands. The API builds the draft; a person ticks the first IAP on the version page and presses Submit. The Game Center drafts the API leaves: not in the report.
+13. After a metadata-only rejection, new screenshots uploaded through the API do not clear it: a person edits and saves the version, then resubmits.
+14. A server-side minimum version compares the build number, not `CFBundleShortVersionString`: that is 1.0.0 on every TestFlight build, so one game's kill switch could not tell them apart.
+
+## Worked example
+
+A puzzle game's first upload, 25 Sep. The upload succeeded, then Apple emailed ITMS-90208: Unity 6000.6's `UnityRuntime.framework` says iOS 15.0 in its plist and 16.0 in its binary. The fix went into the shared package (a post-build step stamps every framework) and the upload script's pre-flight. Another game's TestFlight build then carried Unity's default icon and its next upload was refused, so the build method now refuses without `app_icon.png`. The same pre-flight later refused `m_DisableAudio: 1`, a setting a third game inherited from a cloned project.
+
+## Common mistakes
+
+- No AudioListener on a code-made camera: four games reached TestFlight silent, and Simulator captures hide it (`funtools doctor` warns).
+- Firebase reached only through `RuntimeInitializeOnLoadMethod` was stripped from release in every game: 3 broken uploads.
+- Submitting through the API alone: it dropped one game's first IAP and left Game Center drafts, and the game was pulled from review twice.
+- Trusting "Complete build size": One game's "1.08 GB" was the Xcode project; the archive was 123 MB.
+- Stripped TMP variants: outlined numbers drew as cream blobs in one game's player build.
+- Firebase C++ 13.17 has no arm64 Simulator slice, so every Firebase game failed to link for the Simulator; each game links null stubs (304 in one game), detected by `SIMULATOR_UDID`, because a Simulator reports a real device model.