summer-engine 1.5.0 → 2.2.0

package/skills/scene-and-project/new-project/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: new-project
+description: Use when the user wants a fresh blank Summer Engine project — not from a template. Asks one question (project name) and runs `summer create empty <name>`. Trigger on "new project", "blank project", "empty project", "from scratch", "start fresh", "create new game", "blank canvas", "scaffold a project".
+license: MIT
+compatibility: [Cursor, Claude Code, Codex, Windsurf, Gemini, OpenCode]
+category: scene-and-project
+user-invocable: true
+allowed-tools: Bash Read summer_get_project_context
+paths: ["**/project.godot"]
+---
+
+# /new-project — Scaffold a fresh empty project
+
+When the user wants to start from a blank canvas — not a community template, not a built-in starter scene — this is the path.
+
+## When to use this skill
+
+- "Let's start a new project."
+- "I want to make a [game type] from scratch."
+- "Blank project."
+- "Empty project."
+- "I don't want a template, just a blank starting point."
+
+## When NOT to use this skill
+
+- "Show me templates" / "use a template" → `summer:browse-templates`.
+- "Make me a game" with a defined idea → run `summer:brainstorm-game` first to scope, then come back here once the user knows what they want.
+- "I have an existing Godot project I want to import" → not this skill; have the user run `summer open <path>` directly.
+
+## Steps
+
+### 1. Ask the project name
+
+One question, no menu:
+
+> "What do you want to call your project?"
+
+Default: `my-game`. If they say "anything is fine" or similar, use `my-game` and move on. The directory name is reversible — they can always rename.
+
+### 2. Pick the starting scene
+
+Two built-in options:
+
+- `empty` — root `Node3D` only. Pure blank canvas. Best for: experimentation, when the user knows exactly what they want to build.
+- `3d-basic` — root `Node3D` with `Camera3D`, `DirectionalLight3D`, a floor `MeshInstance3D`, and a `WorldEnvironment`. Best for: first-time users, when "just give me something I can press play on" is the vibe.
+
+If you're not sure which fits, ask:
+
+> "Empty (just a root node) or 3d-basic (camera, light, and a floor — you can press play immediately)?"
+
+If the user has clearly invoked `summer:brainstorm-game` already and the brief calls for 3D, default to `3d-basic` and mention you did. If 2D, use `empty` (we don't ship a 2D-basic yet).
+
+### 3. Create
+
+```
+summer create empty my-game
+```
+
+or
+
+```
+summer create 3d-basic my-game
+```
+
+The command writes `project.godot` and the chosen `main.tscn`. No network call, fast, deterministic.
+
+### 4. Open it
+
+```
+summer run my-game
+```
+
+Confirm the engine launched and the project loaded. If `summer run` fails, run `summer doctor` and surface the failure to the user.
+
+### 5. Don't keep going automatically
+
+After scaffolding, **stop and let the user direct.** A common mistake: fire `summer:fps-controller` or `summer:design-mechanic` automatically because "now we make a game." Wait. The user might want to:
+
+- Brainstorm what to build (`summer:brainstorm-game`)
+- Set the visual direction (`summer:art-direction`)
+- Jump straight into a known mechanic (`summer:design-mechanic`)
+- Build a specific controller (`summer:fps-controller`)
+
+Ask: "Project is open. What do you want to build?"
+
+## Anti-patterns
+
+| Don't | Why |
+|---|---|
+| Skip the name question and use `my-game` silently | The user has opinions about the directory name. Two seconds of asking saves a `mv` later. |
+| Use `summer create 3d-basic` for a 2D game | Wrong starting scene. Use `empty` and let the user/agent build the 2D root from there. |
+| Default to a community template | That's `summer:browse-templates`. This skill is specifically for "blank canvas." |
+| Continue into `summer:fps-controller` automatically | Most users want to brainstorm or set art direction first. Stop and ask. |
+| Run this when the user is in an existing project | Check `summer status` or `summer_get_project_context` first. If a project is already open, the user probably wanted to modify it, not create a new one. |
+
+## Edge cases
+
+- **Engine not running** → that's fine. `summer create` doesn't need the engine. After scaffolding, `summer run <name>` will start it.
+- **User wants 2D but `empty` is the only 2D-friendly built-in** → use `empty`, then in the next breath set up a 2D scene root via `summer_replace_node` (Node3D → Node2D). Mention this — don't surprise the user.
+- **Directory exists** → the CLI errors out. Ask for a different name; don't try to overwrite.
+
+## Closing
+
+End with: "Project `<name>` is created and open. What do you want to build first?"
+
+That's the handoff to whatever skill comes next.

package/skills/scene-and-project/scene-composition/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: scene-composition
-description: How to structure scenes, when to use sub-scenes, node hierarchy conventions, and reusable prefabs. Use when building scenes, organizing nodes, or creating instanced prefabs. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy".
+description: Use when building or organizing scenes in Godot — node hierarchy conventions, when to extract sub-scenes, reusable prefab patterns, instance vs add-node decisions. Trigger on "scene", "sub-scene", "instance", "prefab", "node hierarchy", "scene structure", "PackedScene".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scene-and-project

package/skills/scripting-patterns/gdscript-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gdscript-patterns
-description: Common GDScript idioms — type hints, signals, exports, onready, lifecycle methods, naming conventions. Use when writing GDScript, attaching scripts, or refactoring untyped code. Trigger on "GDScript", "script", "signals", "exports".
+description: Use when writing or refactoring GDScript — type hints, signals, exports, onready, lifecycle methods (`_ready` vs `_process` vs `_physics_process`), `get_node` vs `$NodePath`, naming conventions. Trigger on "GDScript", "script", "signals", "exports", "onready", "_ready", "_process".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: scripting-patterns

package/skills/ui-and-ux/ui-basics/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ui-basics
-description: HUD, menus, health bars, progress bars, and Control-based UI layout. Use when building menus, HUDs, health bars, or any Control-tree UI. Trigger on "UI", "HUD", "menu", "health bar", "Control".
+description: Use when building Godot UI — HUDs, main menus, pause menus, health bars, progress bars, dialogue boxes, or any Control-node tree. Covers anchors, containers (VBox/HBox/Margin), responsive layout, and theme vs inline styling. Trigger on "UI", "HUD", "menu", "health bar", "Control", "anchors", "VBoxContainer", "main menu", "pause menu".
 license: MIT
 compatibility: [Cursor, Claude Code, Windsurf, Codex]
 category: ui-and-ux

package/skills/video/animated-loop/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: animated-loop
+description: Use when generating a short looping video clip — splash screen background, animated logo backdrop, idle title-screen footage, looping environment ambience. Output must loop seamlessly and is wired as a VideoStreamPlayer with autoplay and loop set true. Trigger on "looping background", "splash loop", "title screen video", "animated backdrop", "menu background loop", "ambient loop video", "looping clip", "seamless loop".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: video
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_generate_image summer_search_assets summer_import_from_url summer_add_node summer_set_prop
+paths: ["assets/video/**", "menus/**", "ui/**"]
+---
+
+# animated-loop — 3-5 Second Seamless Background Loop
+
+A loop is the only video format that has to *not have* a beginning or end. The viewer sees it on the title screen for 30 seconds; if the seam between loop iterations is visible, the whole thing reads as broken. This skill exists to force the constraints that make seams invisible: keep the duration short (3-5s), keep the motion ambient (no narrative, no big camera moves), use the cheap fast model (`ltx`), and prompt for a composition where the first and last frames are functionally identical.
+
+If the user wants a 5s punchy marketing shot, that's `video/trailer-shot`. If they want a 10s narrative cutscene, that's `video/cinematic-cutscene`. This skill is the one for video that has to *disappear* — atmosphere behind a logo, mood behind a menu, ambience behind a splash card.
+
+## When to use
+
+- "Looping background for the title screen."
+- "Animated backdrop behind the logo on the splash."
+- "Menu background — torchlit dungeon, just flicker and motes."
+- "Looping ambient video for the pause screen."
+- "Splash loop — fog over a forest."
+- "Need a video that loops behind the level select."
+
+## When NOT to use
+
+- Marketing shot for a trailer (5-10s with punch) — `video/trailer-shot`.
+- Narrative cutscene with a beginning and end — `video/cinematic-cutscene`.
+- Static splash image — generate with `2d-assets/concept-art` and use a `TextureRect`. A still is cheaper, lighter, and never seams.
+- UI element animation (icons, button states) — those are GDScript `Tween` or sprite sheets, not video.
+- A 10-second shot you want to "loop". That seam will be visible. Either accept a hard cut every 10s (ugly) or generate a 3-5s clip designed to loop.
+
+## Steps
+
+### 1. Confirm the loop will be visible for a long time
+
+> Quick check — this loop will play on a screen the user might stare at for 30+ seconds. That means the loop point must be invisible. I'll keep it 3-5s and prompt for ambient motion (drift, flicker, shimmer) rather than a narrative beat. OK?
+
+If the user wants narrative motion (a character walking, a door opening), this is the wrong skill — route to `video/cinematic-cutscene`.
+
+### 2. Pick the model — `ltx` first, always
+
+For loops, `ltx` is correct ~95% of the time. It's $0.10, ~30s, and the constraints (short duration, ambient motion) are exactly the ones `ltx` handles best. Premium models add cost without adding loop quality.
+
+| Model | Cost | Speed | When |
+|---|---|---|---|
+| `ltx` | ~$0.10 | ~30s | Default. Use this. |
+| `kling` | ~$0.50 | 2-4 min | Only if the loop is the centerpiece of a premium splash and quality is visibly lacking on `ltx` |
+| `kling-turbo` | ~$0.30 | 1-2 min | Same as `kling` but faster |
+| `veo3` | ~$1.00 | 3-5 min | Almost never — `veo3` shines on dialogue/identity, neither matters for ambient loops |
+| `minimax` | ~$0.40 | 2-3 min | Stylized / anime aesthetic loops |
+
+### 3. Lock the look with a reference still
+
+The reference still doubles as the *target* loop frame. Generate it deliberately — the video model's first and last frames will gravitate toward the reference, which is exactly what you want for a closing seam.
+
+```
+summer_generate_image(
+  prompt="<subject>, ambient atmospheric scene, cinematic lighting, painterly, balanced composition with no clear focal action",
+  model="nano-banana-2",
+  options={ image_size: "landscape_16_9" }
+)
+```
+
+For vertical menus (mobile portrait splash), generate at portrait and use `aspectRatio="9:16"` on the video call.
+
+### 4. Prompt for loopable motion only
+
+Loopable motion is **continuous, ambient, directionless, or oscillating**. Avoid anything with a beginning or end (a character entering, a sword swinging, a door closing).
+
+Loopable verbs: `drift`, `flicker`, `swirl`, `shimmer`, `sway`, `pulse`, `glow`, `rise`, `fall`, `wave`, `breathe`, `ripple`.
+
+Non-loopable verbs (avoid): `walks`, `enters`, `appears`, `emerges`, `transforms`, `attacks`, `falls down`, `opens`, `closes`.
+
+```
+summer_generate_video(
+  prompt="<subject from reference>, <ambient loopable motion>, slow continuous, looping, seamless, cinematic",
+  model="ltx",
+  imageUrl="<reference URL from step 3>",
+  duration=4,
+  aspectRatio="16:9",
+  options={ negative_prompt: "sudden movement, character action, narrative event, fade to black" }
+)
+```
+
+The phrase **"looping, seamless"** in the prompt biases the model toward stable first/last frames. The negative prompt rules out narrative drift.
+
+### 5. Inspect the seam
+
+Watch the result and the seam (the cut between the last and first frame on replay). If the seam is visible:
+
+- **Most common cause:** something moved across the frame and didn't return (a particle drifted off-screen, a cloud moved). Regenerate with `slow continuous, returning motion, oscillating` in the prompt.
+- **Second cause:** lighting drifted. Regenerate with `constant lighting, no time of day change`.
+- **Third cause:** the duration was too long. Drop from 5s to 3s and regenerate.
+
+If three regenerations don't seam-close, accept a small crossfade in the engine: set up two `VideoStreamPlayer` nodes and crossfade between them via a `Tween`. This is a fallback, not the goal.
+
+### 6. Import and wire as a looping VideoStreamPlayer
+
+```
+summer_import_from_url(url="<fileUrl>", path="assets/video/loops/title_screen_bg.ogv")
+```
+
+Note: Godot's `VideoStreamPlayer` natively plays Ogg Theora (`.ogv`); for `.mp4` you may need to transcode or rely on the engine's bundled WebM/MP4 plugin. Studio's import pipeline handles transcoding when the path extension is set explicitly — confirm the resulting resource type with `summer_inspect_resource` if playback fails.
+
+```
+summer_add_node(parent="./TitleScreen", type="VideoStreamPlayer", name="BackgroundLoop")
+summer_set_prop(path="./TitleScreen/BackgroundLoop", property="stream", value="res://assets/video/loops/title_screen_bg.ogv")
+summer_set_prop(path="./TitleScreen/BackgroundLoop", property="autoplay", value=true)
+summer_set_prop(path="./TitleScreen/BackgroundLoop", property="loop", value=true)
+summer_set_prop(path="./TitleScreen/BackgroundLoop", property="expand", value=true)
+summer_set_prop(path="./TitleScreen/BackgroundLoop", property="anchors_preset", value=15)
+```
+
+Anchors preset 15 is "full rect" — the loop fills the menu. Place the logo and menu buttons as children *above* the `VideoStreamPlayer` in the tree (Godot draws siblings in tree order; later siblings render on top).
+
+### 7. Mute the audio track
+
+Loops should never have a baked audio track that loops with them — the audio seam will be even more obvious than the visual one. The video models don't generate audio anyway, but if you ever import a clip that has audio, mute it:
+
+```
+summer_set_prop(path="./TitleScreen/BackgroundLoop", property="volume_db", value=-80)
+```
+
+Score the menu separately with `audio/music-track`.
+
+## Reference card — prompts that work
+
+Pattern: `<subject> + <ambient loopable motion> + <constant lighting> + "looping, seamless" + <stylistic anchor>`. Keep under 40 words. Always pair with `imageUrl`.
+
+| Goal | Model | Prompt | Cost | Duration |
+|---|---|---|---|---|
+| Title menu — fog forest | `ltx` | `dense pine forest in low fog, fog drifting slowly between trunks, soft moonlight, ambient particles rising, looping, seamless, cinematic painterly` | $0.10 | 4s |
+| Title menu — dungeon torch | `ltx` | `stone dungeon corridor lit by a single torch, flame flickering steadily, dust motes drifting in the light cone, looping, seamless` | $0.10 | 4s |
+| Splash — embers / sky | `ltx` | `dusk sky with slow drifting embers rising upward across frame, deep blue gradient, looping, seamless, cinematic` | $0.10 | 5s |
+| Logo backdrop — magic runes | `ltx` | `dark surface with glowing blue runes pulsing softly in slow rhythm, faint shimmer, no narrative motion, looping, seamless` | $0.10 | 3s |
+| Menu — underwater | `ltx` | `underwater scene with caustic light dancing on a sandy floor, slow drifting bubbles, gentle current sway on kelp, looping, seamless` | $0.10 | 5s |
+| Pause screen — slow rain | `ltx` | `window pane with continuous gentle rain drops, blurred warm interior glow behind, looping, seamless, ambient` | $0.10 | 4s |
+| Title — anime sky | `minimax` | `anime style cumulus clouds drifting slowly across a pastel sunset sky, soft, painterly, looping, seamless, Ghibli` | $0.40 | 4s |
+| Premium splash centerpiece | `kling` | `dragon silhouette breathing in profile against a vast sunset sky, only the chest rising and falling and clouds drifting, looping, seamless` | $0.50 | 5s |
+
+### Bad prompts and why
+
+| Bad | Why it fails |
+|---|---|
+| `looping background of a hero walking through a forest` | "Walking" is non-loopable — the hero arrives and departs. Replace with `forest with fog drifting`. |
+| `dramatic title screen video` | "Dramatic" implies narrative beats; loops want ambient. Specify the ambient motion. |
+| `make it 10 seconds and loop` | 10s loops show their seam. Drop to 5s. |
+| `epic looping background trending on artstation` | Adjective slop. The model already knows "cinematic"; the rest hurts. |
+| `the door slowly opens, looping` | Doors don't loop — they open once. The clip will hard-cut on replay. |
+
+## Anti-patterns
+
+- **Asking the model for a 10s loop.** Past ~6s, identity drifts and the seam shows. Cap at 5s.
+- **Spending `kling` money on a loop.** `ltx` is the right call ~95% of the time. The constraints favor the cheap model.
+- **Prompting narrative motion.** "Hero draws sword" doesn't loop. Use ambient verbs.
+- **Forgetting `loop=true` on the `VideoStreamPlayer`.** The clip will play once and freeze on the last frame.
+- **Forgetting to mute baked audio.** If audio is on, the loop point becomes audible even if it's invisible.
+- **Using `aspectRatio="16:9"` for a portrait splash.** Pillarboxed loops on a vertical splash look broken. Set `9:16` and frame portrait.
+- **Importing without transcoding to a Godot-friendly container.** `VideoStreamPlayer` natively wants Ogg Theora; `.mp4` works with the bundled plugin but isn't guaranteed across platforms — confirm with `summer_inspect_resource`.
+
+## Edge cases
+
+- **Splash loop must be tiny in build size.** Loops compress aggressively because of low motion. Target ≤2MB by exporting at 720p, low bitrate, in DaVinci. Studio's import doesn't re-encode by default.
+- **Mobile portrait splash.** `aspectRatio="9:16"`, reference image at portrait, anchors preset 15 still works.
+- **Loop must sync to a music beat.** The video model doesn't know your BPM. Generate at the duration matching one bar at the menu music tempo (e.g. 120 BPM × 4 beats = 2s, or 8 beats = 4s) and confirm visually.
+- **Loop is behind translucent UI.** Generate with extra contrast headroom — the model tends toward mid-grey, and translucent UI on mid-grey reads muddy. Push for `high contrast cinematic` in the prompt.
+- **Loop seam still visible after 3 regens.** Set up two `VideoStreamPlayer` siblings and crossfade between them with a `Tween` on a 0.5s overlap. Costs an extra GPU decode but hides the seam.
+
+## Fallback (no MCP)
+
+If the Studio MCP server isn't running, route the user to the Studio web dashboard:
+
+1. Image tab → generate the reference still (the loop's "neutral frame").
+2. Video tab → image-to-video with `ltx`, duration 4s, aspect ratio per target.
+3. Prompt with the loopable-motion vocabulary above and `"looping, seamless"`.
+4. Download the result, transcode to `.ogv` if needed, place under `assets/video/loops/`.
+
+Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard.
+
+## Handoff
+
+Once the loop is wired:
+
+> Loop `title_screen_bg` is wired to `TitleScreen/BackgroundLoop` with autoplay + loop. Next:
+> - Score the menu with `audio/music-track` — a quiet ambient bed scored to the loop's mood.
+> - For the logo and menu UI on top, hand off to `2d-assets/ui-graphics`.
+> - If the user wants a punchy 5s shot for the trailer using the same look, hand off to `video/trailer-shot` (reuse the reference image).
+> - If the user wants a narrative intro that plays *before* the title loops, hand off to `video/cinematic-cutscene`.
+
+## See also
+
+- `video/trailer-shot` — punchy marketing footage.
+- `video/cinematic-cutscene` — narrative cutscenes with dialogue.
+- `audio/music-track` — score the menu.
+- `2d-assets/ui-graphics` — logo, menu buttons, HUD that sits over the loop.
+- `2d-assets/concept-art` — produce the reference still that anchors the loop.
+- `_shared/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

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

@@ -0,0 +1,204 @@
+---
+name: cinematic-cutscene
+description: Use when generating a non-interactive cutscene clip — opening scene, story beat, character intro, ending. Locks the look with a reference image, image-to-videos a 5-10s shot, optionally adds TTS dialogue, and wires it as a VideoStreamPlayer that fades in/out. Trigger on "cutscene", "intro cinematic", "opening scene", "ending cinematic", "story beat video", "character intro video", "in-engine cinematic", "non-playable scene".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: video
+user-invocable: true
+allowed-tools: Read Grep Glob Write Edit summer_generate_video summer_generate_image summer_generate_audio summer_search_assets summer_import_from_url summer_add_node summer_set_prop
+paths: ["assets/video/**", "cinematics/**", "trailers/**"]
+---
+
+# cinematic-cutscene — Locked-Look Story Beat in 5-10 Seconds
+
+A cutscene is a non-interactive video clip the game plays back at a fixed moment — opening, story beat, character intro, ending. Quality is dominated by **two things**: continuity (the character on screen looks like the character in the game) and shot length (every clip past 10s drifts in identity, hands, and physics). This skill enforces both — generate a reference image first to lock the look, then image-to-video each shot, then chain shots in sequence rather than asking the model for one long take.
+
+If the user wants 5 seconds of marketing footage, that's `video/trailer-shot`. If they want a 3-second seamless background loop, that's `video/animated-loop`. This skill is for narrative beats with a defined start, middle, and end — usually with dialogue or VO.
+
+## When to use
+
+- "Generate the opening cinematic for the game."
+- "I need a cutscene where the witch turns to the player and warns them about the curse."
+- "Make a 10-second character intro for the boss."
+- "Add an ending sequence after the player defeats the dragon."
+- "Cinematic where the village burns and the protagonist runs."
+- The user has a defined moment with story content — not a vibe loop, not a marketing splash.
+
+## When NOT to use
+
+- "5-second slow-mo combat shot for the trailer" — `video/trailer-shot`.
+- "Looping splash screen background" — `video/animated-loop`.
+- "Animated logo backdrop on the title screen" — `video/animated-loop`.
+- Real-time in-engine cinematic with the actual gameplay characters and camera — that's a Godot AnimationPlayer / Timeline job, not generated video. Route to `summer:scene-composition`.
+- Voice-only narration over a static image — generate the dialogue with `summer_generate_audio` and use a static `TextureRect`, no video needed.
+
+## Steps
+
+### 1. Read the soul file and any prior cutscenes
+
+```
+Read .summer/GameSoul.md
+summer_search_assets(query="cutscene", filter={ kind: "video" })
+summer_search_assets(query="<character name> reference", filter={ kind: "image" })
+```
+
+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.
+
+### 2. Plan the shot list
+
+Cutscenes longer than 10 seconds are **multiple shots**, not one take. Ask the user to break it down:
+
+> 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, ~$1.50 total on kling**. Confirm before spending.
+
+### 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.
+
+```
+summer_generate_image(
+  prompt="<subject>, <setting>, cinematic lighting, film still, <art style from GameSoul.md>",
+  model="nano-banana-2",
+  options={ image_size: "landscape_16_9" }
+)
+```
+
+Show the user the still and confirm it's the right look before video-ing it. Regenerating a $0.05 still beats regenerating a $0.50 video.
+
+### 4. Pick the model
+
+| Model | Cost | Speed | When |
+|---|---|---|---|
+| `ltx` | ~$0.10 | ~30s | Iteration, blocking shots, B-roll, throwaway tests |
+| `kling` | ~$0.50 | 2-4 min | Hero shots, character cutscenes, anything the player will sit and watch |
+| `kling-turbo` | ~$0.30 | 1-2 min | Same as kling when iteration speed matters more than the last 10% of quality |
+| `veo3` | ~$1.00 | 3-5 min | Pitch decks, premium dialogue scenes with synced lip motion, short-form ad |
+| `minimax` | ~$0.40 | 2-3 min | Stylized / anime-leaning content; better at non-photoreal looks than kling |
+
+Default policy: **`ltx` first** to validate the prompt and shot framing. If it lands the composition but quality is rough, escalate to `kling`. Only reach for `veo3` if dialogue lip-sync matters and the user has approved the cost.
+
+### 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"
+)
+```
+
+Returns `{ asset: { fileUrl } }`. Show the user the URL and ask:
+
+> Shot 1 of 3 done. Land or regenerate? If land, I'll move to shot 2.
+
+### 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 the editor (Godot's 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 audio/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.
+
+### 7. Import and wire as a VideoStreamPlayer
+
+```
+summer_import_from_url(url="<fileUrl>", path="assets/video/cinematics/intro_shot_01.mp4")
+```
+
+Build a controller scene at `cinematics/Intro.tscn`:
+
+```
+summer_add_node(parent=".", type="Control", name="Intro")
+summer_add_node(parent="./Intro", type="ColorRect", name="Fade")   # black, alpha 1.0 → 0.0
+summer_add_node(parent="./Intro", type="VideoStreamPlayer", name="Video")
+summer_set_prop(path="./Intro/Video", property="stream", value="res://assets/video/cinematics/intro_shot_01.mp4")
+summer_set_prop(path="./Intro/Video", property="autoplay", value=true)
+summer_set_prop(path="./Intro/Video", property="expand", value=true)
+summer_set_prop(path="./Intro/Fade", property="anchors_preset", value=15)
+```
+
+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.
+
+## Reference card — prompts that work
+
+Pattern: `<subject> + <action> + <camera move> + <lighting> + <stylistic anchor>`. Keep prompts under 50 words; over-prompting confuses the model. Always pair with `imageUrl` to lock the character.
+
+| Goal | Model | Prompt | Cost | Duration |
+|---|---|---|---|---|
+| Opening establishing shot | `kling` | `wide shot of a fog-shrouded medieval village at dawn, slow dolly-in toward the church spire, warm low sun, cinematic, anamorphic lens flare` | $0.50 | 5s |
+| Character intro (hero turns to camera) | `kling` | `young witch with raven on shoulder turns slowly toward camera, candlelit interior, shallow depth of field, cinematic film still` | $0.50 | 5s |
+| Dialogue close-up (no synced lips) | `kling` | `close-up of a grizzled knight, eyes downcast then looking up, firelight on his face, dust motes, 16mm film grain` | $0.50 | 5s |
+| Dialogue close-up (synced lips) | `veo3` | `close-up of the witch saying "they will come for you at dawn", candlelight, cinematic, shallow DOF` | $1.00 | 5s |
+| 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` | $0.50 | 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` | $0.50 | 5s |
+| Throwaway iteration / blocking | `ltx` | same prompt as above | $0.10 | 5s |
+| Anime / stylized cutscene | `minimax` | `anime-style young swordsman draws blade and steps forward, sakura petals, dramatic wind, Studio Ghibli soft painterly` | $0.40 | 5s |
+
+### Bad prompts and why
+
+| Bad | Why it fails |
+|---|---|
+| `epic cutscene of the hero defeating the boss` | No subject, no shot, no camera. Returns a generic action montage. |
+| `the hero walks into the throne room, kneels before the king, draws his sword and says I refuse to serve, then walks out` | Five events in one prompt. Model picks one (badly) or tries all and renders mush. Split into three shots. |
+| `cinematic 4k masterpiece trending on artstation` | Adjective slop. The model already knows "cinematic"; the rest is dead weight. |
+| `make the character look exactly like in the game` | Words can't anchor identity. Use `imageUrl`. |
+| `the camera does a complex handheld weaving move through the crowd` | Video models render simple camera moves (pan, tilt, dolly, truck) reliably and complex moves badly. Pick one verb. |
+
+## 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.
+- **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.** Burn $0.10 on `ltx` to validate framing and prompt; only spend $0.50 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.
+- **Forgetting to import the file.** `summer_generate_video` returns a `fileUrl` on Cloudinary; until you call `summer_import_from_url`, it isn't in `res://` and the scene can't reference it.
+
+## Edge cases
+
+- **Vertical cutscene for a mobile target.** Set `aspectRatio="9:16"`. Reference image must also be 9:16 — generate it with `image_size: "portrait_16_9"` or the framing will crop wrong on the video.
+- **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.
+
+## Fallback (no MCP)
+
+If the Studio MCP server isn't running, the user can do all of this through the Studio web dashboard at the Summer Engine cloud console:
+
+1. Generate a reference image in the Image tab.
+2. Open the Video tab, paste the reference URL into the image-to-video field.
+3. Set model, duration, aspect ratio, and prompt as listed above.
+4. Download the `.mp4` and drop it into `assets/video/cinematics/` in the project, then re-import via the Godot editor.
+
+Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard verbatim.
+
+## Handoff
+
+Once the cutscene is generated and wired:
+
+> Cutscene `intro` wired at `cinematics/Intro.tscn` with fade in/out and `Video.finished` chained to scene change. Next:
+> - Add the dialogue track with `audio/voice-line` if you haven't yet.
+> - Score the moment with `audio/music-track` — a cutscene without music feels like a placeholder.
+> - For the boss reveal cutscene, run this skill again with the same reference image to keep the witch identity stable.
+> - If you want a 5s "money shot" version for marketing, run `video/trailer-shot` against the same reference.
+
+## See also
+
+- `video/trailer-shot` — marketing footage, 5-10s, maximum visual punch.
+- `video/animated-loop` — seamless looping background clips.
+- `audio/voice-line` — TTS dialogue used inside cutscenes.
+- `audio/music-track` — score the cutscene.
+- `2d-assets/concept-art` — generate the reference image axis if no character reference exists yet.
+- `2d-assets/character-portrait` — produce a high-fidelity locked character portrait for use as `imageUrl`.
+- `_shared/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.