Packages overview

Openturn is split across eighteen packages. This page is the decision tree: “I want to do X, which one do I import.”

Authoring

Package	Runtime	Why
`@openturn/core`	worker	The engine. `defineGame`, `definePlayerIDs`, events, states, transitions, `createLocalSession`.
`@openturn/gamekit`	worker	Move-first sugar over core: `defineGame`, moves, phases, outcomes. Use this unless you need the core escape hatch.
`@openturn/json`	worker	`JsonValue` types, `JsonValueSchema`, and validators. Re-exported by most packages; you will import it directly for explicit JSON validation.
`@openturn/bot`	worker	Plug-and-play AI bots over a game. `defineBot({ decide })`, `attachLocalBot` / `attachLocalBots` / `attachHostedBot`, `simulate`. Same bot shape for random, heuristic, and MCTS players.

Hosting and transport

Package	Runtime	Why
`@openturn/protocol`	worker	Wire protocol: `ClientAction`, `BatchApplied`, lobby messages, Zod schemas. Shared between client and server.
`@openturn/server`	worker	Authoritative `RoomRuntime`, `LobbyRuntime`, `createGameWorker` factory for Cloudflare, room tokens, persistence.
`@openturn/client`	worker	WebSocket client. `createHostedClient` handles connect, dispatch, and state synchronization.
`@openturn/bridge`	browser	Iframe↔shell wire. `createGameBridge` on the iframe, `createBridgeHost` on the shell, plus the shell-controls registry the host renders save / load / reset / lobby chrome from.
`@openturn/manifest`	worker	Deployment manifest schema + HTML generator. Shared by `@openturn/deploy` (writer) and the cloud shell (reader). Owns `SHELL_CONTROL_IDS`.

UI and tooling

Package	Runtime	Why
`@openturn/react`	browser	React hooks: `createOpenturnBindings`, `<OpenturnProvider>`, `useMatch`, `useRoom`, `useInspector`, `Lobby`.
`@openturn/lobby`	mixed	Unified lobby surface — protocol extensions, runtime helpers, React UI, bot registry, and bot supervisors. Five subpath exports; only `./react` touches the DOM.
`@openturn/replay`	worker	Saved replay envelopes, timeline materialization, cursor-based playback, branching.
`@openturn/inspector`	worker	Non-UI inspector logic: `buildInspectorTimelineFromSource` (unified replay/hosted entry), diffs, graph highlights.
`@openturn/inspector-ui`	browser	Ready-made React inspector components: `createInspector` returns `{ Inspector, ReplayInspector, HostedInspector }`.
`@openturn/deploy`	Bun	Build pipeline: `discoverOpenturnProject`, `buildOpenturnProject`, manifest, Worker bundle generation.
`@openturn/cli`	Bun	The `openturn` binary: `create`, `dev`, `build`, `deploy`, `login`.

Plugins

Package	Runtime	Why
`@openturn/plugins`	worker	Plugin authoring + composition: `definePlugin`, `definePluginMove`, `withPlugins`. Compose cross-cutting features (chat, votes, emotes) into a gamekit game without forking the host.
`@openturn/plugin-chat`	mixed	First-party in-room chat plugin: `chatPlugin` (worker-safe) plus a `<ChatBubble />` React widget under `./react`.

Quick recipes

“I want to author a game.” — Start with @openturn/gamekit. Drop to @openturn/core if gamekit doesn’t fit. “I want to run a game in my React app.” — @openturn/react’s createOpenturnBindings(game, { runtime, match? }) returns a zero-prop <OpenturnProvider> that auto-resolves transport (in-process for local, bridge fragment for multiplayer — same provider in dev and prod). Read state with useMatch (just the game) or useRoom (full room with lobby, bridge, invite URL). “I want multiplayer.” — @openturn/server on the server, @openturn/client (via React) on the client, @openturn/protocol as the wire format, @openturn/bridge to connect an embedded iframe to its hosting shell. “I want replays.” — @openturn/replay for capture and load, @openturn/inspector-ui for the inspector UI. “I want to deploy.” — openturn build and openturn deploy from @openturn/cli; the build pipeline is @openturn/deploy. “I want a player to play vs the computer.” — @openturn/bot. defineBot({ decide }) writes the bot, attachLocalBot / attachLocalBots binds it to a seat, the runner dispatches autonomously. Same bot works in CLI and over WebSocket via attachHostedBot.

Dependency layering

Packages fan out from @openturn/core. A short dependency map (arrows point “depends on”):

@openturn/core ──┬── @openturn/gamekit
                 ├── @openturn/server ──── @openturn/protocol ── @openturn/json
                 ├── @openturn/client ────┘
                 ├── @openturn/bot ───────┘
                 ├── @openturn/replay
                 ├── @openturn/lobby (depends on core/protocol/server/client/bot)
                 ├── @openturn/plugins ── @openturn/plugin-chat
                 └── @openturn/inspector ── @openturn/inspector-ui
                                           └── @openturn/react ── @openturn/bridge ── @openturn/manifest
                                                                 └── @openturn/deploy ── @openturn/cli

Everything downstream of core treats GameSnapshot and GameDefinition as the canonical interface. You can drop any downstream package from your app and still have a working authored game.

When to reach for the uncommon packages

I need a custom transport (not WebSocket). Implement HostedTransport in @openturn/client — pass it as transport to createHostedClient. The @openturn/protocol message types let you serialize over any duplex channel (BroadcastChannel, Web Transport, an RPC bus for tests). I’m building my own inspector UI (not React). Use @openturn/inspector directly — buildInspectorTimelineFromSource produces a replay-safe timeline of steps from snapshots, batches, and (optionally) a compiled graph. It returns plain data you can render with any UI framework. I’m writing a CLI tool that runs games outside openturn-cloud. Bun-only tools can depend on @openturn/deploy (build pipeline) and @openturn/server (local room runtime) together. See scripts/ for examples. I want to render a saved replay without connecting to any live match. Import @openturn/replay for the envelope schema and @openturn/inspector-ui’s createInspector(bindings).ReplayInspector. No server, no client, no bridge. I’m embedding a game iframe into a non-openturn host. @openturn/bridge is the whole wire. createGameBridge inside the iframe, createBridgeHost on your shell — no dependency on openturn-cloud itself.

Runtime boundaries

Worker-target packages cannot import Node or Bun APIs. Browser packages cannot import Node. Bun packages can import anything. See concepts: runtime boundaries for why and how the checker enforces it.

​Authoring

​Hosting and transport

​UI and tooling

​Plugins

​Quick recipes

​Dependency layering

​When to reach for the uncommon packages

​Runtime boundaries