@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/gamedev-shipping/references/stores-and-ci.md

@@ -0,0 +1,162 @@
+# Stores & CI — Steam, itch.io, Play/App Store, and headless build pipelines
+
+Back to the entrypoint: `../SKILL.md`. Store submission mechanics and per-engine CI.
+
+## Steam (Steamworks + SteamPipe)
+
+1. **Partner setup**: Steamworks account, an **App ID**, and the store page (assets, description,
+   trailers, tags, pricing) filled in the partner site.
+2. **Depots**: a depot is a bucket of files for a platform/language (e.g. one Windows depot, one
+   macOS depot). Map each to your App ID.
+3. **SteamPipe upload** with `steamcmd` driven by VDF scripts.
+
+`app_build_APPID.vdf`:
+
+```
+"appbuild"
+{
+  "appid" "480"
+  "desc"  "1.2.3 - CI build"
+  "buildoutput" "output/"
+  "contentroot" "build/"
+  "setlive" ""                      // leave empty; set a branch live in the site, or "beta"
+  "depots" { "481" "depot_build_481.vdf" }
+}
+```
+
+`depot_build_481.vdf`:
+
+```
+"DepotBuild"
+{
+  "DepotID" "481"
+  "FileMapping" { "LocalPath" "*" "DepotPath" "." "recursive" "1" }
+  "FileExclusion" "*.pdb"
+}
+```
+
+Upload:
+
+```bash
+steamcmd +login <builder_account> +run_app_build $(pwd)/app_build_APPID.vdf +quit
+```
+
+- Push to a **beta branch** first, test, then set it as the default (live) branch in the partner site.
+- Use a dedicated **build account** with 2FA handled for CI (Steam Guard); never the studio owner login.
+- `.pdb`/debug symbols usually excluded from the shipped depot.
+
+## itch.io (butler)
+
+`butler` is itch's CLI. A **channel** encodes the platform:
+
+```bash
+butler push build/windows user/game:windows   --userversion 1.2.3
+butler push build/html5   user/game:html5      --userversion 1.2.3
+butler push build/osx.zip user/game:mac        --userversion 1.2.3
+butler status user/game                        # see channels + versions
+```
+
+- Channel names containing `windows`/`osx`/`linux`/`android` tag the platform for the itch app;
+  `html5`/`web` marks a browser build.
+- For threaded web builds, in the uploaded file's settings tick **"This file will be played in
+  the browser" ▸ SharedArrayBuffer support** so itch serves COOP/COEP (see `web-export-headers.md`).
+- CI auth: `BUTLER_API_KEY` env var (from itch API keys). `butler push` is idempotent and diff-based.
+
+## Google Play
+
+- Upload an **AAB**; enable **Play App Signing**.
+- Meet the current **target API level** requirement (Play enforces a recent level for new uploads and updates).
+- Complete: **content rating** (IARC questionnaire), **Data safety** form, store listing (icon,
+  feature graphic, screenshots per device, short/full description), pricing/countries.
+- Tracks: internal → closed → open → production. Promote a build up the tracks.
+- `versionCode` strictly increasing; can't reuse one.
+
+## Apple App Store
+
+- Archive + upload to **App Store Connect** (Xcode Organizer / Transporter).
+- App Store record: name, subtitle, keywords, description, screenshots per device size, app icon,
+  privacy nutrition labels, **age rating** questionnaire, pricing.
+- **TestFlight** for beta before submitting for review.
+- The store notarizes automatically — no manual `notarytool` for App Store builds.
+
+## Age ratings (shared)
+
+- **IARC** questionnaire generates ratings for Google Play, Microsoft Store, Nintendo eShop in one pass.
+- **ESRB** (NA), **PEGI** (EU), **USK** (DE), **CERO** (JP) as required by platform/region.
+- Apple has its own age-rating questionnaire in App Store Connect.
+- Answer truthfully — misdeclaring content (violence, gambling, user-generated content) risks removal.
+
+## CI/CD — headless builds
+
+Principles: run the export headless, feed a **version/build number** from the CI run, restore
+**signing material from secrets** at runtime, upload the artifact.
+
+### Godot (GitHub Actions)
+
+```yaml
+name: export
+on: { push: { tags: ['v*'] } }
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    container: barichello/godot-ci:4.5.1        # image bundles matching export templates
+    steps:
+      - uses: actions/checkout@v4
+      - name: Prepare templates
+        run: |
+          mkdir -p ~/.local/share/godot/export_templates/4.5.1.stable
+          mv /root/.local/share/godot/export_templates/4.5.1.stable/* \
+             ~/.local/share/godot/export_templates/4.5.1.stable/
+      - name: Export Web + Linux
+        run: |
+          mkdir -p build/web build/linux
+          godot --headless --export-release "Web"   build/web/index.html
+          godot --headless --export-release "Linux/X11" build/linux/game.x86_64
+      - uses: actions/upload-artifact@v4
+        with: { name: builds, path: build/ }
+```
+
+The template version in the image **must** equal the editor build (`4.5.1` here). For Android in CI,
+add JDK 17 + the Android SDK and restore the keystore from a secret.
+
+### Unity (GitHub Actions)
+
+```yaml
+- uses: game-ci/unity-builder@v4
+  with:
+    targetPlatform: Android
+    buildMethod: BuildScript.PerformBuild
+  env:
+    UNITY_LICENSE: ${{ secrets.UNITY_LICENSE }}
+    UNITY_EMAIL:   ${{ secrets.UNITY_EMAIL }}
+    UNITY_PASSWORD: ${{ secrets.UNITY_PASSWORD }}
+```
+
+- License activation is required (personal/pro); store it in secrets via `game-ci/activate`.
+- Matrix over `targetPlatform` for multi-target. Keystore + passwords come from secrets for signed Android.
+
+### Unreal (self-hosted)
+
+- The engine install is multi-GB, so Unreal CI needs a **self-hosted runner** with the engine + SDKs installed.
+- Drive with `RunUAT BuildCookRun ... -clientconfig=Shipping -cook -stage -pak -package -archivedirectory=...`.
+
+### Versioning
+
+```yaml
+env:
+  BUILD_NUMBER: ${{ github.run_number }}          # monotonic → versionCode / CFBundleVersion / Steam desc
+  VERSION: ${{ github.ref_name }}                  # semver tag → versionName / marketing version
+```
+
+- Semver tag (`v1.2.3`) triggers a release build; the run number is the strictly-increasing integer.
+- Feed `BUILD_NUMBER` into Android `versionCode`, iOS `CFBundleVersion`, and the Steam build `desc`.
+- Publish signing secrets (keystore base64, App Store Connect API key, `BUTLER_API_KEY`, `STEAM_*`) as encrypted repo/environment secrets — never in the workflow file.
+
+## Checklist
+
+- [ ] Store page assets + metadata + age rating complete for the target store.
+- [ ] Steam: depots mapped, SteamPipe VDFs correct, pushed to a beta branch first, build account with Steam Guard.
+- [ ] itch: correct channel names, SAB checkbox for web, `BUTLER_API_KEY` in CI.
+- [ ] Play: AAB + Play App Signing + target API level + Data safety.
+- [ ] App Store: archive uploaded, TestFlight tested, privacy labels + age rating done.
+- [ ] CI: headless export, version/build number from the run, signing material from secrets, artifact uploaded.

package/skills/gamedev-shipping/references/web-export-headers.md

@@ -0,0 +1,140 @@
+# Web export — cross-origin isolation, headers, and hosts
+
+Back to the entrypoint: `../SKILL.md`. This is the single deepest source of "my web build
+works locally but breaks when hosted" bugs. Read it before you host a threaded WebAssembly game.
+
+## Why the headers exist
+
+Modern engines run the game loop on Web Workers and share memory between them with
+**`SharedArrayBuffer`**. After Spectre/Meltdown, browsers only expose `SharedArrayBuffer` (and
+high-resolution timers) to pages that are **cross-origin isolated**. A page becomes isolated only
+when the server sends **both**:
+
+```
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+- **COOP: same-origin** severs the page from cross-origin windows/openers (its own browsing-context group).
+- **COEP: require-corp** requires every subresource to explicitly opt in to being embedded (via CORP or CORS), so no untrusted cross-origin resource shares the isolated process.
+
+With both present, `self.crossOriginIsolated === true` and `SharedArrayBuffer` is defined. Miss
+either and you get one of: `SharedArrayBuffer is not defined`, a JS exception during engine init,
+an infinite loading bar, or a blank canvas. The **files are correct** — the *response headers* are the bug.
+
+Quick self-test in the browser console on the hosted page:
+
+```js
+console.log(self.crossOriginIsolated); // must be true for threaded builds
+console.log(typeof SharedArrayBuffer);  // must be "function"
+```
+
+## Do you even need the headers?
+
+| Situation | Headers needed? |
+| --- | --- |
+| Godot 4 web export with **Thread Support ON** | Yes — both. |
+| Godot 4 web export with Thread Support OFF (single-thread) | No — but audio/perf are worse. |
+| Unity WebGL with **multithreading** / threads enabled | Yes — both. |
+| Unity WebGL single-threaded (default older setups) | No. |
+| A build that only *uses* WASM but not threads/SAB | No. |
+
+If you can host somewhere that sets headers, **keep threads on** — it's a real perf win. Only
+disable threads when your host genuinely can't set headers and the shim below isn't viable.
+
+## Setting the headers per host
+
+**Netlify** — `public/_headers` (or the publish dir):
+
+```
+/*
+  Cross-Origin-Opener-Policy: same-origin
+  Cross-Origin-Embedder-Policy: require-corp
+```
+
+**Vercel** — `vercel.json`:
+
+```json
+{
+  "headers": [{
+    "source": "/(.*)",
+    "headers": [
+      { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
+      { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
+    ]
+  }]
+}
+```
+
+**nginx**:
+
+```nginx
+location / {
+    add_header Cross-Origin-Opener-Policy same-origin always;
+    add_header Cross-Origin-Embedder-Policy require-corp always;
+    # serve pre-compressed wasm/pck if present
+    gzip_static on;
+}
+# correct MIME + long cache for the payload
+types { application/wasm wasm; }
+```
+
+**Apache** — `.htaccess`:
+
+```apache
+Header set Cross-Origin-Opener-Policy "same-origin"
+Header set Cross-Origin-Embedder-Policy "require-corp"
+AddType application/wasm .wasm
+```
+
+**Cloudflare Pages** — a `_headers` file like Netlify's, or a Transform Rule adding both response headers.
+
+**itch.io** — no file needed: in the upload settings tick **"This file will be played in the
+browser"**, then check **"SharedArrayBuffer support"**. itch serves your build from a domain that
+sends COOP/COEP for you. This is the fastest correct web host for a jam/demo.
+
+**GitHub Pages / plain static CDN with no header control** — you **cannot** set response headers.
+Two escapes:
+
+1. Export **without** threads (single-threaded) — always works, no headers, some perf loss.
+2. The **`coi-serviceworker`** shim: a small service worker (`coi-serviceworker.js`) you include
+   from the page; on first load it registers, reloads once, and thereafter re-serves every
+   response with COOP/COEP injected, faking cross-origin isolation client-side. Caveats: it needs
+   HTTPS, adds a reload, and won't help resources it can't intercept. Good enough for GitHub Pages demos.
+
+## COEP fallout — the second-order breakage
+
+`COEP: require-corp` also applies to **every** subresource the page loads. Anything cross-origin
+(web fonts, analytics scripts, remote images, iframes, a leaderboard API on another domain) is
+**blocked** unless it sends `Cross-Origin-Resource-Policy: cross-origin` (or proper CORS). Symptoms:
+fonts vanish, a third-party embed 404s in the network tab with a CORP error.
+
+Fixes, in order of preference:
+1. **Self-host** the asset (same origin ⇒ no CORP needed). Best for fonts and small scripts.
+2. Ask the third party to send `Cross-Origin-Resource-Policy: cross-origin` (or use their CORS endpoint).
+3. Switch that page to **`COEP: credentialless`** — a looser mode that loads cross-origin resources
+   without credentials and still grants isolation in supporting browsers. Narrower support than `require-corp`; test.
+
+## Engine specifics
+
+**Godot 4 web**
+- `Editor ▸ Manage Export Templates` must match the editor build; then a **Web** export preset.
+- **Thread Support** toggle drives whether you need the headers. **Extensions Support** enables GDExtension on web.
+- Output: `index.html` + `.js` + `.wasm` + `.pck` (+ worker/audio files). Serve `.wasm` as `application/wasm` and enable gzip/brotli — the `.wasm`/`.pck` are the bulk of the download.
+- **C#/.NET edition has no web export in Godot 4.x** (planned for a later release with .NET 10). If the project is C#, either port the web-facing build to GDScript or drop web as a target. Do not promise a C# web build.
+- Headless CI export: `godot --headless --export-release "Web" build/index.html`.
+
+**Unity WebGL**
+- `File ▸ Build Profiles ▸ Web`; Player Settings ▸ Publishing: enable/disable threads, set the
+  **compression format** (Brotli/Gzip) and keep **Decompression Fallback** on if the host can't
+  send `Content-Encoding` — otherwise the browser can't inflate the payload.
+- Threaded WebGL ⇒ same COOP/COEP requirement.
+
+## Checklist
+
+- [ ] Decide threads on/off; if on, both headers are mandatory.
+- [ ] Headers set at the **host** (or itch's SAB checkbox, or the shim on GitHub Pages).
+- [ ] `self.crossOriginIsolated === true` verified in the console on the deployed URL.
+- [ ] `.wasm` served with `application/wasm` MIME and gzip/brotli.
+- [ ] No cross-origin subresource silently blocked by COEP (check the network tab).
+- [ ] Godot + web ⇒ confirmed GDScript, not C#/.NET.

package/skills/godot/SKILL.md

@@ -0,0 +1,319 @@
+---
+name: godot
+description: "Use when writing, reviewing, or debugging Godot 4.x games in GDScript (typed) or C# — nodes/scenes/custom Resources, autoload singletons and an EventBus, signals via Callable, @onready/@export/@tool, static typing, CharacterBody2D/3D + velocity + move_and_slide(), _process vs _physics_process, .tscn/.tres text formats, and headless GUT/gdUnit4 tests. Enforces Godot 4 APIs and rejects Godot 3 leftovers: yield→await, onready→@onready, .instance()→.instantiate(), KinematicBody→CharacterBody, Spatial→Node3D, string connect(\"sig\",obj,\"m\")→Callable. Triggers: 'write a Godot player controller', 'my move_and_slide does nothing', 'port this Godot 3 script to 4', 'connect a signal in Godot', 'GDScript won't type-check', 'CharacterBody2D won't move', 'add an autoload', 'escribe un script de Godot', 'por qué no se mueve mi personaje'. NOT Unity MonoBehaviour or Unreal (route to unity/unreal); NOT pure C++/CMake tooling unrelated to GDExtension (that is cpp); NOT shader code in .gdshader (that is gamedev-shaders)."
+tags: [godot, gdscript, game-dev, csharp, godot4]
+recommends: [gamedev-shaders, gamedev-multiplayer, gamedev-physics, gamedev-pathing, gamedev-shipping, game-design, cpp]
+profiles: [full]
+origin: risco
+---
+
+# Godot 4.x (GDScript + C#)
+
+Write, review, and debug Godot **4.x** games — 2D and 3D — the way the engine is designed:
+scenes as reusable units, composition over deep node trees, signals for decoupling, static
+typing for speed and safety. GDScript (typed) is primary; C# parity snippets sit beside it.
+
+## Version contract — read first
+
+**This is Godot 4.x. Never emit Godot 3 APIs.** Godot 4 renamed core nodes, moved annotations
+behind `@`, replaced `yield` with `await`, and switched signal/file/tween APIs. A Godot 3 snippet
+will not even parse in 4.x. Before writing or accepting any line, check it against this ban-list:
+
+| Never (Godot 3) | Always (Godot 4.x) |
+| --- | --- |
+| `yield(timer, "timeout")` | `await timer.timeout` |
+| `onready var x = ...` | `@onready var x = ...` |
+| `export var hp = 3` | `@export var hp := 3` |
+| `tool` (script mode line) | `@tool` (annotation, first line) |
+| `KinematicBody` / `KinematicBody2D` | `CharacterBody3D` / `CharacterBody2D` |
+| `Spatial` | `Node3D` |
+| `Area` / `RigidBody` / `StaticBody` | `Area3D` / `RigidBody3D` / `StaticBody3D` |
+| `Sprite` | `Sprite2D` |
+| `scene.instance()` | `scene.instantiate()` |
+| `move_and_slide(velocity, UP)` (positional) | set `velocity` property, then `move_and_slide()` — **no args** |
+| `connect("hit", self, "_on_hit")` | `node.hit.connect(_on_hit)` (Callable) |
+| `File.new()` / `Directory.new()` | `FileAccess.open(...)` / `DirAccess.open(...)` |
+| standalone `Tween` node + `interpolate_property` | `create_tween()` → `tween.tween_property(...)` |
+| `OS.get_ticks_msec` for gameplay timing | `Time.get_ticks_msec()` (OS timing moved to `Time`) |
+| `PoolByteArray` / `PoolVector2Array` | `PackedByteArray` / `PackedVector2Array` |
+
+**Lifecycle overrides must chain the parent** with `super()` (Godot 3 called it implicitly; Godot 4
+does not). If you override `_ready`, `_process`, `_init`, etc. in a script that `extends` another
+script defining them, call `super()` / `super._ready()` or the base logic silently never runs.
+
+**Silent-breakers** (compile fine, behave wrong — the dangerous class):
+
+- `Array.slice(begin, end)` — `end` is now **exclusive** (was inclusive in Godot 3). `[1,2,3,4].slice(1,3)` → `[2,3]`.
+- `Camera2D.zoom` is **inverted** vs Godot 3: a **larger** zoom now means zoomed **in** (magnified). `Vector2(2,2)` = 2× magnification, not half.
+- `TileMap` is **deprecated** → use one `TileMapLayer` node per layer (since 4.3).
+- Angles are radians; `_process(delta)` delta is a `float` (GDScript) / `double` (C#) in **seconds**.
+
+Full table with every rename → `references/godot3-to-4-traps.md`.
+
+## Project & scene organization
+
+- The **scene** (`.tscn`) is the reusable unit — a self-contained tree you instance many times
+  (a Player, a Bullet, a HUD). Prefer **composition**: small scenes/nodes assembled, not one
+  60-node monolith. If a subtree has its own behavior, make it its own scene.
+- One responsibility per script. Attach behavior to the scene's **root**; child nodes are parts.
+- `class_name Foo` registers a global type usable in the inspector and as `Foo.new()`. Use it for
+  reusable scripts and custom Resources; skip it for one-off scene scripts.
+- **Files**: `snake_case.gd` / `snake_case.tscn` for scenes and scripts; `PascalCase` for node
+  names in the tree and for `class_name`. Group by feature (`player/`, `enemy/`, `ui/`), not by type.
+
+## Nodes vs scenes vs scripts vs custom Resources
+
+| You need | Use |
+| --- | --- |
+| A thing in the tree that renders / moves / collides / processes | a **Node** (typed subclass) |
+| A reusable, instanceable bundle of nodes | a **scene** (`.tscn`) |
+| Behavior attached to a node | a **script** (`.gd` / `.cs`) |
+| Pure data (stats, items, dialogue, level config) with no place in the tree | a **custom `Resource`** (`.tres`) |
+
+Custom `Resource`s are Godot's typed, savable, inspector-editable data objects — reach for them
+instead of loose Dictionaries or JSON for game data. See `references/nodes-scenes-resources.md`.
+
+```gdscript
+class_name EnemyStats extends Resource
+@export var max_health: int = 30
+@export var speed: float = 120.0
+@export var loot_table: Array[ItemDrop] = []
+```
+
+## Autoloads / singletons + EventBus
+
+Register a script or scene as an **autoload** (Project → Project Settings → Globals/Autoload) to get
+one always-present instance reachable by name from anywhere. Use it for cross-cutting state (save
+game, audio, run config) — not as a dumping ground.
+
+The **EventBus** pattern decouples unrelated systems: an autoload that owns only signals. Emitters
+and listeners never reference each other, just the bus.
+
+```gdscript
+# event_bus.gd  (autoload named "Events")
+extends Node
+signal enemy_died(position: Vector2, xp: int)
+signal score_changed(new_score: int)
+```
+```gdscript
+# emitter                              # listener (anywhere)
+Events.enemy_died.emit(global_position, 10)
+Events.enemy_died.connect(_on_enemy_died)
+```
+
+Keep gameplay logic in nodes; let the bus carry the *notification*, not the behavior.
+
+## Node access & lifecycle
+
+- `_init()` runs at construction (no tree, no `@onready` yet). `_ready()` runs once the node and
+  all children are in the tree — do node wiring here.
+- `@onready var x = $Path` defers the assignment to `_ready`, so the child exists. Never grab
+  children in `_init`.
+- **Prefer unique names**: mark a node **Unique Name in Owner** (`%`) and access `%HealthBar`
+  instead of the fragile, refactor-breaking `get_node("../../UI/HealthBar")`. `$Foo` is fine for a
+  direct child.
+- Cache node lookups in `@onready` vars; don't call `get_node` every frame.
+
+```gdscript
+extends CharacterBody2D
+@onready var sprite: Sprite2D = $Sprite2D
+@onready var health_bar: ProgressBar = %HealthBar   # unique name, position-independent
+
+func _ready() -> void:
+    super()                       # chain the parent's _ready if the base defines one
+    health_bar.value = 100
+```
+
+## Signals
+
+Signals are Godot's decoupling primitive. In Godot 4 you connect a **Callable**, not strings.
+
+- **Declare** with typed params; **name in the past tense** for facts that happened
+  (`health_depleted`, `item_collected`), present-tense imperative only for requests.
+- **Connect**: `node.signal_name.connect(_on_thing)` — a direct method reference, checked at parse
+  time. Add `CONNECT_ONE_SHOT` for auto-disconnect after one fire.
+- **Disconnect discipline**: a connection to a node that gets freed is cleaned up automatically, but
+  connections you make to *long-lived* objects (autoloads, the bus) from a short-lived node must be
+  disconnected in `_exit_tree()`, or use `CONNECT_ONE_SHOT`, to avoid calls into freed instances.
+
+```gdscript
+signal health_depleted
+signal health_changed(current: int, max: int)
+
+func take_damage(amount: int) -> void:
+    _health -= amount
+    health_changed.emit(_health, _max_health)
+    if _health <= 0:
+        health_depleted.emit()
+```
+
+## @export / @tool (inspector config)
+
+`@export` exposes a variable in the Inspector so designers tune it without touching code. Use ranges,
+groups, and typed exports so the inspector gives real widgets and validation.
+
+```gdscript
+@export var title: String = "Level 1"
+@export_range(0.0, 1.0, 0.05) var volume := 0.8
+@export_group("Movement")
+@export var speed: float = 300.0
+@export var jump_velocity: float = -400.0
+@export var projectile: PackedScene           # drag a .tscn in the inspector
+@export var stats: EnemyStats                 # a custom Resource slot
+```
+
+`@tool` at the top of a script runs it **in the editor** too — for gizmos, procedural previews, or
+validating exported data. Guard runtime-only code with `if Engine.is_editor_hint(): return`.
+
+## Static (typed) GDScript
+
+Type everything. Typed GDScript is faster (the VM skips dynamic dispatch) and catches errors at parse
+time. Use `:=` when the type is inferable, `: Type` when it isn't, and avoid `Variant`/untyped.
+
+```gdscript
+var speed: float = 300.0          # explicit
+var dir := Vector2.ZERO           # inferred
+var enemies: Array[Enemy] = []    # typed array
+
+func distance_to(target: Node2D) -> float:
+    return global_position.distance_to(target.global_position)
+
+func _on_body_entered(body: Node) -> void:
+    var enemy := body as Enemy     # safe cast → null if wrong type, no crash
+    if enemy:
+        enemy.take_damage(10)
+```
+
+Naming: `snake_case` vars/funcs/signals, `PascalCase` types/`class_name`/nodes, `CONSTANT_CASE`
+consts, tabs for indent, lines < 100 cols. Cheat-sheet → `references/gdscript-style.md`.
+
+## `_process` vs `_physics_process`
+
+- `_physics_process(delta)` — **fixed** tick (default 60 Hz), the same every step. All movement,
+  `move_and_slide()`, forces, and collision-dependent logic go here.
+- `_process(delta)` — runs **once per rendered frame** (variable rate). Use for visuals, UI, and
+  non-physics polish.
+- **Always scale rate-based change by `delta`** so behavior is framerate-independent. `move_and_slide()`
+  and `move_and_collide()` already fold in `delta` internally — do **not** multiply the velocity you
+  hand them by `delta` again.
+
+## Resources & data — `.tres` / `.tscn` are strict text formats
+
+`.tscn` and `.tres` are line-oriented text with a strict header/section grammar. **Do not hand-edit
+them past trivial value tweaks, and never launch on a file you hand-authored without validating** —
+one bad `ext_resource` id, `[node]` line, or `load_steps` count corrupts the whole scene and Godot
+refuses to open it. Prefer editing through the editor or building Resources in code and `ResourceSaver.save()`.
+
+- **`preload("res://x.tscn")`** resolves at **parse/compile** time — the dependency is baked in; use
+  for assets you always need.
+- **`load("res://x.tscn")`** resolves at **runtime** — use for dynamic/optional paths (and to avoid
+  circular preloads). Both return a `PackedScene`; call `.instantiate()` to get a node.
+
+## 2D / 3D bodies quickstart
+
+The move-anything-controllable body is `CharacterBody2D` / `CharacterBody3D`. The Godot 4 flow is:
+**write the `velocity` property, then call `move_and_slide()` with no arguments.**
+
+```gdscript
+extends CharacterBody2D
+@export var speed: float = 300.0
+@export var jump_velocity: float = -400.0
+
+func _physics_process(delta: float) -> void:
+    if not is_on_floor():
+        velocity += get_gravity() * delta        # get_gravity(): project-configured vector
+    if Input.is_action_just_pressed("jump") and is_on_floor():
+        velocity.y = jump_velocity
+    var dir := Input.get_axis("move_left", "move_right")
+    velocity.x = dir * speed
+    move_and_slide()                             # NO args in Godot 4 — reads the velocity property
+```
+
+3D is identical with `CharacterBody3D`, `Vector3`, and an X/Z input plane; body/area suffixes are
+`3D`. Deeper body/physics tuning → `gamedev-physics`.
+
+## Language parity — GDScript ↔ C#
+
+Same engine, same nodes; C# uses PascalCase members, `partial` classes, and attributes. Signals
+become C# `event`s (generated by source-gen). C# support requires the **.NET (Mono) build** of Godot.
+
+```gdscript
+# GDScript
+extends Node
+signal health_depleted
+@export var speed: float = 300.0
+
+func _ready() -> void:
+    health_depleted.connect(_on_depleted)
+    health_depleted.emit()
+
+func _on_depleted() -> void:
+    print("dead")
+```
+```csharp
+// C# — same node, .NET build
+using Godot;
+
+public partial class Player : Node
+{
+    [Signal] public delegate void HealthDepletedEventHandler();
+    [Export] public float Speed { get; set; } = 300.0f;
+
+    public override void _Ready()
+    {
+        base._Ready();                       // chain the parent (== super())
+        HealthDepleted += OnDepleted;        // connect via the generated event
+        EmitSignal(SignalName.HealthDepleted);
+    }
+
+    private void OnDepleted() => GD.Print("dead");
+}
+```
+
+`move_and_slide()`→`MoveAndSlide()`, `$Node`→`GetNode<T>("Node")`, `%Node`→`GetNode<T>("%Node")`,
+`preload`→`GD.Load<T>(...)`. Full parity table → `references/export-and-testing.md`.
+
+**GDExtension / C++**: for hot native code, build a `godot-cpp` GDExtension (`.gdextension` file,
+`GDREGISTER_CLASS`, `_bind_methods()`) rather than a Godot module — no engine recompile, and it loads
+like any other library. That is native-tooling territory → pair with `cpp`.
+
+## Export & testing
+
+- **Test with GUT 9.x** (GDScript, `extends GutTest`) or **gdUnit4** (GDScript + C#). Put tests
+  under `test/` or `res://tests/`; assert behavior, not private state.
+- **Run headless in CI**: `godot --headless -s addons/gut/gut_cmdln.gd -gdir=res://test -gexit`
+  (GUT). Export via templates: `godot --headless --export-release "Linux/X11" build/game.x86_64`.
+- Validate a project before shipping: open in the editor once (catches broken `.tscn`/`.tres`),
+  then export-check per platform. Details → `references/export-and-testing.md`.
+
+## Guardrails / gotchas
+
+- Freeing: call `queue_free()` (safe, end of frame), not `free()` mid-signal. Guard reused refs with
+  `is_instance_valid(node)`.
+- Never busy-wait; `await get_tree().create_timer(1.0).timeout` or a signal.
+- `get_node`/`$` on a missing path returns `null` and errors — prefer `%UniqueName` and typed `@onready`.
+- Don't multiply by `delta` twice (see `move_and_slide`). Don't put physics in `_process`.
+- One `TileMapLayer` per layer; `TileMap` is deprecated.
+- Editor-touching code must guard on `Engine.is_editor_hint()` under `@tool`.
+
+## Related skills
+
+- [`game-design`](../game-design/SKILL.md) — mechanics, loops, and feel *before* you script them.
+- [`gamedev-shaders`](../gamedev-shaders/SKILL.md) — `.gdshader` / visual shaders (out of scope here).
+- [`gamedev-physics`](../gamedev-physics/SKILL.md) — joints, RigidBody tuning, deep collision layers.
+- [`gamedev-pathing`](../gamedev-pathing/SKILL.md) — NavigationAgent, A*, steering beyond the basics.
+- [`gamedev-multiplayer`](../gamedev-multiplayer/SKILL.md) — `MultiplayerSynchronizer`/RPC/netcode.
+- [`gamedev-shipping`](../gamedev-shipping/SKILL.md) — store builds, signing, platform export at scale.
+- [`cpp`](../cpp/SKILL.md) — the GDExtension / `godot-cpp` native side and its CMake/build tooling.
+
+## Checklist
+
+- [ ] Zero Godot 3 APIs — checked every line against the ban-list (`yield`/`onready`/`instance()`/`KinematicBody`/`Spatial`/string `connect`/`File`).
+- [ ] `move_and_slide()` called with **no args**; `velocity` set as a property; not multiplied by `delta` twice.
+- [ ] Overridden lifecycle methods call `super()` where a base defines them.
+- [ ] Signals connected via Callable (`x.sig.connect(_on_x)`), named past-tense, disconnected/one-shot where needed.
+- [ ] Everything typed (`:` / `:=`, typed params/returns, typed Arrays); no stray `Variant`.
+- [ ] Physics in `_physics_process`, visuals in `_process`; rate-based values scaled by `delta`.
+- [ ] Node access via `@onready` + `%UniqueName`, not deep `get_node("../..")` chains.
+- [ ] `.tscn`/`.tres` not hand-corrupted; project opens in-editor before export.
+- [ ] C# snippets use `partial`, `[Export]`/`[Signal]`, `base._Ready()`, PascalCase (if C# requested).

package/skills/godot/evals/README.md

@@ -0,0 +1,13 @@
+# Eval harness — `godot` skill
+
+These cases are read by the rsc skill-eval harness (a Claude agent with the full skill catalog
+loaded) or by hand. They assert two things. **Triggering**: the `godot` description fires on each
+`should_trigger` prompt — including symptom-only and Spanish phrasings — and stays quiet on the
+`should_not_trigger` near-misses, routing each to its named sibling (`unity`, `unreal`,
+`gamedev-shaders`, `cpp`, `game-design`, `gamedev-multiplayer`) instead. **Capability**: with
+`SKILL.md` and its references loaded, the generated Godot code satisfies every
+`capability.must_include` bullet — the Godot 4 flow (`velocity` property + no-arg `move_and_slide()`),
+typed GDScript, Callable signals, `@export`/`@onready`, zero Godot 3 leftovers, and a correct C#
+parity block — and clearly beats the no-skill baseline. Because LLM routing is non-deterministic,
+run 3–5 trials per prompt and pass on a majority. No network is required; the capability rubric is
+judged by reading the output against the bullets.