HappyOyster SDK reference

This page documents the public surface of @reactor-models/happy-oyster. For a complete application flow, see the tutorial.

Modes

Choose a mode before connecting:

Mode	World creation options	Live controls
`"adventure"`	`perspective`	Movement, look, interaction, and held axes
`"directing"`	`resolution`, `layout`, and `narrative`	Instructions, pause, resume, and rewind

The mode stays fixed for the client or provider session. Construct a new client, or remount the provider, to switch modes.

const adventure = new HappyOysterModel({ mode: "adventure", videoElement });
const directing = new HappyOysterModel({ mode: "directing", videoElement });

Client construction

JavaScript

import { HappyOysterModel } from "@reactor-models/happy-oyster";

const model = new HappyOysterModel({
  mode: "adventure",
  videoElement,
});

await model.connect(jwt);

videoElement may be omitted at construction and supplied later with attachVideo(element).

React

import {
  HappyOysterProvider,
  HappyOysterVideo,
  useHappyOyster,
} from "@reactor-models/happy-oyster/react";

function App({ jwt }: { jwt: string }) {
  return (
    <HappyOysterProvider mode="directing" jwt={jwt} autoConnect>
      <HappyOysterVideo className="aspect-video w-full" />
      <Controller />
    </HappyOysterProvider>
  );
}

Provider props:

Prop	Type	Required	Description
`mode`	`"adventure" \| "directing"`	Yes	Experience selected before connecting
`jwt`	`string \| (() => string \| Promise)`	No	Static JWT or lazy resolver; omitted for local mode
`autoConnect`	`boolean`	No	Connect when mounted; default `false`
`connectOptions`	`{ sessionId, connectionId? }`	No	Attach to an existing Reactor session
`local`	`boolean`	No	Connect to a locally served model
`apiUrl`	`string`	No	Reactor API base URL

Lifecycle

The client lifecycle is available as model.phase or useHappyOyster().phase:

idle → connecting → connected → starting_stream → streaming → ended / failed

`connect`

Open the session and synchronize the first worldState snapshot.

await model.connect(jwt);

With a provider, use autoConnect or call the hook method:

const { connect } = useHappyOyster();
await connect(getJwt);

`disconnect`

End any active travel and close the session. Worlds remain available for later attachment.

await model.disconnect();

`endTravelSession`

End the active travel while keeping the session and current world.

await model.endTravelSession();

Worlds

`createWorld`

Create a world for the client’s selected mode and make it current. The promise resolves with a WorldStateMessage once the world is ready. Shared parameters:

Parameter	Type	Required	Description
`prompt`	`string`	Yes	Natural-language world description, up to 2,000 chars
`firstFrameImageUrl`	`string`	No	Public starting-image URL
`firstFrameImage`	`File \| Blob`	No	Local starting image, at most 2 MB

Provide only one starting-image source. Adventure parameters:

Parameter	Type	Default
`perspective`	`"first_person" \| "third_person"`	`"third_person"`

const world = await model.createWorld({
  prompt: "A misty ancient forest with a lantern-lit trail.",
  perspective: "third_person",
});

Directing parameters:

Parameter	Type	Default
`resolution`	`"480p" \| "720p"`	`"720p"`
`layout`	`"Stable" \| "Fast"`	—
`narrative`	`"Calm" \| "Dramatic" \| "Normal"`	—

const world = await model.createWorld({
  prompt: "A courier enters a floating city as a storm approaches.",
  resolution: "720p",
  layout: "Stable",
  narrative: "Dramatic",
});

Save world.encrypted_world_id to reopen the world later.

`attachWorld`

Make an existing world current and wait until it is ready:

const world = await model.attachWorld(encryptedWorldId);

The world must belong to the client’s selected mode.

Travel

`startTravel`

Start the current ready world and render its stream into the attached video element:

const result = await model.startTravel();

The method is single-flight: concurrent calls share one attempt. Calling it while already streaming returns the current result. StartTravelResult:

Field	Type	Description
`streaming`	`boolean`	Whether a live stream was opened
`session`	`object`	Session metadata, or `null` when no stream is opened

Video in React

Mount HappyOysterVideo under the provider before starting:

<HappyOysterVideo autoPlay muted playsInline className="aspect-video w-full" />

Adventure controls

Adventure controls are held state. Movement, look, and interaction axes compose until released.

`move`

await model.move("Front");

Values: Front, Back, Left, Right, the four diagonal combinations, and None.

`look`

await model.look("Mouse_Left");

Values: Mouse_Up, Mouse_Down, Mouse_Left, Mouse_Right, the four diagonal combinations, and None.

`interact`

await model.interact("Jump");

Built-in verbs include Jump, Attack, Crouch, and Sprint. The current world’s advertised verbs are available in travelState.character_actions and travelState.environment_actions.

`hold`

Set multiple axes in one call:

await model.hold({
  translation: "Front",
  rotation: "Mouse_Left",
  interaction: "Sprint",
});

`release`

Release selected axes while leaving the others held:

await model.release({ translation: true, interaction: true });

`stop`

Release every axis:

await model.stop();

Directing controls

`instruct`

Submit a text instruction:

const { accepted } = await model.instruct("A storm rolls in over the city.");

Accepted instructions appear in travelState.user_instructions.

`pause`

await model.pause();

`resume`

await model.resume();

`rewind`

Rewind a paused travel to an absolute second. Playback resumes automatically:

const { resumedAtSec } = await model.rewind(8);

Targets use 4-second boundaries; other values are rounded down.

Travel status

model.onTravelStatusChanged((status) => {
  console.log(status); // running, paused, or completed
});

React:

useHappyOysterTravelStatus((status) => {
  setPaused(status === "paused");
});

State

`worldState`

The authoritative current-world snapshot:

Field	Type	Description
`phase`	`WorldPhase`	`no_world`, `creating`, `building`, `ready`, `traveling`, or `failed`
`encrypted_world_id`	`string \| null`	Id used by `attachWorld()`
`world_status`	`string \| null`	Current build status
`first_frame`	`string \| null`	Starting-frame preview URL
`prompt`	`string \| null`	Prompt used to create the world
`mode`	`number \| null`	`1` Adventure or `2` Directing

Subscribe from the class:

const unsubscribe = model.onWorldState((state) => {
  renderWorld(state);
});

Or read the reactive value from useHappyOyster().

`travelState`

The authoritative live-travel snapshot:

Field	Type	Description
`status`	`string`	Current travel status
`user_instructions`	`TravelInstruction[]`	Directing instruction timeline
`chapters`	`TravelChapter[]`	Directing chapters
`character_actions`	`string[]`	Adventure character verbs
`environment_actions`	`string[]`	Adventure environment verbs

const unsubscribe = model.onTravelState((state) => {
  renderTravel(state);
});

React hook surface

useHappyOyster() returns:

model, mode, phase, worldState, travelState, and streaming
connect, disconnect, createWorld, attachWorld, startTravel, and endTravelSession
Adventure methods: move, look, interact, hold, release, stop, and control
Directing methods: instruct, pause, resume, and rewind

Additional hooks:

useHappyOysterWorldState()
useHappyOysterTravelState()
useHappyOysterPhase()
useHappyOysterTravelStatus(handler)
useHappyOysterTravelError(handler)

Errors

HappyOysterActionError exposes the rejected action and a machine-readable code.

Code	Meaning
`TRAVELING`	End the travel before creating or attaching
`BUSY`	Another world action is still running
`NO_WORLD`	Create or attach a world before starting
`WORLD_NOT_READY`	Wait until the current world is ready
`MODE_MISMATCH`	The world belongs to the other experience
`403001`	The world is unknown or belongs to another account
`403004`	Prompt rejected
`403005`	Starting image rejected

try {
  await model.attachWorld(encryptedWorldId);
} catch (error) {
  if (error instanceof HappyOysterActionError) {
    console.error(error.code, error.action, error.message);
  }
}

​Modes

​Client construction

​JavaScript

​React

​Lifecycle

​connect

​disconnect

​endTravelSession

​Worlds

​createWorld

​attachWorld

​Travel

​startTravel

​Video in React

​Adventure controls

​move

​look

​interact

​hold

​release

​stop

​Directing controls

​instruct

​pause

​resume

​rewind

​Travel status

​State

​worldState

​travelState

​React hook surface

​Errors