> ## Documentation Index
> Fetch the complete documentation index at: https://openturn.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Examples

> The openturn repo ships several runnable games. This is the cross-reference.

Every example lives under `examples/<purpose>/<name>` in the monorepo. Most have a `game` worker package (the authored game) and either an `app` browser package (React UI), a `cli` Bun package (terminal), or both.

<Note>
  Looking up a specific package name, path, or `bun --filter` command? See the [Examples index](/docs/reference/examples) — every shipped package with its path and run command in one table.
</Note>

## Featured: Splendor

[Splendor](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/splendor) is the flagship end-to-end example — a Splendor-faithful 2–4 player tabletop with hosted multiplayer, hidden per-player state, three difficulty-tiered AI bots, a polished React 19 + Tailwind v4 + framer-motion table, and a deploy-ready `app/` package. Use it to see what a fully realized openturn game looks like and as the canonical thing to play and stress-test against.

```bash theme={null}
# Local hosted multiplayer (open the printed URL in 2–4 tabs)
bun --filter @openturn/example-splendor-app dev

# Game-logic test suite (setup, hidden-state secrecy, end-of-round trigger, …)
bun --filter @openturn/example-splendor-game test

# One-tab visual preview (no lobby, both seats local) — great for UI work
# Append ?preview=local to the dev URL
```

What it demonstrates:

* **Hidden information** — opponents' reserved cards stay on the worker; `views.player` projects them down to a count.
* **Variable seating** — `MatchInput.minPlayers` lets 2, 3, or 4 players seat through `<Lobby>`.
* **End-of-round triggers** — first to 15 points flips a flag; the round completes before the winner is declared.
* **Bots in the lobby** — per-seat dropdown picks `Random`, `Greedy`, or `Strategic` from the [`bots/`](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/splendor/bots) package.
* **Cloud deploy** — `bun run deploy` from the app dir builds the bundle, uploads the multiplayer Worker, and prints the openturn-cloud play URL.

## Get started: Tic-tac-toe

[Tic-tac-toe](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/tic-tac-toe) is the smallest end-to-end gamekit example and the one every tutorial walks through. Start here when learning openturn — it's reused across the React UI, CLI, multiplayer, replay viewer, chat-plugin, and bot examples, so the same `game/` package shows up in every recipe.

```bash theme={null}
# Local React UI
bun --filter @openturn/example-tic-tac-toe-app dev --port 3000

# Terminal, with optional bot opponent and replay capture
bun --filter @openturn/example-tic-tac-toe-cli demo
bun --filter @openturn/example-tic-tac-toe-cli demo -- --bot 1=minimax
bun --filter @openturn/example-tic-tac-toe-cli demo -- --save-replay out.json
```

Walk it end-to-end in the [Tic-tac-toe with gamekit](/docs/tutorials/tic-tac-toe-gamekit) tutorial.

## End-to-end games

Complete, runnable games under `examples/games/`.

| Example                                                                                              | Authoring | Local UI    | Hosted | Bots                            | Replay  | Hidden info | Notes                                                                          |
| ---------------------------------------------------------------------------------------------------- | --------- | ----------- | ------ | ------------------------------- | ------- | ----------- | ------------------------------------------------------------------------------ |
| [splendor](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/splendor)       | gamekit   | React       | hosted | 3 (random / greedy / strategic) | —       | yes         | Flagship demo. 2–4 players, polished tabletop UI, deploy-ready.                |
| [tic-tac-toe](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/tic-tac-toe) | gamekit   | React + CLI | —      | 2 (random / minimax)            | capture | no          | Get-started example. Reused across multiplayer, replay viewer, chat plugin.    |
| [pig-dice](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/pig-dice)       | gamekit   | CLI         | —      | —                               | —       | no          | Simple 2-player dice push-your-luck CLI.                                       |
| [battleship](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/battleship)   | gamekit   | React       | hosted | —                               | —       | yes         | Hidden fleets, multi-phase (planning → battle → gameOver), hosted multiplayer. |

## Authoring with raw `@openturn/core`

Under `examples/using-core/` — same games as their gamekit counterparts, written without gamekit.

| Example                                                                                                                             | Notes                                                |
| ----------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| [tic-tac-toe-core](https://github.com/openturn-io/openturn/tree/main/openturn/examples/using-core/tic-tac-toe-core)                 | Tic-tac-toe authored with `@openturn/core` directly. |
| [paper-scissors-rock-core](https://github.com/openturn-io/openturn/tree/main/openturn/examples/using-core/paper-scissors-rock-core) | Simultaneous-move RPS in raw core.                   |
| [persistent-wins-core](https://github.com/openturn-io/openturn/tree/main/openturn/examples/using-core/persistent-wins-core)         | Profile lifecycle in raw core.                       |

## Persistent player profiles

Under `examples/using-profiles/` — hydrate → play → commit → apply.

| Example                                                                                                               | Notes                                               |
| --------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
| [persistent-wins](https://github.com/openturn-io/openturn/tree/main/openturn/examples/using-profiles/persistent-wins) | Gamekit demo of the profile lifecycle.              |
| [card-discovery](https://github.com/openturn-io/openturn/tree/main/openturn/examples/using-profiles/card-discovery)   | Card memory game showing the host-side commit hook. |

## By concept

Each example is the canonical demo for one openturn concept.

| Concept                       | Example                                                                                                                                                                                                                     | Notes                                                                                                                                                                                           |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Featured / hosted multiplayer | [splendor](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/splendor)                                                                                                                              | 2–4 player Splendor with `<OpenturnProvider>` + `useRoom` + lobby bots. The flagship end-to-end demo.                                                                                           |
| Simultaneous moves            | [paper-scissors-rock](https://github.com/openturn-io/openturn/tree/main/openturn/examples/simultaneous-moves/paper-scissors-rock)                                                                                           | Hidden submissions until everyone has played. 3 players. Also available in [raw core](https://github.com/openturn-io/openturn/tree/main/openturn/examples/using-core/paper-scissors-rock-core). |
| Hosted multiplayer (minimal)  | [tic-tac-toe-multiplayer](https://github.com/openturn-io/openturn/tree/main/openturn/examples/hosted-multiplayer/tic-tac-toe-multiplayer)                                                                                   | `<OpenturnProvider>` + `useRoom`. Runs against `openturn dev` locally and openturn-cloud in production.                                                                                         |
| Replay capture & playback     | [tic-tac-toe-replay-viewer](https://github.com/openturn-io/openturn/tree/main/openturn/examples/replays/tic-tac-toe-replay-viewer)                                                                                          | Load a saved replay JSON and scrub through it.                                                                                                                                                  |
| Plugin integration            | [tic-tac-toe-with-chat](https://github.com/openturn-io/openturn/tree/main/openturn/examples/plugins/tic-tac-toe-with-chat)                                                                                                  | Tic-tac-toe with the chat plugin wired in.                                                                                                                                                      |
| AI bots                       | [tic-tac-toe/bots](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/tic-tac-toe/bots) and [splendor/bots](https://github.com/openturn-io/openturn/tree/main/openturn/examples/games/splendor/bots) | Tic-tac-toe ships random + alpha-beta minimax wired into the CLI; Splendor ships random/greedy/strategic wired into the lobby.                                                                  |

## Run them

From the monorepo root. For the complete list of packages and commands (including library packages with no `dev` script), see the [Examples index](/docs/reference/examples).

```bash theme={null}
# Splendor (featured) — hosted multiplayer with bots, 2–4 players
bun --filter @openturn/example-splendor-app dev

# Local tic-tac-toe (React)
bun --filter @openturn/example-tic-tac-toe-app dev --port 3000

# Tic-tac-toe CLI with replay capture
bun --filter @openturn/example-tic-tac-toe-cli demo -- --save-replay out.json

# Tic-tac-toe CLI vs an AI bot (random or minimax)
bun --filter @openturn/example-tic-tac-toe-cli demo -- --bot 1=random
bun --filter @openturn/example-tic-tac-toe-cli demo -- --bot 1=minimax

# Tic-tac-toe multiplayer (local hosted)
bun --filter @openturn/example-tic-tac-toe-multiplayer-app dev

# Replay viewer
bun --filter @openturn/example-tic-tac-toe-replay-viewer-app dev --port 3001

# Paper-scissors-rock (gamekit and raw core)
bun --filter @openturn/example-paper-scissors-rock-app dev --port 3003
bun --filter @openturn/example-paper-scissors-rock-core-app dev --port 3004

# Tic-tac-toe with the chat plugin
bun --filter @openturn/example-tic-tac-toe-with-chat-app dev

# Pig dice (CLI only)
bun --filter @openturn/example-pig-dice-cli demo

# Battleship
bun --filter @openturn/example-battleship-app dev
```

## By tutorial

* [Tic-tac-toe with gamekit](/docs/tutorials/tic-tac-toe-gamekit) walks the `tic-tac-toe` example end to end. **Start here.**
* [Tic-tac-toe multiplayer](/docs/tutorials/tic-tac-toe-multiplayer) walks `tic-tac-toe-multiplayer`.
* [Tic-tac-toe replay](/docs/tutorials/tic-tac-toe-replay) walks `tic-tac-toe-replay-viewer`.
* [Tic-tac-toe with core](/docs/tutorials/tic-tac-toe-core) walks `tic-tac-toe-core`.
* [Tic-tac-toe with bots](/docs/tutorials/tic-tac-toe-bot) walks the `tic-tac-toe/bots` package and the bot-aware CLI.

## By how-to

* [Model hidden information](/docs/how-to/model-hidden-info) uses battleship snippets.
* [Handle simultaneous moves](/docs/how-to/handle-simultaneous-moves) uses paper-scissors-rock.
* [Handle randomness](/docs/how-to/handle-randomness) uses pig-dice.
* [Add a CLI front-end](/docs/how-to/add-a-cli) covers the tic-tac-toe and pig-dice CLIs.
* [Persist player state](/docs/how-to/persist-player-state) uses `persistent-wins` (gamekit) and `persistent-wins-core`.