summer-engine 2.0.0 → 2.3.0

package/skills/2d-assets/skybox-panorama/SKILL.md

@@ -0,0 +1,207 @@
+---
+name: skybox-panorama
+description: Use when generating a 360° panoramic sky image for use as a Sky resource (PanoramaSkyMaterial) in a 3D scene. Equirectangular projection, 2:1 aspect. Wires into WorldEnvironment.sky. Trigger on "skybox", "sky panorama", "360 background", "environment sky", "HDRI sky", "panoramic background", "panorama sky".
+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/sky/**", "environments/**"]
+---
+
+# skybox-panorama — 360° Sky for WorldEnvironment
+
+This skill generates a single equirectangular panoramic image (2:1 aspect, e.g. 2048×1024 or 4096×2048) suitable for Godot's `PanoramaSkyMaterial`. Wires it into a `Sky` resource on a `WorldEnvironment` node so the sky is visible from every camera angle in your 3D scene.
+
+The single biggest failure mode is **non-equirectangular output**. Diffusion models default to flat 2D scenes; if you don't explicitly demand "equirectangular projection," the result looks fine in a thumbnail but distorts brutally when wrapped onto a sphere — horizon bows, zenith pinches, the sun stretches into a smear. This skill encodes the prompt suffix and the import discipline that produces a usable sky on the first or second try.
+
+## When to use
+
+- "Generate a fantasy sky for the level."
+- "I need a sci-fi nebula skybox."
+- "Make a sunset panorama for the desert scene."
+- "Stormy night sky for the haunted level."
+- The 3D scene needs a visible sky (not just a flat color background).
+
+## When NOT to use
+
+- The user wants a 2D parallax background → that's a separate `Sprite2D` job, not a panorama.
+- The user wants a HDRI for environment lighting (not just visual sky) → AI panoramas are LDR by default. For real IBL/HDR, use Polyhaven HDRIs (free CC0). Mention this to the user if lighting realism matters.
+- The user wants a 3D-modeled sky-dome with geometry (clouds-as-meshes) → out of scope; use a `Sphere` mesh + custom shader.
+- The scene is 2D → no sky needed.
+
+## Steps
+
+### 1. Search for an existing sky
+
+```
+summer_search_assets(query="<vibe> sky panorama", filter={ kind: "image" })
+```
+
+Polyhaven (`polyhaven.com/hdris`) hosts hundreds of free CC0 HDRIs that beat AI generation for realism and provide IBL data. For realistic exterior scenes, prefer Polyhaven; for stylized / fantasy / sci-fi, AI generation wins.
+
+### 2. Build the prompt — sky description + equirectangular suffix
+
+Pattern:
+
+```
+<sky description>, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam at left and right edges, distortion-correct for sphere mapping, no foreground objects, no ground horizon line, sky and clouds and atmosphere only
+```
+
+Load-bearing phrases:
+
+- **`360 degree panoramic equirectangular projection`** — primes the model for the right format.
+- **`seamless horizontal wrap, no visible seam at left and right edges`** — the left and right edges of the image meet when wrapped. If they don't match, you see a vertical seam in the sky.
+- **`no foreground objects, no ground horizon line`** — skies show only sky. If you include a horizon, it warps weirdly when sphere-mapped and kills the illusion that the sky is at infinite distance.
+- **`distortion-correct for sphere mapping`** — reminds the model that the top/bottom of the image map to the zenith/nadir.
+
+### 3. Generate at 2:1 aspect
+
+```
+summer_generate_image(
+  prompt="dramatic fantasy sky, golden hour, large purple-orange clouds, distant mountains silhouetted at very bottom, soft god-rays, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground objects, sky only",
+  model="nano-banana-2",
+  style="realistic",
+  options={
+    aspectRatio: "2:1",
+    image_size: "landscape_16_9",
+    negative_prompt: "vertical seam, ground objects, horizon-level details, distorted, warped, characters, buildings"
+  }
+)
+```
+
+`aspectRatio: "2:1"` is critical. Equirectangular MUST be 2:1 (width = 2× height). If the model returns 16:9 or 4:3, the wrap will be wrong.
+
+### 4. Verify the seam and projection
+
+Before wiring, inspect:
+
+- **Left edge ↔ right edge:** mentally place them side-by-side. They should match continuously. If there's a cloud cut in half on the left and a different cloud on the right, regenerate with stronger emphasis on `seamless horizontal wrap`.
+- **Top stretching:** the top 10% of the image stretches enormously when mapped to the zenith. If there are tight features (a sun, a cloud edge) high up, they'll smear. Generations with diffuse, soft top regions wrap better than crisp ones.
+- **Bottom:** same applies to the nadir. Most skies don't show much bottom anyway since the camera sits below the horizon — but avoid generating tight features at the very bottom.
+
+If the image fails seam check, regenerate. Some models support `seed` for variation while keeping prompt — bump the seed.
+
+### 5. Import to project
+
+```
+summer_import_from_url(url="<fileUrl>", path="res://art/sky/fantasy_sunset.png")
+```
+
+In the import dock:
+
+- `Repeat: Disabled` (panoramas don't tile — they wrap once via the material).
+- `Filter: Linear with mipmaps` (smoother as the camera turns).
+- `Mipmaps: Enabled`.
+- `Compress: VRAM Compressed` for ship.
+
+### 6. Wire into WorldEnvironment (3 lines)
+
+```
+summer_add_node(parentPath="/root/Game", type="WorldEnvironment", name="WorldEnvironment")
+
+summer_set_resource_property(
+  nodePath="/root/Game/WorldEnvironment",
+  resourceProperty="environment:background_mode",
+  value=2  # BG_SKY
+)
+
+summer_set_resource_property(
+  nodePath="/root/Game/WorldEnvironment",
+  resourceProperty="environment:sky:sky_material",
+  value="<new PanoramaSkyMaterial with panorama: res://art/sky/fantasy_sunset.png>"
+)
+```
+
+Then, if the user wants the sky to also light the scene (image-based lighting):
+
+```
+summer_set_resource_property(
+  nodePath="/root/Game/WorldEnvironment",
+  resourceProperty="environment:ambient_light_source",
+  value=3  # AMBIENT_SOURCE_SKY
+)
+```
+
+Note: AI-generated panoramas are LDR (8-bit per channel). For physically-correct IBL with bright suns, the lighting is muted compared to true HDRI. Mention this to the user if they expect strong IBL.
+
+### 7. Verify in scene
+
+```
+summer_inspect_node(path="/root/Game/WorldEnvironment")
+```
+
+Then `summer_play` and look around. Sun in the right place? Seam invisible? Top/bottom okay?
+
+## Prompt patterns
+
+| Goal | Prompt that works | Why |
+|---|---|---|
+| Fantasy sunset | `dramatic fantasy sky at golden hour, large purple and orange clouds, soft god-rays, distant mountain silhouettes at very bottom only, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground, sky only` | Soft top, distant horizon = clean wrap |
+| Sci-fi space nebula | `vast space nebula, deep blue and magenta gas clouds, scattered bright stars, distant galaxy disc, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground objects, no ground` | Space skies wrap easily; no horizon issues |
+| Stormy night | `dark stormy night sky, heavy rolling clouds, distant lightning flashes, full moon partly obscured, 360 degree panoramic equirectangular, seamless wrap, no foreground` | Diffuse cloud structure tolerates wrapping well |
+| Clear blue day | `bright clear blue sky with scattered cumulus clouds, midday sun upper left, 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no ground` | Tight sun feature warps; place sun off-center |
+| Alien planet sky | `alien planet sky, two suns one large red one small white, swirling green-purple atmosphere, distant ringed planet at horizon, 360 panoramic equirectangular, seamless wrap, no foreground` | Multi-sun setups wrap if features stay diffuse |
+| Underwater (caustic dome) | `underwater scene seen from below, sun rays piercing water surface, deep blue gradient downward to black, 360 panoramic equirectangular, seamless wrap` | Treat ocean surface as the "sky"; works for underwater levels |
+| Stylized painterly sky | `Studio Ghibli painterly sky, soft cumulus clouds at sunset, warm pastel palette, 360 panoramic equirectangular, seamless wrap, no foreground` (style: "none") | Style preset would fight painterly |
+
+### Bad prompts (and why)
+
+| Bad | Failure mode |
+|---|---|
+| `beautiful sky` | No equirectangular suffix. Returns flat 16:9 photograph. Wrap looks broken. |
+| `sky with mountains and trees and a castle` | Foreground objects. Horizon-level details warp catastrophically when sphere-mapped. |
+| `360 sky` (without 2:1 aspect) | Aspect mismatch. Wrap is misaligned. |
+| `panoramic sky in 4k` | "4k" implies 3840×2160 (16:9), not 2:1. Specify aspect. |
+| `sky with the sun in the center top` | Sun at zenith stretches into a smear. Place sun off-axis. |
+
+## Anti-patterns
+
+- **Including foreground or horizon.** Mountains, trees, buildings at horizon level warp weirdly when sphere-mapped (the "swimming horizon" effect). Skies show ONLY sky. If the level needs distant mountains, model them as low-poly meshes in the scene, not in the sky texture.
+- **Not specifying 2:1 aspect.** A 16:9 panorama wrapped equirectangular has obvious horizontal compression. Always `aspectRatio: "2:1"`.
+- **Tight features at zenith/nadir.** Anything in the top or bottom 10% of the image gets pinched. Bias toward soft, diffuse features there.
+- **Expecting HDR / IBL quality.** AI panoramas are 8-bit. If the user needs realistic environment lighting from the sky, point them at Polyhaven HDRIs (CC0). AI is for visual sky, not for lighting.
+- **Forgetting `Repeat: Disabled` on import.** Panoramas wrap once via the material; if `Repeat` is on, you can get duplicate-tile artifacts at the seam.
+- **Visible vertical seam on the wrap.** If left/right edges don't match, regenerate with seed bump or fix the seam in Photoshop/GIMP via the offset trick (offset by 50% horizontally → heal the new visible seam → offset back).
+
+## Edge cases
+
+- **Animated sky (clouds drift).** AI gives one frame. Animate via shader (UV scroll on the panorama texture) or layer two panoramas with `ProceduralSkyMaterial` for the base + a transparent cloud layer.
+- **Day/night cycle.** Generate two panoramas (day + night). Cross-fade the `sky_material` via shader blend or by swapping `panorama` over a tween. Two LDR panoramas + a blend = serviceable cycle.
+- **First-person VR.** AI panoramas at 2048×1024 are too low-res for VR (visible pixels). Generate at 4096×2048 if the model supports it; otherwise use Polyhaven HDRIs at 8K.
+- **Indoor scene.** Skyboxes are wasted indoors — use `BG_COLOR` or a flat black background. Don't generate a sky for a windowless dungeon.
+- **Visible vertical seam after generation.** Fix in Photoshop/GIMP: `Filter → Other → Offset` by 50% horizontally → the seam moves to the center → heal with content-aware fill or clone stamp → offset back to 0. Or regenerate with seed bump and `seamless horizontal wrap, no visible seam at left and right edges` repeated twice in the prompt.
+
+## Fallback (no MCP)
+
+Print the call:
+
+```
+summer_generate_image(
+  prompt="<sky> 360 degree panoramic equirectangular projection, seamless horizontal wrap, no visible seam, no foreground objects, sky only",
+  model="nano-banana-2",
+  style="realistic",
+  options={ aspectRatio: "2:1", negative_prompt: "vertical seam, foreground, distorted, warped, characters, buildings" }
+)
+```
+
+User runs via Summer dashboard, then `summer_import_from_url` to `res://art/sky/<name>.png`, sets `Repeat: Disabled`, and wires the WorldEnvironment manually.
+
+If MCP is offline entirely: Polyhaven (`polyhaven.com/hdris`) has hundreds of free CC0 HDRIs ready to drop into `PanoramaSkyMaterial`. Often a better choice than AI for realistic exteriors anyway.
+
+## Handoff
+
+After the sky is wired:
+
+- **Add atmospheric fog matching the sky's mood** → `summer:scene-composition` (fog is on the same Environment resource).
+- **Add a directional `DirectionalLight3D` matching the sun position in the panorama** → `summer:3d-lighting` for sun + shadows.
+- **Day/night cycle** → re-invoke this skill for the night sky, then write a small tween between the two `panorama` properties.
+- **Tileable ground texture for the level floor** → `summer:2d-assets/tileable-texture`.
+
+## See also
+
+- `summer:3d-lighting` — sun, ambient, fog wired alongside the sky.
+- `summer:2d-assets/tileable-texture` — ground/floor counterpart.
+- `summer:scene-composition` — WorldEnvironment placement and configuration.
+- `summer:asset-pipeline/asset-strategy` — meta-router.
+- `_shared/mcp-tools-reference.md` — `summer_generate_image` schema.

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.