summer-engine 3.8.0 → 4.0.0

package/library/skills/cinematic-cutscene/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: cinematic-cutscene
-description: "Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer."
+description: "Generate a non-interactive cutscene: a reference-locked 5-10s video shot with optional voiced dialogue."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: video
 user-invocable: true
-allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_check_job summer_generate_image summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_video summer_jobs_wait summer_assets_generate_image summer_assets_generate_audio summer_assets_search summer_import_from_url summer_add_node summer_set_prop summer_call
 paths: ["assets/video/**", "cinematics/**", "trailers/**"]
 ---
 
@@ -30,7 +30,7 @@ If the user wants 5 seconds of marketing footage, that's `trailer-shot`. If they
 - "Looping splash screen background" — `animated-loop`.
 - "Animated logo backdrop on the title screen" — `animated-loop`.
 - Real-time in-engine cinematic with the actual gameplay characters and camera — that's an AnimationPlayer job, not generated video. Route to `scene-composition`.
-- Voice-only narration over a static image — generate the dialogue with `summer_generate_audio` and use a static `TextureRect`, no video needed.
+- Voice-only narration over a static image — generate the dialogue with `assets.generate_audio` and use a static `TextureRect`, no video needed.
 
 ## Steps
 
@@ -38,10 +38,10 @@ If the user wants 5 seconds of marketing footage, that's `trailer-shot`. If they
 
 ```
 Read .summer/GameSoul.md
-summer_search_assets(query="<character name> reference", assetType="2d_image", source="all")
+assets.search({ query: "<character name> reference", assetType: "2d_image", scope: "all" })
 ```
 
-`summer_search_assets` has no video filter — `assetType` is one of `2d_image`, `animation`, `3d_model`, `audio`, `music`, `all`, and there is no video member. To find prior cutscene clips, list your own assets with `summer_list_my_assets(query="cutscene")` and read the titles.
+`assets.search` has no video filter — `assetType` is one of `2d_image`, `animation`, `3d_model`, `audio`, `music`, `all`, and there is no video member. To find prior cutscene clips, search your own assets with `assets.search({ query: "cutscene", scope: "mine" })` and read the titles.
 
 If a reference image of the character already exists from a prior `concept-art` or `character-portrait` run, **reuse it** as the `imageUrl` — that single decision is the difference between the character looking like themselves and looking like a stranger.
 
@@ -51,32 +51,32 @@ Cutscenes longer than 10 seconds are **multiple shots**, not one take. Ask the u
 
 > Want this as one 10s shot, or three shots (e.g. wide → close on face → reaction)? Each shot is 5-10s. I'll generate a reference image once, then image-to-video each shot off of it.
 
-Default if the user is vague: **3 shots, 5s each, on kling**. Confirm before spending credits.
+Default if the user is vague: **3 shots, 5s each, on kling**. Confirm before spending credits: `dryRun: true` on a shot's call returns its `estimate` (credits, balance, enough) and renders nothing.
 
 ### 3. Lock the look — generate a reference image first
 
-For any character or hero scene, generate a reference still with `summer_generate_image` *before* generating video. This still drives `imageUrl` on every subsequent shot, so the character is consistent across cuts.
+For any character or hero scene, generate a reference still with `assets.generate_image` *before* generating video. This still drives `imageUrl` on every subsequent shot, so the character is consistent across cuts.
 
 ```
-summer_generate_image(
-  prompt="<subject>, <setting>, cinematic lighting, film still, wide 16:9 framing, <art style from GameSoul.md>",
-  model="nano-banana-2"
-)
+assets.generate_image({
+  prompt: "<subject>, <setting>, cinematic lighting, film still, wide framing, <art style from GameSoul.md>",
+  model: "nano-banana-2",
+  aspectRatio: "16:9"
+})
 ```
 
-`summer_generate_image` has no size or aspect argument — `options.image_size` is dropped without an error and every MCP image comes back at the server's 1:1 default. Ask for the framing in the prompt, or generate the reference in the Summer dashboard (which exposes aspect ratio) and pass its URL. For image-to-video this matters more than usual: the clip's framing is inherited from the reference, so a square reference gives you a square cutscene.
+Set `aspectRatio` to the cutscene's framing (`16:9`, or `9:16` for mobile); `width` and `height` ask for a minimum size. For image-to-video this matters more than usual: the clip's framing is inherited from the reference, so a square reference gives you a square cutscene.
 
 Show the user the still and confirm it's the right look before video-ing it. Regenerating a still costs far less than regenerating a video.
 
 ### 4. Pick the model
 
-**This skill always passes `imageUrl`, which puts every call on the image-to-video route — and that route only accepts three models.** `kling-turbo` and `veo3` are text-to-video only; asking for either with an `imageUrl` set is a 400 `invalid_model`, not a silent downgrade.
+**This skill always passes `imageUrl`, which puts every call on the image-to-video route.** `kling-turbo` and `veo3` are text-to-video only; asking for either with an `imageUrl` set is a 400 `invalid_model`, not a silent downgrade.
 
 | Model | i2v? | Speed | When |
 |---|---|---|---|
 | `ltx` | yes | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
 | `kling` | yes | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
-| `minimax` | yes | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
 | `kling-turbo` | **no** | 1-2 min | Text-to-video only — usable only if you drop the reference image |
 | `veo3` | **no** | 3-5 min | Text-to-video only — usable only if you drop the reference image |
 
@@ -85,24 +85,24 @@ Default policy: **`ltx` first** to validate the prompt and shot framing. If it l
 ### 5. Generate each shot
 
 ```
-summer_generate_video(
-  prompt="<subject does <action>, <camera move>, <lighting>, cinematic, 16mm film grain>",
-  model="kling",
-  imageUrl="<reference image fileUrl from step 3>",
-  duration=5,
-  aspectRatio="16:9"
-)
+assets.generate_video({
+  prompt: "<subject does <action>, <camera move>, <lighting>, cinematic, 16mm film grain>",
+  model: "kling",
+  imageUrl: "<reference image fileUrl from step 3>",
+  duration: 5,
+  aspectRatio: "16:9"
+})
 ```
 
-`duration` accepts **only 5 or 10** — the server coerces anything else to 5. There is no 3s, 4s, 7s or 8s clip.
+On `ltx` and `kling`, `duration` is 5 or 10 — anything else renders 5. The newer models in the `model` list render their nearest supported length.
 
-Video generation is **asynchronous**. The call returns immediately with `{ success, queued: true, jobId, model, resolvedModel, estimatedCost, duration }` and **no `fileUrl`** — the clip is rendered by a background worker. Poll for it:
+`assets.generate_video` always answers at once with a job — `{ status: "running", job: { id } }` and **no `fileUrl`**; the clip is rendered by a background worker. Wait for it:
 
 ```
-summer_check_job(jobId="<jobId from the generate call>")
+jobs.wait({ jobId: "<job.id from the generate call>", timeoutSeconds: 50 })
 ```
 
-Only once the job reports `completed` do you have an asset and a URL. Do not tell the user a shot is done off the back of the generate call — at that moment nothing has rendered yet.
+Call `jobs.wait` again until `finished` is true. Only a finished job with state `done` has the asset and URL in its `result`. Do not tell the user a shot is done off the back of the generate call — at that moment nothing has rendered yet.
 
 `aspectRatio` is applied on the text-to-video path only; on image-to-video the framing comes from the reference image, so a `9:16` cutscene needs a `9:16` reference, not a `9:16` argument.
 
@@ -112,14 +112,14 @@ When the job completes, show the user the URL and ask:
 
 ### 6. Generate dialogue audio (if the scene has dialogue)
 
-Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `summer_generate_audio`. Generate it separately and an AnimationPlayer or your `cinematics/` controller scene syncs them.
+Cutscene dialogue is TTS, not in the video model. The video model can render mouth motion that *looks* like talking, but the audio comes from `assets.generate_audio`. Generate it separately and an AnimationPlayer or your `cinematics/` controller scene syncs them.
 
 ```
-summer_generate_audio(
-  capability="text_to_speech",
-  text="They'll come for you at dawn. Run while you can.",
-  voiceId="<from audio bible — see voice-line>"
-)
+assets.generate_audio({
+  capability: "text_to_speech",
+  text: "They'll come for you at dawn. Run while you can.",
+  voiceId: "<from audio bible — see voice-line>"
+})
 ```
 
 Lip-sync caveat: if the video shows the character clearly mouthing words and the audio is a different cadence, viewers notice. Either (a) keep the camera off the character's face during dialogue, (b) accept the asynchrony for a stylized look, or (c) use `veo3` and prompt the dialogue text directly into the video prompt for synced motion.
@@ -146,19 +146,27 @@ Then:
 summer_import_from_url(url="<hosted .ogv url>", path="res://assets/video/cinematics/intro_shot_01.ogv")
 ```
 
-Build a controller scene at `res://cinematics/Intro.tscn`. Every scene-mutating tool takes an explicit `scenePath`, and `summer_set_prop`'s property argument is named `key`, not `property`:
+Build a controller scene at `res://cinematics/Intro.tscn`: create it, then build its nodes in one script (`scenePath` names the new scene; the editor's open tab comes back afterwards):
 
 ```
-summer_create_scene(path="res://cinematics/Intro.tscn", rootName="Intro", allow_temporary_scene_mutation=true)
-summer_add_node(scenePath="res://cinematics/Intro.tscn", parent=".", type="ColorRect", name="Fade")   # black, alpha 1.0 → 0.0
-summer_add_node(scenePath="res://cinematics/Intro.tscn", parent=".", type="VideoStreamPlayer", name="Video")
-summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Video", key="stream", value="res://assets/video/cinematics/intro_shot_01.ogv")
-summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Video", key="autoplay", value=true)
-summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Video", key="expand", value=true)
-summer_set_prop(scenePath="res://cinematics/Intro.tscn", path="./Fade", key="anchors_preset", value=15)
-summer_save_scene(scenePath="res://cinematics/Intro.tscn")
+summer_create_scene(path="res://cinematics/Intro.tscn", rootName="Intro", rootType="Control")
+summer_run_script(scenePath="res://cinematics/Intro.tscn", source="""
+func run(ctx):
+    var video = ctx.add_node("VideoStreamPlayer", "Video", null, {
+        "stream": load("res://assets/video/cinematics/intro_shot_01.ogv"),
+        "autoplay": true,
+        "expand": true,
+    })
+    video.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+    var fade = ctx.add_node("ColorRect", "Fade", null, {"color": Color(0, 0, 0, 1)})   # black, alpha 1.0 -> 0.0
+    fade.set_anchors_and_offsets_preset(Control.PRESET_FULL_RECT)
+    fade.mouse_filter = Control.MOUSE_FILTER_IGNORE
+    ctx.save_scene()
+""")
 ```
 
+`Fade` comes after `Video` in the tree, so it draws on top of it.
+
 Attach a `Tween` script that fades the `ColorRect` from black to clear over 0.5s on `_ready`, then back to black when `Video.finished` fires, then `queue_free()`s the scene. For multi-shot cutscenes, queue the next `VideoStreamPlayer` in the `finished` signal handler.
 
 For dialogue, add an `AudioStreamPlayer` sibling with the TTS clip and call `play()` in `_ready` after a small delay matching where the line lands in the video.
@@ -176,7 +184,7 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 | Action beat (village burns) | `kling` | `medium wide of a thatched village engulfed in flames at night, embers rising, silhouettes running through smoke, hand-held camera, cinematic` | 5s |
 | Ending shot (hero walks away) | `kling` | `low wide shot of a cloaked figure walking away across a blasted plain at sunset, slow truck-back, golden hour, dust on the wind` | 5s |
 | Throwaway iteration / blocking | `ltx` | same prompt as above | 5s |
-| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | 5s |
+| Anime / stylized cutscene | `kling` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | 5s |
 
 ### Bad prompts and why
 
@@ -191,23 +199,27 @@ Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>
 ## Anti-patterns
 
 - **Generating a 10s shot when you should chain two 5s shots.** Identity, hand consistency, and physics drift every additional second past ~6s. Two 5s shots cut together look better and cost the same.
-- **Skipping the reference image.** Generating four character cutscenes from text prompts alone produces four different-looking people. Always lock the look with `summer_generate_image` first, then `imageUrl` every subsequent video call.
+- **Skipping the reference image.** Generating four character cutscenes from text prompts alone produces four different-looking people. Always lock the look with `assets.generate_image` first, then `imageUrl` every subsequent video call.
 - **Asking the video model to render dialogue without `veo3`.** `kling` and `ltx` will animate mouths but the motion does not match any audio. Use `veo3` if dialogue is on-camera, or keep the camera off the speaker.
 - **Using `kling` for blocking iterations.** Validate framing and prompt on the cheaper `ltx` first; move to `kling` once the composition lands.
 - **Putting the cutscene on a `VideoStreamPlayer` without a fade.** Cuts straight from gameplay to video are jarring. Always wrap in a `ColorRect` fade in/out.
-- **Treating `summer_generate_video` as synchronous.** It returns `{ queued: true, jobId }` and no URL. You must poll `summer_check_job` before there is anything to show or import.
+- **Treating `assets.generate_video` as finished.** It answers `{ status: "running", job }` and no URL. Wait with `jobs.wait` until the job is done before there is anything to show or import.
 - **Importing the `.mp4` as-is.** The engine has no MP4 or WebM loader — only Ogg Theora (`.ogv`). Transcode first; an un-transcoded import fails and is rolled back.
-- **Asking for `duration=3` or `duration=8`.** Only 5 and 10 exist; anything else is silently coerced to 5.
+- **Asking `ltx` or `kling` for `duration: 3` or `duration: 8`.** On those two only 5 and 10 exist; anything else renders 5.
 - **Pairing `imageUrl` with `kling-turbo` or `veo3`.** Neither has an image-to-video endpoint — that combination is a 400.
 
 ## Edge cases
 
-- **Vertical cutscene for a mobile target.** On the image-to-video path `aspectRatio` is not applied at all — the clip inherits the reference image's framing. So the reference *must* be 9:16, and MCP image generation cannot produce that: make it in the Summer dashboard, or crop a square generation to 9:16, then pass its URL as `imageUrl`.
+- **Vertical cutscene for a mobile target.** On the image-to-video path `aspectRatio` is not applied at all — the clip inherits the reference image's framing. So the reference *must* be 9:16: generate it with `aspectRatio: "9:16"`, then pass its URL as `imageUrl`.
 - **Cutscene must match an in-engine character precisely.** No video model will hit pixel-perfect identity. Either (a) accept the artistic license, (b) render the cutscene in-engine with `AnimationPlayer` instead of generating it, or (c) generate a reference image *from* a screenshot of the in-engine character (image-to-image first, then image-to-video).
 - **Dialogue is too long for a 5s shot.** Either trim the line, or split: 5s of speaker, 5s of listener reaction (cheaper because the listener doesn't need synced lips).
 - **Cutscene needs to play and the player isn't looking.** Pause the gameplay timer, push a `Control` overlay with the `VideoStreamPlayer`, restore on finish.
 - **Multi-shot continuity.** Use the same reference image as `imageUrl` across all shots. If lighting differs by shot, generate one reference per lighting setup, not one per shot.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), do steps 1-6 and skip step 7 (`VideoStreamPlayer`). Skip the soul-file read in step 1 when the project has no `.summer/` folder. Save the file where the person asked with `out` (the `summer-assets` skill says how), and tell them the path and format. Each shot is an MP4 and each dialogue line an audio file; the person cuts them together in their own editor.
+
 ## Fallback (no MCP)
 
 If the MCP server isn't running, the user can do all of this in the Summer dashboard:
@@ -237,4 +249,4 @@ Once the cutscene is generated and wired:
 - `music-track` — score the cutscene.
 - `concept-art` — generate the reference image axis if no character reference exists yet.
 - `character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_video`; `summer_search` returns its exact input.

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

@@ -1,7 +1,7 @@
 id: skill/cinematic-cutscene
 kind: skill
 version: 1.0.4
-summary: Generate a non-interactive cutscene — reference-locked look, a 5-10s image-to-video shot, optional TTS dialogue — wired as a fading VideoStreamPlayer.
+summary: "Generate a non-interactive cutscene: a reference-locked 5-10s video shot with optional voiced dialogue."
 use_when:
   - generating a non-interactive cutscene clip — opening scene, story beat, character intro, ending
   - a story beat needs a short pre-rendered clip between gameplay sections — intro, transition, ending

package/library/skills/combat-basics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: combat-basics
-description: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+description: "Damage: hitbox and hurtbox Areas, a reusable Health component, damage signals, knockback, projectiles."
 license: MIT
 compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
 category: gameplay-mechanics

package/library/skills/combat-basics/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/combat-basics
 kind: skill
 version: 1.0.0
-summary: "Damage in Summer Engine: hitbox and hurtbox Areas on opposing layers, a reusable Health component, damage signals, knockback, hit feedback, projectiles."
+summary: "Damage: hitbox and hurtbox Areas, a reusable Health component, damage signals, knockback, projectiles."
 use_when:
   - adding attacks, health and damage, or enemies that can be hit and hit back
   - adding projectiles or bullets — homing, piercing, area-of-effect, or pooling hundreds of them

package/library/skills/compatibility-renderer-traps/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: compatibility-renderer-traps
-description: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+description: "Make a Forward+ game look right on the Compatibility renderer: instance uniforms, MultiMesh, vertex colors."
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: rendering-and-lighting

package/library/skills/compatibility-renderer-traps/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/compatibility-renderer-traps
 kind: skill
 version: 1.0.0
-summary: "Make a Forward+ Summer game also look right on the Compatibility renderer: instance-uniform budget, black MultiMesh colors, sRGB vertex colors."
+summary: "Make a Forward+ game look right on the Compatibility renderer: instance uniforms, MultiMesh, vertex colors."
 use_when:
   - a game must run on phones or weak GPUs that may use the Compatibility or Mobile renderer
   - objects render black, pale or stop animating on one renderer but not another

package/library/skills/concept-art/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: concept-art
-description: "Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset."
+description: "Explore art direction with 3-4 rough concept variants of a character, environment or prop."
 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
+allowed-tools: Read Grep Glob Write Edit summer_assets_generate_image summer_assets_search summer_import_from_url summer_call
 paths: ["assets/**", "art/**", "concepts/**"]
 ---
 
@@ -44,7 +44,7 @@ If "final" → hand off to `character-portrait`. If "explore" → continue.
 ### 2. Search for prior concepts
 
 ```
-summer_search_assets(query="<subject> concept", assetType="2d_image", source="all")
+assets.search({ query: "<subject> concept", assetType: "2d_image", scope: "all" })
 ```
 
 If something already exists, ask if the user wants to riff on it (img2img via `referenceImageUrl`) or start fresh.
@@ -68,16 +68,16 @@ State the axis to the user before generating: "I'll vary on **stylization** —
 Issue 3-4 calls in parallel, one per variant. Use the same subject phrasing across all four; only the style-modifier changes.
 
 ```
-summer_generate_image(
-  prompt="<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting, wide cinematic framing",
-  model="nano-banana-2",
-  style="none"
-)
+assets.generate_image({
+  prompt: "<subject>. <axis variant 1>. concept art, evocative, rough painterly, atmospheric lighting, wide cinematic framing",
+  model: "nano-banana-2",
+  style: "none"
+})
 ```
 
 `style: "none"` is intentional: only `cartoon` and `anime` append anything to the prompt, `realistic` and `none` append nothing, and any other value is coerced to `none`. So the preset cannot override the prompt's stylistic direction — it just contributes nothing, which is what concept art wants. All four variants' divergence has to come from the prompt.
 
-For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine. Background removal is the top-level `removeBackground` argument, not an `options` key.
+For a shape other than square, pass `aspectRatio` (`"16:9"`, `"9:16"`, ...) or `width` + `height`; the result reports the real width and height and the model that ran. Exploration images are thrown away, so square is usually fine. Background removal is the `removeBackground` argument (there is no `options` object). Four variants are four charges: `dryRun: true` on one call shows its credits.
 
 ### 5. Present the batch
 
@@ -124,13 +124,17 @@ The structure: **subject + axis variant + "concept art" + lighting/atmosphere**.
 - **Subject is a fully described scene, not an asset.** You're producing key art, not asset reference. Pass `aspectRatio: "16:9"` (or `width: 1920, height: 1080` for store key art) and bias toward atmospheric.
 - **User wants the final to be 3D.** After they pick a direction, route to `asset-strategy` — concept-art images are not 3D-ready references (they have backgrounds, scene context, dramatic lighting baked in). The 3D pipeline needs its own clean white-background reference.
 
+## Without Summer Engine
+
+In a session without Summer Engine tools (the assets profile; the `summer-assets` skill has the whole loop), every step works. Pass `out` with the person's folder so the batch lands there (the `summer-assets` skill says how), and skip `summer_import_from_url`.
+
 ## Fallback (no MCP)
 
 Print the 4 prompts and the call for each:
 
 ```
-summer_generate_image(prompt="<variant 1>", model="nano-banana-2", style="none")
-summer_generate_image(prompt="<variant 2>", ...)
+assets.generate_image({ prompt: "<variant 1>", model: "nano-banana-2", style: "none" })
+assets.generate_image({ prompt: "<variant 2>", ... })
 ...
 ```
 
@@ -150,4 +154,4 @@ Once the user picks a direction:
 
 - `asset-strategy` — meta-router that delegates here vs other 2d-assets skills.
 - `character-portrait` — the polished single-image counterpart.
-- `../../references/mcp-tools-reference/mcp-tools-reference.md` — `summer_generate_image` parameter schema.
+- `summer_docs_read` id `reference/mcp-tools-reference` — how to call `assets.generate_image`.

package/library/skills/concept-art/resource.yaml

@@ -1,7 +1,7 @@
 id: skill/concept-art
 kind: skill
 version: 1.0.2
-summary: Explore art direction with 3-4 rough concept variants of a character, environment, or prop to pick a vibe before committing to a final asset.
+summary: "Explore art direction with 3-4 rough concept variants of a character, environment or prop."
 use_when:
   - exploring art direction with rough variants before committing to a final asset
   - the user wants a mood board, rough sketches, or 'what could this look like'

package/library/skills/concept-to-level/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: concept-to-level
+description: "Take a 3D map from concept art to a polished, shippable level, with the questions to ask the user, owned lanes, render checks and collision kept in step."
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: level-design
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit Bash summer_assets_generate_image summer_assets_generate_3d summer_jobs_wait summer_call summer_screenshot summer_get_scene_tree summer_inspect_node summer_set_prop summer_save_scene summer_get_diagnostics summer_get_script_errors
+paths: ["**/*.tscn", "**/*.gdshader", "**/*.gdshaderinc", "level/**", "levels/**", "docs/**", ".summer/**"]
+---
+
+# concept-to-level — from concept art to a polished level
+
+Use this when a 3D map has to go from "here is the idea" to a level that
+looks finished, plays right online and offline, and runs well. It is the
+process and the judgment; the specialist skills it names do the leaf work.
+
+Distilled from one long build of a 1v1 arena duel map (a white-marble drill
+yard on a mountain peak above the clouds, with god hands that change the
+map mid-match). Its mistakes are the reason most rules below exist.
+
+**Core principle:** agree the look before you build it, build in lanes that
+each own their files, and never call a lane done without a render you have
+opened for the user.
+
+## When to use
+
+- "Turn this concept art into the real map." (3D, shipping quality)
+- "Rework this level's theme, keep the layout."
+- "Polish this map: materials, props, sky, effects."
+- Several agents will work on one map at once.
+
+## When NOT to use
+
+- A 2D or quick playable scene from a reference image: `scene-to-level`.
+- Designing layout, pacing and encounters on paper: `design-level`.
+- One asset: `prop-model`, `environment-kit`, `organic-model`.
+- Only picking a style: `concept-art`, `art-direction`.
+
+## Ask these before you build
+
+Ask in batches of two or three, not all at once. Record the answers in the
+design doc. Each line says why it matters and what broke when it was not
+asked.
+
+**Theme and fantasy**
+- [ ] What is this place, who owns it, what is the player there? *Drives every
+  prop and material choice. "A drill yard where players are guests" gave
+  the map its whole prop list.*
+- [ ] Which reference frames are the bar? Show 3-4 generated options and get
+  a pick. *A god power built from a text brief was rejected twice; three
+  concept images got a clear pick in one reply.*
+
+**Layout and gameplay**
+- [ ] What layout stays, what may change? May colliders, spawns and zones
+  move? *Decides whether you must recompile server collision and update
+  tests.*
+- [ ] Which surfaces are walkable, lethal, or "risky perches"? Where are the
+  ring-outs? *Fall zones need their own checks.*
+- [ ] Should dynamic events (moving hazards, raised platforms, collapsing
+  walls) feel big and slow or quick? Should the warning show where it lands?
+  *The first sliding-hazard warning drew the whole path on the floor; the
+  user found it too easy to dodge.*
+- [ ] What should the fight feel like? *"A battle for the high ground" turned
+  a vague light platform into layered plates with jump routes.*
+
+**Quality and readability**
+- [ ] What is the quality bar for close-ups? *Users inspect props at arm's
+  length: flat untextured parts, floating chains and sticks clipping
+  surfaces all got flagged.*
+- [ ] What must stay readable? Set a number (we used: player silhouettes keep
+  at least 60% of clean brightness under every effect).
+- [ ] How dark or saturated may effects get? *"Dark and evil, red only in thin
+  veins" was a rule we had to learn after a too-red pass.*
+
+**Platform and runtime**
+- [ ] Target hardware and platforms (mobile? integrated laptops?) and frame
+  budget. *Measure early; one decorative set cost a quarter of all triangles.*
+- [ ] Does the map run online? What does the online build strip? *Our online
+  map build removed particle nodes and ran no map scripts.*
+- [ ] What must be baked versus procedural? (Baked = no CPU, cannot react;
+  procedural = can aim and track.) *The floating statue had to be baked; the
+  god hands had to aim procedurally.*
+
+**Rules and process**
+- [ ] Game rules that limit design (rewards, odds, trading, licences)? Which
+  files are off-limits to you?
+- [ ] Deadlines and demos? *Before a demo: stop background work, commit only
+  verified lanes, keep fallbacks.*
+- [ ] Commit, push and PR policy.
+
+## The pipeline
+
+### 1. Frames first
+
+Generate several cheap options with `assets.generate_image` (see
+`concept-art`): an aerial overview, eye level, one per hero element. Get a
+pick. Save the picked frames in the repo next to the design doc and check
+every lane's renders against them. When a lane stalls on taste, generate
+three directions for that element and ask again; do not iterate blind.
+
+### 2. Design doc
+
+One markdown file per map: theme, layout and what is kept, floor, walls,
+backdrop, props, materials rule, effects, dynamic events, performance
+budget, open questions. Every user answer goes in. Lanes read it; you
+update it when the user changes direction.
+
+### 3. Blockout
+
+Rough geometry for everything at final scale, with a visible "not final"
+material. Remaining blockout material is the to-do list. Keep a stand-in
+player capsule for scale in every render.
+
+### 4. Lanes
+
+Split by system, one owner each:
+
+| Lane | Owns |
+|---|---|
+| Floor | ground materials, inlays, spawn floors |
+| Walls / kit | modular kit, ring or room assembly, wall collision |
+| Backdrop | sky, distant terrain, clouds, fog, kill height |
+| Props | cover pieces, set dressing, shared material library |
+| Cloth | banners and flags with sway |
+| Lighting and effects | sun, fire, glows, corruption-style map states |
+| Events | dynamic hazards, their visuals, spec for the server |
+
+The map scene is shared: every lane edits it only through the live editor,
+saves only its own changes, and reports what it touched. See "Running it
+with parallel agents" below.
+
+### 5. Materials rule
+
+No flat, unshaded surface on any model. Every surface gets real PBR textures
+or procedural detail. Specific rules that came from user feedback:
+
+- Bake a cavity/edge mask per prop, and scale edge wear by part thickness:
+  thin bars and chain links read as clean grey plastic otherwise.
+- Wood: plank UVs at real scale, grain along each board's long axis, darker
+  end grain, grime in the joints. Triplanar noise reads as cork.
+- Forged iron near black, rough (0.6-0.8) so curved bands do not mirror the
+  sky; rust only in recesses.
+- Brass: dark tarnish base, polish only on high points and real wear.
+- One shared material library for the map; props reuse it.
+
+### 6. Verify every lane with renders
+
+After each change, render fixed angles: the user's own angle if they sent a
+screenshot, eye level from the play space, a far view, from above. Open the
+images for the user. Compare to the frames. A lane is done when its renders
+pass, not when its script ran.
+
+### 7. Keep gameplay in step
+
+After any collider, spawn or zone change: recompile the server collision
+artifact, update tests that hard-code positions, run the covering tests,
+and only then commit. Moving a structure means re-running everything placed
+relative to it (see the reference file).
+
+### 8. Commit per verified lane
+
+Commit each lane when its renders and tests pass. Stage only that lane's
+files. Never commit files the editor rewrites on its own unless you meant to
+change them.
+
+## Hard-won technical rules
+
+Short list; details and reasons in
+[references/technical-rules.md](references/technical-rules.md).
+
+1. Never run heavy or reloading scripts in the live editor (recoding
+   shaders, reloading scenes, instantiating or freeing what an open scene
+   uses). It hung and crashed the editor. Build headless; import named files.
+2. Render previews from a separate short-lived engine process that loads
+   from disk; call `RenderingServer.force_draw()` before reading the image.
+3. One heavy process at a time, at low priority. Stop everything for demos.
+4. Online builds may strip particle nodes and map scripts. Make fire, sparks
+   and motes from shader-driven meshes; bake map animation into vertex
+   animation textures and set `custom_aabb`.
+5. Edit an open scene only through the live editor; never text-edit it on
+   disk while it is open.
+6. The editor rewrites some project files on its own. Commit surgically.
+7. Keep a fallback scene when swapping in an experimental asset.
+8. Generated 3D models need cleanup and a notices entry; third-party
+   textures need their source and licence recorded.
+9. Modular kits: zero coplanar overlaps, sealed seams, no see-through holes.
+10. Measure render cost early: triangles, draw calls, shadow casters, lights.
+
+## Running it with parallel agents
+
+- One lane per agent, with the files it owns written down. Shared files (the
+  map scene, a shared material library) have one owner per change.
+- Agents report with renders and exact file lists; the coordinator opens the
+  renders, checks them against the frames, and commits per lane.
+- Relay user feedback with concrete fixes ("thin parts read as grey plastic:
+  scale edge wear by thickness"), not the raw complaint alone.
+- When an agent cannot do something (a permission check blocked it), ask the
+  user; do not route around it.
+- Keep the machine cool: one heavy job at a time across all agents.
+- Before a demo: tell every agent to stop, commit only verified work, and
+  keep experiments out of the map.
+
+See `dispatching-parallel-agents` for the general pattern.
+
+## Definition of polished
+
+- [ ] Every surface has a real material; no blockout material left.
+- [ ] No floating, clipping or interpenetrating parts at close range
+      (chains, cloth, props on floors, decals on walls).
+- [ ] Renders from all fixed angles match the reference frames.
+- [ ] Players stay readable under every effect and event.
+- [ ] Spawns are centred, symmetric where the mode needs it, and face play.
+- [ ] Collision matches the visuals (within a few cm); server collision
+      recompiled; tests pass.
+- [ ] Fall zones kill, safe zones are safe, nothing catches falling players.
+- [ ] Works with the online build's limits (no particles or scripts if
+      stripped).
+- [ ] Render cost measured, biggest offenders known, low-end notes written.
+- [ ] Third-party sources and generated assets recorded in the notices.
+- [ ] Design doc matches what shipped.
+
+## Common mistakes
+
+- Building a hero effect before agreeing its look. Generate options first.
+- Splitting or regenerating a kit piece and overwriting the repo copy before
+  the scene that uses it is updated: parts vanish in the live map.
+- Fixing one banner when all banners share the cause. Check the whole set.
+- Calling a lane done from a headless log. Open a render.
+- Moving a room and forgetting the decals, banners, rock and spawns placed
+  around it.
+
+## See also
+
+- `concept-art`, `art-direction`, `design-level`, `scene-to-level`
+- `environment-kit`, `fabricating-assets`, `prop-model`, `tileable-texture`
+- `3d-lighting`, `vfx-fire`, `vfx-dissolve`, `procedural-animation`
+- `headless-scripting`, `bounded-engine-runs`, `verifying-scenes`
+- `tune-performance`, `dispatching-parallel-agents`