@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/gamedev-shaders/references/unity-and-unreal-shaders.md

@@ -0,0 +1,169 @@
+# Unity 6 & Unreal 5.x shaders
+
+Depth behind SKILL.md's Unity and Unreal sections.
+
+---
+
+## Unity 6 (URP / HDRP)
+
+Unity 6 (6000.x LTS) ships the Scriptable Render Pipeline as the norm: **URP** (Universal) for
+most projects, **HDRP** (High Definition) for high-end PC/console. The retired Built-in RP still
+exists but do not author new shaders for it.
+
+### Choosing the authoring path
+
+| Path | When | Notes |
+| --- | --- | --- |
+| **Shader Graph** | Surface looks, VFX, artist iteration | Visual master stack (Vertex + Fragment blocks); URP/HDRP; compiles to HLSL. |
+| **Hand-written HLSL** | Custom lighting, tight control, compute-driven | ShaderLab wrapper + `HLSLPROGRAM` block including URP libraries. |
+
+**Surface shaders (`#pragma surface`) do NOT compile under URP/HDRP** — they are a Built-in-RP
+feature. Under SRP write a lit HLSL pass or use Shader Graph.
+
+### Minimal URP unlit HLSL shader
+
+```hlsl
+Shader "Custom/URPUnlitScroll" {
+    Properties {
+        _BaseMap ("Texture", 2D) = "white" {}
+        _Tint ("Tint", Color) = (1,1,1,1)
+        _Speed ("Scroll Speed", Float) = 0.1
+    }
+    SubShader {
+        Tags { "RenderPipeline"="UniversalPipeline" "RenderType"="Opaque" }
+        Pass {
+            HLSLPROGRAM
+            #pragma vertex vert
+            #pragma fragment frag
+            #include "Packages/com.unity.render-pipelines.universal/ShaderLibrary/Core.hlsl"
+
+            struct Attributes { float4 positionOS : POSITION; float2 uv : TEXCOORD0; };
+            struct Varyings   { float4 positionHCS : SV_POSITION; float2 uv : TEXCOORD0; };
+
+            TEXTURE2D(_BaseMap); SAMPLER(sampler_BaseMap);
+            CBUFFER_START(UnityPerMaterial)
+                float4 _BaseMap_ST; float4 _Tint; float _Speed;
+            CBUFFER_END
+
+            Varyings vert (Attributes IN) {
+                Varyings o;
+                o.positionHCS = TransformObjectToHClip(IN.positionOS.xyz);   // NOT UnityObjectToClipPos
+                o.uv = TRANSFORM_TEX(IN.uv, _BaseMap);
+                return o;
+            }
+            half4 frag (Varyings IN) : SV_Target {
+                float2 uv = IN.uv + float2(_Time.y * _Speed, 0);
+                return SAMPLE_TEXTURE2D(_BaseMap, sampler_BaseMap, uv) * _Tint;
+            }
+            ENDHLSL
+        }
+    }
+}
+```
+
+For a **lit** pass add `#include ".../Lighting.hlsl"`, compute normals in world space, and call
+`UniversalFragmentPBR` / light loops. `mul(UNITY_MATRIX_MVP, v)` and `UnityObjectToClipPos` are
+Built-in-RP idioms — never emit them for URP.
+
+### Shader Graph mapping (concepts)
+
+- **Master stack** = Vertex block (Position/Normal/Tangent) + Fragment block (Base Color, Metallic,
+  Smoothness, Emission, Alpha, Normal (Tangent Space)).
+- Time node → scrolling; Fresnel Effect node → rim; Sample Texture 2D → maps; Step/Smoothstep →
+  toon banding; Scene Color / Scene Depth nodes need the URP opaque texture / depth toggles on.
+- **Custom Function node** embeds an `.hlsl` snippet inside the graph (the Shader Graph analog of
+  UE's Custom node).
+
+### Runtime parameters
+
+`Material.SetFloat/SetColor/SetTexture`, or a `MaterialPropertyBlock` on the renderer for
+per-instance values without new material instances. Enable keyword variants with `#pragma
+multi_compile` / `shader_feature` and `Material.EnableKeyword`.
+
+### Full-screen / post-process (URP)
+
+Add a **Full Screen Pass Renderer Feature** to the URP Renderer and point it at a *Fullscreen*
+Shader Graph (Fullscreen master) or a Blit material. HDRP uses a Custom Pass Volume / Fullscreen
+Custom Pass. `OnRenderImage`/`Graphics.Blit` image effects are Built-in-RP only.
+
+---
+
+## Unreal 5.x
+
+A **Material** is a node graph compiled to HLSL. Targets UE 5.4+.
+
+### Result-node outputs
+
+Base Color, Metallic, Specular, Roughness, Anisotropy, Emissive Color, Opacity, Opacity Mask,
+Normal, World Position Offset, Ambient Occlusion, Refraction, Pixel Depth Offset. Which are active
+depends on the Blend Mode and Shading Model.
+
+### Material Domain — pick what it drives
+
+| Domain | Use |
+| --- | --- |
+| **Surface** | Standard meshes (default). |
+| **Deferred Decal** | Projected decals onto the g-buffer. |
+| **Light Function** | Modulates a light's contribution. |
+| **Volume** | Volumetric fog/clouds. |
+| **Post Process** | Full-screen effect on a Post Process Volume (see below). |
+| **User Interface** | UMG widget materials. |
+
+**Blend Mode**: Opaque / Masked (uses Opacity Mask + a mask clip value) / Translucent (uses
+Opacity) / Additive / Modulate. **Shading Model**: Default Lit / Unlit / Subsurface / Clear Coat /
+Two Sided Foliage / Hair / Eye / Cloth / Single Layer Water.
+
+Match the pin to the mode: Opacity needs Translucent/Additive; Opacity Mask needs Masked; feeding
+the wrong one is a silent no-op.
+
+### Custom HLSL node
+
+The escape hatch when the node set can't express the logic (loops, bitwise, custom math). Set the
+node's **Output Type**, add named **Inputs** (they become HLSL variables), write HLSL, `return`:
+
+```hlsl
+// Inputs: Time (Scalar), UV (Vector2), Freq (Scalar). Output Type: CMOT Float3.
+float scan = 0.5 + 0.5 * sin(UV.y * Freq + Time * 6.2831);
+float rim  = pow(1.0 - saturate(dot(normalize(V), normalize(N))), 3.0); // wire V,N as inputs
+return float3(scan, scan, scan) * rim;
+```
+
+Prefer graph nodes for anything nodes *can* express — Custom nodes block constant-folding and
+some cross-platform optimizations. Reuse shared logic via **Material Functions**.
+
+### Material Instances
+
+Mark parameters (right-click a constant → *Convert to Parameter*): Scalar, Vector, Texture,
+StaticSwitch. A **Material Instance Constant** is an authored variant; a **Dynamic Material
+Instance** (`CreateDynamicMaterialInstance`) is set at runtime:
+
+```cpp
+UMaterialInstanceDynamic* MID = Mesh->CreateDynamicMaterialInstance(0, BaseMat);
+MID->SetScalarParameterValue("Dissolve", 0.7f);
+MID->SetVectorParameterValue("EdgeColor", FLinearColor(1, 0.4f, 0));
+```
+
+Static switches compile out branches into variants; use them for feature toggles rather than a
+runtime `if`.
+
+### Post-process material
+
+Set Material Domain = **Post Process**, add it to a **Post Process Volume** (or camera). Read the
+frame with **SceneTexture** nodes — `PostProcessInput0` (scene color), `SceneDepth`, world normal,
+custom-depth/custom-stencil for masking specific actors. **Blendable Location** (Before/After
+Tonemapping, etc.) sets ordering; SceneTexture nodes only work in this domain.
+
+---
+
+## Godot ↔ Unity ↔ Unreal quick map
+
+| Concept | Godot 4 | Unity URP | Unreal 5 |
+| --- | --- | --- | --- |
+| Color output | `ALBEDO` / `EMISSION` | Base Color / Emission block | Base Color / Emissive Color |
+| Alpha cutout | `discard` / `ALPHA_SCISSOR_THRESHOLD` | `clip()` / Alpha Clip Threshold | Opacity Mask (Masked) |
+| Fresnel/rim | `1 - dot(NORMAL, VIEW)` | Fresnel Effect node | Fresnel node |
+| Screen color | `hint_screen_texture` | Scene Color node / opaque texture | SceneTexture: PostProcessInput0 |
+| Scene depth | `hint_depth_texture` | Scene Depth node | SceneTexture: SceneDepth |
+| Time | `TIME` | Time node / `_Time.y` | Time node |
+| Runtime param | `set_shader_parameter` | `Material.SetFloat` | `SetScalarParameterValue` (MID) |
+| Full-screen FX | ColorRect + `hint_screen_texture` / CompositorEffect | Full Screen Pass Renderer Feature | Post Process material + volume |

package/skills/gamedev-shipping/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: gamedev-shipping
+description: "Use when exporting, building, packaging, or publishing a game — per engine (Godot export templates, Unity Build Profiles, Unreal Shipping vs Development) and per platform: desktop (Windows/macOS/Linux; macOS codesign + notarytool notarization), web (the COOP same-origin + COEP require-corp headers threaded SharedArrayBuffer WebAssembly builds need, and that Godot's C#/.NET edition can't export to web), mobile (Android JDK 17 build template, AAB vs APK, release keystore; iOS provisioning). Also store prep (icons/splash, metadata, age ratings, AAB for Play, Mac App Store, Steamworks/SteamPipe, itch.io butler), headless-export CI/CD, build/version numbers, and ship-time size/startup optimization. Triggers: 'export my game', 'build for Steam', 'ship to web/mobile', 'publish to the Play Store', 'notarize my Mac build', 'itch.io upload', 'SharedArrayBuffer is not defined'. NOT for writing gameplay/runtime code (that's the engine skill — godot/unity/unreal) or hosting a normal web app/API/container (→ deployment)."
+tags: [export, build, release, packaging, store, steam, itch, notarization, webassembly, aab]
+recommends: [godot, unity, unreal, deployment]
+profiles: [full]
+origin: risco
+---
+
+# Ship the game — export, build & release (per engine · per platform)
+
+Take a finished project from editor → signed, correctly-configured artifact → live on the
+right target (desktop / web / mobile / store), with the platform gotchas that silently break a
+build handled up front. This skill owns the *packaging and release boundary*; the engine skills
+own the code that runs inside the artifact.
+
+```text
+project ──[engine export/build]──▶ artifact ──[per-platform sign/config]──▶ target
+Godot templates·Unity Build Profiles·Unreal Shipping    desktop·web·mobile    Steam·Play·App Store·itch
+```
+
+## Version anchors (what "current" means here — July 2026)
+
+| Tool | Target | Ship note |
+| --- | --- | --- |
+| Godot | 4.5 stable (4.6 dev) | Export templates must match the editor build **exactly** (4.5.1 editor ⇒ 4.5.1 templates). **C#/.NET edition has NO web export** — GDScript/standard only. |
+| Unity | Unity 6 (6000.x) | "Build Settings" is now **Build Profiles**. IL2CPP backend for iOS/Android/WebGL. |
+| Unreal | 5.6 | Ship in the **Shipping** config; test packaged builds in **Development**. |
+| Android | JDK **17**, target a recent API level | AAB required for Google Play (new apps + updates). APK only for sideload/itch/direct. |
+| iOS/macOS | Xcode 16+, `notarytool` | `altool` notarization is dead — use `xcrun notarytool`. |
+
+## When to use / When NOT to use
+
+**Use when:**
+- Configuring export templates / build presets / packaging settings for any target.
+- Signing & notarizing a desktop build, or debugging Gatekeeper/SmartScreen rejections.
+- Fixing a web build that boots to `SharedArrayBuffer is not defined` or a blank canvas.
+- Producing an AAB/APK or an iOS archive; wiring keystores/provisioning.
+- Store submission prep (icons, metadata, ratings) or uploading to Steam/itch/Play/App Store.
+- Automating headless exports in CI, or setting version/build numbers.
+- Shrinking build size / startup time before release.
+
+**NOT for (route elsewhere, say so, stop):**
+- Writing gameplay, shaders, netcode, or any runtime logic → the **engine** skill (`godot`/`unity`/`unreal`) or `gamedev-shaders`/`gamedev-multiplayer`. This skill packages code; it does not write it.
+- Hosting a normal web app, API, or container (Dockerfile, Coolify, Vercel, VPS) → **`deployment`**. A WebAssembly game is *static files*; only its **headers** are special (below).
+- Designing game feel, economy, or narrative → `game-design` / `game-storytelling`.
+
+## Decision rules (settle these before touching a build)
+
+| Question | Rule |
+| --- | --- |
+| Web build uses threads / SharedArrayBuffer? | You **must** serve `COOP: same-origin` + `COEP: require-corp` (cross-origin isolation). No headers ⇒ no threads ⇒ boot failure. |
+| Godot + C# + web? | **Impossible today.** Switch to GDScript for web, or ship that title desktop/mobile only. |
+| Play Store? | **AAB**, signed with an upload key, Play App Signing on. Not APK. |
+| macOS distribution outside the App Store? | codesign (Developer ID) → **notarize** → **staple**. Skipping = Gatekeeper blocks it. |
+| Mac **App Store**? | Different cert (Apple Distribution) + sandbox entitlements; notarization is automatic, not manual. |
+| Steam? | SteamPipe upload via `steamcmd` + an `app_build` VDF; set the default branch live in the partner site. |
+| Quick public build / demo / jam? | **itch.io** + `butler push`. Tick "SharedArrayBuffer support" for threaded web builds. |
+| Release config? | Godot **release** preset (debug off), Unity release/**IL2CPP**, Unreal **Shipping**. Never ship a debug/Development build. |
+
+## Export / build per engine
+
+**Godot** — `Editor ▸ Manage Export Templates` (match version), then `Project ▸ Export`, add one
+preset per platform. Headless for CI:
+
+```bash
+godot --headless --export-release "Windows Desktop" build/game.exe
+godot --headless --export-release "Web"             build/index.html
+# Android AAB needs the Gradle build template + JDK 17 + a release keystore (see references)
+```
+
+Web preset toggles: **Thread Support** (⇒ needs COOP/COEP) and **Extensions Support**. Android
+needs `Project ▸ Install Android Build Template` (enables *Use Gradle Build*).
+
+**Unity** — `File ▸ Build Profiles` (formerly Build Settings). Create a profile per platform;
+override **Player Settings** per profile (company/product name, bundle id, icons, scripting
+backend). iOS/Android/WebGL force **IL2CPP**. CI headless:
+
+```bash
+Unity -quit -batchmode -nographics -projectPath . \
+  -buildTarget Android -executeMethod BuildScript.PerformBuild -logFile -
+```
+
+Android: tick **Build App Bundle (Google Play)** for AAB; set the keystore in *Publishing Settings*.
+WebGL: threads ⇒ COOP/COEP; keep **decompression fallback** for hosts that can't set gzip/br headers.
+
+**Unreal** — build **configurations**, not "modes": Debug, DebugGame, **Development** (test packaged
+builds — keeps logs/console), Test, **Shipping** (release — strips logging, most optimized). Package
+via `Platforms ▸ <target> ▸ Package Project`, the Project Launcher, or UAT for CI:
+
+```bash
+RunUAT BuildCookRun -project="Game.uproject" -platform=Win64 \
+  -clientconfig=Shipping -cook -stage -pak -package -archivedirectory=build
+```
+
+Android adds `-distribution` for an AAB; iOS requires a Mac + provisioning. Run the platform
+**Turnkey**/SDK setup once (Android Studio + NDK, or Xcode) or the cook fails.
+
+→ full per-engine preset/flag tables: `references/mobile-and-desktop.md` and `references/stores-and-ci.md`.
+
+## Per-platform
+
+### Desktop (Windows / macOS / Linux) — the simplest path
+
+| OS | Sign? | Gotcha |
+| --- | --- | --- |
+| Windows | Optional (Authenticode; EV avoids SmartScreen warm-up) | Unsigned still runs but SmartScreen warns; ship `.exe` + engine data next to it, or an installer. |
+| Linux | No | Ship binary + data, or wrap as **AppImage**/**Flatpak** for a portable single file. |
+| macOS | **Required** | Must codesign (Developer ID Application) **+ notarize + staple**, or Gatekeeper refuses to open it. |
+
+macOS notarization (the step everyone forgets):
+
+```bash
+codesign --deep --force --timestamp --options runtime \
+  --sign "Developer ID Application: Studio (TEAMID)" Game.app
+ditto -c -k --keepParent Game.app Game.zip
+xcrun notarytool submit Game.zip --keychain-profile "AC" --wait   # store creds once via store-credentials
+xcrun stapler staple Game.app                                     # staple so it verifies offline
+```
+
+`--options runtime` (Hardened Runtime) is **mandatory** for notarization. Codesign every bundled
+`.dylib`/helper *before* the outer `.app`, inside-out.
+
+### Web — the header trap (read this before blaming your build)
+
+Threaded WebAssembly builds (Godot with Thread Support, Unity WebGL with threads) use
+**`SharedArrayBuffer`**, which browsers gate behind **cross-origin isolation**. The server must send:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Missing them ⇒ `SharedArrayBuffer is not defined`, a hang, or a blank canvas — even though the
+files are fine. Where to set them:
+
+- **Netlify** `_headers`, **Vercel** `vercel.json` headers, **nginx** `add_header` — set both on the game path.
+- **itch.io** — tick **"This file will be played in the browser" ▸ SharedArrayBuffer support**; itch sets the headers for you.
+- **GitHub Pages** — **cannot** set headers. Use a non-threaded export, or the `coi-serviceworker` shim (a service worker that re-serves with the headers).
+
+`COEP: require-corp` also means every cross-origin subresource (fonts, analytics, embeds) must
+send CORP/CORS or it's blocked. **Godot C#/.NET has no web export at all** — use GDScript.
+
+→ hosts, exact configs, the service-worker shim, self-test: `references/web-export-headers.md`.
+
+### Mobile
+
+**Android** — needs **JDK 17** and the engine's Gradle build template. Ship **AAB** to Play
+(Google re-signs and generates per-device APKs), **APK** for sideload/itch/direct. Generate a
+release keystore once and reuse it forever (lose it = you can't update the app without Play App
+Signing key reset):
+
+```bash
+keytool -genkey -v -keystore release.keystore -alias game \
+  -keyalg RSA -keysize 2048 -validity 10000
+```
+
+Keep the keystore + passwords out of git (CI secret). `versionCode` must increase every upload.
+
+**iOS** — Mac + Xcode + Apple Developer account. Bundle ID must match an **App ID**; pick a
+**provisioning profile** (development / ad-hoc / App Store) and a signing certificate. Archive,
+then upload to App Store Connect / TestFlight via Xcode Organizer or **Transporter**. `CFBundleVersion`
+must increase per upload.
+
+→ full keystore, Play App Signing, provisioning, TestFlight walkthrough: `references/mobile-and-desktop.md`.
+
+## Store prep
+
+- **Assets**: platform icons (Android adaptive, iOS icon set, Windows `.ico`, macOS `.icns`), splash/launch, store screenshots per device class, a trailer where required.
+- **Metadata**: title, short + full description, keywords, category, support/privacy URLs, localized strings.
+- **Age ratings**: fill the **IARC** questionnaire (Play, Microsoft, Nintendo) or ESRB/PEGI/USK; Apple has its own age-rating questionnaire. Wrong answers = removal.
+- **Google Play**: AAB + **Play App Signing**, a recent **target API level**, content rating, and the **Data safety** form.
+- **Steam**: Steamworks partner + appid; define **depots**; upload with **SteamPipe** (`steamcmd +run_app_build app_build_APPID.vdf`); store page assets; set the branch live.
+- **itch.io**: `butler push build/ user/game:channel --userversion 1.2.3` — channel name (e.g. `windows`, `html5`) picks the platform.
+- **Mac App Store**: Apple Distribution cert + App Sandbox entitlements (not Developer ID); notarization is handled by App Store submission.
+
+→ Steamworks/SteamPipe VDF, butler channels, Play/App Store checklists: `references/stores-and-ci.md`.
+
+## CI/CD for builds
+
+Headless export in GitHub Actions; version from the run/commit so every artifact is traceable.
+
+- **Godot**: run in a container that bundles matching export templates (e.g. a `barichello/godot-ci`-style image), `godot --headless --export-release`.
+- **Unity**: `game-ci/unity-builder` + a license activation step (secrets); matrix over targets.
+- **Unreal**: needs a **self-hosted runner** with the engine installed (multi-GB); UAT `BuildCookRun`.
+- **Signing in CI**: import the keystore/cert from an encrypted secret at runtime, never commit it. macOS notarization runs on a `macos-latest` runner with `notarytool` + an App Store Connect API key.
+- **Versioning**: semver tag for releases; a monotonic build number from `github.run_number` or the git commit count feeds `versionCode`/`CFBundleVersion`/Steam build description.
+
+→ ready workflows per engine: `references/stores-and-ci.md`.
+
+## Ship-time optimization
+
+- **Texture compression per platform**: ASTC (mobile), BCn/DXT (desktop), ETC2 (GLES fallback). Set per-platform import overrides — never ship uncompressed PNGs to mobile.
+- **Strip the fat**: Unity **Managed Stripping Level: High** + IL2CPP; Unreal **Shipping** drops logs/console; Godot — export only used resources and disable unused modules in a custom template.
+- **Startup**: small boot scene, stream/preload heavy assets, compress the `.pck`/data, use Ogg Vorbis over WAV. Web: enable gzip/brotli on `.wasm`/`.pck`.
+- **Budgets**: set a per-platform size budget (web especially — every MB is download latency) and check the final artifact against it before submitting.
+
+## Anti-patterns — rationalization → STOP
+
+| Rationalization | STOP — do this instead |
+| --- | --- |
+| "Web build works locally, host later" | Set COOP/COEP now; `file://`/simple servers hide the `SharedArrayBuffer` failure. |
+| "I'll add C# web export for Godot" | It doesn't exist in 4.x. GDScript for web, or no web. |
+| "Notarization is optional" | On macOS, no notarize+staple = Gatekeeper blocks the app for every user. |
+| "Ship an APK to the Play Store" | Play requires **AAB** for new apps and updates. |
+| "Commit the keystore so CI can sign" | Keystore/cert live in encrypted CI secrets, never in git. |
+| "Ship the Development/Debug config" | Ship Godot release / Unity IL2CPP release / Unreal **Shipping** — debug leaks console + is slow. |
+| "Templates are close enough (4.5 vs 4.5.1)" | Godot templates must match the editor build exactly or export breaks. |
+| "Uncompressed textures are fine" | Per-platform compression (ASTC/BCn/ETC2) — raw textures blow memory + size. |
+| "Reuse an old versionCode/CFBundleVersion" | Both must strictly increase or the store rejects the upload. |
+
+## Related skills
+
+- `godot`, `unity`, `unreal` — write the game; this skill exports/ships what they build. Draw the line at the export button.
+- `deployment` — Docker/CI/hosting for **web apps & APIs**; borrow its GitHub Actions + header-setting patterns, but a WebAssembly game is static files, not a container.
+- `gamedev-shaders`, `gamedev-multiplayer`, `gamedev-physics` — runtime subsystems packaged into the ship artifact, not configured here.
+- `secure-coding` — signing-key and secret handling this skill assumes for keystores/certs in CI.
+
+## Checklist
+
+- [ ] Release/Shipping config, not Debug/Development.
+- [ ] (Godot) export templates match the editor version exactly.
+- [ ] (Web, threaded) COOP `same-origin` + COEP `require-corp` served; boots without `SharedArrayBuffer` errors.
+- [ ] (Godot + web) confirmed GDScript, not C#/.NET.
+- [ ] (macOS) codesigned (Hardened Runtime) + notarized + stapled.
+- [ ] (Android) AAB for Play, JDK 17, release keystore in CI secrets, `versionCode` bumped.
+- [ ] (iOS) provisioning profile + signing cert correct, `CFBundleVersion` bumped.
+- [ ] Store assets: icons, splash, screenshots, metadata, age rating done.
+- [ ] Version/build number set from CI and traceable.
+- [ ] Textures compressed per platform; build size within budget.
+
+## References
+
+- `references/web-export-headers.md` — cross-origin isolation deep dive: COOP/COEP per host (Netlify/Vercel/nginx/itch/GitHub Pages), the `coi-serviceworker` shim, COEP subresource fallout, self-test snippet, Godot vs Unity web specifics.
+- `references/mobile-and-desktop.md` — Android keystore + Gradle template + Play App Signing; iOS provisioning/TestFlight; full macOS codesign→notarytool→staple; Windows Authenticode; Linux AppImage/Flatpak.
+- `references/stores-and-ci.md` — Steamworks/SteamPipe VDF upload, itch.io butler channels, Play/App Store submission checklists, and per-engine GitHub Actions headless-build workflows with signing.

package/skills/gamedev-shipping/evals/README.md

@@ -0,0 +1,9 @@
+# Evals — gamedev-shipping
+
+These cases assert the skill fires on export/build/package/publish requests across engines
+(Godot/Unity/Unreal) and platforms (desktop/web/mobile/store), and that it stays out of runtime
+code (routes gameplay → engine skills, netcode → gamedev-multiplayer) and normal web-app hosting
+(→ deployment). The capability scenarios check the load-bearing, version-correct facts: the
+COOP/COEP cross-origin-isolation headers for threaded web builds, the macOS
+codesign→notarytool→stapler chain, the Android JDK 17 + AAB + keystore release path, and the
+Godot C#/.NET "no web export" limitation.

package/skills/gamedev-shipping/evals/cases.yaml

@@ -0,0 +1,55 @@
+skill: gamedev-shipping
+
+should_trigger:
+  - prompt: "My Godot game runs in the editor but the exported web build just shows a black screen and the console says 'SharedArrayBuffer is not defined'. How do I host it?"
+    why: "The signature web-ship failure: threaded WebAssembly needs COOP same-origin + COEP require-corp headers set at the host — core web-export-headers scope."
+  - prompt: "How do I export and package my Unity 6 project as an AAB for the Google Play Store and sign it?"
+    why: "Per-engine (Unity Build Profiles) + per-platform Android AAB vs APK + release keystore signing — squarely this skill's packaging boundary."
+  - prompt: "I built my macOS game but users get a 'can't be opened because Apple cannot check it for malware' warning. What do I need to do before distributing it?"
+    why: "macOS Gatekeeper rejection → the codesign (Hardened Runtime) + notarytool + stapler chain this skill owns."
+  - prompt: "Set up a GitHub Actions workflow that headless-exports my Godot game for web and Linux on every tag and uploads the artifacts."
+    why: "Headless-export CI/CD with matching export templates and version numbering — the CI section and stores-and-ci reference."
+  - prompt: "I'm ready to publish to Steam. How do I upload my build with SteamPipe and push it to a beta branch first?"
+    why: "Steamworks/SteamPipe VDF upload via steamcmd and branch promotion — store-prep scope."
+  - prompt: "What's the difference between Development and Shipping when packaging my Unreal game, and which do I use for release?"
+    why: "Unreal build-configuration choice for release packaging — per-engine export/build scope (Shipping vs Development)."
+  - prompt: "Can I export my Godot C# project to the web? It keeps failing."
+    why: "The known limitation: Godot's C#/.NET edition has no web export in 4.x — this skill must state that and route the user (GDScript or non-web target)."
+  - prompt: "Push my HTML5 and Windows builds to itch.io with butler and bump the version."
+    why: "itch.io butler channels + userversion, plus the SharedArrayBuffer support checkbox for web — store-prep scope."
+
+should_not_trigger:
+  - prompt: "Add double-jump and coyote-time to my player controller in Godot."
+    route_to: "godot"
+    why: "Gameplay/runtime code is the engine skill's job; this skill only packages and ships what the engine produces."
+  - prompt: "Write a Dockerfile and Coolify config to deploy my Next.js web app with a Postgres database."
+    route_to: "deployment"
+    why: "Hosting a normal containerized web app/API is deployment's domain; a game ship is static WASM files or a native binary, not a container."
+  - prompt: "My multiplayer game has rubber-banding; how do I add client-side prediction and server reconciliation?"
+    route_to: "gamedev-multiplayer"
+    why: "Netcode runtime behavior, not build/release — belongs to the multiplayer skill."
+  - prompt: "Help me design the progression curve and reward economy for my roguelike."
+    route_to: "game-design"
+    why: "Game feel/economy design is not an export or packaging task."
+  - prompt: "Optimize this fragment shader that's tanking my frame rate on mobile."
+    route_to: "gamedev-shaders"
+    why: "Runtime rendering performance is a shader-authoring concern, distinct from ship-time build-size/startup optimization."
+
+capability:
+  - scenario: "User's threaded Godot 4 web export fails with 'SharedArrayBuffer is not defined' and they plan to host it on Netlify (and later ask about GitHub Pages)."
+    must_include:
+      - "Explains threaded WASM needs cross-origin isolation via BOTH Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp response headers"
+      - "Gives the Netlify _headers (or equivalent) config setting both headers, and notes itch.io's SharedArrayBuffer checkbox as an alternative"
+      - "Notes GitHub Pages can't set headers, so use a single-threaded export or the coi-serviceworker shim"
+      - "Mentions self.crossOriginIsolated === true as the verification check"
+      - "Warns that Godot's C#/.NET edition has no web export in 4.x (only GDScript/standard)"
+  - scenario: "User wants to ship a signed macOS desktop build for distribution outside the App Store."
+    must_include:
+      - "codesign with --options runtime (Hardened Runtime is mandatory for notarization) using a Developer ID Application identity"
+      - "Submit with xcrun notarytool submit --wait (not the deprecated altool)"
+      - "Staple the ticket with xcrun stapler staple so it verifies offline, and that skipping notarization means Gatekeeper blocks it"
+  - scenario: "User asks how to produce and sign an Android release for Google Play from Unity."
+    must_include:
+      - "Requires JDK 17 and building an AAB (not APK) for Google Play"
+      - "Generate/keep a release keystore (keytool) and never commit it; use Play App Signing"
+      - "versionCode must strictly increase on every upload"

package/skills/gamedev-shipping/references/mobile-and-desktop.md

@@ -0,0 +1,127 @@
+# Mobile & desktop — signing, keystores, provisioning, notarization
+
+Back to the entrypoint: `../SKILL.md`. The per-OS steps that gate a shippable build.
+
+## Android
+
+### Toolchain
+
+- **JDK 17** — the version the current Gradle build template expects. JDK 21 or 11 breaks the
+  build with cryptic Gradle errors. Point the engine's Android settings at a JDK 17 home.
+- **Android SDK + build-tools + platform-tools**; NDK for native/IL2CPP.
+- Godot: `Project ▸ Install Android Build Template`, then tick **Use Gradle Build** on the Android
+  preset — required to produce an **AAB** and to use custom Gradle/plugins.
+- Unity: `File ▸ Build Profiles ▸ Android`; **Build App Bundle (Google Play)** for AAB.
+- Unreal: run **Turnkey**/Android setup once (Android Studio + correct NDK), then
+  `RunUAT BuildCookRun ... -platform=Android -clientconfig=Shipping -distribution -cook -stage -pak -package`.
+
+### AAB vs APK
+
+| Format | Use for | Notes |
+| --- | --- | --- |
+| **AAB** (`.aab`) | Google Play (**required** for new apps + updates) | Play generates optimized per-device APKs; you can't install an AAB directly. |
+| **APK** (`.apk`) | Sideload, itch.io, direct download, other stores | Installs directly; use a universal APK for QA. |
+
+### Signing & keystore
+
+Generate a release keystore **once** and guard it — losing it means you can't publish updates
+(unless enrolled in Play App Signing, where Google holds the app-signing key and you rotate the
+upload key):
+
+```bash
+keytool -genkey -v -keystore release.keystore -alias game \
+  -keyalg RSA -keysize 2048 -validity 10000
+```
+
+- Godot: set the **Release** keystore path + alias + passwords in the Android preset (and a debug
+  keystore for debug exports).
+- Never commit the keystore or passwords. In CI, restore the keystore from a base64-encoded secret
+  at runtime and pass passwords via env.
+- **Play App Signing**: you sign the upload with the *upload key*; Google re-signs distribution
+  with the *app-signing key* it stores. Recommended — it lets you recover a lost upload key.
+- `versionCode` (integer) must **strictly increase** every upload; `versionName` is the human string.
+
+### Common failures
+
+- Editor 4.5.1 + templates 4.5 ⇒ export greyed out or Gradle error. Match versions exactly.
+- Wrong JDK ⇒ Gradle build fails. Use 17.
+- Debug keystore used for a release ⇒ Play rejects it.
+- Target API level too old ⇒ Play blocks the submission.
+
+## iOS
+
+- **Mac + Xcode + an Apple Developer Program membership** (paid) are non-negotiable for device/store builds.
+- **Bundle Identifier** must match a registered **App ID** in the developer portal.
+- **Signing certificate** (Apple Development / Apple Distribution) + a **provisioning profile**
+  that ties App ID + certificate + devices/distribution method:
+  - *Development* — run on registered test devices.
+  - *Ad Hoc* — distribute to a fixed device list outside the store.
+  - *App Store* — submit to App Store Connect / TestFlight.
+- Enable **Automatically manage signing** in Xcode for the common case; use manual profiles for CI.
+- Flow: engine exports an Xcode project → open in Xcode → set team/signing → **Product ▸ Archive**
+  → distribute via the Organizer, or upload with **Transporter** to App Store Connect.
+- **TestFlight** for beta: upload a build, add internal/external testers, then submit for review.
+- `CFBundleShortVersionString` = marketing version; `CFBundleVersion` = build number, must
+  **increase** per upload to App Store Connect.
+
+## macOS (desktop, outside the App Store)
+
+Gatekeeper will refuse an unsigned/un-notarized app for end users. The full chain is codesign →
+notarize → staple, inside-out.
+
+```bash
+# 1. Sign every nested binary FIRST, then the outer .app (Hardened Runtime is mandatory)
+codesign --deep --force --timestamp --options runtime \
+  --sign "Developer ID Application: Studio Name (TEAMID)" Game.app
+
+# 2. Store notarization creds once (App Store Connect API key or Apple ID app-password)
+xcrun notarytool store-credentials "AC" \
+  --apple-id you@studio.com --team-id TEAMID --password app-specific-pw
+
+# 3. Zip and submit; --wait blocks until Apple returns accepted/invalid
+ditto -c -k --keepParent Game.app Game.zip
+xcrun notarytool submit Game.zip --keychain-profile "AC" --wait
+
+# 4. Staple the ticket so the app verifies OFFLINE, then verify
+xcrun stapler staple Game.app
+spctl --assess --type execute -vvv Game.app   # should say: accepted, source=Notarized Developer ID
+```
+
+- `--options runtime` (Hardened Runtime) is **required** or notarization is rejected.
+- Sign nested `.dylib`s / helper tools / frameworks before the parent bundle.
+- Distributing a `.dmg`? Notarize and staple the **`.dmg`** too (submit the dmg, staple the dmg).
+- `altool` notarization is retired — use `xcrun notarytool`.
+- If `notarytool` returns `Invalid`, fetch the log: `xcrun notarytool log <submission-id> --keychain-profile "AC"`.
+
+### Mac App Store (different path)
+
+- Sign with **Apple Distribution** (not Developer ID) + **App Sandbox** entitlements.
+- Submit through App Store Connect (via Xcode/Transporter); the store notarizes automatically —
+  you do not run `notarytool`/`stapler` manually for App Store builds.
+
+## Windows
+
+- Signing is **optional** but recommended: an Authenticode code-signing certificate reduces the
+  SmartScreen "unknown publisher" warning. An **EV** certificate builds reputation faster.
+
+```powershell
+signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 /a Game.exe
+```
+
+- Ship the `.exe` alongside the engine data/`.pck` (or bundle into an installer: Inno Setup / NSIS / MSIX).
+- Unsigned still runs; users just click through a SmartScreen prompt.
+
+## Linux
+
+- No signing requirement. Ship the executable + data files, or wrap for portability:
+  - **AppImage** — one self-contained file, runs across distros; easiest for direct/itch distribution.
+  - **Flatpak** — sandboxed, distributed via Flathub; more packaging work, best store reach.
+- Mark the binary executable (`chmod +x`) and test on a clean distro (glibc version differences bite).
+
+## Cross-platform checklist
+
+- [ ] Android: JDK 17, AAB for Play (APK for sideload), release keystore in CI secret, `versionCode` bumped, Play App Signing on.
+- [ ] iOS: App ID + cert + provisioning profile matched, `CFBundleVersion` bumped, archive uploaded.
+- [ ] macOS: codesign (Hardened Runtime) → notarytool → stapler → `spctl` accepted.
+- [ ] Windows: signed (or SmartScreen prompt accepted as known), installer built if needed.
+- [ ] Linux: AppImage/Flatpak or binary+data, tested on a clean distro.