Skip to main content
Build a Next.js app to create and explore Genie 4 worlds. The app supports text and image inputs, video and sound, movement controls, and live instructions.

Installation and setup

You will need: Create the app and install its dependencies:
Create .env.local in the project root and add your Reactor API key:
.env.local
Keep the key on the server. Do not put it in a NEXT_PUBLIC_ variable. Keep the generated app/layout.tsx. Add the token route and replace app/page.tsx with the code below.

How Genie 4 works

The app first connects to a Reactor session, then starts a world within it:
  1. When the session status is ready, the app can send commands.
  2. When the world phase is live, you can explore the world.
A world and a session have different lifetimes. Ending a world leaves the session open. A new world starts from fresh inputs and cannot resume the previous world.
startWorld, setKeys, and instruct send actions without returning a result. The app checks lastError for refused commands. It listens for world updates to show when a world starts, ends, or fails. A command can return before its effect appears in the world. getState reads the current world state. endWorld stops the world and returns its state. Both return undefined if the command fails. After reconnecting, the app clears its old world state. It calls getState again before enabling controls.

Authentication

The server exchanges REACTOR_API_KEY for a session-scoped JWT. The scope names reactor/genie-4. Return { jwt, expires_at } with Cache-Control: private, no-store, including on error responses. The Python alternative below is a token broker for browser clients.
Create the browser resolver below. It caches the token in module scope and combines concurrent requests. The browser HTTP cache does not preserve token identity. A session belongs to the token that created it, so keep that token throughout that session. This resolver refreshes shortly before expiry. End an active session before that refresh point and connect a new session. Replacing the token cannot transfer an existing session to the new token. See Authentication for session binding.
app/token.ts

Build the explorer

Replace app/page.tsx with this file. Genie4Provider declares both receive tracks. Genie4MainVideoView renders the video. useGenie4Track("main_audio") supplies the audio track for an HTML audio element, whose controls allow playback after an autoplay refusal. The keyboard handlers leave text fields, buttons, media controls, and dialogs to the browser. Focus entering those controls releases world input. Keyboard keys and pointer IDs have separate held sets, so one pointer release preserves keys held through another input. The held sets stay local to this client. The keys field in the snapshot combines all clients. The effect reads current actions from a ref because typed command functions can change between renders.
app/page.tsx
Run npm run dev and open the local URL. Connect, start a world, and use the audio controls if needed. The initial dark frame and silence are placeholders. Wait for live and check that the generated world moves and its sound plays. End the world, then use Start new world to try again.

Surfacing refusals

The app renders lastError with operation: "sendCommand" as a command error. It does not turn a refused command into a disconnected state. The store retains the latest error, so the panel describes the last reported failure rather than the result of every later command. startWorld, setKeys, and instruct resolve undefined on success and refusal. Do not use try/catch or a truthy result to decide whether those commands succeeded. The try/catch in start() handles the image upload, which can reject. Later world failures appear in state.last_error. Show its reason, offer retries according to retryable, and include trace_id when reporting a failure.