HappyOyster overview

HappyOyster is a real-time interactive world model with two experiences:

Adventure — explore a world with held movement, look, and interaction controls.
Directing — steer a story with text instructions, pause, resume, and rewind.

The experience is selected when you construct the client or mount the React provider. It stays fixed for that session because each experience connects to its own Reactor model. Build on HappyOyster with the typed @reactor-models/happy-oyster SDK. It provides the HappyOysterModel class, React bindings, world lifecycle methods, live controls, and the <HappyOysterVideo> element.

At a glance

Spec	Value
SDK package	`@reactor-models/happy-oyster`
SDK modes	`"adventure"` and `"directing"`
Pricing
Resolution	Directing: 480p or 720p; Adventure: 720p
Session length	Adventure: 2 minutes per travel; Directing: 3 minutes
World input	Text prompt and optional starting image
Live interaction	Adventure controls or Directing instructions and transport

Install

npm
pnpm

npm install @reactor-models/happy-oyster

pnpm add @reactor-models/happy-oyster

Choose an experience

Use mode: "adventure" for movement controls or mode: "directing" for text steering. Set it before connecting:

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

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

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

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

To switch experiences, disconnect and construct a new client. In React, remount the provider with a different key.

World lifecycle

A session has one current world. Worlds persist after a session ends, so save the encrypted_world_id returned by createWorld() and use attachWorld() to return later.

connect → createWorld / attachWorld → startTravel → controls → endTravelSession / disconnect

connect() opens the Reactor session and synchronizes the first worldState snapshot.
createWorld(params) builds a new world for the client’s selected mode.
attachWorld(encryptedWorldId) reopens an existing world of the same mode.
startTravel() begins the live world stream and reports how long that stream may run.
Adventure uses move, look, interact, release, and stop.
Directing uses instruct, pause, resume, and rewind.

An Adventure travel runs for up to 2 minutes and a Directing travel for up to 3, and the platform ends the stream when that length runs out. startTravel() reports an Adventure travel’s granted length as maxExperienceTimeSec, readable on the client and from useHappyOyster(). The startTravel reference covers both. The model publishes authoritative worldState and travelState snapshots. Drive UI from those snapshots instead of reconstructing state from individual calls.

Quick start

The fastest path to a working HappyOyster app is the create-reactor-app CLI, which scaffolds a runnable project for you. You can also clone the open-source reference frontend directly, or follow the tutorial for a guided walkthrough.

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

const model = new HappyOysterModel({
  mode: "adventure",
  videoElement: document.querySelector("video")!,
});

model.onWorldState((state) => {
  console.log(state.phase, state.encrypted_world_id);
});

await model.connect(jwt);

const world = await model.createWorld({
  prompt: "A sunny grassy meadow with rolling green hills, wildflowers, and a winding dirt path.",
  perspective: "third_person",
});

saveWorldId(world.encrypted_world_id);
await model.startTravel();
await model.move("Front");

"use client";

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

function Controller() {
  const { createWorld, startTravel, worldState } = useHappyOyster();

  async function enter() {
    await createWorld({
      prompt: "A rain-slick neon alley at midnight.",
      resolution: "720p",
      narrative: "Dramatic",
    });
    await startTravel();
  }

  return (
    <button onClick={enter}>{worldState?.phase === "ready" ? "Enter world" : "Build world"}</button>
  );
}

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

See the tutorial for a full application flow, the schema reference for every typed method and state field, and the prompt guide for world authoring.

Overview

FastH3

Visko Orbis Stable

Visko Orbis Dynamic

HappyOyster

LingBot World 2

LingBot

X2

Helios

LongLive-2.0

SANA-Streaming

LTX

HappyOyster overview

At a glance

Install

Choose an experience

World lifecycle

Quick start

​At a glance

​Install

​Choose an experience

​World lifecycle

​Quick start

At a glance

Install

Choose an experience

World lifecycle

Quick start