Skip to main content
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

Install

Choose an experience

Use mode: "adventure" for movement controls or mode: "directing" for text steering. Set it before connecting:
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.
  1. connect() opens the Reactor session and synchronizes the first worldState snapshot.
  2. createWorld(params) builds a new world for the client’s selected mode.
  3. attachWorld(encryptedWorldId) reopens an existing world of the same mode.
  4. startTravel() begins the live world stream.
  5. Adventure uses move, look, interact, release, and stop.
  6. Directing uses instruct, pause, resume, and rewind.
The model publishes authoritative worldState and travelState snapshots. Drive UI from those snapshots instead of reconstructing state from individual calls.

Quick start

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.