summer-engine 2.8.2 → 3.1.0

package/library/skills/character-animation-wiring/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: character-animation-wiring
+description: Use when a rigged, animated character is in the scene (Meshy rig + generated clips, or an imported GLB) and needs to be wired end to end — inspect the clips and bones that actually arrived, build idle/walk/run locomotion with blend times, method-track footsteps and attack frames, still poses and head tracking, blend-shape facial keys, root motion. Trigger on "wire the character", "hook up the animations", "make it walk around", "the GLB has animations", "footstep events", "attack frame", "root motion", "character slides while walking".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: animation
+user-invocable: false
+allowed-tools: Read Grep Edit Write summer_run_script summer_api_docs summer_get_scene_tree summer_inspect_node summer_world_snapshot summer_snapshot_diff summer_screenshot summer_play summer_stop summer_get_runtime_tree summer_inspect_runtime_node summer_save_scene summer_get_script_errors
+paths: ["**/*.gd", "**/*.tscn", "**/*.glb"]
+---
+
+# Character Animation Wiring — Rigged GLB to Living Character
+
+The game-critical path: a rigged, animated character lands in the scene — from `summer_generate_3d({options:{rig:true}})` + `summer_generate_motion`, or an imported GLB — and nothing moves yet. This skill wires it end to end: inspect what actually arrived, build locomotion, fire gameplay events off animation frames, add poses and head tracking, key the face, and handle root motion. Then **prove it in a playtest** — a wired tree that was never played is a claim, not a result.
+
+Two lanes throughout:
+
+- **ctx lane (animation-tier engines):** the animation ctx helpers on `summer_run_script` — `anim_state_machine`, `animate_method`, `bone_pose`, `look_at_modifier`, plus the `animate()` v2 extensions. One script per step, owner handled, failures come back as report entries.
+- **raw lane (any engine):** the same wiring through plain GDScript in `summer_run_script` — the Animation/AnimationTree classes are fully script-bound, just verbose. On an older engine a missing ctx helper is a plain `Invalid call to method ...` script error; fall back to the raw lane, which works everywhere.
+
+Frozen animation-tier signatures (see `scene-scripting` for the full stdlib):
+
+```gdscript
+anim_state_machine(target: Node, spec: Dictionary, player: AnimationPlayer = null) -> AnimationTree
+    # spec: { states: {name: clip_name}, transitions: [[from, to, {auto?: bool,
+    #   blend_s?: float}], ...], start: name }
+animate_method(node: Node, calls: Array, anim_name: String = "",
+               loop: bool = false, player: AnimationPlayer = null) -> AnimationPlayer
+    # calls: [[time_s, method_name, args_array], ...] -> one method-call track
+bone_pose(skeleton: Node, bone: String, pose: Dictionary) -> bool
+    # pose keys position/rotation/scale; unknown bone -> false + report listing bone names
+look_at_modifier(node: Node, target: Node, props: Dictionary = {}) -> Node
+    # LookAtModifier3D under the skeleton/node, owned
+animate(...) v2: keys entries also accept {time, value, interpolation: "nearest"|"linear"|"cubic"};
+    # property may target bones ("<skeleton_node>:<bone_name>/position|rotation|scale")
+    # and blend shapes ("blend_shapes/<name>")
+```
+
+## When to use this skill
+
+- A rigged GLB with clips is instanced and the character T-poses or slides.
+- "Make the goblin idle, walk when moving, run when sprinting."
+- Footstep sounds / attack hit-frames need to fire at exact animation times.
+- A corpse/statue/mannequin needs a still pose; an NPC head should track the player.
+- The character visibly moonwalks — the clip translates the root but the body stays put (root motion).
+
+## When NOT to use this skill
+
+- No clips yet — generate first via `generate-motion` (rigged Meshy target) or import them.
+- Continuous walk↔run blending by speed, upper-body attack overlays, OneShot hit reactions — that graph design lives in `animation-tree`; this skill's state machine is the discrete idle/walk/run backbone.
+- Foot IK, additive lean, ragdoll — `procedural-animation`.
+- Full viseme lipsync from audio — `facial-and-lipsync` (this skill covers the blend-shape keying mechanism it builds on).
+
+## Step 1 — Inspect what actually came in
+
+Never wire against assumed clip names or bone names. Imports differ: the AnimationPlayer may be nested inside the instance, clips may be namespaced (`walk` vs `Walking_Woman` vs `mixamo_com`), bone names vary by rig source. The instance's internals are not owned by the edited scene, so pass `owned: false` when searching:
+
+```gdscript
+func run(ctx):
+    var character = ctx.find("Goblin")
+    if character == null:
+        ctx.report("error", "Goblin not found — check summer_get_scene_tree")
+        return
+    for p in character.find_children("*", "AnimationPlayer", true, false):
+        ctx.report("player:" + str(character.get_path_to(p)), p.get_animation_list())
+    for s in character.find_children("*", "Skeleton3D", true, false):
+        var bones := []
+        for i in s.get_bone_count():
+            bones.append(s.get_bone_name(i))
+        ctx.report("skeleton:" + str(character.get_path_to(s)), bones)
+    for m in character.find_children("*", "MeshInstance3D", true, false):
+        if m.mesh and m.mesh.get_blend_shape_count() > 0:
+            var shapes := []
+            for i in m.mesh.get_blend_shape_count():
+                shapes.append(m.mesh.get_blend_shape_name(i))
+            ctx.report("blend_shapes:" + str(character.get_path_to(m)), shapes)
+```
+
+Read the reports. Every later step quotes these exact strings. If the clip list is empty, the GLB imported without animations (or they landed as a separate AnimationLibrary asset) — route back to `generate-motion` / `retarget` before wiring anything.
+
+## Step 2 — Locomotion state machine (ctx lane)
+
+`ctx.anim_state_machine` gets-or-creates the AnimationTree, wires it to the found (or given) AnimationPlayer, builds the AnimationNodeStateMachine, and sets `active = true`:
+
+```gdscript
+func run(ctx):
+    var character = ctx.find("Goblin")
+    var tree := ctx.anim_state_machine(character, {
+        "states": {"idle": "idle", "walk": "walk", "run": "run"},
+        "transitions": [
+            ["idle", "walk", {"blend_s": 0.2}],
+            ["walk", "idle", {"blend_s": 0.2}],
+            ["walk", "run",  {"blend_s": 0.15}],
+            ["run",  "walk", {"blend_s": 0.15}],
+        ],
+        "start": "idle",
+    })
+    if tree == null:
+        return          # the report names the failure — read it
+    ctx.report("tree", str(tree.get_path()))
+```
+
+State names are yours; **clip names must be the exact strings from Step 1**. An unknown clip name produces a report entry listing the player's actual clips — never silent. Fix the spelling from that list; do not guess again.
+
+Drive it from the controller script (host-edits the `.gd`):
+
+```gdscript
+@onready var tree: AnimationTree = $AnimationTree
+@onready var sm: AnimationNodeStateMachinePlayback = tree["parameters/playback"]
+
+func _physics_process(_delta: float) -> void:
+    var speed := Vector2(velocity.x, velocity.z).length()
+    if speed < 0.1: sm.travel("idle")
+    elif speed < 4.0: sm.travel("walk")
+    else: sm.travel("run")
+```
+
+Thresholded `travel()` is the discrete backbone. When the user wants a continuous speed blend or attack/hit overlays, extend the tree per `animation-tree` — those node types are beyond the `anim_state_machine` spec dict.
+
+## Step 3 — Method tracks: footsteps and attack frames
+
+Gameplay events that must land on an animation frame (footstep audio at heel-strike, damage at the blade's contact frame) belong in a method-call track, not a timer:
+
+```gdscript
+func run(ctx):
+    var character = ctx.find("Goblin")
+    ctx.animate_method(character, [
+        [0.32, "play_footstep", []],
+        [0.84, "play_footstep", []],
+    ], "walk_events", true)          # loop matches the walk clip's loop
+    ctx.animate_method(character, [
+        [0.45, "deal_attack_damage", [25]],
+    ], "attack_events")
+```
+
+The methods must exist on the target node's script — write them there first and check with `summer_get_script_errors`. Play the event clip alongside its motion clip (same timings) from the same tree. **Method tracks fire during playback in the running game; a successful script result proves the track exists, not that the method fires** — verification is a playtest where the footstep actually sounds.
+
+## Step 4 — Still poses and head tracking
+
+A corpse over a railing, a statue mid-swing, a mannequin — edit-time poses, no clip needed:
+
+```gdscript
+func run(ctx):
+    var skel = ctx.find("Goblin").find_children("*", "Skeleton3D", true, false)[0]
+    if not ctx.bone_pose(skel, "RightArm", {"rotation": Quaternion(Vector3.FORWARD, 1.2)}):
+        return          # false -> the report lists the skeleton's real bone names (capped 64)
+    ctx.bone_pose(skel, "Head", {"rotation": Quaternion(Vector3.RIGHT, -0.4)})
+```
+
+Head tracking — one call creates the owned `LookAtModifier3D` under the skeleton:
+
+```gdscript
+    var mod := ctx.look_at_modifier(skel, ctx.find("Player"), {"bone_name": "Head"})
+```
+
+Unknown props land in `prop_warnings` — read them. Angle limits, influence fade-out by distance, and spine-chain distribution are the difference between alive and possessed: tune per `procedural-animation` (A1/A2).
+
+## Step 5 — Facial keys via blend shapes
+
+`animate()` accepts `"blend_shapes/<name>"` property paths (value tracks, weights 0..1) against the MeshInstance3D that owns the shapes — names come from Step 1's report:
+
+```gdscript
+func run(ctx):
+    var head = ctx.find("Goblin").find_children("*", "MeshInstance3D", true, false)[0]
+    ctx.animate(head, "blend_shapes/jawOpen", [
+        {"time": 0.0, "value": 0.0, "interpolation": "linear"},
+        {"time": 0.15, "value": 1.0},
+        {"time": 0.4, "value": 0.0},
+    ], "roar")
+    ctx.animate(head, "blend_shapes/browDown_L", [[0.0, 0.0], [0.2, 1.0]], "roar")  # same clip — track appended
+```
+
+That is the mechanism; a full audio-synced viseme timeline is `facial-and-lipsync`. Bone-track keyframes work the same way through `animate()` v2 — `ctx.animate(character, "Skeleton3D:Head/rotation", keys, "nod")` creates a proper bone rotation track (the helper owns the quaternion conversion; never hand-build quaternion tracks).
+
+## Step 6 — Root motion, honestly
+
+Meshy/mocap locomotion clips translate the root bone forward (Meshy `run` moves ~5m per cycle). Two valid setups — **pick one, never both**:
+
+1. **In-place movement (default):** code drives `velocity`, the clip should NOT translate the root. If the character lunges forward and snaps back every loop, the clip has baked root translation — strip it or switch to setup 2.
+2. **Root motion:** the clip drives movement. Requires, on the AnimationTree: `root_motion_track` set to the root bone's track path (e.g. `"Skeleton3D:Hips"` — the skeleton node path from Step 1, colon, the root bone name), then in `_physics_process` apply `tree.get_root_motion_position()` / `get_root_motion_rotation()` to the CharacterBody3D instead of input-driven velocity. A `RootMotionView` node visualizes the extracted motion in the editor (editor-only helper; it is invisible in the shipped game).
+
+Symptoms map: sliding feet = setup 1 with speed thresholds mismatched to the clip's stride; lunge-and-snap = baked root translation under setup 1; character animates but never moves = setup 2 without the `get_root_motion_*` application code.
+
+Root motion CANNOT be judged from the editor state. Playtest it: `summer_play`, then `summer_get_runtime_tree` + `summer_inspect_runtime_node` on the character — its live `global_position` must advance while walking — plus `summer_screenshot target:"game"` for the pixels. Claim only what those reads show.
+
+## Raw lane — the same wiring on older engines
+
+Every class above is script-bound; `ctx.anim_state_machine` is convenience, not capability. The raw locomotion wiring, verbatim the calls that matter:
+
+```gdscript
+func run(ctx):
+    var character = ctx.get_scene_root().find_child("Goblin", true, false)
+    var player: AnimationPlayer = character.find_children("*", "AnimationPlayer", true, false)[0]
+
+    var sm := AnimationNodeStateMachine.new()
+    for clip in ["idle", "walk", "run"]:          # exact names from Step 1
+        var anim_node := AnimationNodeAnimation.new()
+        anim_node.animation = clip
+        sm.add_node(clip, anim_node)
+    for pair in [["idle", "walk", 0.2], ["walk", "idle", 0.2], ["walk", "run", 0.15], ["run", "walk", 0.15]]:
+        var t := AnimationNodeStateMachineTransition.new()   # one resource PER transition
+        t.xfade_time = pair[2]
+        sm.add_transition(pair[0], pair[1], t)
+
+    var tree := AnimationTree.new()
+    tree.name = "AnimationTree"
+    character.add_child(tree)
+    ctx.set_owner_recursive(tree)                 # BEFORE save, or it vanishes
+    tree.anim_player = tree.get_path_to(player)   # relative NodePath
+    tree.tree_root = sm
+    tree.active = true
+    ctx.report("tree", str(tree.get_path()))
+```
+
+Method tracks raw: `anim.add_track(Animation.TYPE_METHOD)` + `track_set_path(idx, path_to_node)` + `track_insert_key(idx, t, {"method": "play_footstep", "args": []})`, then `player.get_animation_library("").add_animation(name, anim)` (get-or-create the library — `add_animation_library("", AnimationLibrary.new())` when missing; this library step is the one agents get wrong). Still poses raw: `skel.set_bone_pose_rotation(skel.find_bone("Head"), quat)`. Verify unfamiliar members with `summer_api_docs` first — never guess.
+
+## The verification loop (every step)
+
+1. `summer_world_snapshot` before; keep the `snapshot_id`.
+2. Run the script; read `errors`, `reports`, `prop_warnings`, `rolled_back`.
+3. `summer_snapshot_diff from_id:<id>` — exactly the nodes you meant (AnimationTree added, nothing vanished).
+4. `summer_save_scene`, then behavior: `summer_play` → `summer_get_runtime_tree` / `summer_inspect_runtime_node` for live state, `summer_screenshot target:"game"` for pixels → `summer_stop`.
+5. Claim only what the capture and the runtime reads show. "The script succeeded" is not "the character walks." Full discipline: `verifying-scenes`.
+
+## Red Flags — STOP
+
+| Red flag | Reality |
+|---|---|
+| Wiring clip names you never read from the engine | Step 1 exists because imports rename things. Inspect, then quote. |
+| `find_children(...)` returns nothing inside the instance | You left `owned` at its default `true`. Instance internals are unowned — pass `false`. |
+| Retrying `anim_state_machine` with another guessed clip name | The failure report lists the player's actual clips. Use one of those. |
+| Timer-based footsteps/damage synced "by eye" | Method tracks are frame-accurate and survive clip retimes. |
+| `set_bone_pose_*` every frame from `_process` for tracking | That fights the tree. Runtime tracking is `look_at_modifier` / modifiers; `bone_pose` is for edit-time stills. |
+| Root motion AND input velocity applied together | Double movement. Pick one lane (Step 6). |
+| Raw lane: `add_child` without `ctx.set_owner_recursive(tree)` | The saved scene silently loses the AnimationTree. |
+| "Locomotion works" without a playtest | Run it. Read the runtime tree. Look at the frame. Silence is not evidence. |
+
+## Handoff
+
+- Blend spaces, OneShot attacks/hit-reacts, upper-body filters — `animation-tree`.
+- Foot IK, additive lean, ragdoll — `procedural-animation`.
+- Audio-synced lipsync on the blend shapes — `facial-and-lipsync`.
+- Clips missing or on the wrong rig — `generate-motion`, `retarget`.
+- NPC behavior deciding when to travel/fire states — `design-npc`.
+
+## See also
+
+- `scene-scripting` — the ctx stdlib contract, owner rules, budgets, undo/rollback.
+- `verifying-scenes` — snapshot/diff/screenshot/runtime-read discipline this skill leans on.

package/library/skills/character-animation-wiring/resource.yaml

@@ -0,0 +1,39 @@
+id: skill/character-animation-wiring
+kind: skill
+version: 1.0.1
+summary: Wire a rigged, animated character end to end — inspect real clips and bones, locomotion state machine, method-track events, poses, blend shapes, root motion.
+use_when:
+  - a rigged GLB or Meshy rig with generated clips is in the scene and needs idle/walk/run wiring with blend times
+  - footstep or attack-frame events, head tracking, still poses, blend-shape facial keys, or root motion must be hooked up
+  - the user says the character slides while walking, or the GLB has animations but nothing plays
+facets:
+  lifecycle:
+    - build
+  domains:
+    - animation
+    - 3d
+  modalities:
+    - animation
+    - scenes
+    - scripts
+compatibility:
+  engine: ">=4.6"
+related:
+  tools:
+    - tool/run-script
+    - tool/api-docs
+  skills:
+    - skill/animation-tree
+    - skill/generate-motion
+    - skill/retarget
+    - skill/procedural-animation
+    - skill/facial-and-lipsync
+    - skill/design-npc
+    - skill/scene-scripting
+    - skill/verifying-scenes
+source: official
+license: MIT
+status: stable
+recommended: false
+aliases:
+  - skills/animation/character-animation-wiring

package/{skills/3d-assets → library/skills}/character-model/SKILL.md

@@ -11,7 +11,7 @@ paths: ["assets/characters/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
 
 # Character Model — T-Pose to Rigged Humanoid, Gated
 
-This is the **canonical Meshy auto-rig pipeline**. It produces a humanoid `.glb` with a Meshy-compatible skeleton that `summer:animation/generate-motion` can drive directly. The work is split into two paid passes with a **mandatory user-review gate between them** — the rig pass is more expensive and locks the topology, so the user must see the un-rigged preview and approve before you spend on the rig.
+This is the **canonical Meshy auto-rig pipeline**. It produces a humanoid `.glb` with a Meshy-compatible skeleton that `generate-motion` can drive directly. The work is split into two paid passes with a **mandatory user-review gate between them** — the rig pass is more expensive and locks the topology, so the user must see the un-rigged preview and approve before you spend on the rig.
 
 The whole flow:
 
@@ -21,10 +21,10 @@ The whole flow:
 3. ── USER REVIEW GATE ──
 4. Rigged .glb               →  summer_generate_3d(image-to-3d, rig=true)      (~$1.00, ~90s)
 5. Import → editor RESTART → wire as CharacterBody3D / Node3D
-6. Hand off to summer:animation/generate-motion for clips
+6. Hand off to generate-motion for clips
 ```
 
-The animation skill (`summer:animation/generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
+The animation skill (`generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
 
 ## Web Chat / Public Orchestrator Equivalent
 
@@ -46,11 +46,11 @@ Use Studio only when the user explicitly asks for visual/manual picking or when
 
 ## When NOT to use
 
-- Static statue / mannequin display piece (no rig needed) → `summer:3d-assets/prop-model`.
-- Vehicle with a "driver" silhouette but no skeleton needed → `summer:3d-assets/vehicle-model`.
+- Static statue / mannequin display piece (no rig needed) → `prop-model`.
+- Vehicle with a "driver" silhouette but no skeleton needed → `vehicle-model`.
 - Quadruped (wolf, horse, dragon) → Meshy auto-rig is humanoid-only. Generate the mesh here for visuals, but skip the rig step — animation will need a hand-authored skeleton or a quadruped-specific provider (out of scope for this skill).
 - The user already has a rigged character and just wants a re-skin — that's a retexture pass, not this skill.
-- Facial blendshapes / lipsync rig → `summer:animation/facial-and-lipsync`.
+- Facial blendshapes / lipsync rig → `facial-and-lipsync`.
 
 ## Polycount targets
 
@@ -115,13 +115,13 @@ summer_import_asset_by_id(
 )
 ```
 
-### 3. ⛔ USER REVIEW GATE — DO NOT SKIP
+### 3. STOP: USER REVIEW GATE — DO NOT SKIP
 
 Before paying for the rig pass, surface the un-rigged mesh:
 
 > Un-rigged knight mesh ready: `res://assets/characters/knight_unrigged.glb` (~12k tris, [preview link]).
 >
-> Next step is the **rig pass** (~$1.00, ~90s, Meshy auto-rig). It locks the topology and adds a skeleton compatible with `summer:animation/generate-motion`. Once you approve I'll run it.
+> Next step is the **rig pass** (~$1.00, ~90s, Meshy auto-rig). It locks the topology and adds a skeleton compatible with `generate-motion`. Once you approve I'll run it.
 >
 > **Approve the mesh and proceed to rig?** Or regenerate the mesh first (different prompt, different polycount, different model)?
 
@@ -142,7 +142,7 @@ summer_generate_3d({
 
 Returns a job whose result includes `assetId`, `fileUrl`, and `rigAssetId`.
 If you ran with `wait: false`, poll via `summer_check_job(jobId)`. The
-`rigAssetId` is the handle `summer:animation/generate-motion` needs — store it.
+`rigAssetId` is the handle `generate-motion` needs — store it.
 Resolve it before import so the agent has the viewer/download metadata:
 
 Import the rigged version, replacing the un-rigged file:
@@ -155,7 +155,7 @@ summer_import_asset_by_id(
 )
 ```
 
-### 5. ⚠️ Restart the editor
+### 5. WARNING: Restart the editor
 
 **Known gotcha:** after importing a rigged `.glb`, the `Skeleton3D` node appears stale in the scene dock — bones are missing, `skeleton.get_bone_count()` returns 0, and `AnimationPlayer` libraries fail to bind. The fix:
 
@@ -170,7 +170,7 @@ No programmatic workaround is known. Tell the user, wait, then continue.
 | Player or enemy that moves with code, collides with walls, jumps | `CharacterBody3D` | `move_and_slide()` API, kinematic physics, slope handling |
 | Cinematic NPC (talks, idles, never moves under physics) | `Node3D` | No physics overhead; cheaper for crowds |
 | Pure-visual character (background extra, dialogue head) | `Node3D` | Same as above |
-| Ragdoll-on-death enemy | `CharacterBody3D` while alive, swap to `RigidBody3D` skeleton on death | Two-mode rig; see `summer:animation/procedural-animation` |
+| Ragdoll-on-death enemy | `CharacterBody3D` while alive, swap to `RigidBody3D` skeleton on death | Two-mode rig; see `procedural-animation` |
 
 Four things the call shapes below encode:
 
@@ -207,7 +207,7 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 
 > Knight is wired at `./World/Knight` with a Meshy-rigged skeleton. `rigAssetId` saved.
 >
-> Next: `summer:animation/generate-motion` to add idle / walk / run / attack
+> Next: `generate-motion` to add idle / walk / run / attack
 > clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>",
 > backend: "meshy-library", motionName: "walk")`. Custom prompt-driven motion
 > is not shipped; hand-author one-off moves in Summer Engine or import a
@@ -225,10 +225,10 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 
 ## Edge cases
 
-- **Multiple characters share a silhouette.** Generate the rig once, then re-skin via texture swap (cheaper than re-rigging). See `summer:3d-assets/character-model` retexture flow (TBD) — for now, route to `summer:asset-pipeline/asset-strategy`.
+- **Multiple characters share a silhouette.** Generate the rig once, then re-skin via texture swap (cheaper than re-rigging). See `character-model` retexture flow (TBD) — for now, route to `asset-strategy`.
 - **Character has wings, tail, extra limbs.** Meshy's humanoid rig only weights the standard skeleton — extras sag. Either prompt them as static (e.g. cape held by physics in-engine) or hand-rig in Blender post-export.
-- **Child / dwarf / giant.** Generate at correct proportions in the T-pose; the rig retargets cleanly. Locomotion clips from `summer:animation/generate-motion` will retarget but stride length needs `playback_speed` tuning on the AnimationPlayer.
-- **First-person hands-only character.** Generate just hands + forearms in T-pose; rig pass still works. See `summer:character-controllers/fps-controller` for first-person wiring.
+- **Child / dwarf / giant.** Generate at correct proportions in the T-pose; the rig retargets cleanly. Locomotion clips from `generate-motion` will retarget but stride length needs `playback_speed` tuning on the AnimationPlayer.
+- **First-person hands-only character.** Generate just hands + forearms in T-pose; rig pass still works. See `fps-controller` for first-person wiring.
 - **Stylized non-human (goblin, orc, halfling).** Works fine as long as the silhouette is bipedal with two arms, two legs, one head. Quadrupeds and centaurs do not.
 
 ## Fallback (no MCP)
@@ -240,23 +240,23 @@ The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty l
 5. Restart the editor.
 6. Wire as CharacterBody3D / Node3D in Summer Engine manually.
 
-The output is identical to the MCP path — same Meshy skeleton, same compatibility with `summer:animation/generate-motion` (which has its own dashboard fallback).
+The output is identical to the MCP path — same Meshy skeleton, same compatibility with `generate-motion` (which has its own dashboard fallback).
 
 ## Handoff
 
 After the rigged character is wired:
 
 > `Knight` is at `./World/Knight` with a Meshy-rigged skeleton. Next:
-> - **Animations:** `summer:animation/generate-motion` for idle / walk / run / attack. Pass the `rigAssetId` returned in step 4.
-> - **State machine:** after a few clips exist, `summer:animation/animation-tree` for idle → walk → run blends.
-> - **Player input:** if this is the player, wire WASD + mouse via `summer:character-controllers/fps-controller` or a third-person controller skill.
-> - **NPC behavior:** if it's an NPC, `summer:ai-and-npcs/design-npc` for behavior trees and dialogue hooks.
+> - **Animations:** `generate-motion` for idle / walk / run / attack. Pass the `rigAssetId` returned in step 4.
+> - **State machine:** after a few clips exist, `animation-tree` for idle → walk → run blends.
+> - **Player input:** if this is the player, wire WASD + mouse via `fps-controller` or a third-person controller skill.
+> - **NPC behavior:** if it's an NPC, `design-npc` for behavior trees and dialogue hooks.
 > - **Re-skin variants** (palette swap, armor swap): retexture pass — generate new albedo, assign via material override. Avoid re-rigging.
 
 ## See also
 
-- `summer:animation/generate-motion` — the next-step animation skill that consumes the `rigAssetId` produced here.
-- `summer:asset-pipeline/asset-strategy` — meta-router; this skill is the canonical drill-down of its "Image-to-3D for characters" path.
-- `summer:3d-assets/prop-model` — for non-character props.
-- `summer:scene-composition` — for the CharacterBody3D + Mesh + Collider parent pattern.
-- `../../../references/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.
+- `generate-motion` — the next-step animation skill that consumes the `rigAssetId` produced here.
+- `asset-strategy` — meta-router; this skill is the canonical drill-down of its "Image-to-3D for characters" path.
+- `prop-model` — for non-character props.
+- `scene-composition` — for the CharacterBody3D + Mesh + Collider parent pattern.
+- `../../references/mcp-tools-reference/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.

package/library/skills/character-model/resource.yaml

@@ -0,0 +1,36 @@
+id: skill/character-model
+kind: skill
+version: 1.0.2
+summary: Generate a rigged humanoid — player, NPC, enemy, boss — via T-pose reference, user-gated preview, and Meshy auto-rig, wired as CharacterBody3D or Node3D.
+use_when:
+  - generating a humanoid character ready for animation — player avatar, NPC, enemy, boss, companion
+  - the user asks for a rigged humanoid or a model with a skeleton
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 3d
+    - assets
+  modalities:
+    - 3d-models
+    - scenes
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/prop-model
+    - skill/vehicle-model
+    - skill/design-npc
+    - skill/animation-tree
+    - skill/facial-and-lipsync
+    - skill/generate-motion
+    - skill/procedural-animation
+    - skill/asset-strategy
+    - skill/fps-controller
+    - skill/organic-model
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/3d-assets/character-model

package/{skills/2d-assets → library/skills}/character-portrait/SKILL.md

@@ -11,11 +11,11 @@ paths: ["assets/**", "art/portraits/**", "ui/portraits/**"]
 
 # character-portrait — Locked Bust for Dialogue UI
 
-This skill produces ONE polished character portrait — bust or shoulders-up framing, neutral or stylized background, designed to drop into a dialogue UI, character-select screen, or lore card. It is the **opposite** of `summer:2d-assets/concept-art`: concept art explores; this skill commits.
+This skill produces ONE polished character portrait — bust or shoulders-up framing, neutral or stylized background, designed to drop into a dialogue UI, character-select screen, or lore card. It is the **opposite** of `concept-art`: concept art explores; this skill commits.
 
 The single biggest failure mode is **inconsistency across a cast**. Generating five party members one at a time without a locked anchor produces five images that look like they're from five different games — different lighting, different angle, different palette, different rendering style. This skill makes you write a **locked anchor suffix** the first time and re-use it verbatim for every subsequent portrait.
 
-If the user is still exploring the look, this is the wrong skill — route to `summer:2d-assets/concept-art` first, lock a direction, then come back here. The `summer:asset-pipeline/asset-strategy` meta-router asks **"Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?"** to disambiguate.
+If the user is still exploring the look, this is the wrong skill — route to `concept-art` first, lock a direction, then come back here. The `asset-strategy` meta-router asks **"Quick check — exploring the look (3-4 variants for art direction) or generating a final character portrait for dialogue UI?"** to disambiguate.
 
 ## When to use
 
@@ -27,9 +27,9 @@ If the user is still exploring the look, this is the wrong skill — route to `s
 
 ## When NOT to use
 
-- The user is still exploring → `summer:2d-assets/concept-art`.
-- The user wants pixel art → `summer:2d-assets/pixel-art`.
-- The user wants a full-body 3D model → `summer:asset-pipeline/asset-strategy`.
+- The user is still exploring → `concept-art`.
+- The user wants pixel art → `pixel-art`.
+- The user wants a full-body 3D model → `asset-strategy`.
 - The user wants 4+ animated expressions of the same character — generate one base portrait here, then use img2img with the base as `referenceImageUrl` for each expression.
 
 ## Steps
@@ -163,7 +163,7 @@ summer_generate_image(
 - **No anchor file.** Every cast member generated ad-hoc looks unrelated. Define the anchor on portrait #1, re-use for the rest of the cast.
 - **Editing the anchor mid-cast.** If you change lighting from "warm key" to "dramatic side" halfway through, the cast splits visually. Either commit to the change and regenerate everyone, or stick with the anchor.
 - **Regenerating from scratch when img2img would do.** Identity drifts every regen. Iterate via `referenceImageUrl`.
-- **Using the portrait as a 3D reference.** Portraits have dramatic lighting, painterly backgrounds, and cropped framing — all of which corrupt 3D generation. For 3D, generate a separate clean white-bg full-body T-pose via `summer:asset-pipeline/asset-strategy`.
+- **Using the portrait as a 3D reference.** Portraits have dramatic lighting, painterly backgrounds, and cropped framing — all of which corrupt 3D generation. For 3D, generate a separate clean white-bg full-body T-pose via `asset-strategy`.
 - **Expecting `style` to carry the look.** Only `cartoon` and `anime` append anything; `realistic` and `none` append nothing and any other value is coerced to `none`. If the anchor names the style, `"none"` is correct — but the anchor text is doing all the work, not the preset.
 
 ## Edge cases
@@ -171,7 +171,7 @@ summer_generate_image(
 - **Character has a non-human silhouette (lizardfolk, demon, robot).** The anchor still applies — framing, lighting, background, rendering style. Only the subject description changes. Verify the model can hold the silhouette under "bust framing" — some models default to humanoid.
 - **Player wants to swap costumes mid-game.** Generate one base portrait per costume (`aria_traveler.png`, `aria_robes.png`, `aria_armored.png`) and switch by index. Use img2img from the base for consistency.
 - **Cast of 12+ characters.** Anchor discipline gets harder as fatigue sets in. Print the anchor as a header in your generation script and don't write any prompt without it.
-- **User wants the portrait to "read at small size" (32×32 in a portrait list).** That's pixel-art territory; route to `summer:2d-assets/pixel-art`.
+- **User wants the portrait to "read at small size" (32×32 in a portrait list).** That's pixel-art territory; route to `pixel-art`.
 
 ## Fallback (no MCP)
 
@@ -189,13 +189,13 @@ After the portrait is wired:
 
 - **More cast members** → re-invoke this skill with the same anchor. Don't redefine.
 - **Expression variants** → re-invoke with `referenceImageUrl` set to the base portrait.
-- **Pixel-art version of the same character** → `summer:2d-assets/pixel-art`.
-- **3D model of the same character** → `summer:asset-pipeline/asset-strategy` (the portrait is NOT a usable 3D reference; generate a separate T-pose).
-- **Dialogue system wiring** → `summer:scene-composition` for the UI hierarchy.
+- **Pixel-art version of the same character** → `pixel-art`.
+- **3D model of the same character** → `asset-strategy` (the portrait is NOT a usable 3D reference; generate a separate T-pose).
+- **Dialogue system wiring** → `scene-composition` for the UI hierarchy.
 
 ## See also
 
-- `summer:2d-assets/concept-art` — explore the look first if not yet locked.
-- `summer:asset-pipeline/asset-strategy` — meta-router and the 3D pipeline.
-- `summer:scene-composition` — wiring the portrait into a dialogue UI scene.
-- `../../../references/mcp-tools-reference.md` — `summer_generate_image` parameter schema.
+- `concept-art` — explore the look first if not yet locked.
+- `asset-strategy` — meta-router and the 3D pipeline.
+- `scene-composition` — wiring the portrait into a dialogue UI scene.
+- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` parameter schema.

package/library/skills/character-portrait/resource.yaml

@@ -0,0 +1,30 @@
+id: skill/character-portrait
+kind: skill
+version: 1.0.4
+summary: Generate a single polished character bust for dialogue UI, character select, lore cards, or codex entries. One character, locked composition, VN-style.
+use_when:
+  - generating a single polished bust/portrait of a character for dialogue UI, character-select screens, lore cards, or codex entries
+  - a dialogue box, party roster, or codex entry needs one consistent face for a named character
+facets:
+  lifecycle:
+    - build
+  domains:
+    - 2d
+    - assets
+  modalities:
+    - images
+    - assets
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/concept-art
+    - skill/pixel-art
+    - skill/asset-strategy
+    - skill/create-asset-sheet
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/2d-assets/character-portrait

package/{skills/video → library/skills}/cinematic-cutscene/SKILL.md

@@ -29,7 +29,7 @@ If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. I
 - "5-second slow-mo combat shot for the trailer" — `video/trailer-shot`.
 - "Looping splash screen background" — `video/animated-loop`.
 - "Animated logo backdrop on the title screen" — `video/animated-loop`.
-- Real-time in-engine cinematic with the actual gameplay characters and camera — that's a Godot AnimationPlayer / Timeline job, not generated video. Route to `summer:scene-composition`.
+- Real-time in-engine cinematic with the actual gameplay characters and camera — that's a Godot AnimationPlayer / Timeline job, not generated video. Route to `scene-composition`.
 - Voice-only narration over a static image — generate the dialogue with `summer_generate_audio` and use a static `TextureRect`, no video needed.
 
 ## Steps
@@ -237,4 +237,4 @@ Once the cutscene is generated and wired:
 - `audio/music-track` — score the cutscene.
 - `2d-assets/concept-art` — generate the reference image axis if no character reference exists yet.
 - `2d-assets/character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
-- `../../../references/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/library/skills/cinematic-cutscene/resource.yaml

@@ -0,0 +1,29 @@
+id: skill/cinematic-cutscene
+kind: skill
+version: 1.0.4
+summary: Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer.
+use_when:
+  - generating a non-interactive cutscene clip — opening scene, story beat, character intro, ending
+  - a story beat needs a short pre-rendered clip between gameplay sections — intro, transition, ending
+facets:
+  lifecycle:
+    - build
+  domains:
+    - video
+    - assets
+  modalities:
+    - video
+    - assets
+compatibility:
+  engine: ">=4.6"
+related:
+  skills:
+    - skill/character-portrait
+    - skill/concept-art
+    - skill/asset-strategy
+source: official
+license: MIT
+status: stable
+recommended: true
+aliases:
+  - skills/video/cinematic-cutscene