summer-engine 3.3.0 → 3.4.1

package/library/skills/fps-controller/SKILL.md

@@ -5,14 +5,14 @@ license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: character-controllers
 user-invocable: false
-template-id: template-3d-fps
+template-id: template-3d-fps-old-school
 allowed-tools: Read Grep summer_get_scene_tree summer_add_node summer_set_prop summer_set_resource_property summer_input_map_bind summer_save_scene summer_get_script_errors
 paths: ["**/*.gd", "**/*.tscn"]
 ---
 
 # FPS Controller for Summer Engine
 
-The canonical first-person controller. Coyote time, jump buffering, air control, external-velocity, the works. This is the production minimum for an FPS that doesn't feel like a Unity tutorial — it follows the shipping FPS standard for movement (gravity, grace timers, separate ground/air acceleration, external force accumulator) so the player never says "this feels stiff" or "I jumped right at the edge and died unfairly".
+The canonical first-person controller: coyote time, jump buffering, air control and external velocity. It follows the standard shipping FPS movement model (asymmetric gravity, grace timers, separate ground/air acceleration, an external force accumulator), so the player never says "this feels stiff" or "I jumped right at the edge and died unfairly".
 
 ## Scene Structure
 
@@ -24,7 +24,7 @@ Player (CharacterBody3D)
 └── (optional) RayCast3D      # ground / interaction probe
 ```
 
-The Head/Camera split is the industry-standard movement model: yaw rotates the body, pitch rotates only the head. Don't pitch the body or you get tilted capsules and slope-collision bugs.
+The Head/Camera split is the standard: yaw rotates the body, pitch rotates only the head. Don't pitch the body or you get tilted capsules and slope-collision bugs.
 
 ## Step-by-Step Setup via MCP
 
@@ -48,7 +48,7 @@ summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Play
 summer_set_resource_property(scenePath="res://main.tscn", nodePath="./World/Player/Collision", resourceProperty="shape", subProperty="height", value="1.8")
 ```
 
-Two things the older version of this skill got wrong:
+Two rules for these calls:
 
 - **`scenePath` is required** on `summer_add_node`, `summer_set_prop`,
   `summer_set_resource_property` and `summer_save_scene`. Omit it and the call
@@ -61,7 +61,7 @@ Two things the older version of this skill got wrong:
   and external `.tres` resources take the same path. Structural failures are
   explicit — `node not found`, `property is not a resource`, or `resource is
   null` when the property was never assigned — but a bad value shape is silent
-  on current engines: a JSON object instead of a Godot literal string, a
+  on current engines: a JSON object instead of an engine variant string, a
   misspelled `key`/`subProperty`, or a wrong-typed value returns `ok:true` yet
   no-ops or coerces destructively. Assign the resource first, pass class names
   and `Vector3(...)`/`Color(...)` strings, and confirm in the saved `.tscn`,
@@ -234,18 +234,18 @@ func add_external_velocity(impulse: Vector3) -> void:
 | `fall_gravity_multiplier` | `1.4` | Snappier descent than ascent (variable-jump-feel staple). |
 | `ground_accel` / `ground_friction` | `80 / 90` | Crisp start, near-instant stop. |
 | `air_accel` / `air_friction` | `25 / 5` | Reduced air control + minimal air drag. |
-| `coyote_time` | `0.1` | Standard 0.08–0.15s grace — invisible to players, fixes 60% of "unfair death" complaints. |
+| `coyote_time` | `0.1` | Standard 0.08–0.15s grace — invisible to players, removes most "unfair death" complaints. |
 | `jump_buffer_time` | `0.1` | Same window the other direction. |
 | `mouse_sensitivity` | `0.002` | Default raw multiplier; expose via settings. |
 | `external_damping` | `8.0` | Knockback decays over ~0.5s. |
 
 ## Why Each Feature Matters
 
-**Coyote time (~0.1s)** — Players judge ledges by what they see, not by frame-perfect collision. A small grace period after walking off a ledge where jump still works fixes the "I jumped right at the edge and died unfairly" complaint that breaks 60% of new players' tutorials. Cost: 3 lines. Industry-standard window is 0.08–0.15s — short enough to be invisible, long enough to mask the imprecision of human reaction time.
+**Coyote time (~0.1s)** — Players judge ledges by what they see, not by frame-perfect collision. A small grace period after walking off a ledge where jump still works fixes the "I jumped right at the edge and died unfairly" complaint. Cost: 3 lines. The usual window is 0.08–0.15s — short enough to be invisible, long enough to mask the imprecision of human reaction time.
 
 **Jump buffering (~0.1s)** — Pressing jump 50ms before landing should not be punished. Buffer the input for ~0.1s and fire on touchdown. Without this, fast-moving players feel like the controller "ate their input" — they pressed jump, they saw nothing happen, they blame the game. With it, every "near-miss" jump becomes a successful one. Cost: 4 lines.
 
-**Air control with reduced acceleration (~30% of ground)** — Zero air control feels like ice; the player commits to a direction at jump-takeoff and can't course-correct. Full air control feels like a Unity tutorial; momentum is meaningless and a strafe-jump cancels itself. The shipping FPS standard sits around 25–30% of ground accel: enough to course-correct mid-jump, not enough to cancel realistic momentum. The `move_toward` formulation lets designers tune this with one number — `air_accel` — without forking code.
+**Air control with reduced acceleration (~30% of ground)** — Zero air control feels like ice; the player commits to a direction at jump-takeoff and can't course-correct. Full air control feels weightless; momentum is meaningless and a strafe-jump cancels itself. The shipping FPS standard sits around 25–30% of ground accel: enough to course-correct mid-jump, not enough to cancel realistic momentum. The `move_toward` formulation lets designers tune this with one number — `air_accel` — without forking code.
 
 **External velocity accumulator** — Knockback, explosions, jump pads, conveyor belts, wind volumes, and grapple-yanks must not fight player input. Storing them in a separate `external_velocity`, applying once per frame, and decaying via `move_toward(0, damping * delta)` means an explosion shoves the player and then control returns smoothly — no "stuck at terminal velocity" or "input cancels the punch" bugs. The subtract-previous-contribution trick (line 1 of `_physics_process`) is the production fix that prevents accumulation when the player is also sprinting; it's the kind of detail you only learn by shipping multiplayer. Public API (`add_external_velocity`) means any system — AOE attack, jump pad scene, grapple ability — can shove the player with one call, no coupling.
 
@@ -255,7 +255,7 @@ func add_external_velocity(impulse: Vector3) -> void:
 
 Once the skeleton is in, designers tune by feel. Common targets:
 
-**Snappy military shooter (industry-standard FPS feel):**
+**Snappy military shooter:**
 - `walk_speed = 5.5`, `sprint_speed = 8.0`
 - `ground_accel = 90`, `ground_friction = 100`
 - `air_accel = 20`, `air_friction = 4`
@@ -284,14 +284,14 @@ The skeleton doesn't change — only the `@export` defaults. That's the point of
 - **Pressing jump just before landing does nothing** — `_jump_buffer_timer` is being decremented to zero before the player touches floor. The buffer must NOT be cleared by anything except a successful jump.
 - **Knockback compounds forever** — `_prev_external_applied` isn't being subtracted. Step 1 of `_physics_process` MUST run before gravity, or external impulses pile up frame after frame.
 - **Knockback decays too fast / too slow** — tune `external_damping`. `8.0` decays a 5 m/s impulse to near-zero in ~0.6s. Lower = longer hangtime.
-- **Air control feels like ice OR like a Unity tutorial** — `air_accel` is the only knob. Industry-standard is 20–30% of `ground_accel`. Zero = ice. Equal = arcade-y. The shipping FPS standard sits around 25.
+- **Air control feels like ice OR weightless** — `air_accel` is the only knob. The usual range is 20–30% of `ground_accel`. Zero = ice. Equal = arcade-y.
 - **Camera tilts on slopes** — pitch is on the body instead of the Head. Pitch only on `Head`; yaw only on `Player`.
 - **Camera rolls when looking around** — you're calling `rotate_x` on something that's already rotated on Y. Fix: only ever rotate Y on Player and X on Head, never combine.
 - **Mouse look doesn't work** — `Input.mouse_mode` isn't set to `MOUSE_MODE_CAPTURED`, or another node is consuming `_input` before this script. Use `_unhandled_input` to be a good citizen.
 - **Mouse look feels laggy at low FPS** — sensitivity is being applied in `_physics_process`. Mouse-motion handling MUST stay in `_input` or `_unhandled_input` — those fire per-event, not per-physics-tick.
 - **Falling through floor** — floor needs a StaticBody3D + CollisionShape3D on the same physics layer as the player.
 - **Camera clipping geometry** — push `Camera.near` to ~0.05 or shrink the capsule radius slightly.
-- **Player jitters on slopes / stairs** — enable `floor_snap_length = 0.5` and `floor_max_angle = 0.785` (~45°) on the CharacterBody3D. Out of scope for this skeleton; see the character-body-tuning skill when it ships.
+- **Player jitters on slopes / stairs** — enable `floor_snap_length = 0.5` and `floor_max_angle = 0.785` (~45°) on the CharacterBody3D. Out of scope for this skeleton.
 
 ## Networking Note
 
@@ -312,8 +312,8 @@ The skeleton is intentionally ~90 lines. When you outgrow it, add features by *l
 - **Crouch.** Lerp the capsule height (e.g., 1.8 → 1.0) and the Head Y (1.6 → 0.9) over ~0.15s. Halve `walk_speed` while crouched. Block standing if a short upward shapecast hits ceiling.
 - **Sprint FOV punch.** Tween `Camera.fov` from 75 → 82 over 0.2s when sprint starts, back when it ends. The single cheapest "feel of speed" effect available.
 - **Slide.** When sprint + crouch are pressed together with horizontal speed above a threshold, lock direction to current velocity, set a `slide_timer`, and skip the wish-direction step. Apply slide-specific friction. Restore on timer expiry, ceiling clearance, or speed-below-threshold.
-- **Wallrun, dash, double-jump.** Each is its own override state. Build a state machine (see `scripting-patterns/state-machine-patterns/SKILL.md`) and let each state run its own `_physics_process` branch with an early `move_and_slide()` return. Don't pile them as `if/elif` in a single function.
-- **Camera shake.** Add a `trauma` float on the camera, accumulate via `add_trauma(amount)`, decay each frame, apply a randomized rotation offset proportional to `trauma * trauma`. Subtract the previous frame's shake offset before applying the new one to prevent drift. See the post-processing/screen-shake skill.
+- **Wallrun, dash, double-jump.** Each is its own override state. Build a state machine (see `gdscript-patterns`) and let each state run its own `_physics_process` branch with an early `move_and_slide()` return. Don't pile them as `if/elif` in a single function.
+- **Camera shake.** Add a `trauma` float on the camera, accumulate via `add_trauma(amount)`, decay each frame, apply a randomized rotation offset proportional to `trauma * trauma`. Subtract the previous frame's shake offset before applying the new one to prevent drift. See `game-feel`.
 
 Each of these is a separate skill or a separate function, not a fork of this script.
 
@@ -349,9 +349,10 @@ Then patch `project.godot` with the InputMap actions (`input/move_forward = { ..
 
 This skill writes scene nodes, an InputMap, and a `.gd` script. Always ask before applying. Group writes per phase: "May I add the Player + Collision + Head + Camera, bind WASD/jump/sprint, and attach `player_controller.gd`?"
 
-If the user asks for a "third-person FPS", flag the contradiction: FPS = first-person. Either clarify, or hand off to the `tps-controller` skill when it ships.
+If the user asks for a "third-person FPS", flag the contradiction: FPS = first-person. Either clarify, or hand off to `character-movement`, which has the third-person controller.
 
 ## See Also
 
-- `scripting-patterns/state-machine-patterns/SKILL.md` — once movement grows past this skeleton (slide, grapple, hover), refactor into a state machine instead of stuffing more branches into `_physics_process`.
-- `physics/character-body-tuning/SKILL.md` (when shipped) — slope handling, step-up, floor-snap.
+- `gdscript-patterns` — once movement grows past this skeleton (slide, grapple, hover), refactor into a state machine instead of stuffing more branches into `_physics_process`.
+- `character-movement` — 2D and third-person controllers.
+- `game-feel` — camera shake and hit feedback.

package/library/skills/fps-controller/resource.yaml

@@ -20,8 +20,6 @@ related:
   skills:
     - skill/character-movement
     - skill/camera-rigs
-  # Legacy frontmatter declared template-id: template-3d-fps (no such repo exists);
-  # mapped to the real repo template-3d-fps-old-school.
   templates:
     - template/3d-fps-old-school
 source: official

package/library/skills/game-feel/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools: Read Grep Edit Write summer_write_file summer_read_file summer_ge
 paths: ["**/*.gd", "**/*.tscn", "**/*.tres"]
 ---
 
-# /vfx — The Trio That Makes Games Feel Punchy
+# Game Feel — The Trio That Makes Hits Land
 
 Particles do not make a game feel good. Screen shake alone does not either.
 What makes a hit land is three systems firing on the same frame: a sub-frame
@@ -327,7 +327,7 @@ summer_connect_signal(scenePath="res://levels/world.tscn", emitter="./World/Enem
 
 ## Step 8 — Scaling intensity per hit weight
 
-The trio's whole magic is that the same code makes a glancing parry feel different from a critical hit. Calibrate the curve once:
+The same code makes a glancing parry feel different from a critical hit. Calibrate the curve once:
 
 | Hit type | `damage` (HP) | trauma | duck amount |
 |---|---|---|---|
@@ -343,7 +343,7 @@ Because trauma is squared inside the camera, the *felt* difference between 0.35
 
 ```
 summer_save_scene(scenePath="res://levels/world.tscn")
-summer_get_script_errors          # all three scripts parsed?
+summer_get_script_errors(path="res://scripts/vfx/hit_flash.gd")   # repeat for each of the three scripts
 summer_play
 # user reproduces a hit
 summer_get_debugger_errors        # runtime errors from the tweens / bus lookups
@@ -391,7 +391,6 @@ This skill writes 3 GDScript files and adds 1 node + 1 autoload entry. Always as
   version-sensitive API notes
 - `../../references/collaborative-protocol/collaborative-protocol.md` — "May I write" pattern
 - `../../references/gd-style/gd-style.md` — typed GDScript conventions
-- `audio/audio-direction/SKILL.md` — bus layout setup (prerequisite for ducking)
-- `post-processing/screen-shake/SKILL.md` — deeper trauma variants (Perlin noise, stacked sources)
-- `visual-effects/gpuparticles-3d-basics/SKILL.md` — particles to layer on top of the trio
-- `visual-effects/hit-impact-flashes/SKILL.md` — flash material variations beyond white pulse
+- `audio-direction` — bus layout setup (prerequisite for ducking)
+- `vfx-hit-spark` — particles to layer on top of the trio
+- `debugging-game-feel` — when the trio is installed and it still feels wrong

package/library/skills/gameskill/SKILL.md

@@ -15,9 +15,9 @@ You are being invoked at the end (or middle) of a game-development session. Turn
 
 Summer resolves skills in this order: the game project, then the user's agent skills directory, then the skills bundled with the Summer package. Pick the narrowest home that fits:
 
-1. **The game project** (default). Write `SKILL.md` into the project-scoped skills directory of the agent you are running in: `.claude/skills/<slug>/` for Claude Code, `.agents/skills/<slug>/` for Codex, `.cursor/rules/` for Cursor, `.windsurfrules` for Windsurf. `summer skills install --scope project` shows the exact path for the current agent. Commit it with the game.
+1. **The game project** (default). Write `SKILL.md` into the project-scoped skills directory of the agent you are running in: `.claude/skills/<slug>/` for Claude Code, `.agents/skills/<slug>/` for Codex, Cursor, Devin Desktop and the other agents that read the shared folder. `summer skills install --scope project` shows the exact path for the current agent. Commit it with the game.
 2. **The user's agent skills directory** when the lesson applies to every project on this machine (`~/.claude/skills/<slug>/`, `~/.agents/skills/<slug>/`). Do not edit skills that Summer installed there; they are overwritten on the next `summer setup`.
-3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the summer-engine agent repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_library_feedback` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
+3. **The Summer library** when the lesson is general enough for every Summer user. Only possible inside a checkout of the `summerengine/summer` repository: add `library/skills/<slug>/resource.yaml` and `library/skills/<slug>/SKILL.md` (flat slugs, no category folders), then run `npm run generate:registry` and `npm run validate:library`. Everything under `registry/generated/` and every plugin manifest is generated from `library/`; never hand-edit them. Outside that checkout, send the lesson through `summer_library_feedback` (or `summer tool library-feedback`) with the id of the closest existing skill so the maintainers can fold it in.
 
 Read the current project as ground truth. Working code from the real project beats invented examples.
 
@@ -32,7 +32,7 @@ Read the current project as ground truth. Working code from the real project bea
    - A GDScript idiom that beat the obvious approach
    - A UI layout that survived the design pass
    - A bug, its root cause and the fix that was not in any docs
-   - A Godot 4.x quirk (type inference, signal gotchas, plugin configuration)
+   - An engine quirk (type inference, signal gotchas, plugin configuration)
    - A spawning, AI or enemy pattern that worked
    - A performance fix with measured before and after
    - An asset workflow that beat the alternatives

package/library/skills/gdscript-patterns/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/*.gd"]
 
 # GDScript Patterns for Summer Engine
 
-When writing GDScript for Summer Engine projects, follow these patterns. They align with Godot 4.x conventions and work well with MCP scene operations.
+When writing GDScript for Summer Engine projects, follow these patterns. They match the engine's GDScript 4 conventions and work well with MCP scene operations.
 
 ## Type Hints
 
@@ -92,7 +92,7 @@ For health systems, input handling, and state machines, see [reference.md](refer
 
 ## Anti-patterns — introspection traps
 
-Godot's introspection API has Object-instance methods that look like they should work on script-class references. They don't. Calling them on a `const ScriptName = preload(...)` reference is a parse error, not a runtime no-op.
+The engine's introspection API has Object-instance methods that look like they should work on script-class references. They don't. Calling them on a `const ScriptName = preload(...)` reference is a parse error, not a runtime no-op.
 
 | Wrong | Right | Why |
 |---|---|---|
@@ -106,7 +106,7 @@ Godot's introspection API has Object-instance methods that look like they should
 
 ## Anti-pattern — `@onready var = $Path` on nodes that don't exist on every variant
 
-Godot resolves `$Path` (the `get_node` shorthand) at `@implicit_ready` time. If the node is missing from the current scene, you get `Node not found: "X" (relative to "Y")` errors before any of your `_ready()` runtime guards can run.
+The engine resolves `$Path` (the `get_node` shorthand) at `@implicit_ready` time. If the node is missing from the current scene, you get `Node not found: "X" (relative to "Y")` errors before any of your `_ready()` runtime guards can run.
 
 Common case: a script is shared by multiple scene variants where some variants have an optional child. Even if every code path that touches the variable has a `if inventory_ui:` guard, the `@onready` line itself errors at scene load.
 

package/library/skills/generate-motion/SKILL.md

@@ -11,7 +11,7 @@ paths: ["**/*.tscn", "**/*.tres", "**/*.gd"]
 
 # Generate Motion — Curated Meshy Library
 
-Picks a clip from a **curated mocap library** by name and wires it onto a Meshy-rigged humanoid. Fast (~30s) and cheap (~$0.10) and looks great because it's real mocap. The five short aliases that always work are `idle`, `walk`, `run`, `jump`, `attack`; anything else must be an exact library name — see the Reference card before you invent one.
+Picks a clip from a **curated mocap library** by name and wires it onto a Meshy-rigged humanoid. Fast (~30s), and it looks good because it is real mocap. The five short aliases that always work are `idle`, `walk`, `run`, `jump`, `attack`; anything else must be an exact library name — see the Reference card before you invent one.
 
 The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `summer_generate_3d({ kind: "image-to-3d", imageUrl: "...", options: { rig: true } })` call. The result job includes `rigAssetId`. If the user points at a non-rigged mesh, stop and route to `asset-strategy` (or directly call `summer_generate_3d` with `options.rig: true`) before generating motion.
 
@@ -20,22 +20,6 @@ The target must be a **Meshy-rigged humanoid** — a `rigAssetId` from a prior `
 > (`backend: "text-to-motion"`) when the server has it enabled; otherwise fall
 > back to hand-authoring in Summer Engine or importing from Mixamo.
 
-## Web Chat / Public Orchestrator Equivalent
-
-In PublicSummerEngine chat, the equivalent direct tools are:
-
-```
-rigModel({ modelAssetId })
-generateAnimation({ rigAssetId, animationName })
-meshyJobStatus({ jobId })
-```
-
-If the character came from `createCharacter`, it may already be rigged and have `metadata.meshyRigTaskId`; generate animations directly against that rig asset. Verified animation names from the recovered production flow are `idle`, `walk`, `run`, `jump`, and `attack`. `fall` returned `invalid_animation`, so do not present it as a default.
-
-Before generating clips in PublicSummerEngine chat, confirm the rig asset listing/status exposes `hasMeshyRigTask` or `animationsReady:true`. If `generateAnimation` returns `animations_preparing`, wait, poll/list the rig again, and retry; this is the post-rig setup catching up, not a reason to send the user to Studio.
-
-After animation jobs complete, import the rig plus child animation assets together and wire them through `import-character`. Do not hand off to Studio unless the user asked for Studio/manual control or the direct chat tools fail.
-
 ## When to use this skill
 
 - "Add a walk animation to the goblin."
@@ -64,7 +48,7 @@ The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAsset
 
 ### 2. Confirm with the user before spending
 
-> I'm about to generate a "run" animation on `goblin_rigged` via meshy-library — about 30s, ~$0.10. OK?
+> I'm about to generate a "run" animation on `goblin_rigged` via meshy-library — about 30s, and it uses credits. OK?
 
 ### 3. Call the tool
 
@@ -107,7 +91,7 @@ If the character will use multiple clips, leave the AnimationPlayer in place —
 
 ## Confirmation gates
 
-- **Before generation:** state the motion name and est. cost (~$0.10). Wait for OK.
+- **Before generation:** state the motion name and that it uses credits. Wait for OK.
 - **Before attaching:** state which AnimationPlayer and which library slot. Wait for OK.
 - **After generation:** if the user hasn't seen the preview, link `previewUrl` and ask "land or regenerate?" before wiring it into the scene.
 
@@ -129,9 +113,8 @@ nothing like a tidy snake_case scheme — real names look like `Walking_Woman`,
 Plausible-looking names that do **not** resolve, verified against the resolver:
 `attack_sword`, `hit_react`, `death`, `sprint`, `block`, `dodge_left`,
 `crouch_idle`, `walk_back`, `run_strafe_left`, `jump_land`, `idle_combat`,
-`wave`, `dance`, `sit_idle`. They return `null` and the call errors. The tool's
-own description uses `attack_sword` as an example — that example is wrong; use
-`attack`.
+`wave`, `dance`, `sit_idle`. They return `null` and the call errors. For a sword
+attack, use `attack`.
 
 So: if the user asks for something outside the five aliases, do not guess a
 snake_case name. Either use one of the five, quote an exact raw library name you

package/library/skills/godogen-visual-proof-game-generation/SKILL.md

@@ -13,68 +13,61 @@ tags:
 confidence: extracted
 ---
 
-# Godogen-Style Autonomous Game Generation + Visual Proof QC in SummerEngine
 
-## Outcome
+# Godogen-Style Game Generation with Visual Proof QC in Summer Engine
 
-Give SummerEngine an agent workflow that takes a **short game description** and produces a **runnable, visually verified game**, using Godogen's core insight: *judge the result from the running game, never from a clean compile*. The visible output of every iteration is a screenshot or short proof clip from the actual engine, and the host coding agent itself reviews those frames against the brief — no separate verifier model.
+## Outcome
 
-This directly targets a known studio pain point: Summer Engine already has a "validation of the game" step, but it does not yet verify the running game. Godogen's visual QC loop is the reference design to rebuild it.
+Take a **short game description** and produce a **runnable, visually verified game**. The method comes from the open-source Godogen project: *judge the result from the running game, never from a clean compile*. Every iteration ends with a screenshot or short proof clip from the running game, and the host coding agent reviews those frames against the brief itself. There is no separate verifier model.
 
 ## When to Use
 
-- Building complete small games or prototypes from a natural-language brief (mechanics + art style + camera + HUD in one prompt, like Godogen's demo prompts).
-- Fixing SummerEngine's broken game-validation step: you need an agent that can *see* the running game and report concrete visual defects.
-- Unattended generation runs where the deliverable must include proof (15–20s recording) instead of "it compiled, trust me."
+- Building a complete small game or prototype from a natural-language brief (mechanics, art style, camera and HUD in one prompt).
+- The agent says the game works but never looked at it running. You need an agent that *sees* the running game and reports concrete visual defects.
+- Unattended generation runs where the deliverable must include proof (a 15–20s recording) instead of "it compiled, trust me."
 - Asset generation for the game (references, textures, 3D models, animated sprites) as part of the same pipeline.
 
 ## When NOT to Use
 
-- Hand-authored, large-scope production work — this is a generator loop, not a replacement for deliberate design iteration.
-- When no headless/GPU capture environment exists — the QC loop is worthless if frames come from a software renderer (see Failure Modes).
-- Quick code fixes with no visual component — running the engine and capturing is overhead if the change is purely logic.
-
-## Core Principles (extracted)
-
-1. **godogen → game repo → game.** The generator itself is not a game. You publish a thin scaffold into a fresh game repo; the agent then builds the actual game *inside* that repo from a short engine guide.
-
-2. **Thin runtime, smart agent.** The published repo is intentionally minimal: one engine-agnostic runtime manifest (`prompts/runtime.md`), a one-page per-engine guide (`engines/godot.md`), and a single cross-engine asset-generation skill (`asset-gen/`). The model plans, scaffolds, and decomposes the work itself — there are no planner/decomposer/architecture skill files anymore (dropped 2026-07-02).
-
-3. **Proof over claims.** "The agent judges results from the running game (a live URL or a recorded clip), not from a clean compile, so visible defects drive the next iteration."
+- Hand-authored, large-scope production work. This is a generator loop, not a replacement for deliberate design iteration.
+- No GPU capture path. The QC loop is worthless if frames come from a software renderer (see Failure Modes).
+- Quick logic fixes with no visual component. Running and capturing is overhead there.
 
-4. **Host agent self-verifies from captured frames.** Godogen dropped a separate Gemini verification pass on 2026-04-26: "Opus 4.7 / GPT 5.5 self-verify from captured frames; external pass added no signal." One strong coding agent looking at real screenshots is enough.
+## Core Principles (from Godogen)
 
-5. **Two involvement modes, chosen by how the task is framed.** Watch the live game and steer at decision points, or run unattended and receive a 15–20s proof recording at the end, "watched back before done."
+1. **Generator repo → game repo → game.** The generator itself is not a game. It publishes a thin scaffold into a fresh game repo; the agent then builds the actual game *inside* that repo from a short engine guide.
+2. **Thin runtime, smart agent.** The published repo is minimal: one runtime manifest (`prompts/runtime.md`), a one-page engine guide, and one asset-generation skill (`asset-gen/`). The model plans, scaffolds and decomposes the work itself; there are no planner or architecture skill files.
+3. **Proof over claims.** The agent judges results from the running game (a live build or a recorded clip), not from a clean compile, so visible defects drive the next iteration.
+4. **The host agent verifies from captured frames.** Godogen dropped a separate verification model because it added no signal. One strong coding agent looking at real screenshots is enough.
+5. **Two involvement modes, chosen by how the task is framed.** Watch the live game and steer at decision points, or run unattended and receive a 15–20s proof recording at the end, watched back before done.
+6. **Engine-specific runtime traps live in the engine guide.** Defects that survive a compile but fail at runtime are written down where the agent reads them during the run.
 
-6. **Engine-specific runtime traps live in the engine guide** — the defects that "survive a compile but fail at runtime" are documented where the agent will read them during the run.
+## Mapping to Summer Engine
 
-## SummerEngine Architecture Mapping
-
-| Godogen concept | SummerEngine adaptation |
+| Godogen concept | Summer Engine equivalent |
 |---|---|
-| `publish.sh --engine godot --agent codex` | A SummerEngine publish step that renders `AGENTS.md` + skills into the target game repo |
-| `prompts/runtime.md` manifest | One SummerEngine runtime manifest describing delivery contract + involvement modes |
-| `engines/godot.md` one-page guide | SummerEngine engine guide: capture recipes, runtime traps, scene conventions |
-| `asset-gen/` skill | SummerEngine asset-generation skill (Gemini/Grok/Tripo3D stack below) |
-| Proof recording (ffmpeg + xvfb) | Godot viewport screenshot capture + optional ffmpeg clip |
-| C#/.NET + `dotnet build` as compile gate | See note below — Godogen migrated to C# specifically so `dotnet build` replaces per-file validation loops |
-
-**Language note:** Godogen generates Godot games in **C#/.NET** (migrated from GDScript on 2026-04-06) because `dotnet build` gives a cheap, reliable compile gate. If SummerEngine stays GDScript, you need an equivalent cheap gate — e.g. `godot --headless --check-only` script parsing — before the visual stage, since the whole point is: compile gate first, *then* visual proof, never one instead of the other.
+| Publish step that renders the agent files into a game repo | `summer create <template>` plus the installed Summer skills; `.summer/` holds the brief (`GameSoul.md`) and build plan |
+| `prompts/runtime.md` manifest | `.summer/build-plan.md`: delivery contract and involvement mode |
+| One-page engine guide | A project skill with capture recipes, runtime traps and scene conventions (`gameskill` captures new traps) |
+| `asset-gen/` skill | `asset-strategy` and the Summer generation tools |
+| Compile gate (`dotnet build` for C#) | `summer_get_script_errors` per file, then `summer_get_diagnostics` |
+| Proof recording (ffmpeg + xvfb) | `summer_play`, `summer_screenshot target:"game"`, `summer_game_probe`; frame sequences from a `RunVerification` probe's `save_frame`; optional ffmpeg clip |
 
-## Scene / Repo Shape (SummerEngine target)
+**Language note:** Godogen generates C# games because `dotnet build` is a cheap, reliable compile gate. Summer games use GDScript, so the gate is `summer_get_script_errors` on each changed file. The order is the point: compile gate first, *then* visual proof, never one instead of the other.
 
-Published game repo (thin, everything else recreated by the agent):
+## Repo Shape
 
 ```
 my-summer-game/
-├── AGENTS.md                 # host-agent entry (Codex flavor)
-├── prompts/runtime.md        # delivery manifest + involvement modes
-├── engines/summerengine.md   # one-page guide: capture, traps, conventions
+├── AGENTS.md                 # host-agent entry
+├── .summer/
+│   ├── GameSoul.md           # the brief
+│   └── build-plan.md         # delivery contract + involvement mode
 └── .agents/skills/
-    └── asset-gen/            # sole published skill (asset generation)
+    └── <project-guide>/      # capture recipes, runtime traps, conventions
 ```
 
-In-engine capture harness (Godot 4 node shape):
+In-game capture harness, for runs outside the editor:
 
 ```
 Main (Node)
@@ -85,9 +78,9 @@ Main (Node)
     # saves PNGs to user://proof/ on trigger
 ```
 
-## Capture Harness (GDScript, adaptation)
+## Capture Harness (GDScript)
 
-The source says *that* Godogen captures (xvfb + engine screenshots + ffmpeg proof video) but the repo internals were not retrievable. Below is a SummerEngine-facing adaptation, not extracted code:
+Godogen's own capture code is not public; this is an adaptation. Inside a Summer session, prefer `summer_screenshot target:"game"` and `RunVerification` frames, and use this autoload for unattended runs outside the editor.
 
 ```gdscript
 extends Node
@@ -135,89 +128,78 @@ func _on_frame_post_draw() -> void:
     pass  # hook if you need exact-frame capture timing
 ```
 
-The ffmpeg step (from setup.md, `ffmpeg — MP4 encoding of proof videos`):
+Encode the PNG sequence (resolve `user://` to its absolute path first):
 
 ```bash
-ffmpeg -framerate 2 -i user://proof/%03d_rec.png -c:v libx264 -pix_fmt yuv420p proof.mp4
+ffmpeg -framerate 2 -i <user_dir>/proof/%03d_rec.png -c:v libx264 -pix_fmt yuv420p proof.mp4
 ```
 
-Headless run on Linux uses xvfb so rendering is real: `xvfb-run -a godot --headless ...` (setup.md: xvfb is explicitly for "headless Godot/Bevy runs and capture").
-
-## The Visual QC Loop (the core deliverable)
+Unattended Linux runs need a real display for real rendering: run the engine under `xvfb-run -a`.
 
-This is the piece SummerEngine's validation should adopt:
+## The Visual QC Loop
 
 ```
 1. BUILD/EDIT   agent applies a change to the game
-2. COMPILE GATE cheap syntax/build check (dotnet build OR godot script check)
-3. RUN + CAPTURE launch game under xvfb, capture screenshots at defined triggers
+2. COMPILE GATE summer_get_script_errors on changed files, then summer_get_diagnostics
+3. RUN + CAPTURE summer_play, then capture frames at defined triggers
 4. SELF-REVIEW  host agent inspects captured frames against the brief
 5. DEFECT LIST  structured findings: {location, expected, observed, severity}
 6. DECIDE       no blocking defects → go to 7; else → back to 1 with the list
-7. PROOF        15–20s recording, "watched back before done"
+7. PROOF        15–20s recording, watched back before done
 ```
 
 Rules that make it work:
 
-- **Bounded.** Hard cap on rounds (see Tunables). Godogen's delivery manifest frames this as closing with a proof recording, not iterating forever.
-- **Same agent verifies.** Do not add a separate verifier model — Godogen tested that (Gemini verification) and dropped it: no extra signal.
-- **Defects must be visible.** The review prompt asks for concrete visual observations tied to the brief ("character sprite missing against brief's 'chunky iconic sprites'", not "looks wrong").
-- **Engine traps belong in the guide.** Recurring "survives compile, fails at runtime" defects get written into `engines/summerengine.md` so the agent reads them before they happen again.
+- **Bounded.** Hard cap on rounds (see Tunables). The run closes with a proof recording; it does not iterate forever.
+- **Same agent verifies.** Do not add a separate verifier model. Godogen tried it and dropped it.
+- **Defects must be visible.** The review asks for concrete visual observations tied to the brief ("character sprite missing; brief asks for chunky iconic sprites"), not "looks wrong".
+- **Engine traps belong in the guide.** Recurring "survives compile, fails at runtime" defects go into the project guide so the agent reads them before they happen again.
 
-## Asset Generation Pipeline (extracted)
-
-| Need | Tool | Notes |
-|---|---|---|
-| Precise references & characters | Gemini (`GOOGLE_API_KEY`, google-genai) | high-fidelity image generation |
-| Textures & simple objects | xAI Grok (`XAI_API_KEY`) | image/video generation |
-| Image-to-3D, rigged biped animation | Tripo3D (`TRIPO3D_API_KEY`) | 3D conversion |
-| Animated sprites | Grok video → frame extraction (ffmpeg) → loop detection → background removal | BiRefNet multi-signal matting (since 2026-03-25); imagemagick for resize/flip/crop |
+## Asset Generation
 
-asset-gen is the **sole published skill** in a godogen game repo — everything else the agent recreates from the engine guide.
+Godogen calls external image, video and image-to-3D providers with their own API keys, then cuts animated sprites from generated video (frame extraction, loop detection, background removal, imagemagick for resize and crop). In Summer, route asset work through `asset-strategy` and the Summer generation tools (`summer_generate_image`, `summer_generate_3d`, `summer_generate_video`) instead of wiring provider keys into the project.
 
 ## Implementation Steps
 
-1. **Write the thin runtime for SummerEngine**: `prompts/runtime.md` (delivery manifest + the two involvement modes), `engines/summerengine.md` (one page: how to run, how to capture, known runtime traps), and the asset-gen skill. Engine guide content comes from actual SummerEngine run failures — start it now, grow it every time a defect "survives compile."
-2. **Set up headless capture**: Godot 4 (.NET build if following Godogen's C# choice) on PATH, xvfb, ffmpeg, imagemagick, vulkan-tools. Verify GPU path with `vulkaninfo --summary`; a software-renderer fallback on a GPU host is a misconfiguration to fix before trusting any QC frame.
-3. **Implement `ProofCapture`** (GDScript above) as an autoload; wire capture triggers to scene-loaded, state-changed, and recording mode.
-4. **Define the compile gate**: `dotnet build` (C#) or `godot --headless --check-only` (GDScript). Gate must run before every capture round.
-5. **Implement the QC loop protocol**: capture → self-review → structured defect list → fix → re-capture, capped at `max_qc_rounds`. The reviewing prompt receives the original brief + latest frames and must output findings in a fixed JSON shape.
-6. **Add the proof-recording close**: after the loop passes, record 15–20s, encode with ffmpeg, and have the agent watch the clip back before declaring done.
-7. **Support both involvement modes**: if the task is framed open-ended, surface the live game early and checkpoint at taste/scope/cost decisions; if it's a finished brief, run unattended and close with proof.
-8. **Optionally move runs to a server**: tmux/screen for long sessions, GPU instance for faster render+capture, remote-control interface to steer mid-run.
+1. **Write the thin runtime**: the brief in `.summer/GameSoul.md`, the delivery contract and involvement mode in `.summer/build-plan.md`, and a one-page project guide (how to run, how to capture, known runtime traps). Grow the guide every time a defect survives the compile gate.
+2. **Set up capture**: inside a Summer session, `summer_play` plus `summer_screenshot target:"game"`. For unattended Linux runs, add xvfb, ffmpeg and vulkan-tools, and check the GPU path with `vulkaninfo --summary`. A software-renderer fallback on a GPU host is a misconfiguration to fix before trusting any QC frame.
+3. **Add `ProofCapture`** (GDScript above) as an autoload when capturing outside the editor; wire triggers to scene-loaded, state-changed and recording mode.
+4. **Run the compile gate** before every capture round.
+5. **Run the QC loop**: capture → self-review → structured defect list → fix → re-capture, capped at `max_qc_rounds`. The review receives the original brief plus the latest frames and outputs findings in a fixed JSON shape.
+6. **Close with proof**: after the loop passes, record 15–20s, encode with ffmpeg, and have the agent watch the clip back before declaring done.
+7. **Support both involvement modes**: for an open-ended task, show the live game early and checkpoint at taste, scope and cost decisions; for a finished brief, run unattended and close with proof.
 
 ## Tunables
 
-| Parameter | Meaning | Godogen reference |
+| Parameter | Meaning | Reference value |
 |---|---|---|
-| `max_qc_rounds` | hard cap on capture→fix iterations | bounded delivery, not infinite |
+| `max_qc_rounds` | hard cap on capture→fix iterations | bounded, never open-ended |
 | Proof clip length | recording at the end of a run | 15–20 s |
-| Capture triggers | when screenshots fire (scene load / state change / timer) | engine-guide defined |
-| Record fps | frame rate of the QC strip | 2 fps is enough for review; ffmpeg re-encodes |
-| Verification model | which agent reviews frames | host agent itself (Claude Code / Codex); no separate verifier |
+| Capture triggers | when screenshots fire (scene load / state change / timer) | defined in the project guide |
+| Record fps | frame rate of the QC strip | 2 fps is enough for review |
+| Verification model | which agent reviews frames | the host agent itself; no separate verifier |
 | Involvement mode | live-steered vs unattended | chosen by task framing |
 
 ## Failure Modes & Gotchas
 
-- **Trusting a clean compile.** The whole anti-pattern Godogen exists to kill. Compile gate is necessary, never sufficient.
-- **Software-renderer frames.** SwiftShader/llvmpipe/lavapipe output looks wrong and misleads the QC loop; on a GPU host it means the capture path is misconfigured (setup.md warns explicitly).
-- **Unbounded verification loops.** Without `max_qc_rounds` the agent iterates forever on taste-level nitpicks. Close with proof, don't chase perfection.
-- **Adding a separate verifier model.** Godogen tried Gemini verification and dropped it — "external pass added no signal." Don't repeat the experiment.
-- **Capturing before the frame settles.** Grab the viewport after `frame_post_draw`/a short delay, or screenshots show half-rendered scenes and generate false defects.
-- **Harmless headless noise.** `godot --headless --quit` may show RID warnings (setup.md calls them harmless) — don't let the QC loop treat engine noise as defects.
-- **GDScript vs C# trade-off.** Godogen's C# migration was driven by `dotnet build` replacing per-file validation loops. Staying GDScript is fine, but you must provide an equally cheap compile gate or the loop loses its fast first stage.
-- **Stale claims.** The X post mentions "850+ GDScript classes" language reference, but the project migrated to C# in April 2026 — verify current repo state before copying specifics.
+- **Trusting a clean compile.** The compile gate is necessary, never sufficient.
+- **Software-renderer frames.** SwiftShader, llvmpipe and lavapipe output looks wrong and misleads the QC loop. On a GPU host it means the capture path is misconfigured.
+- **Unbounded verification loops.** Without `max_qc_rounds` the agent iterates forever on taste-level nitpicks. Close with proof.
+- **Adding a separate verifier model.** Godogen tried it and found no extra signal.
+- **Capturing before the frame settles.** Grab the viewport after `frame_post_draw` or a short delay, or screenshots show half-rendered scenes and produce false defects.
+- **Headless noise.** Headless runs can print harmless RID warnings on quit. Do not let the QC loop treat engine noise as defects.
+- **An all-black screenshot** usually means the viewport had not redrawn. Recapture before calling it a defect.
 
 ## Verification
 
-Not summerengine-verified. To validate an implementation:
+Not yet verified in Summer Engine. To validate an implementation:
 
-1. Publish a thin SummerEngine game repo from the runtime manifest; confirm the agent scaffolds a runnable project from the one-page guide alone.
-2. Run a small game brief end-to-end; confirm the pipeline produces a running build, not just code.
-3. Intentionally introduce a visible defect (e.g., broken sprite, missing material); confirm the QC loop's self-review detects it from captured frames and fixes it within the round cap.
+1. Scaffold a project and confirm the agent builds a runnable game from the brief and the one-page guide alone.
+2. Run a small brief end to end; confirm the pipeline produces a running build, not just code.
+3. Introduce a visible defect (a broken sprite, a missing material); confirm the self-review finds it from captured frames and fixes it within the round cap.
 4. Confirm the run closes with a 15–20s proof clip that the agent reviews before marking done.
-5. Confirm the compile gate runs before every capture round and that frames come from hardware rendering (check with vulkaninfo).
+5. Confirm the compile gate runs before every capture round and that frames come from hardware rendering.
 
 ## Confidence
 
-`extracted` — Architecture (thin runtime, manifest + engine guide + asset-gen), the proof-over-claims principle, self-verification from captured frames, the dropped Gemini verification, C# migration rationale, capture tooling (xvfb/ffmpeg/imagemagick/vulkan-tools), asset-generation stack, and the two involvement modes are drawn directly from the GitHub README, CHANGELOG.md, and setup.md. The `ProofCapture` GDScript, the QC-loop JSON protocol, and the SummerEngine repo mapping are librarian adaptations — the repository's internal files (`prompts/runtime.md`, `engines/godot.md`, `asset-gen/` contents) could not be retrieved and are referenced only by their README-described roles.
+`extracted`. The architecture (thin runtime, manifest, engine guide, asset-gen), proof over claims, self-verification from captured frames, the dropped verifier model, the C# rationale, the capture tooling and the two involvement modes come from Godogen's public README, CHANGELOG and setup notes. The `ProofCapture` script, the QC-loop JSON protocol and the Summer mapping are adaptations; Godogen's internal prompt and guide files are not public.

package/library/skills/godogen-visual-proof-game-generation/resource.yaml

@@ -9,7 +9,6 @@ use_when:
   - "set up headless capture so an unattended generation run ends with a 15-20 second proof clip"
 do_not_use_when:
   - "large hand-authored production work, purely logical code fixes with no visual component, or hosts with no GPU or headless capture path"
-  - "intake from the gamedev-knowledge pipeline (source-cited, pipeline-validated, not yet exercised in-engine by the Summer team) — verify results in the engine as you would any technique"
 facets:
   lifecycle:
     - build