summer-engine 1.5.0 → 2.2.0

package/skills/2d-assets/sprite-sheet/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: sprite-sheet
+description: Use when generating animated 2D character sprites laid out as a sprite sheet (grid of frames) — walk cycle, attack frames, idle bob, death sequence. Wires into AnimatedSprite2D / SpriteFrames. Trigger on "sprite sheet", "walk cycle", "attack frames", "animated sprite", "frame-by-frame animation", "2D character animation".
+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/**", "sprites/**", "art/sprites/**"]
+---
+
+# sprite-sheet — Frame-by-Frame 2D Animation
+
+This skill produces a grid of animation frames for a 2D character — walk cycle, idle bob, attack swing, death sequence — and wires the result into an `AnimatedSprite2D` via a `SpriteFrames` resource.
+
+**Up-front honesty:** sprite-sheet generation from a single text-to-image call is **unreliable**. Models can render "a sprite sheet of a knight walking" and produce 8 frames, but the inter-frame consistency (same anatomy, same costume, same lighting) is poor. Limbs morph between frames. Pixel sprites get extra fingers in frame 3. The result usually looks worse than the static sprite did.
+
+This skill therefore offers **three paths**, ranked by reliability:
+
+1. **Per-frame img2img** (most reliable) — generate the base pose, then generate each subsequent frame via `referenceImageUrl` with a small pose delta. Composite the frames into a sheet externally or wire each as a separate `SpriteFrames` entry.
+2. **Single-call sheet generation** (fast, unreliable) — one prompt asks for the grid. Works ~30% of the time. Worth trying once for short cycles (4 frames or fewer) before falling back to (1).
+3. **Manual authoring** (most reliable, slowest) — hand-author in **Aseprite** or **Piskel**. For pixel art at 32×32, this is often faster than fixing AI generations.
+
+There is no dedicated sprite-sheet generation tool. Recommended path: per-frame `summer_generate_image` with `referenceImageUrl` (img2img) at consistent angle/lighting, OR external tools (Aseprite/Piskel).
+
+## When to use
+
+- "Generate a walk cycle for the goblin sprite."
+- "I need 4 attack frames for the player character."
+- "Make a death animation — 6 frames of the enemy collapsing."
+- "Create an idle bob, 2-frame loop."
+- The character exists as a static sprite and needs animation.
+
+## When NOT to use
+
+- The character is 3D — use `summer:animation/generate-motion` for skeletal animation.
+- The user wants a single static sprite → `summer:2d-assets/pixel-art` or `summer:2d-assets/character-portrait`.
+- The user wants UI animation (loading spinner, button hover) — animate via `AnimationPlayer` rotating/tweening a static texture instead. Don't sprite-sheet UI.
+- The user has 12+ frames per animation and 4+ animations — that's hundreds of generations at $0.02 each. Pause and discuss budget.
+
+## Steps
+
+### 1. Anchor the base sprite
+
+You need a stable reference. Either:
+
+- The user has a static sprite already (`res://sprites/goblin.png`) — use it as `referenceImageUrl`.
+- Generate a base sprite via `summer:2d-assets/pixel-art` or `summer:2d-assets/character-portrait` first, then return here.
+
+Without a base, every frame drifts.
+
+### 2. Pick the path
+
+Ask the user (or decide based on context):
+
+| Signal | Path |
+|---|---|
+| Short cycle (≤4 frames), willing to accept some drift | Try **single-call sheet** first; fall back if bad |
+| Pixel art at small resolution | **Aseprite manual** is often fastest |
+| Higher-res character (128px+), 6-12 frames | **Per-frame img2img** |
+| User wants exact-pixel consistency | **Aseprite manual** — AI cannot deliver exact pixels |
+
+State the path before starting: "I'll do per-frame img2img — 6 generations, ~$0.12. The first frame is the base; each next frame uses the previous as reference. OK?"
+
+### 3a. Path 1 — Per-frame img2img
+
+Generate frame 1 (or use existing base). For each subsequent frame, prompt the pose delta and pass the previous frame as `referenceImageUrl`:
+
+```
+summer_generate_image(
+  prompt="goblin warrior, walk cycle frame 2 of 6, right leg forward, slight bob upward, identical character, same costume, same palette, transparent background",
+  referenceImageUrl="<frame 1 fileUrl>",
+  model="nano-banana-2",
+  style="<same as base>",
+  options={ image_size: "square_hd", negative_prompt: "different character, different costume, scene background" }
+)
+```
+
+Repeat for each frame. Save each as `goblin_walk_01.png`, `goblin_walk_02.png`, etc.
+
+After all frames return, either:
+
+- Wire each as a separate frame in a `SpriteFrames` resource (Godot will treat them as a sequence — no need to composite into a single sheet image).
+- Composite into a single sheet image via Aseprite (`File → Import Sprite Sheet`) or ImageMagick (`montage frame_*.png -tile 6x1 -geometry +0+0 sheet.png`).
+
+### 3b. Path 2 — Single-call sheet (try once)
+
+```
+summer_generate_image(
+  prompt="goblin warrior walk cycle, sprite sheet, 6 frames in a horizontal row, identical character across frames, side view, transparent background, frames clearly separated, consistent lighting, consistent palette",
+  model="nano-banana-2",
+  style="pixel",
+  options={ image_size: "landscape_16_9", negative_prompt: "different character per frame, scene background, varying lighting" }
+)
+```
+
+Inspect the result. If frames are coherent and the count matches, proceed. If anatomy morphs or count is wrong, fall back to Path 1 or Path 3.
+
+### 3c. Path 3 — Aseprite manual fallback
+
+Tell the user:
+
+> AI sprite-sheet generation is unreliable — best path for clean pixel animation is to hand-author in Aseprite (or Piskel for free in-browser). Onion-skin frame-by-frame; ~10 minutes for a 4-frame walk cycle. Want me to generate a base reference image you can trace?
+
+If yes, generate the static base via `summer:2d-assets/pixel-art` and stop here. The user takes it to Aseprite.
+
+### 4. Import frames into Godot
+
+For per-frame import (Path 1):
+
+```
+summer_import_from_url(url="<frame 1>", path="res://sprites/goblin/walk_01.png")
+summer_import_from_url(url="<frame 2>", path="res://sprites/goblin/walk_02.png")
+...
+```
+
+For a composited sheet (Path 2 or external composite):
+
+```
+summer_import_from_url(url="<sheet>", path="res://sprites/goblin/walk_sheet.png")
+```
+
+Set `Filter: Nearest` on import for pixel art, `Linear` for high-res.
+
+### 5. Wire as AnimatedSprite2D
+
+```
+summer_add_node(parentPath="/root/Game/Goblin", type="AnimatedSprite2D", name="Sprite")
+```
+
+Create a `SpriteFrames` resource and add an animation named `walk`. For per-frame textures:
+
+```
+summer_set_resource_property(
+  nodePath="/root/Game/Goblin/Sprite",
+  resourceProperty="sprite_frames:animations/walk/frames",
+  value=["res://sprites/goblin/walk_01.png", "res://sprites/goblin/walk_02.png", ...]
+)
+summer_set_resource_property(
+  nodePath="/root/Game/Goblin/Sprite",
+  resourceProperty="sprite_frames:animations/walk/speed",
+  value=8.0
+)
+summer_set_resource_property(
+  nodePath="/root/Game/Goblin/Sprite",
+  resourceProperty="sprite_frames:animations/walk/loop",
+  value=true
+)
+```
+
+For sheet-based (Path 2): use `AtlasTexture` with one region per frame, then add each AtlasTexture as a frame.
+
+### 6. Trigger from code
+
+```gdscript
+@onready var sprite: AnimatedSprite2D = $Sprite
+
+func _physics_process(delta):
+    if velocity.length() > 0.1:
+        sprite.play("walk")
+    else:
+        sprite.play("idle")
+```
+
+## Prompt patterns
+
+### Per-frame img2img (Path 1)
+
+| Goal | Frame 1 (base) | Frame N prompt skeleton (with `referenceImageUrl: <frame N-1>`) |
+|---|---|---|
+| Walk cycle (6 frames, side view) | `<character>, side view, idle stance, transparent bg` | `<character>, walk cycle frame N of 6, <leg position description>, identical character, same costume, transparent bg` |
+| Attack swing (4 frames) | `<character>, side view, weapon raised over head` | `<character>, attack frame N, <weapon position: descending / impact / recovery>, identical character, transparent bg` |
+| Idle bob (2 frames, loop) | `<character>, neutral stance, slightly compressed` | `<character>, idle bob upper position, slightly extended upward, identical character, transparent bg` |
+| Death (6 frames) | `<character>, hit react, leaning back` | `<character>, death frame N, <position: stumbling / kneeling / falling / collapsed>, identical character, transparent bg` |
+| Jump (3 frames) | `<character>, crouched ready to jump` | `<character>, jump frame N, <apex extended / falling tucked / land impact>, identical character, transparent bg` |
+
+### Single-call sheet (Path 2)
+
+| Goal | Prompt that sometimes works |
+|---|---|
+| 4-frame walk cycle | `<character> walk cycle, sprite sheet, 4 frames in horizontal row, side view, identical character, transparent background, clear frame separation, consistent lighting` |
+| 2-frame idle | `<character> idle bob, sprite sheet, 2 frames horizontal, identical character, slight up-down delta, transparent background` |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `goblin walking` | Returns one image of a walking goblin. Not a sheet, not multiple frames. |
+| `12-frame walk cycle in one image` | Frame count too high for single-call. Anatomy morphs across the row. |
+| `walk cycle for any character` | No character anchor. Frames have different characters. |
+| Per-frame without `referenceImageUrl` | Each frame is a different goblin. |
+| `sprite sheet, photorealistic` | Photoreal characters in tight frames lose identity coherence fast. Stay stylized. |
+
+## Anti-patterns
+
+- **Skipping the base anchor.** Without a stable reference (existing sprite or generated base), every frame drifts. Anchor first.
+- **Generating walk cycles at high frame counts (12+) via single call.** Will fail. Use per-frame img2img or split into chunks.
+- **Wiring an inconsistent sheet anyway** because you don't want to regenerate. Ship the inconsistency and the player notices the morphing limbs immediately. Cut the frame count or hand-author instead.
+- **Sprite-sheeting things that don't need to be sprite-sheeted.** UI animation, simple bobs, fades — use `AnimationPlayer` to tween a static texture instead. Sprite sheets are for character animation specifically.
+- **Pretending Aseprite is a failure.** Hand-authoring 4 pixel-art frames takes 10 minutes and looks better than 8 AI generations. Don't oversell AI here.
+
+## Edge cases
+
+- **Pixel art at low resolution.** AI per-frame img2img at 16×16 or 32×32 is ~impossible — the model can't preserve exact pixel positions. Aseprite or Piskel manual is the only reliable path. Generate a high-res reference and trace it down.
+- **Character with cloth / cape physics.** Cloth animation is hard for any AI. Use a base sprite and add cloth as a separate `AnimationPlayer`-tweened layer (`Sprite2D` for the cape, sin-wave-tweened rotation).
+- **8-direction sprite (top-down RPG with N/NE/E/SE/S/SW/W/NW).** Generate one direction's full cycle, then for each other direction generate the FIRST FRAME via img2img with a "rotated to face X" prompt and use it as the new base for that direction's per-frame work. Multiplies generation count by 8 — pause for budget confirmation.
+- **User wants a turn-around (rotating in place over 8 frames).** Same as 8-direction; generate single-frame per angle as anchor, accept that AI rotation won't be perfectly consistent.
+- **Animation needs to loop seamlessly.** Make frame N+1 explicitly bridge back to frame 1 in your prompt. Or generate one extra "bridge" frame and drop it.
+
+## Fallback (no MCP)
+
+Print the per-frame call sequence:
+
+```
+Frame 1: summer_generate_image(prompt="<base>", model="nano-banana-2", style="pixel", ...)
+Frame 2: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 1>", ...)
+Frame 3: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 2>", ...)
+...
+```
+
+Tell the user to run via the Summer dashboard. Or recommend Aseprite (paid, $20) / Piskel (free in-browser) for hand-authoring — for pixel art under 64×64, it is the faster path even with MCP available.
+
+## Handoff
+
+After the animation is wired:
+
+- **More animations on the same character** (idle, attack, death) → re-invoke this skill with the same base anchor, vary the delta.
+- **Sound effects synced to animation frames** → `summer:audio/sound-effect`, then wire via `Call Method Track` in `AnimationPlayer`.
+- **Multi-direction sprites** → re-invoke per direction (budget warning).
+- **Pixel-art static base if not yet generated** → `summer:2d-assets/pixel-art` first.
+- **3D character animation instead** → `summer:animation/generate-motion`.
+
+## See also
+
+- `summer:2d-assets/pixel-art` — base sprite generation.
+- `summer:2d-assets/character-portrait` — base portrait for higher-res characters.
+- `summer:animation/generate-motion` — 3D-skeletal counterpart.
+- `summer:audio/sound-effect` — frame-synced SFX.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.

package/skills/2d-assets/tileable-texture/SKILL.md

@@ -0,0 +1,205 @@
+---
+name: tileable-texture
+description: Use when generating a seamless tileable texture for walls, floors, terrain, ceilings — square tile that repeats cleanly on all four edges. Wires onto PlaneMesh / CSGBox3D / MeshInstance3D as a StandardMaterial3D albedo. Trigger on "tileable texture", "seamless texture", "wall texture", "floor texture", "ground texture", "terrain texture", "tiled material".
+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 summer_inspect_node
+paths: ["assets/**", "art/textures/**", "materials/**"]
+---
+
+# tileable-texture — Seamless Square That Repeats Cleanly
+
+This skill generates a seamless square texture (typically 1024×1024) that tiles cleanly on all four edges with no visible seams. Output goes onto a `PlaneMesh`, `CSGBox3D`, or `MeshInstance3D` as a `StandardMaterial3D` albedo, often with `uv_scale` cranked up so a single tile covers a small area and the surface repeats it across a wall or floor.
+
+The hard part is "seamless." Most diffusion models violate edge continuity by default — generate a brick wall and the bricks stop mid-row at the edge. This skill encodes the prompt suffix and the post-import verification that catches seams before they ship.
+
+## When to use
+
+- "Generate a brick wall texture for this room."
+- "I need a grass ground texture for the level."
+- "Tileable wood-floor texture, 1024×1024."
+- "Stone tile texture for the dungeon."
+- "Sand / dirt / metal-panel — seamless."
+
+## When NOT to use
+
+- The user wants a 3D-modeled wall with geometric brick relief → `summer:asset-pipeline/asset-strategy` (image-to-3D).
+- The user wants a unique mural / non-tiling artwork → `summer:2d-assets/concept-art` or `summer:2d-assets/character-portrait`.
+- The user wants a skybox / 360° environment → `summer:2d-assets/skybox-panorama`.
+- The user wants a normal map / PBR material set — generation today is albedo-only. Normals must be derived (`MaterialMaker`, `NormalMap-Online`) or hand-authored.
+
+## Steps
+
+### 1. Search for an existing texture
+
+```
+summer_search_assets(query="<material> tileable", filter={ kind: "image" })
+```
+
+Texture libraries (AmbientCG, Polyhaven) often have free PBR sets that beat AI generation for realism. If the user wants photorealistic tiling, pause and suggest those.
+
+### 2. Build the prompt — material + the seamless suffix
+
+Pattern:
+
+```
+<material description>, seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no edges, square format, no specific objects in frame
+```
+
+The load-bearing phrases are:
+
+- **`seamless tileable texture`** — primes the model.
+- **`top-down view`** — kills perspective convergence (which is the #1 source of visible seams).
+- **`uniform lighting`** — kills directional shadows that bake into the tile and stripe across the surface when it repeats.
+- **`no perspective, no shadows, no edges`** — explicit negation of common failure modes.
+- **`no specific objects in frame`** — kills "interest" features the model adds (a single bright leaf, a chip in one brick) that scream "this is a repeating tile."
+
+### 3. Generate
+
+```
+summer_generate_image(
+  prompt="weathered red brick wall, seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square format, photographic detail",
+  model="nano-banana-2",
+  style="realistic",
+  options={
+    image_size: "square_hd",
+    negative_prompt: "perspective, vanishing point, directional shadow, vignette, single feature, scene context, sky, sun"
+  }
+)
+```
+
+`style: "realistic"` is the right default for textures (most are aiming for photographic surface). Switch to `"none"` for stylized/painterly.
+
+### 4. Import to project
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://art/textures/brick_red.png")
+```
+
+In the import dock, set:
+
+- `Repeat: Enabled` (REQUIRED for tiling).
+- `Filter: Linear with mipmaps` (smoother at distance).
+- `Mipmaps: Enabled` (textures viewed at angle need mipmaps).
+- `Compress: VRAM Compressed` for ship; `Lossless` while iterating.
+
+### 5. Verify the seam
+
+Before wiring into a scene, view the texture tiled. Quick check: in the editor's filesystem dock, right-click the texture → preview → set repeat 4×4 mentally. Or apply to a `PlaneMesh` with `uv_scale = (4, 4)` and look from above.
+
+If you see a grid of identical "interest features" (a chip, a stain, a bright pixel) repeating, the tile has a hotspot — regenerate with stronger negative on "single feature."
+
+If you see hard horizontal/vertical seams, the edges don't match — regenerate with extra emphasis on `seamless` or run the texture through a seamless-tile filter (Photoshop "Offset" + heal, GIMP "Make Seamless", or Aseprite's Tiled Mode).
+
+### 6. Wire onto geometry
+
+**On a PlaneMesh (floor/ceiling):**
+
+```
+summer_add_node(parentPath="/root/Level", type="MeshInstance3D", name="Floor")
+summer_set_resource_property(nodePath="/root/Level/Floor", resourceProperty="mesh", value="<new PlaneMesh resource>")
+summer_set_prop(path="/root/Level/Floor", property="mesh:size", value="Vector2(20, 20)")
+```
+
+Then create a `StandardMaterial3D`, set `albedo_texture` to the imported texture, and crank `uv1_scale` so each tile covers ~1m of world space:
+
+```
+summer_set_resource_property(
+  nodePath="/root/Level/Floor",
+  resourceProperty="material_override",
+  subProperty="albedo_texture",
+  value="res://art/textures/brick_red.png"
+)
+summer_set_resource_property(
+  nodePath="/root/Level/Floor",
+  resourceProperty="material_override",
+  subProperty="uv1_scale",
+  value="Vector3(20, 20, 1)"
+)
+```
+
+`uv1_scale = (20, 20, 1)` on a 20m plane means the texture tiles 20× across — each tile covers 1m².
+
+**On a CSGBox3D (walls):**
+
+```
+summer_add_node(parentPath="/root/Level", type="CSGBox3D", name="WallNorth")
+summer_set_prop(path="/root/Level/WallNorth", property="size", value="Vector3(10, 3, 0.3)")
+```
+
+Then attach the same material with `uv1_scale` tuned to wall dimensions.
+
+## Prompt patterns
+
+| Goal | Prompt that works | Why |
+|---|---|---|
+| Brick wall | `weathered red brick wall, seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square, photographic` | Top-down + uniform lighting kill perspective seams |
+| Grass ground | `dense fresh grass, seamless tileable texture, top-down view, uniform lighting, no shadows, no flowers, no patches, square` | "No flowers, no patches" kills hotspot features |
+| Wood floor | `oak wood floor planks, seamless tileable, top-down view, uniform lighting, no perspective, no nails, no knots emphasized, square` | "No knots emphasized" kills the ONE bright knot per tile |
+| Stone tiles | `cobblestone path, seamless tileable, top-down, uniform lighting, no shadows, no moss patches, square, photographic` | "No moss patches" kills hotspot |
+| Metal panel | `industrial metal floor panel, seamless tileable, top-down, uniform lighting, no rust hotspots, no scratches concentrated, square` | Diffuse rust spreads across the tile instead of clumping |
+| Sand / dirt | `dry desert sand, seamless tileable, top-down view, uniform soft lighting, no footprints, no rocks, no shadows, square` | Negative space is ideal for tiling |
+| Stylized painterly grass | `stylized painterly grass, Studio Ghibli, seamless tileable, top-down, uniform lighting, no specific blades emphasized, square` (style: "none") | Style preset would fight the painterly direction |
+| Sci-fi panel | `sci-fi metal floor panel with subtle glowing seams, seamless tileable, top-down, uniform lighting, square, the glowing seams form a regular grid that aligns with tile edges` | Make the seams part of the design |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `brick wall` | No "seamless," no "top-down." Returns a 3D-photographed wall with perspective and a corner. Useless for tiling. |
+| `seamless brick wall in a dungeon at night` | Scene context bakes shadows and ambience that won't tile. |
+| `tileable grass with flowers and rocks` | Hotspot features. Each tile has the SAME flower. Visible repeat. |
+| `seamless wood floor (not specifying square / top-down)` | Often returns floor-from-eye-level with perspective. |
+| `pbr wood floor texture` | "PBR" implies a material set (albedo + normal + roughness). The model only outputs albedo. Generate albedo, derive maps separately. |
+
+## Anti-patterns
+
+- **Skipping `Repeat: Enabled` on import.** Default is `Repeat: Disabled`. The texture stretches across the whole surface instead of tiling. Looks blurry at distance.
+- **Not tuning `uv1_scale`.** Default scale of (1, 1, 1) on a 20m floor means the 1m-real texture is stretched to 20m. Always scale to physical sizing.
+- **Hotspot features** that scream "repeated tile." Regenerate with stronger negative on single-feature words.
+- **Generating PBR sets with one image.** Diffusion outputs albedo only. For normals/roughness, use a derivation tool or hand-author. Don't claim it's PBR-ready when it's not.
+- **Forgetting mipmaps.** Tileable textures viewed at distance need mipmaps; without them, you get shimmering moire.
+- **Using textures with directional shadow** baked in. Even subtle shadow stripes when tiled. Always demand "uniform lighting."
+
+## Edge cases
+
+- **User wants normal map / roughness / AO too.** Generation today produces albedo only. Use `Materialize` (free) or `MaterialMaker` (open source) to derive a normal from the albedo. Hand-paint roughness if the surface is heterogeneous (wood = low roughness on knots, high on grain). Set the user's expectation: AI gives albedo; PBR is a follow-up step.
+- **Texture must tile in only one direction (e.g., a brick wall that runs horizontally but not vertically).** Generate 1024×1024 seamless, then crop to your actual aspect; the horizontal tile remains seamless. Or: prompt `tileable horizontally only, distinct top and bottom edges` for ceiling-to-floor walls.
+- **Texture must read at very low resolution (mobile, distant LOD).** Generate at `square_hd`, downscale on import via `Compress: VRAM Compressed`. Avoid generating at low resolution — model quality drops.
+- **User wants animated water / lava texture.** Generate a still tileable texture and use a `ShaderMaterial` with UV scrolling to animate. Don't try to generate frames.
+- **Visible seam after generation.** Run through GIMP `Filters → Map → Make Seamless` or open in Aseprite, set Tiled mode, paint over the seam manually. AI-generated tileables often need a 5-minute touch-up.
+
+## Fallback (no MCP)
+
+Print the call:
+
+```
+summer_generate_image(
+  prompt="<material> seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square",
+  model="nano-banana-2",
+  style="realistic",
+  options={ image_size: "square_hd", negative_prompt: "perspective, directional shadow, single feature, scene context" }
+)
+```
+
+Tell the user to run via the Summer dashboard, then `summer_import_from_url` to `res://art/textures/<name>.png`, set `Repeat: Enabled`, and tune `uv1_scale` to physical size.
+
+If MCP is offline entirely: AmbientCG and Polyhaven offer free CC0 PBR texture sets that often beat AI for realism. For stylized, hand-author in Aseprite/Krita with tile-mode preview.
+
+## Handoff
+
+After the texture is wired:
+
+- **More textures in the same biome** → re-invoke this skill, hold style/lighting consistent.
+- **Apply to a procedurally-built level** → `summer:scene-composition` for CSG and modular wall kits.
+- **PBR set with normals/roughness** → out of MCP scope today; user runs derivation in MaterialMaker.
+- **Skybox for the level's environment** → `summer:2d-assets/skybox-panorama`.
+
+## See also
+
+- `summer:asset-pipeline/asset-strategy` — meta-router and 3D pipeline.
+- `summer:2d-assets/skybox-panorama` — sky/environment counterpart.
+- `summer:scene-composition` — applying textures to CSG and MeshInstance3D.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.

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.