> ## Documentation Index > Fetch the complete documentation index at: https://docs.reactor.inc/llms.txt > Use this file to discover all available pages before exploring further. # HappyOyster prompt guide > How to write HappyOyster world prompts that build rich, controllable worlds, in Adventure and Directing modes. A HappyOyster prompt is applied once by `createWorld()`, and its effect is permanent. It defines what exists, what the player can control inside the world, and what the player's inputs mean once the stream is live. After creation you steer with controls (Adventure) or instructions (Directing). The creation prompt is the world's identity, and it is the contract the model reads your live inputs against. A strong prompt says five things, in this order: ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} REGISTER = the camera and realism vocabulary the world renders in SUBJECT = who or what you are, cast in second person with concrete detail WORLD = terrain, landmarks, sky, and weather, staged around you DYNAMICS = how the world reacts around you as you act STYLE = a short line of concrete photographic descriptors ``` The prompt can be up to 2,000 characters. Each principle below owns one beat. ## Detail buys control Consistent output comes from a clear, detailed prompt. A broad prompt is still valid input, but every region it leaves unsaid the model fills with its own invention, which can be different on every rerun. The difference is easiest to see side by side. This prompt leaves a lot up to the model:
A cyberpunk city street at night, neon lights, rain, atmospheric, cinematic, 8K.
The Neon City prompt, one of the example worlds featured in the Happy Oyster JS-SDK example project, describes the same street in specific detail:
A rain-slicked cyberpunk city street at night. Neon signs in pink, cyan and orange reflect in deep puddles on the asphalt, steam rises from grates and vents, and holographic billboards flicker above crowded noodle stalls. Narrow alleys branch off between towering buildings strung with cables, and the wet air glows under the city lights.
It names what the world must render: * the surfaces: rain-slicked asphalt and deep puddles * the light sources: neon in three named colors and holographic billboards * the inhabitants: crowded noodle stalls * the landmarks that reward exploring: alleys branching off between the buildings ## Recurring anchors Three to six anchors, named early and referred back to as the prompt continues, hold a world together better than a long list of details that each show up once and never return. A world built around desert ruins might commit to four: sandstone, golden hour, wind-worn carved stone, and a caravan trail. Every later sentence is one of those four made specific. The model also renders the nouns the prompt supplies, so negation does not work: a negation still supplies its noun.
A vast, empty desert. No people, no structures, no signs of civilization.
"No people" places people in the world's attention. Spend the words on what occupies each region instead:
A vast, empty desert: broken columns and half-buried arches, carved reliefs worn smooth by wind, a distant caravan trail, heat shimmer over the sand.
## Embody the subject Adventure worlds work best written in the second person, "you are the wolf" rather than "a wolf runs", which ties the camera to the subject and keeps the world staged around it. A prompt that describes the subject from the outside, like a spectator watching a scene, leaves the controls with nothing to attach to:
A cloaked traveler walks up a narrow forest trail, carrying a lantern.
That sentence describes a shot of someone else. Cast the subject with concrete physical detail in the same sentence you declare it, so the model knows its scale and silhouette from the first frame:
You are a traveler on the narrow trail, cloaked and carrying a lantern that swings as you walk.
For third-person Adventure worlds, the `createWorld()` [`perspective`](/model-api-reference/happy-oyster/schema#createworld) parameter (`"third_person"`) frames the subject on screen. The prompt still addresses it as "you". ## Pair the subject with a premise A subject alone has nothing to do. Give it an objective or a disruption, something it's trying to reach or something that breaks the routine, and later instructions (or in Adventure, a player's held controls) have something to push against instead of a static backdrop to wander. ```text theme={"theme":{"light":"github-light","dark":"github-dark-high-contrast"}} SUBJECT = who or what the world is staged around SYSTEM = the unusual world or rule they are inside OBJECTIVE = the simple goal or disruption pulling them forward ```
A lone courier moves through a city where gravity reverses every hour.
The subject and the system are there, but nothing pulls the courier forward, so the world just sits around them.
A lone courier races to deliver a sealed letter across a city where gravity reverses every hour, sprinting to clear each rooftop before the pull flips beneath her.
## Direct visible change A world that only describes appearance renders a single held frame:
A cavernous ice cave glitters with blue light, hung with rows of long icicles.
Give it something that moves on its own, independent of any control, and it starts moving the moment the travel opens. Favor verbs that point at a visible before and after: awakens, unfolds, drifts, ripples, deepens, comes alive, gives way.
A cavernous ice cave glitters with blue light, hung with rows of long icicles; meltwater drips from their tips into a still pool below, rings spreading across the surface with each drop.
## Close with concrete photographic descriptors Light, atmosphere, and materials are things a renderer can paint. Quality words describe nothing renderable:
...breathtaking, cinematic, epic, 8K masterpiece.
Close with concrete photographic descriptors, placed as a short fragment after the complete scene: the quality of the light, the type of weather, the texture of the surfaces.
...heat shimmer rises off the sand, and the sky burns amber and rose above the horizon.
Camera language belongs to this beat too, and for Directing worlds it has a real counterpart to agree with: `layout` fixes the camera's movement style for the whole travel, `"Stable"` or `"Fast"`. A prompt closing on a slow pullback or a fixed frame reads as Stable; one closing on a tracking shot or a whip pan reads as Fast. Write toward whichever `layout` you picked, not the other one. ## Adventure and Directing HappyOyster ships two modes, selected before connecting with `mode: "adventure"` or `mode: "directing"`. Adventure is played: you hold movement and interaction controls in real time, closer to how [LingBot](/model-api-reference/lingbot/overview) and [LingBot World](/model-api-reference/lingbot-world-2/overview) work. Directing is steered: you write instructions in plain English that land on the story as it plays, closer to how [LongLive](/model-api-reference/longlive-v2/overview) and [Helios](/model-api-reference/helios/overview) work. The paragraph shape above holds in both, but the emphasis differs, covered next for each mode in turn. ### Adventure The subject carries the prompt: the player controls it directly, issuing held commands in real time. Choose `perspective` to match the casting: `"first_person"` when you are the eyes, `"third_person"` when the subject should be on screen. While a travel runs, the world advertises interaction verbs; the [SDK reference](/model-api-reference/happy-oyster/schema#adventure-controls) covers the control surface. The engine attempts any free-form verb it is sent, so a subject cast with obvious affordances, like a wolf that pounces or a boat that jumps a wake, gives the verbs something to work with. A verb that plays out as nothing is a cue to reword it toward an action the world advertises. ### Directing The prompt is your opening shot: stage, cast, atmosphere, and whatever story tension the first instructions will pull on. A legible scene with named actors matters most, because every later instruction refers back to what the prompt established. Pick `resolution` (480p or 720p) at creation. You can also set a `layout` (camera movement style, `Stable` or `Fast`) and a `narrative` register (`Calm`, `Dramatic`, or `Normal`). The prompt can be as short as a story idea: the generation layer expands a high-level premise into a multi-act script on its own. To keep the authorship, write the script into the prompt yourself. Timing guidance takes whatever ranges fit the scene ("from 0 to 15 seconds, the messenger climbs through the fog"), together with character actions or dialogue, camera direction, emotion, and scene changes; the ranges are free-form, and the layer maps them onto the engine's four-second blocks. At the granular end you can script act by act, one act per block of about four seconds, up to 45 acts, which is roughly three minutes of directed story. ## Starting images An optional starting frame sharpens the prompt's authority, and each mode consumes it in its own way: * Adventure treats the image as a visual anchor: the model generates the world from image and prompt together. Write the prompt to describe the image's scene. When they disagree, you are asking for two different worlds at once. * Directing uses the image as the literal first frame and skips AI first-frame generation. What you upload is shot one, so write the prompt as the scene that shot opens. An image earns its place when visual consistency matters: a character design or a scene's exact look survives a long travel better anchored in pixels than in prose. The `createWorld()` parameters, the URL and upload constraints, and the content-policy codes are in the [SDK reference](/model-api-reference/happy-oyster/schema#createworld). ## Common pitfalls * **A spectator prompt in an Adventure world.** "A knight rides across the plain" describes a shot, and the controls have no one to move; forward becomes a camera guess. Cast the subject in second person and pick the `perspective` that matches the casting. * **No line that moves on its own.** A prompt that is all appearance renders a held diorama. One named ambient motion, fireflies in the hollows, lanterns coming alive, gives the world life before any input arrives. * **A starting image the prompt argues with.** In Adventure the model generates one world from both; in Directing the image is shot one. Write the prompt as the scene the image shows or opens. * **A close that fights the `layout`.** A prompt ending on whip pans with `layout: "Stable"`, or on a locked frame with `"Fast"`, sends the travel two camera briefs. Write toward the layout you picked. * **A travel's worth of story in one instruction.** Instructions land one block at a time, and a three-act instruction fights that cadence. One actor, one action, one intended outcome per instruction. * **Words spent on what must not appear.** A negation supplies its noun: "no people" places people in the world's attention. Describe what occupies the space instead.