summer-engine 2.0.0 → 2.3.0

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.

package/skills/video/trailer-shot/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: trailer-shot
+description: Use when generating marketing or trailer footage — slow-mo combat, dramatic establishing shots, hero beats, splash screens, pitch-deck B-roll. Optimizes for maximum visual punch in 5-10 seconds. Trigger on "trailer", "marketing footage", "Steam capsule video", "splash screen", "hero shot", "pitch deck clip", "promo clip", "money shot", "B-roll".
+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/**", "trailers/**", "marketing/**"]
+---
+
+# trailer-shot — Loud, Confident, 5-10 Seconds of Punch
+
+A trailer shot is not a cutscene and not a loop. It is a single, deliberately-composed beat designed to live inside an edit — Steam capsule video, social cut, pitch-deck reel, Discord teaser, Twitter promo. Every shot has to earn its slot in 5 seconds or less because viewer attention drops past that. This skill produces those shots one at a time, with strong composition references and trailer-grade prompting, then hands the user off to a non-linear editor (DaVinci Resolve, Premiere, CapCut) to chain them. **Studio doesn't ship a video editor** — generation is the part this skill owns; the cutting is yours.
+
+If the user is generating a non-interactive narrative beat with dialogue, that's `video/cinematic-cutscene`. If they want a seamless background loop for a splash screen, that's `video/animated-loop`. This skill is for the punchy stuff — the kind of shot that ends up on the Steam page or in the first 10 seconds of a launch trailer.
+
+## When to use
+
+- "Generate a slow-mo combat shot for the trailer."
+- "I need a hero shot of the boss for the Steam capsule."
+- "Dramatic establishing shot of the kingdom for the pitch deck."
+- "Make a splash-screen video for the title menu."
+- "Some B-roll of the swamp environment."
+- "Money shot — wide low-angle of the dragon roaring at sunset."
+
+## When NOT to use
+
+- Multi-shot story sequence with dialogue — `video/cinematic-cutscene`.
+- Seamless looping background — `video/animated-loop`.
+- Static marketing key art — `2d-assets/concept-art` then `2d-assets/character-portrait`.
+- Animated GIF of UI — that's a screen recording, not a generated video.
+- A literal Steam trailer (the assembled cut) — generate the shots here, then take them to your NLE.
+
+## Steps
+
+### 1. Pick the shot
+
+Trailer shots fall into a small number of archetypes. Pick one before prompting:
+
+| Archetype | Composition | When |
+|---|---|---|
+| **Hero close-up** | Tight on the protagonist or boss, low angle | Reveal a character |
+| **Slow-mo combat** | Mid shot, time dilation, frozen impact | Action sells |
+| **Establishing wide** | Wide landscape, slow dolly-in | Sell a world |
+| **Dolly-in on detail** | Push toward a key prop or face | Build tension |
+| **Whip pan reveal** | Fast pan, lands on a beat | Reveal a turn |
+| **Low-angle hero** | Looking up at the subject, sky framing | Make the subject feel large |
+| **Splash card** | Static composition, atmospheric motion only | Title cards, logos |
+
+State the archetype and composition out loud before generating: "I'll do a low-angle hero shot of the boss, slow tilt-up, golden hour. OK?"
+
+### 2. Lock the look with a reference image (when subject identity matters)
+
+For shots featuring a specific character, weapon, or environment, generate a reference still first and pass it as `imageUrl`. Without it, the boss in your trailer looks different from the boss in the game.
+
+```
+summer_generate_image(
+  prompt="<subject>, <archetype-driven framing>, cinematic, dramatic lighting, film still",
+  model="nano-banana-2",
+  options={ image_size: "landscape_16_9" }
+)
+```
+
+For pure environment / abstract / VFX shots, you can skip this and prompt text-to-video directly.
+
+### 3. Pick the model
+
+| Model | Cost | Speed | When |
+|---|---|---|---|
+| `kling` | ~$0.50 | 2-4 min | Default for trailer hero shots — best motion + composition |
+| `kling-turbo` | ~$0.30 | 1-2 min | Same look as kling, faster, slight quality dip |
+| `veo3` | ~$1.00 | 3-5 min | Pitch deck for investors, the one shot that has to be perfect, premium social ad |
+| `ltx` | ~$0.10 | ~30s | B-roll, throwaway tests, blocking the composition before committing |
+| `minimax` | ~$0.40 | 2-3 min | Anime / stylized trailer looks |
+
+Default: **`ltx` first to block the composition, then `kling` for the final**. For the *one* hero shot that drives the Steam page, escalate to `veo3` only if `kling` failed twice.
+
+### 4. Generate the shot
+
+```
+summer_generate_video(
+  prompt="<archetype framing>, <subject>, <action>, <camera move>, <lighting>, <film grain / lens / stylistic anchor>",
+  model="kling",
+  imageUrl="<optional reference URL from step 2>",
+  duration=5,
+  aspectRatio="16:9"
+)
+```
+
+For vertical social (TikTok, Reels, Shorts): `aspectRatio="9:16"` and frame the subject vertically in your reference image.
+
+For square (Instagram feed): `aspectRatio="1:1"`.
+
+### 5. Review against trailer logic
+
+Show the user the result and ask the trailer-specific questions:
+
+> Shot delivered. Three checks:
+> 1. Does it read in 2 seconds with the sound off? (Trailer viewers are scrubbing.)
+> 2. Is the subject in the frame's golden zone or buried in noise?
+> 3. Would this shot survive being preceded by a hard cut and followed by a hard cut?
+>
+> Land or regenerate?
+
+If "regenerate", revise *one* axis (camera move, lighting, or framing) — don't rewrite the whole prompt. Iteration converges.
+
+### 6. Import for archive (optional)
+
+Trailer footage usually lives on the user's local disk and goes straight into the NLE. But for shots that double as in-engine splash content, import:
+
+```
+summer_import_from_url(url="<fileUrl>", path="assets/video/trailers/hero_boss_reveal.mp4")
+```
+
+For pure trailer use (DaVinci / Premiere), the user can grab the `fileUrl` and download directly.
+
+### 7. Hand off to the NLE
+
+Studio does not ship a video editor. After all the shots land, tell the user:
+
+> All 6 shots are at these URLs. Studio doesn't cut video. Drop these into DaVinci Resolve (free), Premiere, or CapCut. Recommended order based on what we generated:
+> 1. Establishing wide (cold open)
+> 2. Hero close-up (subject reveal)
+> 3-5. Action beats (slow-mo combat, environmental destruction)
+> 6. Money shot (low-angle hero, ends on logo card)
+>
+> Score it with the music from `audio/music-track`. Add SFX hits on the cuts with `audio/sound-effect`.
+
+## Reference card — prompts that work
+
+Pattern: `<archetype framing> + <subject> + <action verb> + <camera move> + <lighting / time of day> + <stylistic anchor>`. Keep under 50 words. Anchor with a reference image whenever a specific character or asset appears.
+
+| Goal | Model | Prompt | Cost | Duration |
+|---|---|---|---|---|
+| Hero boss reveal | `kling` | `low-angle hero shot of an armored dragon turning toward camera, slow tilt-up, volcanic backlight, embers in air, cinematic, anamorphic flare, 16mm grain` | $0.50 | 5s |
+| Slow-mo combat impact | `kling` | `mid shot of a swordsman striking a parry, sparks fly, time-dilation slow motion, dust and motion blur, dramatic side-light, cinematic` | $0.50 | 5s |
+| Establishing kingdom wide | `kling` | `wide aerial of a clifftop fortress at golden hour, slow dolly forward, low sun raking the towers, cinematic, anamorphic, faint heat haze` | $0.50 | 5s |
+| Splash screen card | `kling` | `static composition of a lone hooded figure on a windswept ridge, only the cloak and grass moving, dusk, painterly cinematic, room for title text upper third` | $0.50 | 5s |
+| Whip pan reveal | `kling` | `whip pan from left to right across a battlefield at night, lands on the protagonist standing alone among bodies, torches flickering, cinematic` | $0.50 | 5s |
+| Detail dolly-in | `kling` | `slow dolly-in on a glowing rune-etched sword embedded in stone, motes of magic rising, blue-cold key light, shallow depth of field, cinematic` | $0.50 | 5s |
+| Vertical social hero | `kling` | `vertical close-up of a young witch raising hands, magical wind, hair flowing, candle-warm key, cinematic, framed for 9:16` | $0.50 | 5s |
+| Pitch-deck premium shot | `veo3` | `wide cinematic of a fleet of airships emerging through cloud cover at dawn, slow truck forward, golden god-rays, soaring orchestral cinematic` | $1.00 | 5s |
+| Cheap B-roll iteration | `ltx` | `mid shot of a knight walking through fog, slow truck backward, dawn light, cinematic` | $0.10 | 5s |
+| Anime style hero | `minimax` | `anime-style hero girl draws a katana in slow motion, sakura petals swirling, dramatic side-light, dynamic camera, Ghibli painterly` | $0.40 | 5s |
+
+### Bad prompts and why
+
+| Bad | Why it fails |
+|---|---|
+| `epic trailer shot of the boss` | No framing, no action, no camera. Returns a generic montage. |
+| `the camera flies through the entire battlefield, sees the king, then the dragon, then the hero` | Three shots in one prompt. The model picks one badly. Generate three shots. |
+| `cool cinematic with lots of explosions and combat` | Adjective stew. Pick one beat: "wide shot of a barricade exploding, debris arc into camera, slow-mo, side-lit". |
+| `realistic 4k 60fps trending on artstation` | Trash modifiers. The model knows "cinematic" already; the rest is noise. |
+| `the dragon roars at the hero and the hero strikes back` | Two characters interacting reliably fails — the model loses identity on the second one. Generate them in separate shots and intercut. |
+
+## Anti-patterns
+
+- **Trying to chain shots inside one video generation.** Each clip is one beat. The cut between shots is the editor's job, not the model's. A 10s prompt with three actions returns mush.
+- **Skipping the reference image for the hero shot.** The boss in the Steam capsule must look like the boss in the game. Always lock identity with `imageUrl`.
+- **Using `veo3` for B-roll.** Burn $0.10 on `ltx` for blocking and B-roll; reserve `veo3` for the one shot that has to be perfect.
+- **Generating shots without composing the trailer first.** Make a 6-shot list before generating shot 1. Otherwise you'll generate shots that don't intercut.
+- **Using `aspectRatio="16:9"` for vertical social.** TikTok / Reels / Shorts are `9:16`. Pillarboxed 16:9 reads as a desktop YouTube embed and gets demoted by the algorithm.
+- **Forgetting that Studio doesn't cut video.** The user has to take the shots into an NLE. Tell them, don't pretend Studio can stitch.
+- **Asking for "the camera does X then Y then Z".** Pick one camera move per shot.
+
+## Edge cases
+
+- **Steam capsule animated header (Steam asset).** Steam wants `.webm` at 616x353 or 1920x1080, ≤6s, 30fps, no audio, ≤4MB. Generate at 16:9, transcode in DaVinci, export `.webm` with VP9. The video model gives you the source; format conversion is on you.
+- **Pitch deck for investors.** One shot, `veo3`, money composition (low-angle hero or wide establishing). Worth the $1.00.
+- **Vertical for TikTok / Shorts.** `aspectRatio="9:16"`, reference image at portrait, frame the subject in the upper-middle so titles can sit at the bottom.
+- **Subject is a UGC environment the player built.** Take a screenshot of the in-engine view, run it through `summer_generate_image` as `referenceImageUrl` to "upgrade" the look, then use that as the video reference. The model can stylize a screenshot; it can't invent the user's level.
+- **Logo splash with motion graphics.** Generate a static logo card in `summer_generate_image` (or use the user's existing logo PNG), then prompt video as `static composition of <logo>, only background particles drifting, cinematic, room for title text` — keep the foreground motionless.
+
+## 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.
+2. Video tab → image-to-video with the reference URL, model `kling`, duration 5s, aspect ratio per platform.
+3. Download the `.mp4` directly into the user's editing project (DaVinci / Premiere / CapCut).
+
+Print the exact prompt + model + duration + aspect ratio so the user can paste it into the dashboard verbatim.
+
+## Handoff
+
+Once the shots are generated:
+
+> Generated 6 shots, ready for the cut. Next:
+> - Take them into DaVinci Resolve (free) or Premiere. Studio doesn't cut video.
+> - Score the trailer with `audio/music-track` — a 60-second trailer cue with a swell and a cold ending.
+> - Add hit SFX on the cuts with `audio/sound-effect` (impact whooshes between shots).
+> - For the title-card splash that ships in-engine, hand off to `video/animated-loop` with the established palette.
+> - For a narrative beat inside the trailer (a 10s "story" segment), hand off to `video/cinematic-cutscene`.
+
+## See also
+
+- `video/cinematic-cutscene` — narrative beats with dialogue.
+- `video/animated-loop` — seamless background clips for splash screens / title menus.
+- `audio/music-track` — trailer score.
+- `audio/sound-effect` — cut SFX (whooshes, impacts, stingers).
+- `2d-assets/concept-art` — generate the reference image axis when no asset exists yet.
+- `_shared/mcp-tools-reference.md` — `summer_generate_video` parameter schema and error codes.

package/skills/visual-effects/_building-blocks/additive-billboard-particles.md

@@ -0,0 +1,28 @@
+# Additive Billboard Particles — Canonical Material Settings
+
+Reusable `BaseMaterial3D` configuration for additive particle billboards (motes, sparks, glow, ash). Used by `magic-glow`, optionally substitutable in `hit-spark` and `fire` if a custom shader is overkill.
+
+## Settings
+
+```
+transparency: BaseMaterial3D.TRANSPARENCY_ALPHA
+blend_mode: BaseMaterial3D.BLEND_MODE_ADD
+shading_mode: BaseMaterial3D.SHADING_MODE_UNSHADED
+billboard_mode: BaseMaterial3D.BILLBOARD_PARTICLES
+emission_enabled: true
+emission_energy_multiplier: 3.0   // 1.0–5.0 typical; bump for HDR bloom
+disable_receive_shadows: true
+shadow_to_opacity: false
+no_depth_test: false              // true only if particles must read on TOP of opaque geometry
+albedo_color: Color(R, G, B, 1.0)
+emission: Color(R, G, B)          // usually same as albedo for single-color motes
+```
+
+## When to use this vs a custom shader
+
+- **Use this `BaseMaterial3D` config** when the effect is just a tinted soft-circle mote (magic glow, sparkles, dust). Less code, faster iteration, free Godot-managed billboard math.
+- **Use a custom `ShaderMaterial`** when you need per-particle color ramps over `CUSTOM.x` age (fire), shape masks (muzzle flash star burst), or stretched streaks (hit-spark). Those can't be expressed in `BaseMaterial3D`.
+
+## Performance note
+
+Additive overdraw is fillrate-bound. Keep `draw_pass_1.size <= 0.2` for motes/sparks; larger quads at full additive intensity destroy mobile fillrate budgets fast.