Installation and setup
You will need:- Node.js 18.18 or later.
- A Reactor API key (starts with
rk_).
.env.local in the project root and add your Reactor API key:
.env.local
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:- When the session status is
ready, the app can send commands. - 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 exchangesREACTOR_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.
app/token.ts
Build the explorer
Replaceapp/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
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 renderslastError 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.