@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/godot/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: godot
+description: "Use when writing, reviewing, or debugging Godot 4.x games in GDScript or C# — scenes, nodes, custom Resources, autoload/EventBus signals, typed GDScript, CharacterBody2D/3D movement, GUT/gdUnit4 — or porting Godot 3 APIs to 4. NOT Unity/Unreal (that is `unity`/`unreal`), NOT `.gdshader` code (`gamedev-shaders`), NOT GDExtension C++ tooling (`cpp`)."
+tags: [godot, gdscript, game-dev, csharp, godot4]
+recommends: [gamedev-shaders, gamedev-multiplayer, gamedev-physics, gamedev-pathing, gamedev-shipping, game-design, cpp]
+profiles: [full]
+origin: ai-hub
+---
+
+# Godot 4.x (GDScript + C#)
+
+Build 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 — `get_node`/`$` on a missing path returns `null` and errors.
+- Cache node lookups in `@onready` vars; don't call `get_node` every frame.
+- **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 `await` a signal.
+
+```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`.
+
+## Hand off to
+
+Mechanics, loops, and feel *before* you script them → [`game-design`](../game-design/SKILL.md).
+`.gdshader` / visual shaders → [`gamedev-shaders`](../gamedev-shaders/SKILL.md). Joints, RigidBody
+tuning, deep collision layers → [`gamedev-physics`](../gamedev-physics/SKILL.md). NavigationAgent,
+A*, steering → [`gamedev-pathing`](../gamedev-pathing/SKILL.md). `MultiplayerSynchronizer`/RPC/netcode
+→ [`gamedev-multiplayer`](../gamedev-multiplayer/SKILL.md). Store builds, signing, platform export at
+scale → [`gamedev-shipping`](../gamedev-shipping/SKILL.md). The GDExtension / `godot-cpp` native side
+and its CMake/build tooling → [`cpp`](../cpp/SKILL.md).

package/skills/shared/godot/evals/README.md

@@ -0,0 +1,13 @@
+# Eval harness — `godot` skill
+
+These cases are read by the ai-hub 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.

package/skills/shared/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/shared/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/shared/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/shared/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.