summer-engine 3.1.0 → 3.2.0

package/library/skills/combat-basics/SKILL.md

@@ -0,0 +1,159 @@
+---
+name: combat-basics
+description: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: gameplay-mechanics
+user-invocable: false
+allowed-tools: Read Grep summer_read_file summer_write_file summer_replace_text summer_add_node summer_set_prop summer_batch summer_project_setting summer_save_scene summer_get_script_errors summer_get_diagnostics
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# Combat Basics
+
+The Godot combat pattern is hitbox + hurtbox + health, wired by signals. Build it
+component-first: the same three pieces work for player, enemies, and destructibles.
+
+## The layer model (set this up first)
+
+Attacks are `Area2D`/`Area3D`, not solid bodies. A hitbox (the attack) detects a
+hurtbox (the thing that can be hurt) via collision layers/masks:
+
+| Node | on layer | masks (detects) |
+|------|----------|-----------------|
+| Player hurtbox | PlayerHurt | EnemyHit |
+| Player hitbox (sword) | PlayerHit | EnemyHurt |
+| Enemy hurtbox | EnemyHurt | PlayerHit |
+| Enemy hitbox | EnemyHit | PlayerHurt |
+
+Rule: every combat Area masks only the OPPOSING side. This is why the player's
+sword never damages the player. An Area reports `area_entered` only for areas on
+a layer in its OWN mask, so the hurtbox below (which listens) must mask the
+opposing hitbox layer; a hurtbox with an empty mask never registers a hit.
+
+Name the layers once so you are not counting bits by hand —
+`summer_project_setting(key="layer_names/2d_physics/layer_4", value="PlayerHit")`
+(use `layer_names/3d_physics/...` for 3D), one call per layer.
+
+## Health component (reuse everywhere)
+
+Attach to any damageable node. It owns HP and fires signals; UI and death logic
+just listen.
+
+```gdscript
+class_name Health extends Node
+
+signal damaged(amount: int, current: int)
+signal died
+
+@export var max_health: int = 100
+var current: int
+
+func _ready() -> void:
+	current = max_health
+
+func take_damage(amount: int) -> void:
+	if current <= 0:
+		return
+	current = maxi(0, current - amount)
+	damaged.emit(amount, current)
+	if current == 0:
+		died.emit()
+
+func heal(amount: int) -> void:
+	current = mini(max_health, current + amount)
+```
+
+## Hurtbox -> Health
+
+The hurtbox is an Area on the body; when a hitbox overlaps it, read the hitbox's
+damage and route it to the Health node.
+
+```gdscript
+extends Area2D   # Hurtbox, child of the character
+
+@export var health_path: NodePath
+@onready var health: Health = get_node(health_path)
+
+func _ready() -> void:
+	area_entered.connect(_on_area_entered)
+
+func _on_area_entered(hitbox: Area2D) -> void:
+	if hitbox.has_method("get_damage"):
+		health.take_damage(hitbox.get_damage())
+```
+
+## Hitbox
+
+```gdscript
+extends Area2D   # Hitbox, child of weapon or attack
+
+@export var damage: int = 10
+func get_damage() -> int:
+	return damage
+```
+
+Enable the hitbox only during the active frames of a swing (toggle
+`monitoring`/`monitorable` or the CollisionShape's `disabled`), driven by an
+AnimationPlayer track. An always-on melee hitbox hits on touch, which feels wrong.
+
+## Death, knockback, feedback
+
+- On `died`: `queue_free()`, spawn a death VFX, drop loot, `add_kill()` on your
+  game manager. For the player, switch to a GAME_OVER state instead of freeing.
+- Knockback: push the victim `velocity = (victim.global_position -
+  attacker.global_position).normalized() * force`, decay it each frame.
+- Every hit needs feedback or it reads as broken: a flash (`modulate` to white for
+  0.05s), a damage number (floating Label), a small screen shake, a hitstop
+  (`Engine.time_scale = 0.05` for one frame). Silent damage feels like a no-op.
+
+## Projectiles (short version)
+
+An `Area2D/3D` that moves forward and calls `take_damage` on what it hits, then
+frees itself.
+
+```gdscript
+extends Area2D   # projectile
+
+@export var speed: float = 600.0
+@export var damage: int = 15
+var direction: Vector2 = Vector2.RIGHT
+
+func _ready() -> void:
+	body_entered.connect(_on_hit)
+	get_tree().create_timer(3.0).timeout.connect(queue_free)  # lifetime
+
+func _physics_process(delta: float) -> void:
+	position += direction * speed * delta
+
+func _on_hit(body: Node) -> void:
+	if body.has_node("Health"):
+		body.get_node("Health").take_damage(damage)
+	queue_free()
+```
+
+Homing, piercing, AoE, and pooling many bullets are in this skill's
+`references/projectiles-and-aoe.md` — read it only when you need one of those.
+
+## Traps
+
+- Hitbox on the wrong layer/mask = no hits or friendly fire. Verify the layer
+  table above before debugging the scripts.
+- Two Areas with neither `monitoring` nor `monitorable` never report overlap.
+- Freeing a node mid-signal can error - defer with `queue_free()` (safe), not
+  `free()`.
+- Damaging in `_process` instead of on overlap = continuous per-frame damage.
+
+## Applying it in Summer Engine
+
+- Scripts (`health.gd`, `hurtbox.gd`, `hitbox.gd`, `projectile.gd`) are files:
+  create with `summer_write_file(path=..., content=..., create_only=true)`,
+  change with `summer_replace_text`. Check each with `summer_get_script_errors`.
+- Nodes (the Area, its CollisionShape, the Health child) are scene mutations:
+  `summer_add_node` / `summer_set_prop` with `scenePath`, or one `summer_batch`
+  with `AddNode` / `SetProp` ops so the scene saves once. Set `collision_layer`
+  and `collision_mask` as integers (bit values), not layer names.
+- Prove a hit with a `RunVerification` probe (see `playtesting-a-feature`):
+  spawn or find one enemy, press the attack action, `report()` the enemy's
+  `Health.current` before and after. A static scene check cannot show that a
+  hit registered.

package/library/skills/combat-basics/references/projectiles-and-aoe.md

@@ -0,0 +1,100 @@
+# Projectiles, AoE, and Pooling
+
+Extends the base projectile in SKILL.md. Pick the behavior you need; they compose.
+
+## Homing
+
+Steer the direction toward the nearest target each frame. Turn rate keeps it from
+being unavoidable.
+
+```gdscript
+@export var turn_rate: float = 4.0
+var target: Node2D
+
+func _physics_process(delta: float) -> void:
+	if is_instance_valid(target):
+		var desired := (target.global_position - global_position).normalized()
+		direction = direction.lerp(desired, turn_rate * delta).normalized()
+	position += direction * speed * delta
+	rotation = direction.angle()
+```
+
+Find the nearest target by querying a group: iterate
+`get_tree().get_nodes_in_group("enemies")` and keep the min `distance_to`. For
+hundreds of enemies, cache the list and refresh every few frames, not per bullet.
+
+## Piercing
+
+Do not free on first hit; count hits and track who was already hit.
+
+```gdscript
+@export var pierce: int = 3
+var _hit: Array = []
+
+func _on_hit(body: Node) -> void:
+	if body in _hit:
+		return
+	_hit.append(body)
+	_apply_damage(body)
+	pierce -= 1
+	if pierce <= 0:
+		queue_free()
+```
+
+## Area of effect (explosion)
+
+Spawn an Area with a large CollisionShape for one frame, damage everything
+overlapping, then free. Scale damage by distance for a shockwave feel.
+
+```gdscript
+func explode() -> void:
+	for body in $Blast.get_overlapping_bodies():
+		if body.has_node("Health"):
+			var t := 1.0 - global_position.distance_to(body.global_position) / radius
+			body.get_node("Health").take_damage(int(max_damage * maxf(t, 0.2)))
+	spawn_vfx()
+	queue_free()
+```
+
+Ground DOT (burning patch): an Area that ticks damage on a `Timer.timeout` to
+bodies currently inside it, for a lifetime, then frees.
+
+## Object pooling (many projectiles)
+
+Instancing and freeing hundreds of bullets per second stutters. Reuse a fixed pool.
+
+```gdscript
+extends Node2D   # BulletPool autoload or level node
+
+@export var bullet_scene: PackedScene
+@export var pool_size: int = 200
+var _pool: Array[Node2D] = []
+var _next: int = 0
+
+func _ready() -> void:
+	for i in pool_size:
+		var b := bullet_scene.instantiate()
+		b.set_process(false)
+		b.hide()
+		add_child(b)
+		_pool.append(b)
+
+func fire(pos: Vector2, dir: Vector2) -> void:
+	var b := _pool[_next]
+	_next = (_next + 1) % pool_size
+	b.global_position = pos
+	b.direction = dir
+	b.set_process(true)
+	b.show()
+	# bullet hides + set_process(false) instead of queue_free on hit/lifetime
+```
+
+Deactivate (hide + `set_process(false)`) instead of freeing; the pool recycles the
+oldest. This is how survivors-style games sustain thousands of projectiles.
+
+## Traps
+
+- Homing with no turn cap = undodgeable and unfun. Cap `turn_rate`.
+- Pooled bullets that `queue_free()` defeat the pool - hide and disable instead.
+- AoE that reads overlaps in `_process` re-damages every frame; do it once.
+- Distance-scaled damage with no floor (`maxf(t, 0.2)`) makes edges deal 0.

package/library/skills/combat-basics/resource.yaml

@@ -0,0 +1,34 @@
+id: skill/combat-basics
+kind: skill
+version: 1.0.0
+summary: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+use_when:
+  - adding attacks, health and damage, or enemies that can be hit and hit back
+  - adding projectiles or bullets — homing, piercing, area-of-effect, or pooling hundreds of them
+  - wiring death and respawn, or debugging hits that never land or friendly fire
+do_not_use_when:
+  - auto-fire weapons that over-commit or overkill targets — that is the pending-damage pattern in auto-fire-targeting
+  - hits work but feel weak or floaty — tune the feedback layer with game-feel or debugging-game-feel
+facets:
+  lifecycle:
+    - build
+  domains:
+    - gameplay
+    - scripting
+    - game-design
+  modalities:
+    - scripts
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/make-game
+    - skill/character-movement
+    - skill/game-feel
+    - skill/auto-fire-targeting
+    - skill/design-npc
+source: official
+license: MIT
+status: preview
+recommended: false

package/library/skills/concept-art/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: concept-art
-description: Use when the user is exploring art direction — wants 3-4 rough variants of a character, environment, or prop to pick a vibe before committing to a final asset. Generates a batch of evocative concept images, not finals. Trigger on "concept art", "art direction", "explore the look", "give me some variants", "what could this character look like", "mood board", "rough sketches".
+description: "Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/create-asset-sheet/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: create-asset-sheet
-description: Use when the user wants to generate a pack of 2D game assets from a single prompt — a tile sheet, UI kit, menu screen, character pack, or biome set. The skill plans the prompt, generates a coherent sheet, removes the background, vision-detects each item, classifies it, and saves as a single pack ArtAsset. Trigger on "asset sheet", "asset pack", "tile sheet", "tileset", "UI kit", "asset pack for", "make me a sheet of", "generate a bunch of <category> assets".
+description: "Generate a pack of 2D game assets from one prompt — tile sheet, UI kit, character pack, or biome set — sliced, classified, and saved as one pack ArtAsset."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 2d-assets

package/library/skills/debug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug
-description: Use when the user reports a bug, crash, error, or unexpected behavior in a Summer project, before making code or scene changes. Runs a disciplined script-errors, console, debugger, hypothesis, fix, and verify loop. Trigger on "debug", "crash", "error", "broken", "not working", "freezes", "wrong".
+description: "Disciplined bug/crash/error loop for Summer projects — script errors, console, debugger, hypothesis, fix, verify — before making code or scene changes."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: debugging

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

@@ -1,6 +1,6 @@
 ---
 name: debugging-game-feel
-description: Use when a gameplay feature works correctly but feels wrong — floaty jumps, mushy combat, sluggish camera, weightless impacts. Different from logical bug debugging; the bug is subjective and lives in tuning, timing, and feedback layers.
+description: "Debug features that work but feel wrong — floaty jumps, mushy combat, sluggish camera — subjective bugs living in tuning, timing, and feedback layers."
 ---
 
 # Debugging Game Feel

package/library/skills/design-level/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-level
-description: Use when designing a single level — layout, pacing, encounters, secrets, reward gating. Outputs a level design doc and a concrete node-tree skeleton for `summer_create_scene`. Trigger on "design a level", "design level 1", "tutorial level", "boss arena", "design the encounter", "make a level layout".
+description: "Design a single level — layout, pacing, encounters, secrets, reward gating — outputs a level design doc and a node-tree skeleton for summer_create_scene."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: level-design

package/library/skills/design-mechanic/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-mechanic
-description: Use when designing one specific game mechanic in detail — input, response, feedback, failure modes, depth, tunables. Outputs a design doc and a scaffolding-ready node-graph sketch + GDScript stub. Trigger on "design a mechanic", "how should X work", "design the parry", "design the dash", "design the inventory", "the loop is broken".
+description: "Design one game mechanic in detail — input, response, feedback, failure modes, depth, tunables — outputs a design doc, node-graph sketch, GDScript stub."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: gameplay-mechanics

package/library/skills/design-npc/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design-npc
-description: Use when the user wants to design an enemy, NPC, boss, companion, civilian, or wave-spawned mob's behavior. Walks perception, personality knobs, intent layer, action state machine, telegraphs, defeat handling, and group emergence — outputs a state-machine GDScript stub plus the recommended node tree. Trigger on "enemy", "NPC", "boss", "companion", "AI", "behavior", "mob", "perception", "design enemy".
+description: "Design enemy/NPC/boss/companion behavior — perception, personality, intent, action state machine, telegraphs — outputs a GDScript stub plus node tree."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ai-and-npcs

package/library/skills/diagnosing-perf-regressions/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: diagnosing-perf-regressions
-description: Use when frame rate, frame time, or load time has gotten worse since a known-good state — "it used to run at 60, now it's at 30." Focused on finding the cause of a regression, not general performance tuning.
+description: "Find why frame rate, frame time, or load time got worse since a known-good state — regression hunting, not general performance tuning."
 ---
 
 # Diagnosing Performance Regressions

package/library/skills/dispatching-parallel-agents/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: dispatching-parallel-agents
-description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies
+description: "Work 2+ independent tasks in parallel when they share no state and have no sequential dependencies."
 ---
 
 # Dispatching Parallel Agents

package/library/skills/driving-the-editor-ui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: driving-the-editor-ui
-description: Use when a task is an editor-workflow step a human would do with the mouse — open Project Settings or a dock, switch the 2D/3D/Script main screen, toggle a panel, clear a dialog that is blocking the editor, read what a dock shows — and when deciding whether a request is UI work or scene work. Drives the editor by NAME through summer_ui_actions, reads it as structure through summer_ui_tree, activates the long tail by path through summer_ui_activate, and treats summer_ui_screenshot as the pixels-last fallback. Preview — the ops ship with a follow-up engine build.
+description: "Drive the editor UI by name: invoke actions, clear blocking dialogs, switch the main screen, read a dock — and route scene work to the scene tools instead."
 ---
 
 # Driving the Editor UI

package/library/skills/environment-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: environment-kit
-description: Use when generating a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corner blocks that snap together to form a level. Multiple meshes that share a visual style. Trigger on "build a dungeon kit", "modular walls", "level kit", "tileset", "interior pieces", "snap-together pieces", "make a kit for the temple".
+description: "Generate a modular environment kit — wall pieces, floor tiles, pillars, doors, arches, corners — snap-together meshes sharing one visual style."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: 3d-assets

package/library/skills/export-and-ship/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: export-and-ship
-description: Use when the user wants to assess or prepare a Summer game export. Inventories the templates and targets actually available in the installed Summer Engine build, validates release assets and configuration, and produces only locally supported builds after approval. It does not publish, upload, host, or submit a game. Trigger on "export", "ship", "release", "build", "Steam", "itch", "HTML5", "iOS", "Android", "submit", "publish".
+description: "Assess and prepare a game export: inventory installed templates and targets, validate release assets and config, produce supported builds after approval."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: deployment

package/library/skills/fabricating-assets/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fabricating-assets
-description: Use when an asset needs Blender's mesh tooling rather than generation or a library download — a modular kit with exact dimensions and snapping, VFX meshes (shatter fragments, curve sweeps, LOD chains), or decimating/UV-unwrapping/baking a generated model — and you are about to write a bpy script for summer_fabricate_3d. Covers the route decision (fabricate vs generate vs import), the bpy rules that survive glTF export, the script -> import -> snapshot -> screenshot loop, every failure_reason and what to do about it, and the licensing shape (the user's own Blender, never bundled).
+description: "Fabricate meshes with a bpy script in the user's own Blender (summer_fabricate_3d) — kits with exact dimensions, VFX meshes, post-processing generated models."
 ---
 
 # Fabricating Assets

package/library/skills/facial-and-lipsync/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: facial-and-lipsync
-description: Use when the user has a voice-over (or wants one) and needs the character's mouth to actually move with the words — phoneme extraction from audio, mapping to viseme blendshapes, plus emotional facial expressions (smile, frown, surprise). Trigger on "lipsync", "lip sync", "talking head", "phonemes", "viseme", "facial animation", "blendshapes", "make him talk", "dialogue animation".
+description: "Make a character's mouth move with a voice-over — phoneme extraction from audio, viseme blendshape mapping, and emotional facial expressions."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation

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

@@ -1,6 +1,6 @@
 ---
 name: fps-controller
-description: Use when building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces — production-quality first-person controller with WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling. Trigger on "FPS", "first-person", "WASD", "character controller", "mouse look", "player movement", "jump".
+description: "Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: character-controllers
@@ -295,12 +295,14 @@ The skeleton doesn't change — only the `@export` defaults. That's the point of
 
 ## Networking Note
 
-For multiplayer, two viable patterns:
-
-1. **Server-authoritative (the open-source-friendly path):** gate physics with `if not multiplayer.is_server(): return` for non-local players, sync `global_position` + `velocity` via `MultiplayerSynchronizer`, send input via RPC. This skeleton is compatible — wrap the `_physics_process` body in a `is_local_player` check and add a separate `apply_remote_player_physics` that interpolates from network snapshots.
-2. **Custom action protocol (the shipped-game path):** the same skeleton runs on every client; one peer is "host" and broadcasts authoritative state at a fixed interval. Out of scope for this skill — see the multiplayer-and-networking category.
-
-The external-velocity accumulator pattern is a multiplayer-correctness gift either way: explosions and knockbacks happen on the host, the impulse is RPC'd to the affected player, and the client's controller absorbs it without fighting local input. That's why the subtract-previous-contribution trick at the top of `_physics_process` exists — it is the single fix that prevents knockback drift in netcode.
+In a Summer multiplayer game this controller stays on the player's own
+client: it moves the local body, and the client publishes the resulting pose
+for the authority to check (`multiplayer-movement`). Other players' bodies
+are drawn from their published poses, never simulated locally. Never sync it
+with `@rpc` or `MultiplayerSynchronizer`. Knockback, explosions and jump pads
+that the authority decides arrive as an authority `reset()` of the pose, or
+as State the owner applies to `external_velocity`; the external-velocity
+accumulator above absorbs them without fighting input.
 
 ## Beyond This Skeleton
 

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

@@ -1,6 +1,6 @@
 id: skill/fps-controller
 kind: skill
-version: 1.0.3
+version: 1.0.4
 summary: Production-quality first-person controller — WASD, mouse look, jump, coyote time, jump buffering, air control, and external-velocity handling.
 use_when:
   - building an FPS, first-person movement, or a 3D character that walks, jumps, and reacts to external forces
@@ -17,6 +17,9 @@ facets:
 compatibility:
   engine: ">=4.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:

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

@@ -1,6 +1,6 @@
 ---
 name: game-feel
-description: Use when a Summer game "feels flat", "lacks impact", "needs juice", or "needs punch", or the user asks for hit feedback, screen shake, camera shake, audio ducking, or general game feel. Walks through Summer Engine's hit-flash, trauma camera shake, and audio-ducking stack, wired so one hit fires all three. Trigger on "vfx", "juice", "punch", "feels flat", "game feel", "hit flash", "screen shake", "camera shake", "ducking".
+description: "Add juice: hit-flash, trauma-based camera shake, and audio ducking wired so one hit fires all three — for games that feel flat or lack impact."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: visual-effects

package/library/skills/gameskill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gameskill
-description: Use when finishing a game-development session and you want to capture what you just learned as a reusable skill so the next session starts smarter. Trigger on "gameskill", "/gameskill", "capture learnings", "save to skills".
+description: "Capture what a game-dev session just learned as a reusable skill (project, user or Summer library) so the next session starts smarter."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: workflow

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

@@ -1,6 +1,6 @@
 ---
 name: gdscript-patterns
-description: Use when writing or refactoring GDScript — type hints, signals, exports, onready, lifecycle methods (`_ready` vs `_process` vs `_physics_process`), `get_node` vs `$NodePath`, naming conventions. Trigger on "GDScript", "script", "signals", "exports", "onready", "_ready", "_process".
+description: "GDScript conventions — type hints, signals, exports, onready, lifecycle methods, get_node vs $NodePath, naming."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scripting-patterns

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

@@ -1,6 +1,6 @@
 ---
 name: generate-motion
-description: Use when the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library. Picks the right curated motion, attaches the resulting clip to an AnimationPlayer. Trigger on "animation", "animate", "idle", "walk", "run", "attack animation", "motion", "mocap", "dance", "death animation".
+description: "Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: animation
@@ -15,10 +15,10 @@ Picks a clip from a **curated mocap library** by name and wires it onto a Meshy-
 
 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.
 
-> **Custom prompt-driven motion** (e.g. "drops to one knee, draws bow") is on
-> the roadmap but not shipped yet. For one-off signature moves not on the
-> curated list, fall back to hand-authoring in Summer Engine or importing from
-> Mixamo. See the Edge cases section.
+> **Custom or non-humanoid motion** (e.g. "drops to one knee, draws bow", a
+> nodding flower, a creature) goes to the `text-to-motion` skill
+> (`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
 
@@ -50,7 +50,7 @@ After animation jobs complete, import the rig plus child animation assets togeth
 - The user wants facial / lipsync animation — that's `facial-and-lipsync`.
 - The mesh isn't rigged. Rig first; never call `summer_generate_motion` on a static `.glb`.
 - The user wants procedural look-at, IK, foot placement — that's `procedural-animation`.
-- The user described a **custom signature move** that isn't on the curated list. Today, route to the manual-authoring fallback below.
+- The user described a **custom signature move** that isn't on the curated list — use `text-to-motion`; if the server answers `backend_unavailable`, use the manual-authoring fallback below.
 
 ## Steps
 
@@ -71,7 +71,7 @@ The result must include `rigAssetId: <id>` on a Meshy rig. If it shows `rigAsset
 ```
 summer_generate_motion(
   rigAssetId: "<id>",
-  backend: "meshy-library",   // only option today
+  backend: "meshy-library",   // curated library (default)
   motionName: "run"           // exact name from the curated list — see Reference card
 )
 ```
@@ -154,11 +154,11 @@ have actually seen, or route to the manual-authoring fallback.
 ## Edge cases
 
 - **Custom signature move** (e.g. "drops to one knee, draws bow"). The custom
-  prompt-driven backend is on the roadmap but not shipped today. Workarounds:
+  prompt-driven route is `text-to-motion`. If it is unavailable, workarounds:
   hand-author the clip in Summer Engine's animation panel, import a licensed
   clip as an `AnimationLibrary`, or compose curated clips in an
   `AnimationTree` OneShot blend.
-- **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds, hand-author or import a Mixamo-style external library (out of scope for this skill).
+- **Quadruped rig.** Meshy library is humanoid-only. For quadrupeds and other non-humanoid rigs use `text-to-motion`, or hand-author / import an external library.
 - **Character is < 1m tall (child / dwarf).** Library clips assume a ~1.8m humanoid. Apply the clip; the proportions retarget but stride length looks long. Either accept it or tune `playback_speed` on the AnimationPlayer track.
 - **Character has wings / tail.** The library ignores the extra bones — they sag. Hand-author additive overlays for the extra bones, or accept the visual hit.
 

package/library/skills/generate-motion/resource.yaml

@@ -1,6 +1,6 @@
 id: skill/generate-motion
 kind: skill
-version: 1.0.3
+version: 1.0.4
 summary: Attach an animation clip to a rigged character from the curated Meshy motion library — idle, walk, run, attack — wired via AnimationPlayer.
 use_when:
   - the user needs an animation clip on a rigged character — idle/walk/run/attack from the curated Meshy library
@@ -24,6 +24,7 @@ related:
     - skill/facial-and-lipsync
     - skill/procedural-animation
     - skill/retarget
+    - skill/text-to-motion
     - skill/asset-strategy
     - skill/fps-controller
 source: official

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

@@ -1,6 +1,6 @@
 ---
 name: godogen-visual-proof-game-generation
-description: "Use when adopting Godogen's thin-runtime autonomous game generation and its 'proof over claims' visual QC loop for SummerEngine: capture frames from the running engine, let the host agent self-verify against the brief, and drive bounded fix iterations until a proof recording closes the run."
+description: "Godogen-style game generation with a visual QC loop — capture frames from the running game, self-verify against the brief, bounded fix rounds, proof clip."
 license: MIT
 category: workflow
 tags:

package/library/skills/headless-scripting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: headless-scripting
-description: Use when a Summer project needs an operation no MCP tool exposes, such as baking a navmesh, generating collision shapes, authoring an Animation, building a TileSet, re-importing assets after file changes, or preparing a supported local export. Runs a GDScript file against Summer Engine from the shell. Also use when a plan involves "run it headless and screenshot it", which does not work and this skill explains why.
+description: "Run a GDScript file against Summer Engine from the shell for operations no MCP tool exposes — navmesh baking, collision shapes, TileSets, re-imports."
 ---
 
 # Headless Scripting