summer-engine 2.6.6 → 2.8.0

package/skills/2d-assets/pixel-art/SKILL.md

@@ -13,7 +13,15 @@ paths: ["assets/**", "art/pixel/**", "sprites/**"]
 
 This skill generates pixel-art assets — sprites, items, tiles, icons, portraits — at a target resolution (32×32, 64×64, 128×128, etc.). Pixel art has hard constraints (grid alignment, limited palette, no anti-aliased edges) that diffusion models violate by default. This skill encodes the prompt patterns and post-processing discipline that makes the output actually look like pixel art and not "blurry small image."
 
-**Backing tool:** `summer_generate_image` with `style: "pixel"` and an explicit pixel-art prompt. Pass `options.image_size: "square_hd"` and have the agent enforce pixel-perfect by setting the project's default texture filter to Nearest (and downscaling to the target resolution post-gen). Output is upscaled by the model — you generally request a small generation (or downscale post-gen) to get crisp pixels.
+**Backing tool:** `summer_generate_image` with an explicit pixel-art prompt.
+
+Two things about that tool you have to know before writing a call, because both silently do nothing:
+
+- **There is no `"pixel"` style preset.** `style` accepts exactly `realistic`, `cartoon`, `anime`, `none`; anything else is coerced to `none`. Only `cartoon` and `anime` do anything at all (they append a short suffix); `realistic` and `none` append nothing. So `style: "pixel"` is identical to `style: "none"` — the pixel look has to come entirely from the prompt. Use `style: "none"` and say so honestly.
+- **`options` is not a general passthrough.** The MCP tool forwards `options` to the server, which only recognizes Nano Banana provider keys: `seed`, `outputFormat`, `safetyTolerance`, `syncMode`, `systemPrompt`, `limitGenerations`, `thinkingLevel`. `image_size` and `negative_prompt` are not among them and are dropped without an error. There is no size or aspect-ratio argument on this tool at all — MCP images come back at the server's 1:1 default. Put framing and exclusions in the prompt text instead.
+
+Pixel-perfect output is enforced in Summer Engine with Nearest texture filtering
+and by downscaling to the target resolution after generation.
 
 ## When to use
 
@@ -54,7 +62,7 @@ shading: 3-tone (light, mid, shadow), no gradients, no AA
 ### 2. Search for existing assets
 
 ```
-summer_search_assets(query="<subject> pixel", filter={ kind: "image" })
+summer_search_assets(query="<subject> pixel", assetType="2d_image", source="all")
 ```
 
 ### 3. Build the prompt
@@ -71,17 +79,17 @@ The model can't actually generate at 32×32 — it generates at 1024×1024 with
 
 ```
 summer_generate_image(
-  prompt="pixel art slime monster, 32x32 sprite, PICO-8 palette, hard 1px outline in palette's darkest color, 3-tone shading, no anti-aliasing, no blur, sharp pixel edges, transparent background, front-facing",
+  prompt="pixel art slime monster, 32x32 sprite, PICO-8 palette, hard 1px outline in palette's darkest color, 3-tone shading, no anti-aliasing, no blur, sharp pixel edges, front-facing. Not blurry, no smooth gradients, no soft edges, not photorealistic, no 3D render.",
   model="nano-banana-2",
-  style="pixel",
-  options={
-    image_size: "square_hd",
-    negative_prompt: "blurry, smooth gradients, anti-aliasing, photorealistic, 3D render, soft edges"
-  }
+  style="none",
+  options={ removeBackground: true }
 )
 ```
 
-`negative_prompt` is critical for pixel art — without it the model smuggles in soft edges and gradients.
+Two deliberate choices there:
+
+- **The negations live in the prompt.** There is no `negative_prompt` argument — putting one in `options` is dropped silently. Diffusion models honor in-prompt negations less reliably than a real negative-prompt field, so state them as plain sentences at the end and expect to regenerate more often than you would on a provider UI that exposes the field.
+- **`options.removeBackground: true` is real** and is the only `options` key in this skill that does anything: it runs a real background-removal pass after generation and returns a PNG with true alpha. Prefer it over asking for "transparent background" in the prompt, which is what makes models paint a literal checkerboard.
 
 ### 5. Downscale to target resolution
 
@@ -89,7 +97,9 @@ The generated image is 1024×1024 pixel-style. To get true crisp pixels at 32×3
 
 - Import to the engine, then in the import dock set `Filter: Nearest` (no smoothing).
 - For a true 32×32 atlas/icon, downscale in an external editor (Aseprite, GIMP "nearest neighbor") to 32×32 before importing. Aseprite's "Sprite > Sprite Size" with Nearest gives the cleanest result.
-- In Godot, set `Project Settings → Rendering → Textures → Default Texture Filter: Nearest` if the entire game is pixel-art. This kills bilinear smoothing project-wide.
+- In Summer Engine, set `Project Settings → Rendering → Textures → Default
+  Texture Filter: Nearest` if the entire game is pixel art. This disables
+  bilinear smoothing project-wide.
 
 ### 6. Import and wire
 
@@ -100,13 +110,16 @@ summer_import_from_url(url="<fileUrl>", path="res://sprites/slime.png")
 For a `Sprite2D`:
 
 ```
-summer_set_resource_property(
-  nodePath="/root/Game/Slime/Sprite2D",
-  resourceProperty="texture",
+summer_set_prop(
+  scenePath="res://main.tscn",
+  path="./Slime/Sprite2D",
+  key="texture",
   value="res://sprites/slime.png"
 )
 ```
 
+`texture` is a property **on the node**, so it is `summer_set_prop`. `summer_set_resource_property` is for reaching *inside* a resource the node already holds (mesh size, material albedo) and needs all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value` — there is no two-argument form.
+
 Confirm `Filter: Nearest` is set in the import dock OR project-wide.
 
 ## Prompt patterns
@@ -126,15 +139,16 @@ Confirm `Filter: Nearest` is set in the import dock OR project-wide.
 |---|---|
 | `8-bit sword` | "8-bit" is interpreted loosely. Returns a smooth render of a sword with vague pixel feel. Specify resolution + palette + "no AA" explicitly. |
 | `pixel art knight, photorealistic` | Conflicting directives. Model averages and gives you neither. |
-| `pixel art at 32x32` (no negative_prompt) | Model adds soft edges and gradient shading. Always add negative prompt for AA / blur / gradients. |
+| `pixel art at 32x32` with no negations | Model adds soft edges and gradient shading. Always spell out "no anti-aliasing, no blur, no smooth gradients" in the prompt itself — there is no negative-prompt argument to fall back on. |
 | `pixel sprite walk cycle` | Walk cycles need consistent frames — single-prompt sprite sheets fail. Route to `summer:2d-assets/sprite-sheet`. |
 | `cute pixel art` | "Cute" without subject is undefined. Specify what. |
 
 ## Anti-patterns
 
 - **Skipping the downscale.** The model returns a 1024×1024 pixel-style image. If you import that as a 1024 texture, the "pixels" are actually 32-pixel blocks of soft color. Downscale to true target resolution OR set `Filter: Nearest` so the up-rendering doesn't smooth.
-- **No `Filter: Nearest`.** Default Godot texture filtering is bilinear. Pixel art bilinearly filtered looks like garbage. Set it on import or project-wide.
-- **No negative prompt.** Without `blurry, anti-aliasing, gradients, soft edges` in the negative, ~50% of generations are off-style.
+- **No `Filter: Nearest`.** The default texture filtering is bilinear. Set
+  Nearest on import or project-wide for pixel art.
+- **Reaching for `negative_prompt` or `image_size`.** Neither exists on this tool; both are dropped without an error, so the call looks like it worked and the output is off-style. Negations go in the prompt text; size is fixed.
 - **Inconsistent palette across the cast.** Pick a named palette (PICO-8, NES, custom hex list) and re-use across every asset in the project. Different palettes = the project doesn't read as one game.
 - **Generating walk-cycle frames as one image.** Sprite sheets via single-prompt are unreliable. Route to `summer:2d-assets/sprite-sheet`.
 
@@ -152,13 +166,15 @@ Print the call:
 
 ```
 summer_generate_image(
-  prompt="<pixel art prompt with full anchor>",
+  prompt="<pixel art prompt with full anchor>. Not blurry, no smooth gradients, no anti-aliasing.",
   model="nano-banana-2",
-  style="pixel",
-  options={ image_size: "square_hd", negative_prompt: "blurry, smooth gradients, anti-aliasing" }
+  style="none",
+  options={ removeBackground: true }
 )
 ```
 
+The Summer dashboard *does* expose size and negative-prompt controls that the MCP tool does not — if the user is running it there, tell them to set square + a real negative prompt.
+
 Tell the user to run via the Summer dashboard, downscale in Aseprite/GIMP to true target resolution with nearest-neighbor, then `summer_import_from_url` (or drop into `res://sprites/`) and set `Filter: Nearest`.
 
 If MCP is offline entirely: open Aseprite or Piskel and hand-author the asset. For pixel art at small resolutions, hand-authoring is often faster than fixing a generation.
@@ -177,4 +193,4 @@ After the asset is wired:
 - `summer:2d-assets/sprite-sheet` — animated pixel frames.
 - `summer:2d-assets/character-portrait` — high-res counterpart.
 - `summer:asset-pipeline/asset-strategy` — meta-router.
-- `references/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_image` schema.

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

@@ -11,7 +11,10 @@ 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.
+This skill generates a single equirectangular panoramic image (2:1 aspect,
+e.g. 2048×1024 or 4096×2048) suitable for Summer Engine's
+`PanoramaSkyMaterial`. It wires the image into a `Sky` resource on a
+`WorldEnvironment` node so the sky is visible from every camera angle.
 
 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.
 
@@ -35,7 +38,7 @@ The single biggest failure mode is **non-equirectangular output**. Diffusion mod
 ### 1. Search for an existing sky
 
 ```
-summer_search_assets(query="<vibe> sky panorama", filter={ kind: "image" })
+summer_search_assets(query="<vibe> sky panorama", assetType="2d_image", source="all")
 ```
 
 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.
@@ -55,22 +58,25 @@ Load-bearing phrases:
 - **`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
+### 3. Generate, then fix the aspect yourself
+
+Equirectangular MUST be 2:1 (width = 2× height). **`summer_generate_image` cannot give you that.** The tool takes only `prompt`, `model`, `style`, `referenceImageUrl`, and `options` — there is no aspect or size argument, so every MCP image comes back at the server's 1:1 default. `aspectRatio` and `image_size` inside `options` are not recognized and are dropped without an error; the underlying provider does support 2:1-class aspect ratios, but nothing on this surface lets you request one.
 
 ```
 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",
+  prompt="dramatic fantasy sky, golden hour, large purple-orange clouds, distant mountains silhouetted at very bottom, soft god-rays, 360 degree panoramic equirectangular projection, wide 2:1 panoramic framing, seamless horizontal wrap, no visible seam, no foreground objects, sky only. No vertical seam, no ground objects, no horizon-level detail, not distorted or warped, no characters, no buildings.",
   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"
-  }
+  style="realistic"
 )
 ```
 
-`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.
+Asking for "2:1 panoramic framing" in the prompt biases the composition; it does not change the returned pixel dimensions. So one of these has to happen before the image is usable as a panorama:
+
+- **Generate in the Summer dashboard instead**, which does expose aspect ratio, and bring the 2:1 result back with `summer_import_from_url`. This is the right path when the sky matters.
+- **Or crop the 1:1 result to 2:1** in any image editor before importing. You lose the top and bottom, which is usually acceptable for sky-only content — the zenith and nadir are the least informative regions — but it will clip a sun placed high in frame.
+- **Or use a Polyhaven HDRI**, already 2:1 and better for realistic exteriors.
+
+Do not import a 1:1 image as a `PanoramaSkyMaterial` panorama and call it done — it wraps with obvious horizontal compression.
 
 ### 4. Verify the seam and projection
 
@@ -97,38 +103,28 @@ In the import dock:
 
 ### 6. Wire into WorldEnvironment (3 lines)
 
-```
-summer_add_node(parentPath="/root/Game", type="WorldEnvironment", name="WorldEnvironment")
+This is not three tool calls. `summer_set_resource_property` reaches exactly **one** level into a resource — it takes `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`, and there is no `"a:b:c"` colon-path form for walking Environment → Sky → SkyMaterial. Write the `Environment` (with its `Sky` and `PanoramaSkyMaterial` as sub-resources) as a `.tres`, then attach it in one property set:
 
-summer_set_resource_property(
-  nodePath="/root/Game/WorldEnvironment",
-  resourceProperty="environment:background_mode",
-  value=2  # BG_SKY
+```
+summer_write_file(
+  path="res://environments/fantasy_sunset.tres",
+  content="<Environment .tres: background_mode = 2 (BG_SKY), sky = Sky with a PanoramaSkyMaterial whose panorama is res://art/sky/fantasy_sunset.png, ambient_light_source = 3 (AMBIENT_SOURCE_SKY) if you want IBL>",
+  create_only=true
 )
 
-summer_set_resource_property(
-  nodePath="/root/Game/WorldEnvironment",
-  resourceProperty="environment:sky:sky_material",
-  value="<new PanoramaSkyMaterial with panorama: res://art/sky/fantasy_sunset.png>"
-)
+summer_add_node(scenePath="res://main.tscn", parent=".", type="WorldEnvironment", name="WorldEnvironment")
+summer_set_prop(scenePath="res://main.tscn", path="./WorldEnvironment", key="environment", value="res://environments/fantasy_sunset.tres")
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
-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
-)
-```
+Every scene-mutating tool takes an explicit `scenePath`; node paths are relative to that scene's root (`./`), not absolute `/root/...` runtime paths.
 
 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")
+summer_inspect_node(path="WorldEnvironment")
 ```
 
 Then `summer_play` and look around. Sun in the right place? Seam invisible? Top/bottom okay?
@@ -158,7 +154,7 @@ Then `summer_play` and look around. Sun in the right place? Seam invisible? Top/
 ## 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"`.
+- **Assuming `options.aspectRatio` gave you 2:1.** It is silently ignored — the call succeeds and hands you a square image. A 1:1 or 16:9 panorama wrapped equirectangular has obvious horizontal compression. Crop it, or generate in the dashboard where the control exists.
 - **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.
@@ -180,12 +176,11 @@ 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" }
+  style="realistic"
 )
 ```
 
-User runs via Summer dashboard, then `summer_import_from_url` to `res://art/sky/<name>.png`, sets `Repeat: Disabled`, and wires the WorldEnvironment manually.
+The dashboard is actually the *better* surface for this skill, not just the fallback: it exposes aspect ratio and a real negative prompt, which MCP does not. Tell the user to set 2:1 and a negative of `vertical seam, foreground, distorted, warped, characters, buildings`, then `summer_import_from_url` to `res://art/sky/<name>.png`, set `Repeat: Disabled`, and wire the WorldEnvironment.
 
 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.
 
@@ -204,4 +199,4 @@ After the sky is wired:
 - `summer:2d-assets/tileable-texture` — ground/floor counterpart.
 - `summer:scene-composition` — WorldEnvironment placement and configuration.
 - `summer:asset-pipeline/asset-strategy` — meta-router.
-- `references/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_image` schema.

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

@@ -5,7 +5,7 @@ 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
+allowed-tools: Read Grep Glob Write Edit summer_generate_image summer_slice_asset_sheet summer_get_studio_workflow summer_search_assets summer_import_from_url summer_import_asset_by_id summer_set_resource_property summer_add_node summer_set_prop
 paths: ["assets/**", "sprites/**", "art/sprites/**"]
 ---
 
@@ -18,10 +18,12 @@ This skill produces a grid of animation frames for a 2D character — walk cycle
 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).
+2. **Single-call sheet + auto-slice** (fast; sheet coherence is the gamble, not the cutting) — one prompt asks for the grid, then `summer_slice_asset_sheet` cuts it into individual frame assets server-side. 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).
+There is no single "generate a sprite sheet" tool, but there **is** a shared two-tool sheet pipeline, and it is the same one Studio's Guided "sprite-sheet" workflow runs: `summer_generate_image` produces one sheet, then `summer_slice_asset_sheet({ assetId })` runs the server-side vision slicer that removes the background, detects each frame's bounding box, crops, and uploads every frame as its own asset. Call `summer_get_studio_workflow({ workflowId: "sprite-sheet" })` for the current ordered recipe and its stated limitations. Only Studio's frame-preview and visual timing-review UI is unreachable from MCP — the generation and the slicing both are reachable.
+
+So do not tell the user to cut a generated sheet by hand or in ImageMagick. The cutting is automated; what is unreliable is inter-frame *consistency* inside the generated sheet.
 
 ## When to use
 
@@ -68,33 +70,44 @@ Generate frame 1 (or use existing base). For each subsequent frame, prompt the p
 
 ```
 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",
+  prompt="goblin warrior, walk cycle frame 2 of 6, right leg forward, slight bob upward, identical character, same costume, same palette. Not a different character, not a different costume, no scene 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" }
+  options={ removeBackground: true }
 )
 ```
 
-Repeat for each frame. Save each as `goblin_walk_01.png`, `goblin_walk_02.png`, etc.
+`summer_generate_image` has no `image_size` and no `negative_prompt` — put negations in the prompt text; there is no size argument at all. `options.removeBackground: true` is real and gives you true alpha instead of a prompted "transparent background" the model may paint as a literal checkerboard. `referenceImageUrl` only works on edit-capable models (`nano-banana-2`, `seedream-5-pro`, `nano-banana-lite`, `gpt-image-2`, `gemini-flash`, `flux-2`); `grok-imagine` has no edit endpoint and returns `edit_not_supported`.
 
-After all frames return, either:
+Repeat for each frame. Save each as `goblin_walk_01.png`, `goblin_walk_02.png`, etc.
 
-- 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`).
+After all frames return, wire each as a separate frame in a `SpriteFrames`
+resource. Summer Engine treats them as a sequence; there is no need to
+composite them into one sheet image.
 
-### 3b. Path 2 — Single-call sheet (try once)
+### 3b. Path 2 — Single-call sheet, then auto-slice
 
 ```
 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",
+  prompt="goblin warrior walk cycle, sprite sheet, 6 frames in a horizontal row, identical character across frames, side view, frames clearly separated with empty space between them, consistent lighting, consistent palette. No scene background, no varying lighting, not a different character per frame.",
   model="nano-banana-2",
-  style="pixel",
-  options={ image_size: "landscape_16_9", negative_prompt: "different character per frame, scene background, varying lighting" }
+  style="none",
+  options={ removeBackground: true }
 )
 ```
 
-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.
+There is no `"pixel"` style preset (`style` is `realistic | cartoon | anime | none`; anything else is coerced to `none`), no `image_size`, and no `negative_prompt` — the layout and the negations have to be in the prompt.
+
+Then cut it with the same server-side slicer Studio uses, passing the asset id the generation returned:
+
+```
+summer_slice_asset_sheet(assetId="<generated sheet assetId>")
+```
+
+It returns the source dimensions plus per-slice URLs, names, categories, and bounding boxes. Import the frames you want by id with `summer_import_asset_by_id`.
+
+Inspect the result. If the frames are coherent and the count matches, proceed. If anatomy morphs across the row, or the slicer returns one giant box (items touching / no gaps), fall back to Path 1 or Path 3 — re-prompting with more separation between frames is the first thing to try.
 
 ### 3c. Path 3 — Aseprite manual fallback
 
@@ -104,7 +117,7 @@ Tell the user:
 
 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
+### 4. Import frames into Summer Engine
 
 For per-frame import (Path 1):
 
@@ -125,30 +138,21 @@ 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")
+summer_add_node(scenePath="res://main.tscn", parent="./Goblin", type="AnimatedSprite2D", name="Sprite")
 ```
 
-Create a `SpriteFrames` resource and add an animation named `walk`. For per-frame textures:
+Every scene-mutating tool takes an explicit `scenePath`, and node paths are relative to that scene's root (`./`), not absolute `/root/...` runtime paths.
+
+Building the `SpriteFrames` itself is **not** an MCP job. `summer_set_resource_property` takes five flat arguments (`scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value`) and its `value` is restricted to a single string, number, or boolean — it cannot take a frame array, and there is no `"a:b/c"` colon-path form for reaching nested sub-resources. Author the `SpriteFrames` as a `.tres` with `summer_write_file` and then point the node at it:
 
 ```
-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
-)
+summer_write_file(path="res://sprites/goblin/goblin_frames.tres", content="<SpriteFrames .tres with the walk animation, its frames, speed and loop>", create_only=true)
+summer_set_prop(scenePath="res://main.tscn", path="./Goblin/Sprite", key="sprite_frames", value="res://sprites/goblin/goblin_frames.tres")
+summer_set_prop(scenePath="res://main.tscn", path="./Goblin/Sprite", key="animation", value="walk")
+summer_save_scene(scenePath="res://main.tscn")
 ```
 
-For sheet-based (Path 2): use `AtlasTexture` with one region per frame, then add each AtlasTexture as a frame.
+For sheet-based (Path 2): the slicer already returns individual frame images, so import those and list them as frames. If you would rather keep one packed sheet, declare `AtlasTexture` sub-resources with one region per frame inside the same `.tres`.
 
 ### 6. Trigger from code
 
@@ -198,6 +202,7 @@ func _physics_process(delta):
 - **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.
+- **Sending the user to ImageMagick or Aseprite to *cut* a generated sheet.** `summer_slice_asset_sheet` does that server-side. Hand off the creative work, not the mechanical work.
 
 ## Edge cases
 
@@ -212,7 +217,7 @@ func _physics_process(delta):
 Print the per-frame call sequence:
 
 ```
-Frame 1: summer_generate_image(prompt="<base>", model="nano-banana-2", style="pixel", ...)
+Frame 1: summer_generate_image(prompt="<base>", model="nano-banana-2", style="none", ...)
 Frame 2: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 1>", ...)
 Frame 3: summer_generate_image(prompt="<base + delta>", referenceImageUrl="<frame 2>", ...)
 ...
@@ -236,4 +241,4 @@ After the animation is wired:
 - `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.
-- `references/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_image` schema.

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

@@ -35,7 +35,7 @@ The hard part is "seamless." Most diffusion models violate edge continuity by de
 ### 1. Search for an existing texture
 
 ```
-summer_search_assets(query="<material> tileable", filter={ kind: "image" })
+summer_search_assets(query="<material> tileable", assetType="2d_image", source="all")
 ```
 
 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.
@@ -60,17 +60,16 @@ The load-bearing phrases are:
 
 ```
 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",
+  prompt="weathered red brick wall, seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square format, photographic detail. No vanishing point, no directional shadow, no vignette, no single standout feature, no scene context, no sky, no sun.",
   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"
 )
 ```
 
-`style: "realistic"` is the right default for textures (most are aiming for photographic surface). Switch to `"none"` for stylized/painterly.
+Two things about the arguments:
+
+- **There is no `image_size` and no `negative_prompt`.** `summer_generate_image` takes only `prompt`, `model`, `style`, `referenceImageUrl`, and `options`, and `options` only recognizes Nano Banana provider keys (`seed`, `outputFormat`, `safetyTolerance`, `syncMode`, `systemPrompt`, `limitGenerations`, `thinkingLevel`) plus `removeBackground`. Anything else is dropped without an error, so the call looks like it worked. Put the negations in the prompt text. Square is what you get regardless — MCP images come back at the server's 1:1 default, which is exactly what a tileable texture wants.
+- **`style: "realistic"` is a no-op.** Only `cartoon` and `anime` append anything to the prompt; `realistic` and `none` append nothing, and any other value is coerced to `none`. The photographic look has to come from the prompt (`photographic detail`). Switching to `"none"` for stylized work likewise changes nothing on its own — change the prompt.
 
 ### 4. Import to project
 
@@ -97,27 +96,35 @@ If you see hard horizontal/vertical seams, the edges don't match — regenerate
 
 **On a PlaneMesh (floor/ceiling):**
 
+Every scene-mutating tool takes an explicit `scenePath`; node paths are relative to that scene's root (`./`); `summer_set_prop`'s property argument is named `key`; and `summer_set_resource_property` needs all five of `scenePath`, `nodePath`, `resourceProperty`, `subProperty`, `value` (there is no two-argument form and no `"mesh:size"` colon-path form).
+
+Assigning a bare class name to a resource property auto-instantiates it, so the mesh comes first:
+
 ```
-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)")
+summer_add_node(scenePath="res://levels/level_01.tscn", parent="./Level", type="MeshInstance3D", name="Floor")
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/Floor", key="mesh", value="PlaneMesh")
+summer_set_resource_property(scenePath="res://levels/level_01.tscn", nodePath="./Level/Floor", resourceProperty="mesh", subProperty="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:
+Then the material. `material_override` is a `Material`, and `StandardMaterial3D` is the class name that auto-instantiates:
 
 ```
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/Floor", key="material_override", value="StandardMaterial3D")
 summer_set_resource_property(
-  nodePath="/root/Level/Floor",
+  scenePath="res://levels/level_01.tscn",
+  nodePath="./Level/Floor",
   resourceProperty="material_override",
   subProperty="albedo_texture",
   value="res://art/textures/brick_red.png"
 )
 summer_set_resource_property(
-  nodePath="/root/Level/Floor",
+  scenePath="res://levels/level_01.tscn",
+  nodePath="./Level/Floor",
   resourceProperty="material_override",
   subProperty="uv1_scale",
   value="Vector3(20, 20, 1)"
 )
+summer_save_scene(scenePath="res://levels/level_01.tscn")
 ```
 
 `uv1_scale = (20, 20, 1)` on a 20m plane means the texture tiles 20× across — each tile covers 1m².
@@ -125,8 +132,8 @@ summer_set_resource_property(
 **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)")
+summer_add_node(scenePath="res://levels/level_01.tscn", parent="./Level", type="CSGBox3D", name="WallNorth")
+summer_set_prop(scenePath="res://levels/level_01.tscn", path="./Level/WallNorth", key="size", value="Vector3(10, 3, 0.3)")
 ```
 
 Then attach the same material with `uv1_scale` tuned to wall dimensions.
@@ -141,7 +148,7 @@ Then attach the same material with `uv1_scale` tuned to wall dimensions.
 | 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 |
+| Stylized painterly grass | `stylized painterly grass, Studio Ghibli, seamless tileable, top-down, uniform lighting, no specific blades emphasized, square` | The painterly direction has to be in the prompt; no `style` value produces it |
 | 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)
@@ -167,7 +174,7 @@ Then attach the same material with `uv1_scale` tuned to wall dimensions.
 
 - **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.
+- **Texture must read at very low resolution (mobile, distant LOD).** You cannot request a generation size over MCP anyway — take the default and downscale on import (`Compress: VRAM Compressed`, or set a smaller size in the import dock).
 - **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.
 
@@ -177,10 +184,9 @@ Print the call:
 
 ```
 summer_generate_image(
-  prompt="<material> seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square",
+  prompt="<material> seamless tileable texture, top-down view, uniform lighting, no perspective, no shadows, no specific objects, square. No directional shadow, no single standout feature, no scene context.",
   model="nano-banana-2",
-  style="realistic",
-  options={ image_size: "square_hd", negative_prompt: "perspective, directional shadow, single feature, scene context" }
+  style="realistic"
 )
 ```
 
@@ -202,4 +208,4 @@ After the texture is wired:
 - `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.
-- `references/mcp-tools-reference.md` — `summer_generate_image` schema.
+- `../../../references/mcp-tools-reference.md` — `summer_generate_image` schema.