summer-engine 2.0.0 → 2.3.0

package/skills/2d-assets/ui-graphics/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: ui-graphics
+description: Use when generating UI elements — icons, buttons, panels, frames, HUD widgets, badges. Flat-design, transparent-background, game-UI style. Wires the result via TextureRect / NinePatchRect / AtlasTexture. Trigger on "UI icon", "button graphic", "HUD element", "panel frame", "menu background", "inventory slot", "ability icon", "badge".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 2d-assets
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_search_assets summer_import_from_url summer_set_resource_property summer_add_node summer_set_prop
+paths: ["assets/**", "ui/**", "art/ui/**"]
+---
+
+# ui-graphics — Icons, Buttons, Panels, HUD
+
+This skill generates flat, game-UI-style graphics: icons (skill / item / status), buttons (idle / hover / pressed states), panels and frames (NinePatch-friendly), HUD widgets (health frames, minimaps, badges). Output is **transparent PNG** by default and wires via Godot's `TextureRect`, `NinePatchRect`, or `AtlasTexture`.
+
+UI graphics succeed or fail on **two specific things**: a clean transparent background (no checkerboard residue) and a consistent visual language across the set (all icons share line weight, color treatment, lighting). This skill encodes both.
+
+## When to use
+
+- "Generate a fire-spell icon for the ability bar."
+- "I need a parchment panel background for the inventory."
+- "Make a set of 8 status-effect icons (poison, burn, freeze, stun, ...)."
+- "Create a button frame I can NinePatch."
+- "HUD frame for the health bar."
+
+## When NOT to use
+
+- The user wants a character portrait → `summer:2d-assets/character-portrait`.
+- The user wants pixel-art UI → `summer:2d-assets/pixel-art` (UI in pixel style needs a different prompt pattern).
+- The user wants a 3D HUD element → that's a 3D mesh job; route to `summer:asset-pipeline/asset-strategy`.
+- The user wants a font → fonts aren't generated; use a `.ttf`/`.otf` and import via `FontFile`.
+
+## Steps
+
+### 1. Lock the UI style anchor
+
+Check `.summer/ui-anchor.md`. If it doesn't exist, define it on the first UI asset and re-use:
+
+```
+## UI anchor
+
+style: flat design with subtle gradient, soft inner shadow
+line: 2px outline in deep navy (#1a2332)
+fill palette: gold (#d4a24c), parchment (#f5e6c4), dark teal accent (#2c5f5d)
+shape language: rounded rectangles, no sharp 90deg corners
+mood: warm fantasy, slightly weathered
+background: transparent PNG
+```
+
+Every icon / button / panel re-uses this anchor verbatim. Skipping this step produces the most common UI failure: 12 icons that all look like they came from 12 different games.
+
+### 2. Search before generating
+
+```
+summer_search_assets(query="<subject> icon", filter={ kind: "image" })
+```
+
+### 3. Pick the right pattern (icon vs button vs panel)
+
+| Asset class | Image size | Wiring node | Notes |
+|---|---|---|---|
+| Icon (ability, item, status) | `square_hd` | `TextureRect` (or `AtlasTexture` if part of an icon sheet) | Centered subject, generous padding |
+| Button (idle / hover / pressed) | `landscape_4_3` | `Button` with custom theme OR `TextureButton` | Generate 3 variants of the same shape |
+| Panel / frame (NinePatch-friendly) | `square_hd` | `NinePatchRect` | Border + center MUST be visually separable for 9-slicing |
+| HUD bar frame | `landscape_16_9` | `NinePatchRect` over `ProgressBar` | Frame only — bar fill is a separate gradient texture |
+| Badge / emblem | `square_hd` | `TextureRect` | Symmetric, centered, no text |
+
+### 4. Build the prompt — subject + anchor + transparent
+
+Pattern:
+
+```
+<asset class> of <subject>, game UI, <anchor style>, flat design, clean edges, transparent background, centered, isolated
+```
+
+`transparent background` and `isolated` are the load-bearing words. Without them, you get a square card with a textured background that defeats the purpose.
+
+### 5. Generate
+
+**Icon example:**
+```
+summer_generate_image(
+  prompt="ability icon for a fire spell, glowing flame in cupped hand, game UI, flat design with subtle gradient and soft inner shadow, 2px deep navy outline, gold and parchment palette, rounded square frame, transparent background, centered, isolated",
+  model="nano-banana-2",
+  style="none",
+  options={ image_size: "square_hd", negative_prompt: "photorealistic, 3D render, scene background, busy, multiple objects" }
+)
+```
+
+**Button (3 states in 3 calls):**
+```
+summer_generate_image(prompt="<subject>, idle state, ...")
+summer_generate_image(prompt="<subject>, hover state, slightly brighter glow, ...")
+summer_generate_image(prompt="<subject>, pressed state, darker, slight inset shadow, ...")
+```
+
+**Panel for NinePatch:**
+```
+summer_generate_image(
+  prompt="parchment scroll panel frame, ornate gold border, weathered tan center, clear distinction between border and center area, game UI, fantasy, transparent background, square format, centered",
+  ...
+)
+```
+
+The "clear distinction between border and center" is the NinePatch hint — without it, the border bleeds into the center and 9-slicing produces artifacts.
+
+### 6. Import with transparency preserved
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://ui/icons/fire_spell.png")
+```
+
+Verify in the import dock: `Mipmaps: off` (UI shouldn't mipmap), `Filter: Linear` for high-res UI (or `Nearest` if pixel-style).
+
+### 7. Wire into the scene
+
+**Icon as TextureRect:**
+```
+summer_add_node(parentPath="/root/UI/AbilityBar", type="TextureRect", name="FireSpellIcon")
+summer_set_prop(path="/root/UI/AbilityBar/FireSpellIcon", property="texture", value="res://ui/icons/fire_spell.png")
+summer_set_prop(path="/root/UI/AbilityBar/FireSpellIcon", property="expand_mode", value=1)  # KEEP_SIZE → 1 = STRETCH
+summer_set_prop(path="/root/UI/AbilityBar/FireSpellIcon", property="stretch_mode", value=5)  # KEEP_ASPECT_CENTERED
+```
+
+**Panel as NinePatchRect:**
+```
+summer_add_node(parentPath="/root/UI", type="NinePatchRect", name="InventoryPanel")
+summer_set_prop(path="/root/UI/InventoryPanel", property="texture", value="res://ui/panels/parchment.png")
+summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_left", value=24)
+summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_right", value=24)
+summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_top", value=24)
+summer_set_prop(path="/root/UI/InventoryPanel", property="patch_margin_bottom", value=24)
+```
+
+Tune patch margins to match the actual border width in the generated texture. Open the texture in the editor's NinePatch preview to verify.
+
+**Multiple icons as AtlasTexture:**
+
+If you generate a 4×4 grid of icons in one image, each icon becomes an `AtlasTexture` referencing the same source. Saves draw calls. Use a `Region` rect per icon.
+
+## Prompt patterns
+
+| Goal | Prompt that works | Why |
+|---|---|---|
+| Ability icon | `ability icon for <effect>, <visual metaphor>, game UI, flat design, 2px outline, <palette>, rounded square frame, transparent background, centered, isolated` | Visual metaphor (cupped hand, swirling vortex) reads better than abstract |
+| Item icon (potion) | `inventory icon of red health potion, glass bottle with red liquid, cork stopper, game UI, flat design, soft inner shadow, transparent background, centered, isolated, three-quarter view` | Three-quarter beats pure front for items |
+| Status icon (poison) | `status effect icon, green skull with dripping liquid, game UI, flat, bold silhouette readable at 32px, 2px outline, transparent background` | "Readable at 32px" forces bold silhouette |
+| Button frame | `wooden button frame, ornate corners, slight bevel, game UI fantasy, transparent background, no text, no icon inside, just the empty frame` | "No text, no icon" prevents the model adding fake labels |
+| NinePatch panel | `parchment panel frame, ornate gold border, weathered tan center, clear border-vs-center distinction, transparent background, square` | "Clear border-vs-center" enables 9-slicing |
+| Badge / rank emblem | `gold rank emblem, laurel wreath, central star, symmetric, game UI heraldry style, transparent background, centered` | Symmetry + centered is critical for emblems |
+| HUD health frame | `decorative frame for a horizontal health bar, ornate metal border, hollow center for the bar to show through, transparent background, landscape format` | "Hollow center" is the key for frame-over-bar |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `cool button` | No subject, no anchor. Returns a generic button on a card background. |
+| `transparent button with icon` (no negative prompt) | Model often renders a checkerboard "transparent" pattern as the actual fill. Add `no checkerboard pattern` to negative. |
+| `8 ability icons in one image` | Inconsistent style across the 8. Generate one at a time with the same anchor. |
+| `realistic 3D rendered button` | Conflicts with flat-UI. Stay flat. |
+| `button with the word "Play"` on it | Models render text badly. Add text in Godot via a `Label` over the button, not in the texture. |
+
+## Anti-patterns
+
+- **Skipping the anchor.** A 12-icon ability bar with no anchor looks like 12 unrelated games. Define the anchor on icon #1.
+- **Letting the model render text.** Diffusion models can't render reliable text. Always overlay text in Godot via a `Label` node. The button texture is the frame; the label is the word.
+- **Forgetting `transparent background` in the prompt.** Default is opaque. Without the keyword, you import an icon with a 200×200 white square around the actual icon.
+- **Using `style: "realistic"` for UI.** UI is flat. `style: "none"` lets the prompt's "flat design" land cleanly.
+- **NinePatch with no border-vs-center distinction.** The 9-slice scaling smears the border into the center.
+- **Mipmaps on UI.** UI textures shouldn't mipmap — they're displayed at 1:1 or near it. Mipmaps waste memory and blur sharp edges.
+
+## Edge cases
+
+- **User wants the same icon at multiple sizes (32, 64, 128).** Generate once at high res. Godot's `TextureRect` with `STRETCH_KEEP_ASPECT_CENTERED` scales it down cleanly. Don't generate three sizes.
+- **User wants pixel-style UI.** Route to `summer:2d-assets/pixel-art` — different prompt pattern, different filter, different anchor.
+- **User wants animated UI (spinning loading icon).** Generate the static frame here. Animate via `AnimationPlayer` rotating the `TextureRect`, not as a sprite sheet.
+- **Transparency comes back as a checkerboard pattern in the image.** The model rendered the checkerboard literally. Regenerate with `no checkerboard pattern, true alpha transparency` in the negative prompt.
+- **Icons need to read at very small size (16-24px in a packed bar).** Bias prompts toward bold silhouette + minimal interior detail. Ornate detail is invisible at 16px and adds noise.
+
+## Fallback (no MCP)
+
+Print the call:
+
+```
+summer_generate_image(
+  prompt="<asset + anchor + transparent>",
+  model="nano-banana-2",
+  style="none",
+  options={ image_size: "square_hd", negative_prompt: "scene background, photorealistic, 3D, busy" }
+)
+```
+
+User runs via the Summer dashboard, then `summer_import_from_url` to `res://ui/icons/<name>.png` and wires manually.
+
+## Handoff
+
+After the UI graphic is wired:
+
+- **More icons in the same set** → re-invoke this skill with the same anchor.
+- **Button states (hover/pressed)** → re-invoke for each state.
+- **Theme assembly (combining icons + panels into a Godot Theme resource)** → `summer:scene-composition` for the Theme resource wiring.
+- **Pixel-art UI** → `summer:2d-assets/pixel-art`.
+- **Dialogue UI with portraits** → `summer:2d-assets/character-portrait` for the portrait, then back here for the surrounding panel.
+
+## See also
+
+- `summer:2d-assets/character-portrait` — for in-UI character images.
+- `summer:2d-assets/pixel-art` — pixel-style UI.
+- `summer:scene-composition` — Theme and Control hierarchy.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/3d-assets/character-model/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: character-model
+description: Use when generating a humanoid character ready for animation — player avatar, NPC, enemy, boss, companion. Generates a T-pose reference image, gates an un-rigged preview past the user, then runs the Meshy auto-rig pass and wires the result as a CharacterBody3D (movement) or Node3D (cinematic). Trigger on "make a character", "generate the player", "I need an enemy model", "create an NPC", "rigged humanoid", "character with a skeleton", "model for animation".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_image summer_generate_3d summer_import_from_url summer_add_node summer_set_prop summer_set_resource_property summer_inspect_node summer_inspect_resource summer_get_scene_tree summer_save_scene summer_check_job summer_generate_motion
+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.
+
+The whole flow:
+
+```
+1. T-pose reference image    →  summer_generate_image                          (~$0.05, ~10s)
+2. Un-rigged 3D mesh         →  summer_generate_3d(image-to-3d)                (~$0.50, ~60s)
+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
+```
+
+The animation skill (`summer:animation/generate-motion`) requires a rigged humanoid; a static `.glb` won't drive motion.
+
+## When to use
+
+- "Make a knight character for the player to control."
+- "I need a goblin enemy."
+- "Generate an old wizard NPC for the tavern."
+- "Create a boss — a four-armed demon."
+- The user is about to ask for animations and has nothing rigged yet.
+
+## 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`.
+- 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`.
+
+## Polycount targets
+
+| Role | Tris | Pass via |
+|---|---|---|
+| Hero character (player, close camera) | 8k–15k | `target_polycount: 12000` |
+| Grunt enemy (mid-range, multiple onscreen) | 3k–6k | `target_polycount: 5000` |
+| Crowd / background NPC (LOD-able) | 1k–2k | `target_polycount: 1500` |
+| Mobile-game character | 1k–3k | `target_polycount: 2000` |
+| Cinematic hero (no realtime constraint) | 20k–40k | `target_polycount: 30000` |
+
+Pass at the **mesh-generation step** (step 2). The rig pass preserves the topology; you can't reduce polycount after rigging without breaking weights.
+
+## Steps
+
+### 1. Generate the T-pose reference image
+
+The rig pass requires a **front-facing T-pose** with arms out and legs slightly apart. If the reference is in an action pose, the rig will bend wrong and locomotion clips will look broken (knees inverted, elbows snapped — common Meshy failure mode).
+
+```
+summer_generate_image(
+  prompt="A fantasy knight in full plate armor, red cape, T-pose, arms straight out horizontal, legs slightly apart, front-facing, neutral expression. Game character asset, stylized, clean white background, soft studio lighting, full body in frame, ready for 3D mesh generation.",
+  model="nano-banana-2"
+)
+```
+
+The phrase `T-pose, arms straight out horizontal, legs slightly apart, front-facing` is load-bearing — drop any of those and the model will drift toward A-pose or a hero stance.
+
+If the user already has a concept image in an action pose, re-pose it to T-pose via img2img without re-rolling the design:
+
+```
+summer_generate_image({
+  referenceImageUrl: "<existing concept image>",
+  prompt: "<character> in T-pose, arms extended horizontally, neutral facing camera, white background, clean lighting"
+})
+```
+
+Show the image to the user:
+
+> Generated the T-pose reference. [link]. Approve to proceed to mesh generation, or regenerate?
+
+### 2. Generate the un-rigged 3D mesh
+
+```
+summer_generate_3d(
+  kind="image-to-3d",
+  imageUrl="<image url from step 1>",
+  model="hunyuan",
+  options={ target_polycount: 12000 },
+  wait=true
+)
+```
+
+Returns `{ asset: { fileUrl } }` — an un-rigged static `.glb`. Import it for preview only:
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://assets/characters/knight_unrigged.glb")
+```
+
+### 3. ⛔ 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.
+>
+> **Approve the mesh and proceed to rig?** Or regenerate the mesh first (different prompt, different polycount, different model)?
+
+If the user wants changes, loop back to step 1 or 2. Do NOT silently run the rig pass — it doubles the cost and locks the design.
+
+### 4. Run the rig pass
+
+```
+summer_generate_3d({
+  kind: "image-to-3d",
+  imageUrl: "<image url from step 1>",
+  options: { rig: true, polyTarget: 12000 }   // polyTarget is best-effort; backend may use options.target_polycount
+})
+```
+
+Returns a job whose result includes `{ asset: { fileUrl }, 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.
+
+Import the rigged version, replacing the un-rigged file:
+
+```
+summer_import_from_url(url="<rigged fileUrl>", path="res://assets/characters/knight.glb")
+```
+
+### 5. ⚠️ Restart the editor
+
+**Known Godot 4.5 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:
+
+> The rigged mesh is imported. Please restart the Summer Engine editor (close and reopen) so the Skeleton3D rebuilds correctly. Without the restart, animations will fail to bind.
+
+There is no programmatic workaround as of Godot 4.5.x. Tell the user, wait, then continue.
+
+### 6. Wire as CharacterBody3D or Node3D — pick the right parent
+
+| Use case | Parent type | Why |
+|---|---|---|
+| 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` |
+
+**CharacterBody3D wiring (player / enemy):**
+
+```
+summer_add_node(parent="./World", type="CharacterBody3D", name="Knight")
+summer_set_prop(path="./World/Knight", property="position", value="Vector3(0, 0, 0)")
+summer_add_node(parent="./World/Knight", type="Node3D", name="Mesh")
+# Instantiate the imported scene as a child of the Mesh node
+summer_set_prop(path="./World/Knight/Mesh", property="scene", value="res://assets/characters/knight.glb")
+summer_add_node(parent="./World/Knight", type="CollisionShape3D", name="Collider")
+# Add a CapsuleShape3D resource (height ~1.7m, radius ~0.4m) to the collider
+summer_save_scene
+```
+
+**Node3D wiring (cinematic NPC):**
+
+```
+summer_add_node(parent="./World/Tavern", type="Node3D", name="OldWizard")
+summer_set_prop(path="./World/Tavern/OldWizard", property="scene", value="res://assets/characters/wizard.glb")
+summer_save_scene
+```
+
+The imported `.glb` includes its own `Skeleton3D` and `AnimationPlayer` (empty library). The animation skill writes into that AnimationPlayer.
+
+### 7. Hand off to animation
+
+> Knight is wired at `./World/Knight` with a Meshy-rigged skeleton. `rigAssetId` saved.
+>
+> Next: `summer:animation/generate-motion` to add idle / walk / run / attack clips. Example call: `summer_generate_motion(rigAssetId: "<saved id>", backend: "meshy-library", motionName: "walk")`. The animation skill uses Meshy's curated mocap library (~70 standard motions). Custom prompt-driven motion is on the roadmap; for one-off signature moves not on the curated list, fall back to hand-authoring in the Godot editor or importing from Mixamo.
+
+## Anti-patterns
+
+- **Skipping the user-review gate.** Doubles cost, locks the design, and removes the user's chance to course-correct cheaply.
+- **Generating the mesh from a non-T-pose image.** Locomotion will look broken (inverted knees, snapped elbows). Always re-pose first.
+- **Forgetting the editor restart.** Animations will appear to bind successfully but play to a stale skeleton — the character T-poses motionless. The fix is always restart, never code.
+- **Wrapping a cinematic NPC in CharacterBody3D.** Wastes physics ticks; use Node3D.
+- **Wrapping the player in Node3D.** No `move_and_slide()`, no collision — the player walks through walls.
+- **Picking the rig pass before approving the silhouette.** The mesh defines what the character looks like; once the rig is on, you can't cheaply iterate the design.
+- **Using `meshy` model for the mesh step.** Legacy. `hunyuan` is the default and produces cleaner topology that Meshy's auto-rig handles better.
+
+## 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`.
+- **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.
+- **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)
+
+1. Generate the T-pose reference at the Summer dashboard (or any image gen — Midjourney, nano-banana web, DALL-E).
+2. Upload to Meshy at meshy.ai → Image to 3D → enable rigging.
+3. Download the `.glb`.
+4. Drop into `res://assets/characters/` — Godot's import dock picks it up.
+5. Restart the editor.
+6. Wire as CharacterBody3D / Node3D in the Godot editor 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).
+
+## 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.
+> - **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.
+- `_shared/mcp-tools-reference.md` — full parameter schemas for `summer_generate_3d`, `summer_generate_image`, and `summer_generate_motion`.

package/skills/3d-assets/environment-kit/SKILL.md

@@ -0,0 +1,164 @@
+---
+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".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: 3d-assets
+user-invocable: true
+allowed-tools: Read Grep summer_search_assets summer_generate_3d summer_generate_image summer_import_from_url summer_add_node summer_set_prop summer_inspect_node summer_get_scene_tree summer_save_scene
+paths: ["assets/kits/**", "assets/models/**", "**/*.tscn", "**/*.gd"]
+---
+
+# Environment Kit — Style-Locked Modular Pieces
+
+A kit is a *family* of meshes — wall, floor, door, pillar, corner, arch — that the level designer snaps together to build interiors and exteriors. The skill exists to solve **one specific failure mode**: generating each piece with a fresh prompt produces six pieces that look like they came from six different games. The fix is the **style anchor pattern** — generate one piece first, lock its prompt suffix, and reuse that exact suffix for every subsequent piece.
+
+The backing tool is `summer_generate_3d`, called multiple times. Each call costs ~$0.50, so a 6-piece kit is ~$3 and ~5 minutes. Confirm scope before starting.
+
+## When to use
+
+- "Build me a dungeon kit — walls, floor, door, pillar."
+- "I need modular wall pieces for a sci-fi corridor."
+- "Make a tileset for a wooden tavern interior."
+- "Generate the pieces for a stone temple — I'll assemble the level."
+- The user wants to build a level out of repeating, snapping pieces.
+
+## When NOT to use
+
+- A single hero prop (single chest, single throne) → `summer:3d-assets/prop-model`.
+- Open-world terrain (rolling hills, forests) → use a heightmap + scattered organic models from `summer:3d-assets/organic-model`.
+- Repeating flat surfaces only (just walls and floors, no decorative pieces) → `summer:asset-pipeline/asset-strategy` Pipeline 2 (textures + CSG) is cheaper and snaps perfectly to grid.
+- Characters or vehicles in the scene — those are separate skills.
+
+## The style anchor pattern
+
+This is the whole skill. Get this right and the kit looks unified. Get this wrong and you waste $3.
+
+1. **Generate the anchor piece first.** Pick the most visually defining piece — usually the wall or the door. Iterate the prompt until the user approves it visually.
+2. **Extract the style suffix.** Everything after the object description. Example anchor prompt:
+   ```
+   A stone dungeon wall section, mossy granite blocks with iron reinforcements, 
+   torch-bracket sconce, weathered surface. Game asset, centered, stylized 
+   low-poly game art, warm torchlight palette, white background, isolated object.
+   ```
+   The suffix to lock is everything from `Game asset, ...` onward, plus `mossy granite blocks with iron reinforcements, weathered surface, warm torchlight palette` — the material + palette tokens.
+3. **Reuse the suffix verbatim** for every other piece. Only change the object description at the front.
+
+| Anchor: wall | `A stone dungeon wall section, ...` + LOCKED SUFFIX |
+| Floor tile | `A stone dungeon floor tile, square, ...` + SAME LOCKED SUFFIX |
+| Pillar | `A stone dungeon pillar, square base, fluted shaft, ...` + SAME LOCKED SUFFIX |
+| Door | `A stone dungeon doorway, arched, heavy wooden door with iron studs, ...` + SAME LOCKED SUFFIX |
+| Corner block | `A stone dungeon corner wall section, two walls joined at right angle, ...` + SAME LOCKED SUFFIX |
+| Arch | `A stone dungeon archway with keystone, ...` + SAME LOCKED SUFFIX |
+
+If the user says "the door doesn't match the rest", the answer is almost always: the suffix drifted. Check the exact strings.
+
+## Snap-grid alignment
+
+Kit pieces only feel modular if they snap to a fixed grid. Pick the grid before generating and tell the user.
+
+| Grid size | Use for | Notes |
+|---|---|---|
+| **1m** | Tight interiors (dungeons, ship corridors, cells) | Wall = 1×3×0.3m. Floor = 1×1m. Most common. |
+| **2m** | Standard interiors (homes, taverns, offices) | Wall = 2×3×0.3m. Floor = 2×2m. Halves piece count. |
+| **4m** | Exteriors and large halls (temples, warehouses, throne rooms) | Wall = 4×4×0.4m. Floor = 4×4m. Quarter the piece count for the same area. |
+
+**Critical:** include the dimensions in the prompt. `summer_generate_3d` doesn't enforce them, but Hunyuan respects scale cues — `2 meter tall wall section` produces a mesh that imports near 2m tall. Then verify with `summer_inspect_resource` and scale-correct in the editor if needed.
+
+## Steps
+
+### 1. Confirm scope and pick the grid
+
+> About to build a dungeon kit. Suggested pieces: wall, floor, pillar, door, corner, arch (6 pieces, ~$3, ~5 min). Snap grid: 2m (standard interior). OK?
+
+### 2. Generate the anchor (wall)
+
+Use the prop-style prompt with explicit dimensions:
+
+```
+summer_generate_3d(
+  prompt="A 2 meter wide by 3 meter tall stone dungeon wall section, mossy granite blocks with iron reinforcements, torch-bracket sconce, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.",
+  model="hunyuan",
+  options={ target_polycount: 1500 },
+  wait=true
+)
+summer_import_from_url(url="<fileUrl>", path="res://assets/kits/dungeon/wall.glb")
+```
+
+Show the result to the user. **Iterate the anchor until approved** — every other piece copies its style.
+
+### 3. Lock the suffix and generate the remaining pieces
+
+Once the user says "yes, that's the look", store the locked suffix and crank through the rest. Same model, same polycount, same `options`. Only the object description changes.
+
+```
+# Floor
+summer_generate_3d(prompt="A 2 by 2 meter square stone dungeon floor tile, mossy granite blocks with iron reinforcements, weathered surface. Game asset, centered, stylized low-poly game art, warm torchlight palette, white background, isolated object.", model="hunyuan", options={ target_polycount: 800 })
+
+# Pillar
+summer_generate_3d(prompt="A 3 meter tall stone dungeon pillar, square base, fluted shaft, mossy granite blocks with iron reinforcements, weathered surface. Game asset, ...", model="hunyuan", options={ target_polycount: 1500 })
+
+# Door, Corner, Arch — same pattern.
+```
+
+Polycount targets per kit piece: walls/floors 800–1500 tris (placed dozens of times), decorative (pillar, arch) 1500–3000, doors 2000–3000.
+
+### 4. Import and stage in a kit scene
+
+Don't dump the kit into the level scene. Make a `kit_dungeon.tscn` that holds one of every piece, labelled, positioned next to each other on the snap grid. The level designer instantiates from there.
+
+```
+summer_add_node(parent="./KitRoot", type="Node3D", name="Wall")
+summer_set_prop(path="./KitRoot/Wall", property="scene", value="res://assets/kits/dungeon/wall.glb")
+summer_set_prop(path="./KitRoot/Wall", property="position", value="Vector3(0, 0, 0)")
+# ...repeat for floor, pillar, door, corner, arch with positions Vector3(2,0,0), Vector3(4,0,0), ...
+summer_save_scene
+```
+
+### 5. Verify scale and pivots
+
+```
+summer_inspect_resource(path="res://assets/kits/dungeon/wall.glb")
+```
+
+Check the AABB. If the wall is 1.85m tall when you asked for 3m, scale it in the editor (or re-import with `Scale` in the import dock). Pivots should sit at the *bottom-back* corner for walls and *bottom-center* for floors — that makes snapping to a 2m grid trivial. If pivots are wrong, use Godot's "Center to Origin" import option.
+
+## Anti-patterns
+
+- **Drifting style suffix.** Each piece gets a slightly different suffix → the kit looks mismatched. Copy-paste the exact string.
+- **Different polycount per piece.** A 5k-tri pillar next to a 500-tri wall reads as "the pillar is a hero piece" — wrong; they should feel like equal kit citizens. Match polycount within ~2× across the kit.
+- **Skipping the anchor approval.** If you generate all six pieces in a batch, you bake in whatever the first call's interpretation of the style was — and the user may hate it after $3 of generation.
+- **Generating walls / floors as individual meshes when you only need a tileable texture.** A flat wall section is cheaper as a textured `CSGBox3D`. Reserve the kit for pieces that need actual geometric detail (sconces, mouldings, doorways, arches).
+- **No scale cue in the prompt.** Wall comes back 0.4m tall. Always include `2 meter wide by 3 meter tall` (or your chosen grid).
+- **Forgetting the snap grid.** A 1.87m-tall wall with no scale fix → level looks crooked when tiled.
+
+## Edge cases
+
+- **Curved or organic kit (cave, alien hive).** Modular geometry resists snapping. Generate longer pieces (4m walls, transition tiles) and accept some overlap. Or switch to procedural — `summer:level-design` can scatter cave pieces with rotation jitter.
+- **Outdoor kit (cliffs, ruins, forest path).** Use the kit pattern but accept rotation/jitter at placement time. Mesh edges should fade naturally rather than snap cleanly. Pair with `summer:3d-assets/organic-model` for foliage scatter.
+- **Sci-fi kit (corridors, doors, terminals).** The style suffix becomes critical — `clean panels, soft cyan emissive trim, brushed metal, white background, isolated object`. Hard surfaces drift more than organic ones; review every piece.
+- **The user wants to add a piece later.** The locked suffix lives in the kit's notes (drop it in `assets/kits/dungeon/STYLE.md` if the user wants persistence). Reuse it verbatim for any addition — never re-derive.
+
+## Fallback (no MCP)
+
+1. Run each prompt at the Summer dashboard (or Hunyuan / Trellis web UIs), keeping the locked suffix.
+2. Download each `.glb`.
+3. Drop into `res://assets/kits/<kit-name>/`.
+4. Build the kit-display scene manually in Godot — one of each piece, snapped to grid.
+5. Hand to the level designer.
+
+## Handoff
+
+After the kit is staged:
+
+> Dungeon kit ready: `res://assets/kits/dungeon/` with wall, floor, pillar, door, corner, arch on a 2m snap grid. Display scene at `res://assets/kits/dungeon/kit_dungeon.tscn`.
+>
+> Next: hand off to the level-design step — instantiate kit pieces into `level_01.tscn`, snap to the 2m grid, dress with props (`summer:3d-assets/prop-model`) and foliage (`summer:3d-assets/organic-model`). For lighting, see `summer:3d-lighting`.
+
+## See also
+
+- `summer:3d-assets/prop-model` — for the chests, statues, and decorative props that dress the kit.
+- `summer:3d-assets/organic-model` — for foliage and rocks that break up modular repetition.
+- `summer:asset-pipeline/asset-strategy` — Pipeline 2 (textures + CSG) is the cheaper alternative when pieces are flat.
+- `summer:scene-composition` — how to organize the kit scene and the level scenes that consume it.
+- `summer:3d-lighting` — interior kit pieces typically need warm point lights at sconce positions.