Directing Story Scenes

# The Scene Director makes ONE Gemini call per scene that returns:
response.parts = [
    Part(text="Panel 1 narration..."),
    Part(inline_data=<panel 1 illustration>),
    Part(text="Panel 2 narration..."),
    Part(inline_data=<panel 2 illustration>),
    # ... up to 5 panels
]

The backend parses these parts, separates text from images, and packages them into the typed scene JSON. The Visual Motion Director provides style/composition guidance as INPUT to this call (style bible, character descriptions), but the actual image generation happens here inside the Scene Director's Gemini call.

Capabilities

• Writes scenes as 3–5 sequential comic panels.
• Generates panel illustrations inline via Gemini interleaved output (text + image in one call).
• Balances narration, dialogue, silence, and visual storytelling.
• Keeps the emotional focus clear in each panel.
• Builds scenes that work with or without voiceover.
• Writes motion direction per panel — what should move in the 2-3 second GIF (character actions, environmental motion, camera movement).
• Ends scenes on a strong beat, especially before choices.
• Produces typed JSON the visual and audio agents can consume directly.
• Receives style bible and character reference descriptions from the Visual Motion Director as input context.

Workflow

1. Read the story bible and current state. Understand the scene purpose before writing.
2. Decide the scene beat. Each scene should do one main job:
   • invite
   • test
   • reveal
   • confront
   • resolve
3. Plan 3–5 panels.
   • Panel 1: orient mood and setting
   • Panels 2–4: escalate conflict or deepen reflection
   • Final panel: land the beat or present the choice
4. Write concise prose and dialogue. Keep lines speakable for TTS and readable on screen.
5. Add narration beats. These should support, not repeat, what the panel already shows.
6. Write motion direction per panel. Describe what should move in the 2-3 second GIF — character actions (turning, reaching, reacting), environmental motion (wind, flickering light), and camera movement (zoom, pan) when it serves the story. Think like a cinematographer.
7. Control pacing. Alternate motion-heavy beats with spoken or silent beats.
8. Prepare for multimodal use. Each panel should include enough meaning to survive GIF or audio failure.
9. Return typed JSON.

Recommended panel fields

• panel_id
• purpose
• visual_beat
• motion_direction (what moves in the GIF — character action, environment, camera)
• dialogue
• narration
• emotion
• estimated_duration_sec

Example

{
  "scene_id": "scene_A3",
  "anchor": "A3",
  "panels": [
    {
      "panel_id": "p1",
      "purpose": "arrival",
      "visual_beat": "The courier stands in a hall of sealed letters that whisper his own thoughts.",
      "motion_direction": "Letters on shelves subtly flutter and glow. Faint wisps of light drift between the shelves. Camera holds steady on the courier's silhouette.",
      "dialogue": [],
      "narration": "Some rooms do not echo. They answer.",
      "emotion": "unease",
      "estimated_duration_sec": 4
    },
    {
      "panel_id": "p2",
      "purpose": "revelation",
      "visual_beat": "One letter opens by itself, showing the promise he once made to silence himself.",
      "motion_direction": "The letter slowly unfolds, casting warm golden light across the courier's face. His eyes widen. Slow push-in on the letter.",
      "dialogue": ["'You wrote the law you now obey.'"],
      "narration": "The trap had not been built around him. It had been built from him.",
      "emotion": "shock",
      "estimated_duration_sec": 5
    }
  ]
}

Scene guardrails

• Do not exceed 5 panels unless there is a very strong reason.
• Do not write overwritten prose.
• Do not explain what the image already communicates.
• Do not lose the emotional mirror to the user's original issue.

Project references

• AGENTS.md — 3–5 comic panels, dark immersive tone, graceful degradation rules.
• docs/PRD.md — per-scene multimodal requirements, panel pacing, voiceover and timing expectations.
• docs/roadmap.md — MVP scene delivery uses AI-generated GIFs with real motion, falling back to static images.