summerengine/summer/cinematic-cutscene

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 trailer-shot. If they want a seamless background loop, that's 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" — trailer-shot.
• "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 assets.generate_audio and use a static TextureRect, no video needed.

Steps

1. Read the soul file and any prior cutscenes

Read .summer/GameSoul.md
assets.search({ query: "<character name> reference", assetType: "2d_image", scope: "all" })

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.

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, 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 assets.generate_image before generating video. This still drives imageUrl on every subsequent shot, so the character is consistent across cuts.

assets.generate_image({
  prompt: "<subject>, <setting>, cinematic lighting, film still, wide framing, <art style from GameSoul.md>",
  model: "nano-banana-2",
  aspectRatio: "16:9"
})

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. 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.

Default policy: `ltx` first to validate the prompt and shot framing. If it lands the composition but quality is rough, escalate to kling. veo3 is a real tradeoff, not an upgrade: reaching for it means giving up imageUrl, which is the one thing that holds character identity across shots. Take that trade only when on-camera lip-sync matters more than continuity, and only with the user's approval on cost.

5. Generate each shot

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"
})

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.

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:

jobs.wait({ jobId: "<job.id from the generate call>", timeoutSeconds: 50 })

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.

When the job completes, 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 assets.generate_audio. Generate it separately and an AnimationPlayer or your cinematics/ controller scene syncs them.

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.

7. Import and wire as a VideoStreamPlayer

Import the `.mp4` as it is; the import converts it. Summer Engine plays video only as Ogg Theora (.ogv), so every Summer import tool (summer_import_from_url, its batch, summer_import_asset_by_id, summer_import_asset) converts a video on the way in and saves it at the path you asked for with .ogv. The answer names the file in videoConversions and note:

summer_import_asset_by_id(assetId="<the shot's asset id>", path="res://assets/video/cinematics/intro_shot_01.mp4")
→ importedTo: res://assets/video/cinematics/intro_shot_01.ogv

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", 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.

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.

Bad prompts and why

Anti-patterns