> ## AI Agent Context
> - Full documentation index: https://aistudio.google.com/llms.txt
> - Gemini Docs MCP server (consistent live info): https://gemini-api-docs-mcp.dev
> - Coding agent skills & setup guide: https://aistudio.google.com/docs/coding-agents.md

# Genie 4 prompt and controls guide

Prompts written like movie trailers behave unpredictably in Genie 4
(`models/genie-4`). Requests like `"an upbeat synth soundtrack"`,
`"quick cuts to an aerial drone shot"`, or
`"a room that flashes red when I walk in"` work poorly on a live `24 fps`
camera stream. Room-wide triggers fire prematurely at frame 1, background music
keywords become physical Foley sounds, and camera cuts fracture spatial
continuity.

This guide covers how to prototype worlds in Google AI Studio and five tested
prompt and control patterns for building reliable interactive experiences on the
[Interactions API](/docs/genie).

{% button href="https://aistudio.google.com/live?model=genie-4" variant="ais" %}Open Genie 4 in Google AI Studio{% /button %}

## Prototyping in Google AI Studio  {% id="ai-studio-playground" %}

Before writing client code, test your world prompt and action bindings in the
[Google AI Studio Live playground](https://aistudio.google.com/live?model=genie-4)
(requires a [paid-tier API key](/docs/pricing#genie-4)):

*   **Starter worlds and empty-state templates:** Launch curated worlds—such as
    *Step inside a living oil painting*, *Espresso Machine Logic*, *Wine Cellar
    Sommelier*, or *Golf Cart Fairway Drive*—to inspect how world prompts and
    action prompts pair together.
*   **Native movement (`WASD` + Arrow keys):** Click the video viewport to focus
    keyboard capture. `W`, `A`, `S`, `D` control forward, backward, and strafe
    movement; Arrow keys pan and tilt the camera (`~0.2-0.5s` response).
*   **Custom Key Bindings (`E`, `Q`, `R`, mouse clicks):** Bind custom keys to
    reusable action prompts (for example, `E` → `"Make heavy snow fall across
    the painted village"`). AI Studio enforces a `2-second` cooldown on custom
    key bindings so overlapping text impulses do not collide.
*   **Mid-session prompt bar & spoken dialogue:** Type live environmental shifts
    at any point during the stream, or wrap text in quotation marks
    (`"\"What wine would you recommend?\""`) to converse with a character in
    front of you.
*   **Session timer & background-tab protection:** A live session health
    indicator warns as you approach `90 seconds` (where long-horizon drift
    increases). Switching away from or hiding the browser tab for more than
    `10 seconds` automatically pauses/ends the stream so idle tabs do not burn
    paid video tokens.

## Five tested patterns for interactive worlds  {% id="patterns" %}

### Pattern 1: Causal world rules ("Chekhov's lever")  {% id="causal-world-rules" %}

You can embed cause-and-effect triggers directly inside your `world_setup`
prompt using `Rule: ...` clauses so approaching or interacting with an object
changes the world state:

```none
A spaceship bridge with a big red lever on a console far away from me. Rule: Pulling the red lever makes the stars outside the window stretch into bright hyperspace streaks.
```

You can also chain two sequential object/character rules in a single scene:

```none
First-person POV in a long stone hallway with a heavy red wooden door far away from me at the end of the corridor. Rule: Opening the red door reveals a smiling clown standing far away from me who waits until a rule is triggered. Rule: Approaching the clown makes colorful paper confetti burst from the ceiling with crisp rustling paper sounds.
```

Follow three phrasing rules validated in live testing:

1.  **Bind triggers to a concrete object or character, never a location:**
    `"Pulling the red lever"` or `"Opening the red door"` works; `"Entering the
    bridge"` or `"Reaching the end of the hall"` misfires because the model
    cannot measure abstract zone boundaries.
2.  **Place the trigger `"far away from me"`:** Spawning a lever or door at
    arm's reach often causes Genie 4 to fire the rule immediately during initial
    world setup before the player presses `W`.
3.  **Tell characters to wait:** Add `"who waits until a rule is triggered"` so
    characters stay idle in their starting pose until the player approaches or
    speaks to them.

{% callout type="note" %}
  **Treat `Rule:` clauses as probabilistic steering, not a game script:** These
  three phrasing rules are empirical workarounds for world-model attention rather
  than a deterministic state machine. When your application needs a guaranteed
  on-demand trigger at the press of a button, pair `world_setup` with explicit
  client key bindings ([Pattern 2](/docs/genie-prompting#key-bound-actions)).

{% /callout %}

### Pattern 2: Key-bound action verbs (`E`, `Q`, `R` controls)  {% id="key-bound-actions" %}

Genie 4's `user_action` protocol natively trains spatial movement (`key_w`,
`key_a`, `key_s`, `key_d`) and camera look (`arrow_up`, `arrow_down`,
`arrow_left`, `arrow_right`), but does **not** hardcode game mechanics onto
`key_e` or `space`. To give players custom action buttons—weather shifts,
stunt ramps, character cues, or object interactions—bind keys like `E`, `Q`, and
`R` in your client to send mid-session `input` text impulses (`10×` at `150 ms`
intervals, with a `2-second` cooldown).

**Walk-first exploration (most reliable):** First-person walking worlds give
players forgiving pacing while `~1-2s` text-steered events take effect:

*   `world_setup` prompt:
    `Immersive first-person POV standing on a cobblestone canal bridge inside a vibrant, thick-impasto post-impressionist oil painting of a starry riverside village at twilight. Swirling cobalt-blue sky currents and glowing golden cafe lanterns shimmer with living, tactile brushstroke textures that ripple gently in the breeze, with a wooden rowboat moored at the stone steps ahead. Audio: Gentle water lapping against the stone steps, leaves rustling in a soft evening breeze, footsteps on cobblestone.`
*   `E` key (`input`): `"Make heavy snow fall across the painted village"`
*   `Q` key (`input`): `"Burst bright golden fireworks above the village rooftops"`
*   `R` key (`input`): `"Send a flock of white doves flying past"`

**Cockpit driving variant (higher latency sensitivity):** You can also anchor
first-person cockpit games when network RTT to US servers is low (`< 100 ms`):

*   `world_setup` prompt:
    `Immersive first-person cockpit POV gripping the leather steering wheel of an open-frame desert rally buggy stationary on a sun-baked red sandstone canyon trail. Winding dirt hairpins, wooden jump ramps, and narrow rock arches stretch ahead along a cliffside track under golden late-afternoon sunlight. Audio: Crunching desert gravel beneath rubber tires, rushing canyon wind, and metallic suspension rattles.`
*   `E` key (`input`): `"Kick up a thick plume of red canyon dust ahead"`
*   `Q` key (`input`): `"Spawn a wooden stunt jump ramp on the trail ahead"`
*   `R` key (`input`): `"Send loose sandstone pebbles tumbling down the canyon wall"`

**Cockpit driving caveats:** Pressing `S` slows or reverses visual motion
gradually rather than braking like a rigid-body physics engine; panning the
camera sideways with Arrow keys while holding `W` bends the vehicle's travel
direction toward the camera gaze; and network latency above `150 ms` makes tight
canyon turns clip through rock walls.

### Pattern 3: 16:9 landscape painting image seeds  {% id="image-seeded-worlds" %}

Passing a `16:9` `reference_image` alongside `world_prompt` in `world_setup`
locks frame 1's composition, palette, and art style before handing camera
control to the user:

```json
{
  "event_type": "world_setup",
  "world_prompt": {
    "text": "Immersive first-person walk along a sunlit wheatfield path beneath swirling painted clouds, with tactile impasto brushstrokes rippling across the tall stalks. Audio: Crisp dry wheat rustling in a steady breeze, footsteps on packed earth, distant skylark calls."
  },
  "reference_image": {
    "mime_type": "image/jpeg",
    "data": "<BASE64_1280X720_JPEG_UNDER_48KB>"
  }
}
```

**Image seeding rules and boundaries:**

*   **Use `16:9` landscape framing (`< 48 KB` JPEG on WebRTC):** Portrait (`9:16`)
    or square (`1:1`) images force aspect-ratio padding or hallucinated side
    walls. Over WebRTC, compress `1280x720` JPEGs under `48 KB` so the base64
    JSON payload fits inside the `64 KB` SCTP data channel limit.
*   **Prefer stylized art, architectural renders, or empty landscapes:** Street
    photographs containing identifiable bystanders, public figures, or
    copyrighted logos frequently trip input or output safety filters and
    terminate the stream.
*   **Expect rolling canvas memory:** Walking forward into the painting works
    smoothly, but turning `180 degrees` away and turning back `10 seconds` later
    generates a fresh interpretation of the scene rather than restoring the
    exact starting pixels.

### Pattern 4: Broadband Foley audio and frame-0 visible propulsion  {% id="audio-foley-and-motion" %}

Genie 4's internal world planner actively rewrites prompts before rendering
video and `48 kHz` stereo audio. Writing *with* those planner rules instead of
against them eliminates unexpected visuals and muffled audio:

1.  **Request broadband physical contact Foley, not music or narrowband drones:**
    Genie 4 strips or rewrites soundtrack requests (`"arcade synth score"`,
    `"orchestral soundtrack"`) and sustained narrowband drone words (`"engine
    hum"`, `"deep rumble"`, `"jet roar"`). Specify crisp, broadband surface
    interactions instead: footsteps on wet cobblestone, gravel crunching, water
    lapping against wood, leaves rustling, ceramic clinking, or rain pattering
    on canvas.
2.  **Give forward motion a visible physical cause at frame 0:** If your prompt
    describes gliding across a lake or racing down a track without stating *how*
    you are moving, Genie 4 often invents a boat hull, kayak paddle, or vehicle
    hood mid-session to justify camera velocity. Anchor the propulsion source in
    the opening sentence (`"standing on a footpath"`, `"sitting in the driver's
    seat gripping the steering wheel"`, `"holding a wooden canoe paddle dipping
    into clear water"`).
3.  **Expect subtle ambient motion even while idle:** Genie 4 continuously
    animates small environmental details—drifting steam, water ripples, swaying
    foliage, flickering lantern light—so worlds never freeze like a static
    photograph when no keys are held.

{% table %}
  * Weak prompt phrasing (planner fights or rewrites)
  * Planner-aligned phrasing (crisp visual & audio uptake)

  ---

  * `"Gliding fast over an alpine lake. Audio: Deep ambient drone and relaxing piano music."`
  * `"First-person POV seated in a wooden canoe with a cedar paddle dipping into an alpine lake. Audio: Water lapping against wooden planks, droplets trickling off the paddle, wind in shoreline pines."`

  ---

  * `"Cyberpunk street with neon hum, synthwave soundtrack, and roaring hovercars."`
  * `"First-person walk down a rain-slicked neon alleyway with steaming street grates. Audio: Footsteps splashing through puddles, steady rain pattering on metal awnings, distant tire hiss on wet asphalt."`

  ---

  * `"Cut to a wide shot when I enter the courtyard."`
  * `"Continuous first-person walk through a stone archway that opens onto a sunlit courtyard with a splashing fountain."`
{% /table %}

### Pattern 5: Short-horizon locked-gaze causal vignettes  {% id="locked-gaze-vignettes" %}

Because Genie 4 tracks object state across recent frames rather than a permanent
3D database, tabletop and close-up object interactions work best as **focused
`25-45 second` vignettes** where the camera stays pointed at the interactive
subject.

**Verified vignette — Espresso Machine (`25 seconds`):**

```none
First-person POV standing in front of an espresso machine. An empty ceramic mug rests on the drip tray beneath the spout. A glowing "brew" button is visible on the front panel.
```

Run a timed three-beat interaction without panning away from the machine:

1.  **`0s-5s` (Observe idle state):** Let the stream settle; faint steam rises
    from the grouphead while the ceramic mug sits empty on the metal tray.
2.  **`5s` (Trigger state change):** Send `"Press the brew button"` (`10×` every
    `150 ms`). Within `~1-2s`, the button state activates and dark espresso with
    golden crema pours into the mug accompanied by pump and liquid Foley.
3.  **`12s-25s` (Inspect and complete):** Tap `key_w` briefly (`0.5s`) to lean
    closer, send `"Reach out and pick up the full mug"`, watch the hand lift the
    filled cup from the drip tray, and call `complete()`.

**Boundary to design around:** If you pan the camera `90-180 degrees` away from
the counter for `8+ seconds` and look back, the mug may return to empty or the
brew button may shift position. Design short, forward-facing interactive scenes
rather than multi-room fetch quests.

## Limitations  {% id="limitations" %}

{% table %}
  * Constraint
  * What happens in practice
  * How to design around it

  ---

  * **Object permanence (`~8s` off-screen)**
  * Objects and buildings behind you or out of view for `8+ seconds` shift or reset when you look back; coherence degrades past `60-90s` (`120s` session cap).
  * Design `30-60 second` forward-moving paths or locked-gaze tabletop vignettes instead of backtracking mazes.

  ---

  * **Two-tier control latency**
  * Native `WASD` / Arrow `user_action` responds in `~0.2-0.5s`; mid-session `input` text steering takes `~1-2s`.
  * Use `WASD` / Arrows for continuous steering and map `E` / `Q` / `R` to macroscopic world or object events with a `2s` cooldown.

  ---

  * **Reserved `user_action` keys**
  * `key_e` and `space` exist in the `user_action` enum but have no trained "interact" or "jump" model semantics.
  * Intercept `E`, `Q`, `R`, or `Space` in your client and send explicit `input` text prompts (`10×` every `150 ms`).

  ---

  * **Audio soundtrack & drone rewriting**
  * Background music genres and narrowband drone words (`hum`, `rumble`, `synth`) are stripped or rewritten.
  * Prompt explicitly for broadband physical contact Foley (footsteps, water, wind, gravel, clinking glass) and quoted character speech.

  ---

  * **US-only serving & WebRTC `64 KB` SCTP cap**
  * `>150 ms` RTT outside North America makes fast driving/platforming sluggish; oversized base64 images fail on WebRTC data channels.
  * Prefer walking/director-paced worlds for global users, and compress `16:9` WebRTC JPEG seed images under `48 KB`.

  ---

  * **Safety & recitation filters**
  * Real human faces, public figures, and recognizable brand IP can block `world_setup` or close an active session.
  * Use stylized art, original fictional environments, and public-domain landscape paintings.
{% /table %}

## What's next  {% id="whats-next" %}

*   Build a browser WebRTC or Python WebSocket client in
    [Interactive world generation with Genie 4](/docs/genie).
*   Review model specs on the [Genie 4 model page](/docs/models/genie-4).
*   Check [Genie 4 pricing](/docs/pricing#genie-4) and
    [rate limits](/docs/rate-limits#genie-4).

