@ericrisco/rsc 0.1.35 → 0.1.36

package/skills/godot/evals/cases.yaml

@@ -0,0 +1,50 @@
+skill: godot
+
+should_trigger:
+  - prompt: "Write a Godot 4 top-down player controller for a CharacterBody2D with 8-direction movement and a dash."
+    why: "Core use case: authoring a typed GDScript CharacterBody2D using the velocity + move_and_slide() flow."
+  - prompt: "My CharacterBody2D just won't move — I call move_and_slide(velocity) every frame and nothing happens. What's wrong?"
+    why: "Symptom-only trigger routing here via the Godot 4 velocity-property + no-arg move_and_slide fix (they passed the Godot 3 positional arg)."
+  - prompt: "Convert this Godot 3 script to Godot 4 — it uses onready, yield, .instance() and connect(\"hit\", self, \"_on_hit\")."
+    why: "The version-contract ban-list is the skill's center of gravity; each named API has a modern replacement here."
+  - prompt: "How do I connect a signal between two nodes in Godot and pass the health value along?"
+    why: "Signals via Callable (node.sig.connect / .emit) with typed params is a named trigger."
+  - prompt: "Set up an autoload EventBus in Godot so my enemies can broadcast that they died without referencing the score UI."
+    why: "Autoload/singleton + EventBus decoupling pattern is explicitly owned by this skill."
+  - prompt: "My GDScript won't type-check — how do I properly type an Array of a custom class and cast a colliding body?"
+    why: "Static typed GDScript (typed Arrays, `as` casts, typed params/returns) is a core section."
+  - prompt: "Show me the same Godot player script in both GDScript and C#, including how the signal and export differ."
+    why: "GDScript ↔ C# parity (partial class, [Export]/[Signal], base._Ready()) is a first-class deliverable."
+  - prompt: "Escribe un script de Godot 4 para que un CharacterBody3D salte y tenga gravedad."
+    why: "Spanish trigger for a Godot 4 CharacterBody3D controller — squarely this skill."
+
+should_not_trigger:
+  - prompt: "Write a Unity C# MonoBehaviour that moves a Rigidbody with FixedUpdate and input."
+    route_to: "unity"
+    why: "Unity's MonoBehaviour/Rigidbody/FixedUpdate model is a different engine; C# alone doesn't make it Godot."
+  - prompt: "Set up an Unreal Engine character with a Blueprint jump and a C++ movement component."
+    route_to: "unreal"
+    why: "Unreal Blueprint/UE C++ is a separate engine skill."
+  - prompt: "Write a .gdshader that does a dissolve effect with a noise texture and an edge glow."
+    why: "Shader authoring in .gdshader/visual shaders is delegated to gamedev-shaders, not GDScript gameplay code."
+    route_to: "gamedev-shaders"
+  - prompt: "Build a godot-cpp GDExtension purely as a CMake project and set up the compiler toolchain and SCons/CMake flags."
+    route_to: "cpp"
+    why: "The native C++ build/tooling side is cpp; this skill only points at GDExtension from the gameplay side."
+  - prompt: "Design the core game loop and progression economy for my roguelike before I build anything."
+    route_to: "game-design"
+    why: "Mechanics/loop/feel design precedes scripting and belongs to game-design."
+  - prompt: "Implement client-side prediction and server reconciliation for my Godot multiplayer shooter's netcode."
+    route_to: "gamedev-multiplayer"
+    why: "Deep netcode/RPC/synchronizer work is the multiplayer sibling; this skill stops at single-player node/signal basics."
+
+capability:
+  - scenario: "Author a Godot 4.x 2D platformer player: a typed CharacterBody2D with gravity, run, and a floor-only jump, that emits a signal when it dies, plus the equivalent C# version."
+    must_include:
+      - "extends CharacterBody2D and sets the `velocity` property, then calls `move_and_slide()` with NO arguments (not move_and_slide(velocity, ...))"
+      - "Applies gravity via get_gravity() * delta (or a project-settings gravity) scaled by delta, inside _physics_process, and does not multiply the velocity passed to move_and_slide by delta again"
+      - "Uses gravity/jump only when appropriate with is_on_floor(), and reads input via Input.get_axis / Input.is_action_just_pressed"
+      - "Declares a signal (e.g. `signal died`) and emits it with `died.emit()`, never emit_signal string form as the primary API"
+      - "Is statically typed: typed params (delta: float), typed vars (:= / : Type), and a -> void / typed return where relevant"
+      - "Uses @export for tunables (speed, jump_velocity) and @onready + $ or %UniqueName for node refs — no onready/export without @, no yield, no .instance()"
+      - "C# version uses `public partial class ... : CharacterBody2D`, `_PhysicsProcess(double delta)` calling `base` where a base defines it, `[Export]`, `[Signal] ...EventHandler`, `EmitSignal(SignalName....)`, sets `Velocity` then `MoveAndSlide()`"

package/skills/godot/references/export-and-testing.md

@@ -0,0 +1,102 @@
+# Export, testing & GDScript↔C# parity (Godot 4.x)
+
+## GDScript ↔ C# full parity table
+
+C# needs the **.NET (Mono) build** of Godot 4. Members are PascalCase; scripts are `partial` classes
+extending the node type; annotations become attributes; signals become source-generated `event`s.
+
+| Concept | GDScript | C# |
+| --- | --- | --- |
+| Class decl | `extends Node2D` (+ `class_name Foo`) | `public partial class Foo : Node2D` |
+| Ready | `func _ready():` | `public override void _Ready()` |
+| Physics | `func _physics_process(delta):` (`delta: float`) | `public override void _PhysicsProcess(double delta)` |
+| Chain parent | `super()` / `super._ready()` | `base._Ready()` |
+| Export | `@export var speed := 300.0` | `[Export] public float Speed { get; set; } = 300f;` |
+| Export range | `@export_range(0,1) var v := 0.5` | `[Export(PropertyHint.Range, "0,1")] public float V { get; set; }` |
+| Signal decl | `signal hit(dmg: int)` | `[Signal] public delegate void HitEventHandler(int dmg);` |
+| Emit | `hit.emit(10)` | `EmitSignal(SignalName.Hit, 10)` |
+| Connect | `node.hit.connect(_on_hit)` | `node.Hit += OnHit;` |
+| Disconnect | `node.hit.disconnect(_on_hit)` | `node.Hit -= OnHit;` |
+| Child (direct) | `$Sprite2D` | `GetNode<Sprite2D>("Sprite2D")` |
+| Child (unique) | `%HealthBar` | `GetNode<ProgressBar>("%HealthBar")` |
+| onready | `@onready var s := $Sprite2D` | assign in `_Ready()` |
+| Preload | `const B := preload("res://b.tscn")` | `GD.Load<PackedScene>("res://b.tscn")` |
+| Instance | `B.instantiate()` | `b.Instantiate<Node2D>()` |
+| Free | `queue_free()` | `QueueFree()` |
+| Print | `print(x)` | `GD.Print(x)` |
+| Move | set `velocity` → `move_and_slide()` | set `Velocity` → `MoveAndSlide()` |
+| Await signal | `await obj.sig` | `await ToSignal(obj, Node.SignalName.Sig)` |
+| Await frame | `await get_tree().process_frame` | `await ToSignal(GetTree(), SceneTree.SignalName.ProcessFrame)` |
+| Group | `add_to_group("enemies")` | `AddToGroup("enemies")` |
+| Random | `randf_range(0,1)` | `GD.RandRange(0,1)` |
+
+C# gotchas: use the generated `SignalName`/`PropertyName`/`MethodName` string caches, not raw
+strings; C# `Vector2`/`Vector3` fields can't be mutated through a property getter (copy → mutate →
+assign back, like `var v = Velocity; v.X = 1; Velocity = v;`); `[Export]` needs a public
+property or field of a Godot-marshalable type.
+
+## GDExtension / C++ (native code)
+
+For CPU-hot systems (procedural gen, heavy sims), write a **GDExtension** with `godot-cpp` instead of
+recompiling the engine as a module:
+
+- A `.gdextension` manifest points at the compiled shared lib per platform.
+- Classes extend a Godot type and register with `GDREGISTER_CLASS(MyClass)`; expose methods/props via
+  `static void _bind_methods()` using `ClassDB::bind_method(...)` and `ADD_PROPERTY(...)`.
+- Build with SCons or CMake against the `godot-cpp` bindings; it loads like any resource, no engine
+  rebuild. This is native C++ tooling → pair with the `cpp` skill for the build side.
+
+## Testing
+
+Two mature frameworks for Godot 4:
+
+- **GUT 9.x** (Godot Unit Test) — GDScript. Test scripts `extends GutTest`; methods named
+  `test_*`; assertions like `assert_eq`, `assert_true`, `assert_signal_emitted`. Install via the
+  Asset Library or a git submodule under `addons/gut`.
+- **gdUnit4** — GDScript **and** C#, with scene-runner helpers for driving input and awaiting frames;
+  ships CI templates and a fluent `assert_that(...)` API.
+
+```gdscript
+# test/test_health.gd
+extends GutTest
+
+func test_takes_damage() -> void:
+    var h := HealthComponent.new()
+    h.max_health = 100
+    watch_signals(h)
+    h.take_damage(30)
+    assert_eq(h.current, 70)
+
+func test_emits_died_at_zero() -> void:
+    var h := HealthComponent.new()
+    watch_signals(h)
+    h.take_damage(999)
+    assert_signal_emitted(h, "died")
+```
+
+Test **behavior through the public surface** (signals, exported state, method results), not private
+`_underscore` fields. For node-tree tests, `add_child_autofree(node)` so GUT frees it.
+
+## Headless CI & export
+
+Godot runs without a display via `--headless` — the backbone of CI:
+
+```bash
+# Run the GUT suite headless and exit with the pass/fail code
+godot --headless -s addons/gut/gut_cmdln.gd -gdir=res://test -ginclude_subdirs -gexit
+
+# gdUnit4 headless
+godot --headless -s res://addons/gdUnit4/bin/GdUnitCmdTool.gd -a res://test
+
+# Import/validate assets once (populates .godot/, catches broken resources) — good first CI step
+godot --headless --import
+
+# Export a release build for a preset defined in export_presets.cfg
+godot --headless --export-release "Linux/X11" build/game.x86_64
+godot --headless --export-release "Web" build/index.html
+```
+
+- Export **templates** for the matching engine version must be installed on the CI runner.
+- Run `--import` before `--export-*` on a clean checkout so `.godot/` is built.
+- A green editor open + a passing headless suite + a successful export per target = shippable; deep
+  store/signing/platform work belongs to `gamedev-shipping`.

package/skills/godot/references/gdscript-style.md

@@ -0,0 +1,84 @@
+# GDScript style & formatting cheat-sheet (Godot 4.x)
+
+Mirrors the official GDScript style guide. When in doubt, run the editor's built-in formatter
+(Ctrl/Cmd+Shift+I) and `gdformat` (from `gdtoolkit`) in CI.
+
+## Naming
+
+| Thing | Case | Example |
+| --- | --- | --- |
+| File (script/scene) | `snake_case` | `player_controller.gd`, `main_menu.tscn` |
+| `class_name` / type | `PascalCase` | `class_name EnemyStats` |
+| Node name in tree | `PascalCase` | `HealthBar`, `AttackTimer` |
+| Variable / function | `snake_case` | `var max_health`, `func take_damage()` |
+| Signal | `snake_case`, past tense | `signal health_depleted` |
+| Constant | `CONSTANT_CASE` | `const MAX_SPEED := 400.0` |
+| Enum type / members | `PascalCase` / `CONSTANT_CASE` | `enum State { IDLE, RUN }` |
+| Private (convention) | leading underscore | `var _internal_timer` |
+| Virtual/lifecycle | leading underscore | `_ready`, `_process`, `_on_body_entered` |
+
+## Formatting
+
+- **Tabs** for indentation (not spaces). Editor default.
+- Lines **< 100 columns**.
+- One space around binary operators (`a + b`, `x := 1`), none inside call parens.
+- Two blank lines between functions at top level; one inside classes as needed.
+- Prefer `:=` (inferred) when the RHS makes the type obvious; `: Type =` when it does not.
+
+## Typed by default
+
+```gdscript
+var speed: float = 300.0          # explicit annotation
+var dir := Vector2.ZERO           # inferred
+var slots: Array[Item] = []       # typed collection
+const GRAVITY := 980.0
+
+func heal(amount: int) -> void:   # typed params AND return
+    _health = mini(_health + amount, _max_health)
+
+func find_target() -> Node2D:     # return type declared
+    return get_tree().get_first_node_in_group("player")
+```
+
+- Declare `-> void` on functions that return nothing; declare the real type otherwise.
+- Use `as` for safe downcasts: `var e := body as Enemy` → `null` on mismatch (no crash).
+- Avoid untyped `var x` and `Variant` params — they disable the compiler's checks and the VM's
+  typed fast paths.
+
+## Script layout order (recommended top-to-bottom)
+
+1. `@tool` (if any) — must be the very first line.
+2. `class_name` then `extends` (or `extends` alone).
+3. `## docstring` comment.
+4. `signal` declarations.
+5. `enum` / `const`.
+6. `@export` vars, then plain member vars, then `@onready` vars.
+7. Built-in virtuals: `_init`, `_ready`, `_process`, `_physics_process`, `_input`, …
+8. Public methods, then private (`_underscore`) methods, then signal handlers (`_on_*`).
+
+```gdscript
+@tool
+class_name Turret extends Node2D
+## Auto-aiming turret; @export the fire rate in the inspector.
+
+signal fired(at: Vector2)
+
+const MAX_RANGE := 600.0
+enum Mode { IDLE, TRACKING }
+
+@export var fire_rate := 2.0
+var _cooldown := 0.0
+@onready var muzzle: Marker2D = %Muzzle
+
+func _physics_process(delta: float) -> void:
+    _cooldown = maxf(_cooldown - delta, 0.0)
+
+func _on_area_entered(_area: Area2D) -> void:
+    pass
+```
+
+## Common built-in math helpers (Godot 4 names)
+
+`absf/absi`, `minf/mini`, `maxf/maxi`, `clampf/clampi`, `snappedf`, `lerpf`, `move_toward`,
+`deg_to_rad` / `rad_to_deg`, `randf_range`, `randi_range`. The unsuffixed `abs/min/max/clamp` still
+work on Variants but the typed suffixed forms are faster and clearer.

package/skills/godot/references/godot3-to-4-traps.md

@@ -0,0 +1,89 @@
+# Godot 3 → 4.x migration ban-list (full table)
+
+Godot 4 is a hard break from 3.x. The engine ships a project converter, but it does **not** catch
+everything — and an agent generating fresh code must simply never emit the left column. Use this as
+the authoritative reference when porting or reviewing.
+
+## Won't-parse renames (hard errors)
+
+| Godot 3 | Godot 4.x | Note |
+| --- | --- | --- |
+| `yield(obj, "signal")` | `await obj.signal` | Coroutines are now `await`; the function must not need `yield`'s return-value trick. |
+| `yield(get_tree().create_timer(1),"timeout")` | `await get_tree().create_timer(1.0).timeout` | |
+| `onready var` | `@onready var` | Annotation. |
+| `export var` / `export(int) var` | `@export var` / `@export_range(...) var` | Typed annotations replace the `export(Type)` hint syntax. |
+| `tool` | `@tool` | Must be the first line. |
+| `remote`/`master`/`puppet func` | `@rpc(...)` annotations | Networking model changed entirely. |
+| `setget set_fn, get_fn` | `set(v): ...` / `get: ...` inline accessors | |
+
+## Node / class renames
+
+| Godot 3 | Godot 4.x |
+| --- | --- |
+| `Spatial` | `Node3D` |
+| `KinematicBody` / `KinematicBody2D` | `CharacterBody3D` / `CharacterBody2D` |
+| `Area` | `Area3D` |
+| `RigidBody` / `StaticBody` | `RigidBody3D` / `StaticBody3D` |
+| `Sprite` | `Sprite2D` |
+| `Sprite3D` | `Sprite3D` (unchanged) |
+| `AnimatedSprite` | `AnimatedSprite2D` |
+| `CollisionShape` | `CollisionShape3D` |
+| `Camera` | `Camera3D` |
+| `Light2D` (old) / `Light` | `PointLight2D` / `DirectionalLight2D` / `OmniLight3D` etc. |
+| `Viewport` (as node) | `SubViewport` (embedded) |
+| `YSort` (node) | `y_sort_enabled` property on `Node2D`/`CanvasItem` |
+| `ARVROrigin` / `ARVRCamera` | `XROrigin3D` / `XRCamera3D` |
+| `Reference` | `RefCounted` |
+| `TileMap` | `TileMapLayer` (one per layer; `TileMap` deprecated 4.3+) |
+
+## Method / API changes
+
+| Godot 3 | Godot 4.x |
+| --- | --- |
+| `scene.instance()` | `scene.instantiate()` |
+| `move_and_slide(velocity, up_direction)` | set `velocity` property → `move_and_slide()` (no args) |
+| `move_and_slide_with_snap(...)` | set `floor_snap_length` → `move_and_slide()` |
+| `connect("sig", obj, "method", [args])` | `obj.sig.connect(method.bind(args))` (Callable) |
+| `disconnect("sig", obj, "method")` | `obj.sig.disconnect(method)` |
+| `emit_signal("sig", a)` | `sig.emit(a)` (string form still exists but prefer the property) |
+| `is_connected("sig", obj, "m")` | `sig.is_connected(m)` |
+| `call_deferred("method", a)` | `method.bind(a).call_deferred()` or `call_deferred("method", a)` |
+| `File.new()` + `open()` | `FileAccess.open(path, FileAccess.READ)` |
+| `Directory.new()` | `DirAccess.open(path)` / `DirAccess.dir_exists_absolute(...)` |
+| `OS.get_ticks_msec()` | `Time.get_ticks_msec()` |
+| `OS.get_datetime()` | `Time.get_datetime_dict_from_system()` |
+| `PoolByteArray` / `PoolStringArray` / `PoolVector2Array` | `PackedByteArray` / `PackedStringArray` / `PackedVector2Array` |
+| `Tween` node + `interpolate_property` | `var t := create_tween(); t.tween_property(node, "position", target, 0.5)` |
+| `rand_range(a, b)` | `randf_range(a, b)` (float) / `randi_range(a, b)` (int) |
+| `deg2rad` / `rad2deg` | `deg_to_rad` / `rad_to_deg` |
+| `stepify(x, s)` | `snapped(x, s)` |
+| `.empty()` | `.is_empty()` |
+| `get_node("Path")` still valid | prefer `%UniqueName` for refactor-safety |
+| `KEY_*` / input constants mostly renamed | check `Key`, `MouseButton` enums |
+
+## Silent behavior changes (compile clean, act wrong)
+
+- **`Array.slice(begin, end, step, deep)`** — `end` is **exclusive** in Godot 4 (was inclusive in 3).
+  `[10,20,30,40].slice(1,3)` → `[20,30]`.
+- **`Camera2D.zoom`** — meaning **inverted**. Larger value = zoom **in**. `zoom = Vector2(2,2)`
+  magnifies 2×; in Godot 3 that zoomed out. To zoom out now, use values **below** 1.
+- **Y-sort** is a property (`y_sort_enabled`), not a node — porting a `YSort` parent silently loses
+  sorting unless you set the property.
+- **Physics interpolation / gravity** — read gravity via `get_gravity()` (2D/3D) or
+  `ProjectSettings`; the old default constants changed.
+- **Signal argument order** on some built-in signals changed; verify against the 4.x docs, don't
+  assume the 3.x signature.
+- **`_ready`/`_process` no longer auto-call the base** — you must `super()` when extending a script
+  that defines them.
+- **Integer division** with typed ints truncates as expected; mixing float/int in Godot 4 follows
+  stricter typed rules — annotate to avoid surprises.
+
+## Porting workflow
+
+1. Open the Godot 3 project in Godot 4 → run the built-in **Project Converter** (backs up first).
+2. Fix red parse errors top-down (renames above).
+3. Search the codebase for each string-form `connect(`, `yield(`, `.instance()`, `File.new`,
+   `Directory.new`, `Pool*Array`, `move_and_slide(` with args — the converter misses some.
+4. Fix the silent-breakers deliberately (slice bounds, Camera2D zoom, y-sort) — tests or a manual
+   pass, since nothing errors.
+5. Re-open every scene once; a converter-mangled `.tscn` fails loudly in the editor.

package/skills/godot/references/nodes-scenes-resources.md

@@ -0,0 +1,109 @@
+# Nodes, scenes, scripts & custom Resources (Godot 4.x)
+
+The four building blocks and when each is the right tool. Getting this decomposition right is what
+separates a maintainable Godot project from a monolithic scene that nobody can touch.
+
+## The mental model
+
+- **Node** — a live object in the running tree. It has a transform (2D/3D), can render, process,
+  collide, receive input. Everything on screen is a node. Pick the most specific typed subclass
+  (`Sprite2D`, `Area3D`, `CharacterBody2D`, `Timer`, `AudioStreamPlayer`).
+- **Scene** (`.tscn`) — a saved tree of nodes with a designated **root**, instanceable N times. The
+  reusable unit of a Godot game. A scene can instance other scenes (composition).
+- **Script** (`.gd` / `.cs`) — code attached to one node, giving it behavior. Attach to the scene
+  root; treat children as parts the root drives.
+- **Resource** (`.tres` / `.res`) — a reference-counted **data** object, not in the tree. Textures,
+  audio, materials are Resources; so are your **custom** data classes.
+
+## Composition over inheritance / deep trees
+
+Prefer assembling small scenes over one giant tree or a deep script inheritance chain.
+
+- A `Player` scene = `CharacterBody2D` root + `Sprite2D` + `CollisionShape2D` + `Camera2D` +
+  instanced `HealthComponent` + `HurtboxComponent` sub-scenes.
+- Behaviors as **components**: a `HealthComponent` (its own scene/script exposing `signal died`) can
+  be dropped onto a player, an enemy, or a crate — no shared base class needed.
+- Reach for `extends MyBase` only for genuine "is-a" specialization; reach for composed child nodes
+  for "has-a" behavior. The latter is the Godot-idiomatic default.
+
+## `class_name` — when to register a global type
+
+```gdscript
+class_name HealthComponent extends Node
+signal died
+@export var max_health := 100
+var _current := max_health
+```
+
+- Register (`class_name`) reusable scripts and **all** custom Resources — it enables `is`/`as`
+  checks, `HealthComponent.new()`, and a proper inspector type/slot.
+- Skip it for one-off scene-root scripts that nothing else references by type.
+- Names are global and must be unique across the project.
+
+## Custom Resources — typed game data
+
+Use a custom `Resource` instead of loose `Dictionary`/JSON whenever you have structured game data:
+stats, items, dialogue lines, wave definitions, ability configs. You get inspector editing, type
+safety, `@export` slots, and save/load for free.
+
+```gdscript
+# item.gd
+class_name Item extends Resource
+@export var display_name: String = ""
+@export var icon: Texture2D
+@export var max_stack: int = 99
+@export var value: int = 0
+```
+```gdscript
+# Use it as a typed @export slot on any node:
+@export var starting_items: Array[Item] = []
+
+# Create/save/load in code:
+var potion := Item.new()
+potion.display_name = "Potion"
+ResourceSaver.save(potion, "res://data/potion.tres")
+var loaded := load("res://data/potion.tres") as Item
+```
+
+**Gotcha — shared vs unique**: a Resource assigned in the inspector is **shared by reference** across
+all instances by default. If each node must own its copy (e.g. runtime-mutated stats), enable
+**Local to Scene** on the resource, or `duplicate()` it in `_ready()`. Otherwise mutating one
+enemy's `stats.health` mutates every enemy sharing that `.tres`.
+
+## `preload` vs `load`
+
+| | `preload("res://x")` | `load("res://x")` |
+| --- | --- | --- |
+| Resolved | parse/compile time | runtime, when the line runs |
+| Path | must be a constant literal | can be a variable/computed |
+| Use for | assets you always need; breaks fast if the path is wrong | dynamic/optional assets, avoiding circular preloads |
+| Returns | the Resource/`PackedScene` | same |
+
+```gdscript
+const BULLET := preload("res://bullet.tscn")   # PackedScene, baked in
+func shoot() -> void:
+    var b := BULLET.instantiate()               # -> a Node
+    add_child(b)
+
+# runtime path
+var scene := load("res://enemies/%s.tscn" % enemy_id) as PackedScene
+```
+
+## Instancing & freeing lifecycle
+
+- `PackedScene.instantiate()` → a detached node; add it with `add_child(node)` (or
+  `add_sibling`) to bring it into the tree and trigger `_ready`.
+- Free with `queue_free()` (deferred to end of frame — safe during signals/physics). Avoid `free()`
+  unless you know the node is out of the tree and not mid-callback.
+- After freeing, guard any retained reference with `is_instance_valid(node)` before touching it.
+- `add_child(node, true)` forces a readable unique name; useful when spawning many of one scene.
+
+## `.tscn` / `.tres` are strict text — validation rule
+
+Both formats are line-oriented with a header (`[gd_scene load_steps=N format=3 ...]`),
+`[ext_resource ...]` / `[sub_resource ...]` blocks, and `[node ...]` / property lines. A wrong
+`load_steps` count, a dangling `ExtResource("x")` id, or a malformed `[node]` path makes Godot
+refuse to open the file. **Do not machine-generate or hand-edit these beyond trivial value tweaks,
+and always open the project in the editor once before relying on a changed scene** — the editor is
+the only reliable validator. Build data-Resources in code + `ResourceSaver.save()` instead of
+writing `.tres` by hand.

package/skills/level-design/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: level-design
+description: "Use when designing a game level, map, arena, or encounter — laying out a blockout/greybox, fixing pacing that drags or spikes, guiding players without hand-holding, placing secrets and rewards, or diagnosing a level that plays as boring, confusing, or where players get lost or stuck. Engine-agnostic craft: the blockout->greybox->playtest->art pipeline, sightlines and landmarks, tension/release rhythm, the introduce->develop->twist->combine encounter progression, readability via light/color/composition, and traversal heatmaps. Triggers: 'design this level', 'my level is boring/confusing', 'players keep getting lost', 'how do I pace this', 'blockout', 'greybox', 'encounter design', 'where do I put the secret'. NOT systemic mechanics or economy tuning (that's game-design), NOT narrative or story beats (that's game-storytelling), and NOT engine-specific level tooling — nav meshes, occlusion, tilemap editors, lightmap baking (that's the godot/unity/unreal skill)."
+tags: [level-design, blockout, pacing, encounter, playtest]
+recommends: [game-design, godot, unity, unreal]
+profiles: [full]
+origin: risco
+---
+
+# Level design — space that plays before it's pretty
+
+*Shape the space, the rhythm, and the encounters so the player always knows where to go, never gets bored, and feels smart for exploring. Prove it in grey boxes; add art last.*
+
+This skill owns the **craft of physical space and its play**: how a level is laid out, how it reads, how its intensity rises and falls, how encounters teach, and where reward hides. It is **engine-agnostic** — every technique here is validated in a blockout, then handed to an engine skill for the actual tooling (nav meshes, occlusion, lightmaps, tilemaps). It does not design the mechanics the level exercises (that's the systemic layer) or write the story it tells.
+
+## When to use / When NOT to use
+
+**Use when:** blocking out a new level/map/arena; a level playtests as boring, confusing, or too hard/easy; players get lost or stuck; you need to pace a level, space encounters, or add breathers; you're guiding players without arrows/waypoints; placing secrets, rewards, or shortcuts; teaching a mechanic through the space itself.
+
+**Do NOT use for:**
+
+- **Systemic / mechanic design** — the verbs, rules, economy, and numbers the player brings *into* the level (jump height as a rule, weapon balance, loot tables, progression systems). That's `game-design`. This skill *exercises* those verbs in space; it doesn't invent or tune them.
+- **Narrative, quests, dialogue, environmental story beats** — what the space *says*. That's `game-storytelling`. Level design places the beat; storytelling writes it.
+- **Engine-specific level tooling** — nav-mesh baking, occlusion culling, terrain/tilemap/ProBuilder editors, lightmap/GI bakes, streaming volumes, collision setup. Defer to `godot` / `unity` / `unreal`. This skill decides *what* the space must do; the engine skill implements *how*.
+
+## The craft laws (non-negotiable)
+
+1. **Art last.** Never model or texture a space you haven't proven fun in blockout. Art-first means reworking expensive assets when the layout inevitably changes.
+2. **Metrics before geometry.** Lock the player's dimensions (height, jump, reach, cover) first; build everything as multiples of them. → `references/blockout-to-art.md`
+3. **The player always knows where to go, never how it ends.** Guide the critical path; leave exploration to earn its own reward. Lostness is a readability bug, not player error.
+4. **Watch, don't tell.** A level is only as good as it plays for someone you didn't coach. Every claim ("this is obvious", "the fight is fun") is a hypothesis until a fresh player validates it.
+5. **Rhythm, not a flat line.** Intensity must rise and fall. Sustained peak = fatigue; sustained calm = boredom. Design the graph, not just the rooms.
+6. **Teach through space, not text.** Introduce a threat where it's safe to learn it, before it can kill.
+
+## The pipeline: blockout -> greybox -> playtest -> art (never art-first)
+
+| Stage | You build | You answer | Gate to next |
+|---|---|---|---|
+| **Blockout** | Primitive geometry only (boxes/planes at true metrics). No materials, no props. | Does the space flow? Are timings/distances right? Can I find my way? | Layout & traversal feel right. |
+| **Greybox** | Blockout + temp neutral materials, placeholder lighting, stand-in enemies/interactables. | Does it *read*? Does the fight/encounter work? Is pacing right? | Encounters and readability hold up in playtest. |
+| **Playtest** | Nothing — you watch fresh players. | Where do they hesitate, get lost, die, skip? | Fixes are cheap because it's still grey. |
+| **Art pass** | Meshes, materials, VFX, final lighting, audio — *serving* the proven layout. | Does art reinforce the guidance the greybox already established? | Ship. |
+
+Iterate blockout↔playtest many times before art. Changing a grey box is minutes; changing a finished art set-piece is days. Full stage detail, the metrics block, and the art-pass handoff checklist → `references/blockout-to-art.md`.
+
+## Spatial composition — leading the eye
+
+- **Sightlines are your steering wheel.** Control what's visible from each point: frame the objective in a doorway/arch, block distracting views, open a reveal at the moment of a decision.
+- **Landmarks (the "weenie").** One large, distinct, distant silhouette per area that the player orients toward (tower, spire, mountain) — Disney's term for the visual magnet that pulls you forward. Self-locating beats a minimap.
+- **Lead the eye** with converging lines (rails, beams), framing (foreground arches), contrast (a bright end to a dark corridor), and motion. The eye goes to the brightest, highest-contrast, most-different thing — put that on the path you want taken.
+- **Silhouette readability.** Enemies, interactables, and hazards must read by shape alone at a glance. Two things sharing a silhouette is an unintended trap.
+- **Golden path vs exploration.** The **critical path** is the always-legible guaranteed route to the objective; **exploration** is optional branches and loops off it. Prefer loops that return the player forward (avoid dead-end backtracking); breadcrumb side routes with a visible reward.
+
+Framing, contrast, and layout topologies (loops, hubs, gates) → `references/guidance-and-readability.md`.
+
+## Pacing & rhythm — tension and release
+
+Design the **intensity graph** for the whole level, not room by room. A good level is a sawtooth trending upward: each peak (combat, platforming gauntlet, chase) followed by a valley — a **safe room / breather** with no threat, low stimulus, often a save/restock.
+
+- **Space encounters in time and distance, and *vary* both** — three identical-length fights back to back feel like one long slog.
+- **Breathers earn the next peak.** The calm between (Halo's cadence is often described as "thirty seconds of fun" on repeat) is what makes the fun read as fun. Use it to let adrenaline drop, reward observation, and telegraph the next escalation.
+- **Difficulty within the level** trends up but resets at checkpoints — re-enter competent, then ramp. End on the hardest, most spectacular test, not a whimper.
+- **Contrast the modes** (fast↔slow, loud↔quiet, open↔tight, combat↔traversal↔puzzle). Monotony of *any* mode reads as boredom even if each moment is individually good.
+
+Intensity-graph template, breather patterns, and difficulty-curve worked example → `references/pacing-and-encounters.md`.
+
+## Encounter design — introduce, develop, twist, combine
+
+The four-beat progression teaches a mechanic/threat through space (the pattern behind Portal, Half-Life 2, and Mario level craft):
+
+1. **Introduce** — meet the new element somewhere it *can't* hurt you. A single turret across a safe gap; one platform of the new hazard. Learn it risk-free.
+2. **Develop** — use it for real, low stakes. The turret now guards a corridor you must cross.
+3. **Twist** — recontextualize it. Two turrets flanking; the turret is *behind* glass; you must use the turret against enemies. The rule bends.
+4. **Combine** — the mastery test: the new element plus everything learned earlier, at full intensity.
+
+Design rules for the **arena** (the shape a fight happens in):
+
+- **Match sightline length to weapon/threat range** — long lanes favor ranged, tight rooms favor melee/shotgun. The geometry *is* the difficulty knob.
+- **Cover rhythm, flanks, verticality.** Space cover so the player advances in beats; give at least one flank so a fight isn't a static peek-war; use height for pressure and reward (the Doom-2016 arena: multi-tier, resources placed to pull the player *through* the space, not hunker).
+- **Chokepoints need release valves** — pair a choke with an exit or a way to break the standoff, or the fight stalls.
+- **An encounter = enemy composition × space × objective × resources.** Change any one for a "new" encounter without new assets.
+
+Encounter template, arena patterns, and a full introduce→develop→twist→combine example → `references/pacing-and-encounters.md`.
+
+## Guidance & readability — direct without hand-holding
+
+Guide with the environment so you never need a floating arrow:
+
+- **Light leads.** Players move toward light (the moth effect) and higher value-contrast. Light the path, objective, and exit; keep dead-ends dim. Placeholder lighting is a greybox *design* tool, not a final-art afterthought.
+- **Reserve one accent color for "you can interact / go here"** (Mirror's Edge runner red, Dishonored's usable glint) and **never** use it decoratively. Consistency is the whole point; break it once and you've lied to the player.
+- **Composition** — framing, leading lines, and negative space point the eye like a photographer's shot. The critical path should be the most-framed, highest-contrast route from any decision point.
+- **Affordances & signifiers** (Norman/Gibson): a ledge that looks grabbable must be grabbable. Establish the visual language early and hold it — if a trim means "climb here", it appears *only* where you can climb. Inconsistent affordances are the #1 cause of "I didn't know I could do that."
+- **Deny wrong turns visually** (subtle dead-ends, unlit gaps, a "not-a-path" material) rather than with invisible collision.
+
+Full catalog — lighting/color/composition, the affordance language, the "critical-path readability" self-test → `references/guidance-and-readability.md`.
+
+## Metrics & playtesting — where players get lost and stuck
+
+You cannot see your own level fresh. **Observe, don't coach:**
+
+- **Watch a first-timer play, silent.** Note every hesitation (readability gap), wrong turn (navigation gap), repeated death (telegraph/difficulty gap), and skipped content (reward-placement gap). Do **not** answer "where do I go?" — that question *is* the finding.
+- **Traversal telemetry** turns anecdote into pattern: **position heatmaps** (cold zones players never enter = wasted level), **death heatmaps** (clusters = unfair/unreadable threats), **path traces** (golden path or lost?), **dwell time** at forks (long dwell = unclear guidance), and **look/aim heatmaps** (did they even see the landmark?).
+- **Read the map:** a cold region means the space doesn't pull the player there — re-light, add a landmark/reward, or cut it. A death cluster means fix the telegraph or arena, not the player. A branch nobody takes needs a visible reward at its mouth.
+
+Playtest protocol, question scripts, and turning heatmaps into fixes → `references/guidance-and-readability.md`.
+
+## Reward & secret placement, risk vs reward
+
+- **Reward the wandering eye.** Put secrets where a *curious* player naturally looks — behind the waterfall, up the ledge you already lit and framed, down the branch you breadcrumbed. Reward observation, not pixel-hunting; a secret nobody can reasonably find just frustrates.
+- **Breadcrumb the secret** with a glint, an out-of-place object, a suspicious seam, an "impossible" bit of geometry visible from the path. The player should feel *clever* — which means the game showed them the thread first.
+- **Risk vs reward.** Gate the best optional reward behind the biggest optional risk or detour. Keep the *critical path* rewarding on its own so risk-averse players aren't punished; put the *extra* behind the extra effort, both visible before committing.
+- **Never hide mandatory progression like a secret** — a required key/door disguised as optional is a stuck-player generator. Secrets are optional by definition.
+- **Vary reward types**: power/upgrade, resources, lore/collectible, a **shortcut unlock** (best long-term — reshapes the level), and pure spectacle.
+
+Reward taxonomy, secret-signposting, and risk/reward tuning → `references/guidance-and-readability.md`.
+
+## Anti-patterns / rationalizations -> STOP
+
+| Rationalization | Reality / Fix |
+|---|---|
+| "Let's make it look good first, then tune the layout." | Art-first burns days reworking assets when the layout changes. Blockout, playtest, *then* art. |
+| "It's obvious where to go." | Obvious to *you*, the author. Fresh players get lost. Watch one before you believe it. |
+| "I'll just add a waypoint arrow / big text prompt." | That's a patch over a readability failure. Fix it with light, framing, and a landmark first. |
+| "The whole level is intense — it's exciting!" | Sustained peak = fatigue and it all flattens into noise. Add breathers so the peaks read. |
+| "Backtracking reuses the space for free." | Repeated dead-end backtracking reads as padding. Use loops that return the player forward. |
+| "Players will figure the new mechanic out." | Not while it's killing them. Introduce it where it's safe, then develop/twist/combine. |
+| "Yellow paint everywhere so they see the ledges." | Only if yellow means *exactly* climbable and appears nowhere else. Inconsistent affordances lie. |
+| "The secret's hidden well — no one will find it." | A secret with no breadcrumb is just frustration. Show the thread; reward the curious eye. |
+| "The gap/cover/door width feels about right." | Guessing metrics breaks traversal later. Set the metrics block first; build to multiples. |
+
+## Quick reference
+
+| Lever | Default | Where |
+|---|---|---|
+| Build order | blockout → greybox → playtest → art (art last) | `references/blockout-to-art.md` |
+| Metrics block | lock player height/jump/reach/cover first; build to multiples | `references/blockout-to-art.md` |
+| Navigation | one dominant landmark per area; legible critical path + breadcrumbed loops | `references/guidance-and-readability.md` |
+| Pacing | sawtooth: peak → breather (safe room) → higher peak | `references/pacing-and-encounters.md` |
+| Encounter teaching | introduce → develop → twist → combine | `references/pacing-and-encounters.md` |
+| Arena shape | sightline length matched to threat range; flanks + verticality | `references/pacing-and-encounters.md` |
+| Guidance | light leads; one reserved interact color; consistent affordances | `references/guidance-and-readability.md` |
+| Playtest | watch silent; log hesitation/lost/death/skip; read heatmaps | `references/guidance-and-readability.md` |
+| Secrets / risk | breadcrumb them; best optional reward behind biggest optional risk | `references/guidance-and-readability.md` |
+
+## Related skills
+
+- **`game-design`** — the systemic layer: mechanics, verbs, economy, progression, difficulty *systems*. Level design exercises those verbs in space; if the request is about the rules themselves, route there.
+- **`game-storytelling`** — narrative, quests, dialogue, and the meaning of environmental beats. Level design places the beat; storytelling authors it.
+- **`godot` / `unity` / `unreal`** — the engine tooling that *implements* a proven layout: nav meshes, occlusion, terrain/tilemap editors, lightmap/GI bakes, streaming, collision. Hand off here after the blockout plays well.
+- **`harness`** — the `02-DOCS` Karpathy-wiki this skill records level conventions into.
+- **References:** `references/blockout-to-art.md` (pipeline, metrics block, art handoff, playtesting the blockout); `references/pacing-and-encounters.md` (intensity graph, encounter template, arena patterns, difficulty curve); `references/guidance-and-readability.md` (light/color/composition, affordances, playtest protocol, telemetry, reward & secrets).
+
+## Checklist
+
+- [ ] Player metrics block locked (height, jump, reach, cover, door/corridor widths) before geometry.
+- [ ] Layout proven in blockout/greybox — never modeled or textured before it plays well.
+- [ ] Critical path is legible from every decision point; a fresh player can find the objective without being told.
+- [ ] One dominant landmark orients each area; light and framing lead the eye along the intended path.
+- [ ] Intensity graph is a sawtooth (peaks + breathers), not a flat line; encounters vary in length and spacing.
+- [ ] At least one safe room / breather follows each major peak.
+- [ ] Every new mechanic/threat is introduced safely, then developed, twisted, and combined.
+- [ ] Arenas match sightline length to threat range and offer a flank/verticality option, not a static peek-war.
+- [ ] One reserved accent color for interactables/path, used consistently and never decoratively; affordances hold everywhere.
+- [ ] Played by a fresh, uncoached tester (and/or telemetry): hesitations/lost/deaths/skips logged, no dead cold-zones, no unfair death clusters, no ignored branches.
+- [ ] Secrets are breadcrumbed and reward observation; no mandatory progression hidden as a secret; best optional reward sits behind the biggest optional risk.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+When this skill runs in a project with a `02-DOCS/` layer (the [`harness`](../harness/SKILL.md) Karpathy wiki), record the level-design conventions there and index them from the root `CLAUDE.md`, so the next agent inherits them instead of re-deriving:
+
+1. **Find the article** `02-DOCS/wiki/stack/level-design.md`, indexed in `02-DOCS/wiki/index.md` (the Knowledge map).
+2. **If missing or stale**, create/update it with the project's real conventions — the metrics block, the reserved interact-color, the pacing/breather cadence, the encounter-teaching pattern, and any per-level intensity graphs — then index it.
+3. **Read it first on every use** and stay consistent; when a convention changes, update the article (bump its `Updated` date) in the same change.
+
+No `02-DOCS/` layer? Skip silently (optionally suggest `harness`). Conventions are *recorded, not gated* — never block the design work on this.