@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/unity/SKILL.md

@@ -0,0 +1,282 @@
+---
+name: unity
+description: "Use when writing, reviewing, or structuring Unity game code in C# for current Unity 6 LTS (6000.x) — GameObjects and Transform hierarchy, MonoBehaviour lifecycle, prefabs and prefab variants, ScriptableObjects for data, scenes and additive loading, the new Input System, coroutines vs async/await/Awaitable, Addressables, and build/player settings for 2D and 3D. Triggers: 'my Unity script', 'Awake vs Start', 'why is my physics jittery', MonoBehaviour .cs files, 'set up the new Input System', 'ScriptableObject config', 'load a scene additively', 'Instantiate a prefab', 'convert Input.GetAxis to the new system', 'build for Android/WebGL', 'por qué no se llama mi Start', 'com carrego una escena en additiu'. NOT Godot/GDScript (that is godot); NOT Unreal/Blueprint/C++ engine work (that is unreal); NOT the netcode wire protocol itself (that is gamedev-multiplayer)."
+tags: [unity, csharp, game-dev, monobehaviour, input-system]
+recommends: [gamedev-multiplayer, gamedev-physics, gamedev-shaders, gamedev-pathing, gamedev-shipping, godot, unreal]
+profiles: [full]
+origin: risco
+---
+
+# Unity + C# (Unity 6 LTS)
+
+> Idiomatic C# for the current Unity engine — 2D and 3D. Owns engine-side patterns (components,
+> lifecycle, prefabs, scenes, data, input, async, builds). Not Godot (`godot`) or Unreal (`unreal`);
+> stops at the netcode wire (`gamedev-multiplayer`).
+
+## Version contract — read first
+
+**Target: Unity 6 LTS, versioned `6000.x`.** Current LTS at authoring is **Unity 6.3 LTS (`6000.3`)**
+(supported to Dec 2027); **Unity 6.0 LTS (`6000.0`)** to Oct 2026. Unity 6 dropped the year-based names
+(2020/2021/2022 LTS) for the `6000.x` scheme. Confirm the project version in
+`ProjectSettings/ProjectVersion.txt` before assuming an API exists.
+
+**Ban-list — never emit these; use the modern replacement:**
+
+| Deprecated / removed | Use instead |
+| --- | --- |
+| `Input.GetAxis` / `GetKey` / `GetButton` (legacy Input Manager) | **new Input System** (`com.unity.inputsystem`): `InputActionAsset` / `InputAction` / `PlayerInput` — §6 |
+| `UnityEngine.Networking` (UNet), `NetworkServer`/`NetworkClient`, its `NetworkBehaviour` | **removed** since 2022.2. → **Netcode for GameObjects** (`com.unity.netcode.gameobjects`) + `gamedev-multiplayer` |
+| `Resources.Load(...)` for game content | **Addressables** (`com.unity.addressables`) — §8 |
+| `FindObjectOfType<T>()` / `FindObjectsOfType<T>()` | `FindFirstObjectByType<T>()` / `FindAnyObjectByType<T>()` / `FindObjectsByType<T>(FindObjectsSortMode.None)` (old ones obsolete since 2023.1) |
+| `WWW` | `UnityWebRequest` |
+| `OnGUI` / IMGUI for runtime game UI | **UI Toolkit** (runtime) or uGUI; keep IMGUI for editor tools only |
+| Setting `transform.position` on a `Rigidbody` in `Update` | `Rigidbody.MovePosition/MoveRotation` in `FixedUpdate` — §4 |
+| `GameObject.Find`/`FindWithTag` by string in `Update` | cache the ref in `Awake`, or `[SerializeField]` it |
+
+Prefer the new Input System even for single-player prototypes. Keep `Debug.Log` out of hot loops and
+strip it from ships.
+
+## 1. GameObject / Component model & Transform hierarchy
+
+A **GameObject** is an empty container; behaviour comes from **Components** you attach
+(`Transform`, `Rigidbody`, `MeshRenderer`, and your `MonoBehaviour` scripts). Every GameObject has
+exactly one `Transform` (or `RectTransform` under a Canvas) giving position/rotation/scale.
+
+- Get components: `TryGetComponent(out var rb)` (no-alloc, preferred), `GetComponent<T>()`,
+  `GetComponentInChildren/InParent<T>()`. Cache in `Awake` — `GetComponent` in `Update` is a perf sink.
+- Hierarchy: `transform.parent`, `transform.SetParent(newParent, worldPositionStays: true)`,
+  `transform.childCount`, `foreach (Transform child in transform)`. Child world = parent × local.
+- Same object model for 2D and 3D: 2D uses `Rigidbody2D`/`Collider2D`/`SpriteRenderer`; 3D uses
+  `Rigidbody`/`Collider`/`MeshRenderer`. Never mix 2D and 3D physics components on one body.
+
+```csharp
+[RequireComponent(typeof(Rigidbody))]
+public sealed class Mover : MonoBehaviour
+{
+    Rigidbody _rb;
+    void Awake() => _rb = GetComponent<Rigidbody>(); // cache once
+}
+```
+
+## 2. Prefabs & prefab variants; instantiation
+
+A **Prefab** is a reusable GameObject template (an asset). A **Prefab Variant** inherits from a base
+prefab and overrides selected properties/children — like subclassing for assets (e.g. `Enemy` base →
+`EnemyFast` variant). Edit the base and variants inherit the change unless they override that value.
+
+- Spawn with `Instantiate(prefab, position, rotation, parent)`; it returns the concrete type
+  (`var e = Instantiate(_enemyPrefab);` with `[SerializeField] Enemy _enemyPrefab;`). Store the
+  serialized reference; do not `Resources.Load` it.
+- Destroy with `Destroy(gameObject)` (end of frame) or `Destroy(obj, delay)`. Never `DestroyImmediate`
+  at runtime. For frequently spawned objects (bullets, VFX) **pool** them (`UnityEngine.Pool.ObjectPool<T>`)
+  instead of Instantiate/Destroy churn.
+- Editor-only prefab authoring uses `PrefabUtility` (wrap in `#if UNITY_EDITOR`); absent in builds.
+
+## 3. Scenes & scene management (additive loading)
+
+A **Scene** holds a set of GameObjects. Register scenes in **Build Profiles → Scene List** (Unity 6;
+formerly Build Settings) so they can load by index or name.
+
+```csharp
+using UnityEngine.SceneManagement;
+
+// Additive: keep the current scene, layer another on top (e.g. UI, a level chunk).
+var op = SceneManager.LoadSceneAsync("Level_02", LoadSceneMode.Additive);
+op.completed += _ => Debug.Log("Level_02 loaded");
+await op; // Unity 6: AsyncOperation is awaitable
+
+// Unload just that scene later:
+await SceneManager.UnloadSceneAsync("Level_02");
+```
+
+- `LoadSceneMode.Single` (default) unloads everything first; `Additive` composes scenes — the basis of
+  streaming worlds, persistent manager scenes, and separate UI scenes.
+- `SceneManager.MoveGameObjectToScene` moves an object between loaded scenes; `DontDestroyOnLoad` objects
+  survive `Single` loads (use for a bootstrap/services scene). Prefer `LoadSceneAsync` to avoid a hitch.
+
+## 4. MonoBehaviour lifecycle
+
+Order per frame and where each concern belongs (full ordering in `references/lifecycle-deep-dive.md`):
+
+| Method | When | Put here |
+| --- | --- | --- |
+| `Awake` | once, on instantiation (even if disabled) | cache `GetComponent`, self-init, no cross-object refs |
+| `OnEnable` | each time the object/component enables | subscribe to events, register callbacks |
+| `Start` | once, before first `Update`, only if active | cross-object wiring (other objects' `Awake` has run) |
+| `FixedUpdate` | fixed timestep (physics tick), 0..n / frame | **all physics** — `Rigidbody` forces/`MovePosition`, `ApplyForce` |
+| `Update` | every frame | input reads, game logic, timers (scale by `Time.deltaTime`) |
+| `LateUpdate` | every frame, after all `Update` | camera follow, look-at, anything tracking moved objects |
+| `OnDisable` | each disable / before destroy | **unsubscribe** everything subscribed in `OnEnable` |
+| `OnDestroy` | once, on destruction | release native/unmanaged resources, final cleanup |
+
+Rules that bite:
+- **Physics goes in `FixedUpdate`**, never `Update`. Reading input in `FixedUpdate` drops events —
+  read input in `Update`, cache intent, apply forces in `FixedUpdate`.
+- Frame-rate independence: multiply per-frame movement by `Time.deltaTime` (`Update`) — but
+  `FixedUpdate` already runs at a fixed `Time.fixedDeltaTime`.
+- `Awake` runs even on inactive objects; `Start` does not run until the object is active. Cross-object
+  references belong in `Start`, not `Awake`.
+- Every `OnEnable` subscription needs a matching `OnDisable` unsubscription or you leak and get
+  double-fires after re-enable.
+
+## 5. ScriptableObjects for data/config; serialization
+
+A **ScriptableObject** is a data asset that lives outside any scene — ideal for config, tuning tables,
+enemy/item definitions, and event channels. One asset is shared by reference (no per-instance copy),
+so it saves memory and lets designers tweak values without touching code.
+
+```csharp
+[CreateAssetMenu(fileName = "WeaponDef", menuName = "Game/Weapon Definition")]
+public sealed class WeaponDefinition : ScriptableObject
+{
+    [SerializeField] float _damage = 10f;
+    [SerializeField] float _fireRate = 2f;
+    public float Damage => _damage;      // expose read-only
+    public float FireRate => _fireRate;
+}
+```
+
+**`[SerializeField] private` vs `public`:** default to `[SerializeField] private` + a public
+property/method. It shows in the Inspector and survives serialization *without* letting arbitrary code
+mutate the field — encapsulation intact. Use bare `public` only for genuine data bags.
+
+**Serialization rules (they trip everyone):**
+- Unity serializes: `public` or `[SerializeField]` fields of supported types (primitives, `string`,
+  Unity types, enums, arrays/`List<T>` of those, and `[Serializable]` plain classes/structs).
+- Unity does **not** serialize: properties (use `[field: SerializeField] public float X { get; private set; }`),
+  `static`, `readonly`, `const`, `Dictionary<,>` (use two lists or a serializable wrapper), or
+  polymorphic references — for interface/abstract fields use `[SerializeReference]`.
+- Do not hold runtime mutable state on a shared ScriptableObject expecting it to reset — it persists in
+  the Editor between play sessions. Keep SOs for config; put mutable per-instance state on MonoBehaviours.
+
+## 6. Input System (new) — with a legacy contrast
+
+The new Input System (`com.unity.inputsystem`) is enabled by default in Unity 6 and is device-agnostic
+and event-driven. Define an **Input Action Asset** with **Action Maps** (e.g. "Player", "UI") and
+**Actions** (e.g. "Move" = Value/`Vector2`, "Jump" = Button). Generate a C# wrapper or use the
+`PlayerInput` component. Full setup, `PlayerInput`, and rebinding in `references/input-system.md`.
+
+```csharp
+// New Input System — subscribe to the generated actions (no per-frame polling).
+using UnityEngine.InputSystem;
+
+public sealed class PlayerController : MonoBehaviour
+{
+    InputSystem_Actions _controls;   // generated C# class from the .inputactions asset
+    Vector2 _move;
+
+    void Awake() => _controls = new InputSystem_Actions();
+    void OnEnable()
+    {
+        _controls.Player.Enable();
+        _controls.Player.Move.performed += ctx => _move = ctx.ReadValue<Vector2>();
+        _controls.Player.Move.canceled  += _  => _move = Vector2.zero;
+        _controls.Player.Jump.performed += _  => Jump();
+    }
+    void OnDisable() => _controls.Player.Disable();
+}
+```
+
+Legacy contrast (do not write this in new code):
+```csharp
+// LEGACY Input Manager — string axes, per-frame polling, device-blind. Avoid.
+float x = Input.GetAxis("Horizontal");
+if (Input.GetButtonDown("Jump")) Jump();
+```
+The new system also polls if you prefer: `_controls.Player.Move.ReadValue<Vector2>()` in `Update`.
+
+## 7. Coroutines vs async/await vs Awaitable
+
+| Use | Reach for | Why |
+| --- | --- | --- |
+| Frame-sequenced gameplay (timers, tweens, "wait then spawn") | **Coroutine** or **Awaitable** | frame-aware yields; auto-tie to object lifetime |
+| Unity-native async in Unity 6 (default for new async gameplay) | **`Awaitable`** | main-thread, low-alloc (pooled), frame + thread awaits, cancels via `destroyCancellationToken` |
+| True background CPU work / library `Task` APIs | **`async Task` + `await`** | thread pool; but marshal back — Unity APIs are main-thread only |
+
+```csharp
+// Coroutine — classic, MonoBehaviour-bound, stops when the object disables/destroys.
+IEnumerator SpawnWave()
+{
+    yield return new WaitForSeconds(1f);
+    Instantiate(_enemyPrefab);
+}
+void Start() => StartCoroutine(SpawnWave());
+
+// Awaitable (Unity 6) — the modern replacement. Cancels automatically on destroy.
+async Awaitable SpawnWaveAsync()
+{
+    await Awaitable.WaitForSecondsAsync(1f, destroyCancellationToken);
+    await Awaitable.NextFrameAsync(destroyCancellationToken);
+    Instantiate(_enemyPrefab);
+}
+```
+
+Rules:
+- **Coroutines** run only while the MonoBehaviour is enabled; they die silently on disable. No return
+  value; exceptions across `yield` are awkward.
+- **`Awaitable`**: never `await` the same instance twice (pooled → undefined behavior). Pass
+  `destroyCancellationToken` so it stops when the object is destroyed. Switch threads with
+  `Awaitable.BackgroundThreadAsync()` / `Awaitable.MainThreadAsync()`.
+- **`Task`**: does *not* auto-cancel on destroy — thread a `CancellationToken` yourself, and never touch
+  Unity API off the main thread (it throws). Prefer `Awaitable` in Unity 6 unless you need `Task`.
+
+## 8. Addressables (intro) + the Resources anti-pattern
+
+**Addressables** (`com.unity.addressables`) is the modern content-loading system: assets get string
+addresses, load asynchronously, and can ship in the build or from a remote CDN with dependency tracking
+and memory-managed release.
+
+```csharp
+using UnityEngine.AddressableAssets;
+
+var handle = Addressables.InstantiateAsync("Prefabs/Boss");
+GameObject boss = await handle.Task;      // or handle.Completed += ...
+// when done: Addressables.ReleaseInstance(boss);  // release to free memory
+```
+
+**`Resources/` is an anti-pattern for game content:** everything under it is forced into the build,
+loaded synchronously, bloats size/startup, and can't be patched or streamed. Reserve it for tiny
+always-needed defaults; migrate real content to Addressables.
+
+## 9. Build settings, platforms & player settings
+
+- **Build Profiles** (Unity 6, `File → Build Profiles`) supersede the old Build Settings window: per-platform
+  scene list, target platform, and overridable player settings.
+- **Scripting backend:** **IL2CPP** (AOT — required for iOS/consoles/WebGL, faster, harder to reverse)
+  vs **Mono** (JIT, Editor/desktop, faster iteration). Set per platform in Player Settings.
+- **Player Settings:** product/company name, bundle identifier, icons, orientation, API compatibility
+  level (`.NET Standard 2.1` default), managed stripping. **2D vs 3D** is a template choice, not a
+  different build path.
+- WebGL/mobile specifics and the shipping checklist: `references/build-and-platforms.md` + `gamedev-shipping`.
+
+## Guardrails / gotchas
+
+- `==`/`!= null` on a destroyed `UnityEngine.Object` works (overloaded), but `?.` and cached refs treat
+  a destroyed object as non-null. Re-check with `if (obj)` after possible destruction.
+- Don't mix input systems: with `PlayerInput`, don't also `Input.GetKey` — in "New" mode legacy calls throw.
+- One `Rigidbody` per body (child colliders fine); non-uniform scale breaks physics bodies.
+- Coroutines/`InvokeRepeating` stop on `SetActive(false)`; async `Task`s keep running unless cancelled.
+- No allocation (`new`, LINQ, boxing) in `Update`/`FixedUpdate` hot paths.
+
+## Related skills
+
+- `gamedev-multiplayer` — networking/netcode (Netcode for GameObjects); this skill hands off the wire.
+- `gamedev-physics` — deep physics tuning (joints, solver, determinism) beyond "put it in FixedUpdate".
+- `gamedev-shaders` — Shader Graph / HLSL, URP/HDRP materials and rendering.
+- `gamedev-pathing` — NavMesh, agents, steering, path solving.
+- `gamedev-shipping` — store builds, signing, size budgets, platform certification.
+- `godot` / `unreal` — the other engines; route Godot/GDScript and Unreal/Blueprint/C++ there.
+
+## Checklist
+
+- [ ] Confirmed the project's Unity version (`ProjectVersion.txt`); no year-based-LTS assumptions.
+- [ ] No banned API emitted (`Input.GetAxis`, `UnityEngine.Networking`, `Resources.Load` for content,
+      `FindObjectOfType`, `WWW`, runtime `OnGUI`).
+- [ ] `GetComponent` results cached in `Awake`; no string `Find` in `Update`.
+- [ ] Physics in `FixedUpdate`; input read in `Update`; camera/tracking in `LateUpdate`.
+- [ ] Every `OnEnable` subscription has a matching `OnDisable` unsubscription.
+- [ ] `[SerializeField] private` + property used instead of bare `public` where encapsulation matters.
+- [ ] New Input System used (actions/maps), not legacy polling; systems not mixed.
+- [ ] Async uses `Awaitable` (or coroutine) with `destroyCancellationToken`; no double-await.
+- [ ] Content via Addressables, not `Resources/`.
+- [ ] Scenes registered in Build Profiles; async/additive loading where it avoids a hitch.

package/skills/unity/evals/README.md

@@ -0,0 +1,8 @@
+# unity evals
+
+These cases assert the skill fires on Unity/C# engine work (MonoBehaviour lifecycle, prefabs,
+ScriptableObjects, scenes, the new Input System, coroutines/async/Awaitable, Addressables, builds) and
+that it defers correctly: pathfinding→gamedev-pathing, shaders→gamedev-shaders, netcode→gamedev-multiplayer,
+Godot→godot, Unreal→unreal. Capability cases check current Unity 6 patterns (physics in FixedUpdate with
+Rigidbody.MovePosition, new Input System over Input.GetAxis, Awaitable + destroyCancellationToken, no
+double-await) rather than deprecated APIs.

package/skills/unity/evals/cases.yaml

@@ -0,0 +1,43 @@
+skill: unity
+should_trigger:
+  - prompt: "My Unity player character teleports and jitters through walls when I move it with the arrow keys. Here's my MonoBehaviour."
+    why: "Physics-in-Update / setting transform on a Rigidbody — core lifecycle + FixedUpdate guidance this skill owns."
+  - prompt: "What's the difference between Awake and Start in Unity, and where should I grab my other components?"
+    why: "Directly the MonoBehaviour lifecycle section (Awake caches, Start does cross-object wiring)."
+  - prompt: "Help me convert my old Input.GetAxis(\"Horizontal\") movement to Unity's new Input System with an action map."
+    why: "Legacy→new Input System migration; ban-list + §6/input-system reference."
+  - prompt: "I want to store all my enemy stats (health, speed, damage) as data assets I can tweak in the Inspector. Best way in Unity?"
+    why: "ScriptableObject for data/config + [SerializeField] vs public + serialization rules."
+  - prompt: "How do I load a second Unity scene on top of the current one for my UI without unloading the level?"
+    why: "Scenes & additive loading (LoadSceneAsync + LoadSceneMode.Additive)."
+  - prompt: "Should I use a coroutine, async Task, or Awaitable for a 'wait 2 seconds then spawn' timer in Unity 6?"
+    why: "Coroutines vs async/await vs Awaitable decision — §7, including destroyCancellationToken."
+  - prompt: "Setting up multiplayer in Unity — I found UNet / UnityEngine.Networking tutorials, do they still work?"
+    why: "Version contract: UNet removed → Netcode for GameObjects; routes the wire itself onward but Unity owns the 'it's removed' fact."
+should_not_trigger:
+  - prompt: "How do I write a NavMeshAgent that chases the player and avoids obstacles smoothly?"
+    route_to: "gamedev-pathing"
+    why: "Pathfinding/steering algorithms are the pathing skill; Unity only owns the component wiring."
+  - prompt: "Design a Shader Graph for a dissolving-enemy effect with an emissive edge in URP."
+    route_to: "gamedev-shaders"
+    why: "Shader/material authoring belongs to the shaders skill."
+  - prompt: "I'm making a game in Godot 4 with GDScript and my _ready() isn't firing."
+    route_to: "godot"
+    why: "Godot/GDScript engine — explicitly out of scope; route to godot."
+  - prompt: "In Unreal Engine 5 my Blueprint Actor won't replicate movement to clients."
+    route_to: "unreal"
+    why: "Unreal/Blueprint engine work — route to unreal."
+  - prompt: "Write the authoritative server tick and client-side prediction/reconciliation for our netcode."
+    route_to: "gamedev-multiplayer"
+    why: "Netcode protocol/authority design is the multiplayer skill; Unity stops at 'use Netcode for GameObjects'."
+capability:
+  - scenario: "User asks how to move a Rigidbody with input from the new Input System without jitter, in Unity 6."
+    must_include:
+      - "reads input in Update (caches intent) but applies movement in FixedUpdate"
+      - "uses Rigidbody.MovePosition (or AddForce), not setting transform.position on the body"
+      - "uses the new Input System (InputAction / action map / ReadValue<Vector2>), not Input.GetAxis"
+  - scenario: "User asks whether to use a coroutine or async for a delayed spawn and how to make it stop when the object is destroyed."
+    must_include:
+      - "recommends Awaitable (or coroutine) over raw Task for Unity gameplay in Unity 6"
+      - "passes destroyCancellationToken to the Awaitable so it cancels on destroy"
+      - "warns never to await the same Awaitable instance twice (it is pooled)"

package/skills/unity/references/build-and-platforms.md

@@ -0,0 +1,65 @@
+# Build, platforms & player settings (Unity 6)
+
+Reference: Unity Manual "Build Profiles", "Player Settings", "IL2CPP".
+
+## Build Profiles (Unity 6) — replaces the old Build Settings window
+
+`File → Build Profiles`. A **Build Profile** is a saved, per-platform configuration:
+- **Scene List** — which scenes are included and their build index (index 0 = first/boot scene). Scenes
+  not in the list can only be loaded Additively if already present, so register everything you load.
+- **Target platform & architecture** — Windows/macOS/Linux, Android, iOS, WebGL, consoles.
+- **Overrides** — a profile can override Player Settings (e.g. a "Demo" profile with a different bundle id).
+
+`Shared Settings` hold the defaults; each profile diffs from them. Build with `Build` or `Build And Run`.
+Headless/CI builds go through `BuildPipeline.BuildPlayer` in an editor script.
+
+## Scripting backend: IL2CPP vs Mono
+
+`Player Settings → Configuration → Scripting Backend`:
+
+| | IL2CPP | Mono |
+| --- | --- | --- |
+| How | C# → IL → C++ → native (AOT) | JIT at runtime |
+| Platforms | required for iOS, WebGL, consoles; available desktop/Android | Editor + desktop + Android |
+| Runtime speed | faster | slower |
+| Build time | slower | faster (good for iteration) |
+| Reverse-engineering | harder | easier |
+| Reflection/`dynamic` | AOT limits (no runtime codegen; `System.Reflection.Emit` unsupported) | full |
+
+Ship production builds on **IL2CPP**; iterate in the Editor (always Mono/interpreted). IL2CPP + AOT means
+generic code reached only via reflection can be stripped — see managed stripping below.
+
+## Player Settings essentials
+
+- **Identity**: Company Name, Product Name, **bundle identifier** (`com.company.game` — must match store
+  listing), version + build/bundle number.
+- **Icons & splash**, default orientation (mobile), resolution/presentation.
+- **API Compatibility Level**: `.NET Standard 2.1` (default, smaller) vs `.NET Framework` (broader API,
+  larger). Prefer Standard unless a dependency needs Framework.
+- **Managed Stripping Level** (`Minimal`/`Low`/`Medium`/`High`): strips unused IL to shrink builds. High
+  can strip types only used via reflection/serialization — preserve them with a `link.xml` or
+  `[Preserve]`.
+- **Graphics APIs** per platform (Vulkan/Metal/D3D12/GLES3/WebGPU), color space (Linear recommended).
+
+## Platform quick-notes
+
+- **WebGL**: IL2CPP only; **no multithreading by default** (so `System.Threading`/most `Task`
+  parallelism is unavailable — `Awaitable` frame awaits are fine); no synchronous file I/O; build size
+  and memory matter; use compression (Brotli/Gzip) + a server that serves the right headers.
+- **Android**: set target/min SDK, choose ARM64 (required for Play Store), build **AAB** for the store
+  (APK for sideload). Configure keystore signing.
+- **iOS**: Unity emits an Xcode project; sign & archive in Xcode. IL2CPP + ARM64.
+- **Desktop**: simplest; Mono or IL2CPP.
+
+## Rendering pipeline choice (affects builds & shaders)
+
+- **URP** (Universal RP) — default for most 2D/3D projects, scales phone→desktop.
+- **HDRP** — high-end desktop/console visuals.
+- **Built-in** — legacy; new projects should pick URP/HDRP.
+
+Pipeline choice changes materials and shader authoring — see the `gamedev-shaders` skill.
+
+## Handoff
+
+Store submission, signing, size budgets, certification, and release ops belong to the `gamedev-shipping`
+skill. This reference stops at producing a correct platform build from the Editor.

package/skills/unity/references/input-system.md

@@ -0,0 +1,102 @@
+# Input System (new) — setup, patterns, migration
+
+Package: `com.unity.inputsystem`. Enabled by default in Unity 6. Device-agnostic, event-driven,
+supports rebinding, composites, local multiplayer, and touch. Reference: Unity Input System package
+manual.
+
+## Project mode
+
+`Edit → Project Settings → Player → Active Input Handling`:
+- **Input System Package (New)** — legacy `Input.*` calls throw. Recommended for new projects.
+- **Both** — new + legacy coexist (migration only; avoid mixing per-feature).
+- **Input Manager (Old)** — legacy only. Do not target for new work.
+
+Unity 6 also has **Project-wide Actions** (`Edit → Project Settings → Input System Package`): a default
+`InputActionAsset` shared across the whole project, reachable via `InputSystem.actions`.
+
+## Anatomy
+
+- **Input Action Asset** (`.inputactions`): the container. Enable "Generate C# Class" in its importer to
+  get a strongly-typed wrapper (e.g. `InputSystem_Actions`).
+- **Action Map**: a group of actions active together — e.g. "Player", "UI", "Vehicle". Enable/disable
+  maps to switch context (`_controls.Player.Disable(); _controls.UI.Enable();`).
+- **Action**: a named input with a **type**:
+  - *Value* (continuous, e.g. `Vector2` Move) — `performed` fires on change, `ReadValue<T>()`.
+  - *Button* (Jump, Fire) — `started` / `performed` / `canceled` phases.
+  - *Pass-Through* (raw device, every event).
+- **Binding**: the physical control → action. **Composite** bindings combine controls, e.g. a "2D Vector"
+  composite maps W/A/S/D to a single `Vector2`. **Control schemes** group bindings per device set
+  (Keyboard&Mouse, Gamepad).
+
+## Three ways to consume input
+
+### 1. Generated C# class (recommended for a single player)
+
+```csharp
+using UnityEngine.InputSystem;
+
+public sealed class PlayerController : MonoBehaviour
+{
+    InputSystem_Actions _controls;
+    Vector2 _move;
+
+    void Awake() => _controls = new InputSystem_Actions();
+    void OnEnable()
+    {
+        _controls.Player.Enable();
+        _controls.Player.Move.performed += OnMove;
+        _controls.Player.Move.canceled  += OnMove;
+        _controls.Player.Jump.performed += _ => Jump();
+    }
+    void OnDisable()
+    {
+        _controls.Player.Move.performed -= OnMove;
+        _controls.Player.Move.canceled  -= OnMove;
+        _controls.Player.Disable();
+    }
+    void OnDestroy() => _controls.Dispose();   // it owns native resources
+    void OnMove(InputAction.CallbackContext ctx) => _move = ctx.ReadValue<Vector2>();
+}
+```
+
+### 2. Polling (when event-driven feels heavy)
+
+```csharp
+Vector2 move = _controls.Player.Move.ReadValue<Vector2>();
+bool jumped  = _controls.Player.Jump.WasPressedThisFrame();   // edge-triggered, read in Update
+```
+
+### 3. `PlayerInput` component (fastest wiring, local multiplayer)
+
+Attach `PlayerInput`, assign the action asset, pick a **Behavior**:
+- *Send Messages* / *Broadcast Messages* — calls `OnMove(InputValue)` etc. by name.
+- *Invoke Unity Events* — wire in the Inspector.
+- *Invoke C# Events* — subscribe in code.
+
+For local co-op, `PlayerInputManager` spawns a `PlayerInput` per joined device, isolating each player's
+action instance and pairing devices automatically.
+
+## Rebinding at runtime
+
+```csharp
+var rebind = _controls.Player.Jump.PerformInteractiveRebinding()
+    .WithControlsExcluding("Mouse")
+    .OnComplete(op => { op.Dispose(); SaveBindings(); })
+    .Start();
+// Persist: string json = _controls.asset.SaveBindingOverridesAsJson();
+// Restore: _controls.asset.LoadBindingOverridesFromJson(json);
+```
+
+## Migration from legacy
+
+| Legacy | New Input System |
+| --- | --- |
+| `Input.GetAxis("Horizontal")` | Move action (Value/`Vector2`) → `ReadValue<Vector2>().x` |
+| `Input.GetButtonDown("Jump")` | Jump action (Button) → `WasPressedThisFrame()` or `performed` |
+| `Input.GetKey(KeyCode.E)` | action bound to `<Keyboard>/e` → `IsPressed()` |
+| `Input.mousePosition` | `Mouse.current.position.ReadValue()` |
+| `Input.GetMouseButtonDown(0)` | `Mouse.current.leftButton.wasPressedThisFrame` |
+| `Input.touchCount` / `Input.GetTouch` | `Touchscreen.current` / Enhanced Touch API |
+
+Do not leave `Input.*` polling alongside new-system actions — in "New" mode the legacy calls throw, and
+in "Both" mode you double-handle the same physical input.

package/skills/unity/references/lifecycle-deep-dive.md

@@ -0,0 +1,75 @@
+# MonoBehaviour lifecycle — deep dive (Unity 6)
+
+Full execution order for a `MonoBehaviour`, and the exact reason each callback exists. Reference:
+Unity Manual "Order of execution for event functions".
+
+## Initialization (once per object, in this order)
+
+1. **`Awake`** — called when the script instance is loaded, **even if the component is disabled**, and
+   before any `Start`. Cache `GetComponent`/`TryGetComponent`, allocate internal state. Do NOT reach
+   into *other* objects here — their `Awake` may not have run yet.
+2. **`OnEnable`** — every time the object/component becomes enabled (including re-enable). Subscribe to
+   C# events, register with managers, enable input actions. Must be mirrored by `OnDisable`.
+3. **`Start`** — once, just before the first `Update`, and **only if the component is active**. Safe
+   place for cross-object wiring because every object's `Awake` has already run. If an object is created
+   disabled and never enabled, `Start` never runs.
+
+Across a scene: all `Awake`s run, then all `OnEnable`s, then all `Start`s — so `Start` is your
+"everyone exists now" hook.
+
+## Physics loop (`FixedUpdate`) — 0..n times per frame
+
+- Runs on a fixed timestep (`Time.fixedDeltaTime`, default 0.02s = 50 Hz). May run zero times (high FPS)
+  or several times (low FPS) per rendered frame.
+- **All `Rigidbody` work goes here:** `AddForce`, `MovePosition`, `MoveRotation`, velocity changes.
+  Setting `transform.position` directly on a physics body fights the solver → jitter/tunneling.
+- Do NOT read edge-triggered input here (`WasPressedThisFrame`) — you'll miss events. Read in `Update`,
+  store the intent, consume it in `FixedUpdate`.
+- Collision/trigger callbacks (`OnCollisionEnter`, `OnTriggerEnter`, and their `Stay`/`Exit`, plus 2D
+  variants) fire from the physics step.
+
+## Game logic loop (per frame)
+
+4. **`Update`** — once per rendered frame. Input, timers, non-physics movement, state machines.
+   Frame-rate independent movement multiplies by `Time.deltaTime`.
+5. **`LateUpdate`** — after every `Update` in the scene has run. Camera follow, look-at, IK, procedural
+   bone adjustments — anything that must read the *final* positions of objects that moved this frame.
+
+## Rendering-adjacent (advanced)
+
+- `OnPreCull`, `OnBecameVisible`/`OnBecameInvisible`, `OnWillRenderObject`, `OnRenderImage` (Built-in RP;
+  URP/HDRP use `RenderPipelineManager` callbacks / render features instead).
+- `OnDrawGizmos` / `OnDrawGizmosSelected` — Editor scene-view debug drawing only.
+- `OnGUI` — legacy IMGUI, called multiple times per frame; editor tooling only, never runtime gameplay.
+
+## Teardown
+
+6. **`OnDisable`** — when the object/component disables (and just before `OnDestroy`). Unsubscribe from
+   everything subscribed in `OnEnable`, disable input actions, stop coroutines you own. A missing
+   unsubscribe here is the #1 cause of leaks and "handler fired twice after re-enable".
+7. **`OnDestroy`** — once, when the object is destroyed (or scene unloads / app quits). Release native
+   handles, dispose `IDisposable`s (`NativeArray`, `InputActionAsset` you `new`ed), final cleanup.
+8. **`OnApplicationQuit`** / `OnApplicationPause` / `OnApplicationFocus` — app-level lifecycle for
+   save-on-quit and mobile pause handling.
+
+## Coroutine yield timing (where a coroutine resumes)
+
+| `yield return` | Resumes |
+| --- | --- |
+| `null` | next frame, after `Update` |
+| `new WaitForSeconds(t)` | after `t` scaled seconds (affected by `Time.timeScale`) |
+| `new WaitForSecondsRealtime(t)` | after `t` real seconds (ignores `timeScale`) |
+| `new WaitForFixedUpdate()` | after the next physics step |
+| `new WaitForEndOfFrame()` | after rendering, before present (good for screen capture) |
+| `new WaitUntil(() => cond)` / `WaitWhile(...)` | when the predicate flips |
+| another `IEnumerator` | when the nested coroutine completes |
+
+Gotcha: `new WaitForSeconds(t)` allocates every call — cache the instance if you yield it in a loop, or
+switch to `Awaitable.WaitForSecondsAsync`.
+
+## Script execution order
+
+If object A must initialize before object B, don't rely on scene order — set it in
+`Project Settings → Script Execution Order`, or better, express the dependency explicitly (have B pull
+what it needs in its own `Start`, or use an explicit init call). `[DefaultExecutionOrder(n)]` sets it
+per-class in code.