# Oriverse — AI agent quickstart

Human? Paste this page's URL into your AI agent (Claude Code, Codex, ChatGPT,
claude.ai) and ask it to build you a game. AI agent? This page is everything
you need to get set up; once connected, MCP is the source of truth.

Oriverse is a game engine with a live editor. You build games by writing Weave
(Oriverse's language) over MCP. The flow: connect MCP → read the Weave skill →
build and playtest → deliver: `share_game` (play link), `publish_game` (the
user's account page), or `submit_pending_world` into the user's running editor.

Building, playtesting and sharing need no client: the MCP server runs the
engine for you. A signed-in client (step 1) is needed only to land the world in
the user's own editor (`submit_pending_world`) and for the editor's Publish.

## 1. Get a live client (optional — needed for submit / Publish)

- **Windows (default): desktop app** — see "Desktop download" below; you can
  run the whole download yourself.
- **Everything else (macOS/Linux, or no-install preference): web editor** —
  ask the user to open https://www.oriverse.com/editor in a WebGPU browser
  (Chrome/Edge, or Safari 26+) and sign in (free account), then skip to step 2.

Either way the app/page must stay open and signed in for `submit_pending_world`:
it routes to the live client, and only when the agent's MCP OAuth account matches
the client's signed-in account.

### Desktop download (Windows x86_64)

1. Fetch the release manifest: https://www.oriverse.com/binary/editor/latest.json
2. Show the user the version (`tag`) and download size (`zip_bytes`), and ask
   before downloading or running anything.
3. Download `zip_url`, verify `zip_sha256`, extract, start `entrypoint`:

~~~powershell
$m = Invoke-RestMethod https://www.oriverse.com/binary/editor/latest.json
$zip = Join-Path $PWD "oriverse-$($m.tag).zip"
Invoke-WebRequest $m.zip_url -OutFile $zip
$actual = (Get-FileHash $zip -Algorithm SHA256).Hash.ToLowerInvariant()
if ($actual -ne $m.zip_sha256.ToLowerInvariant()) { throw "SHA-256 mismatch" }
$dir = Join-Path $PWD "oriverse-$($m.tag)"
Expand-Archive -LiteralPath $zip -DestinationPath $dir
Start-Process (Join-Path $dir $m.entrypoint)
~~~

Do not bypass Windows security prompts — let the user approve them. The user
then signs in (or creates a free account) and leaves the app open.

### No sign-in? Agent CLI lane (Windows)

The desktop exe is also a self-documenting CLI — no account, no MCP needed.
`oriverse.exe tools` lists every agent tool and writes `agent_readme.md` (the
CLI quickstart, also shipped next to the exe) with the calling conventions.
Build: `read_skill("weave_coding")` → `stage_new_world` → `playtest` →
`share_game` (a hosted play link: browser or desktop app, one shared live
session per link). The GUI exe has no console: call it via Start-Process with
output redirects, and pass tool args as `--args-file <path.json>`. Publishing
to an account still needs the signed-in lane below.

## 2. Connect your agent to MCP

MCP server: `https://mcp.oriverse.com/relay/mcp` (Streamable HTTP + OAuth).

Codex CLI:

~~~text
codex mcp add oriverse --url https://mcp.oriverse.com/relay/mcp
codex mcp login oriverse
codex mcp list
~~~

Claude Code:

~~~text
claude mcp add --transport http oriverse https://mcp.oriverse.com/relay/mcp
~~~

then run `/mcp` and authenticate.

claude.ai / ChatGPT: add `https://mcp.oriverse.com/relay/mcp` as a connector
(ChatGPT: Settings → Apps & connectors → Developer mode → Create, choose
OAuth, sign in).

Sign in with the SAME Oriverse account as the client from step 1. After OAuth,
restart the agent or open a new session so the tools load.

## 3. Build

1. Call `read_skill("weave_coding")` before writing or changing any Weave —
   it returns the language reference matching the connected client's version.
   Never guess Weave syntax or reuse Weave docs found elsewhere.
2. Inspect the available tools and the current client/project state, then use
   the MCP tools to stage, patch, and run the world against the live client.
3. Keep user confirmations for destructive, publishing, or purchasing actions.

## 4. Share

When the game is ready, the user presses **Publish** in the editor. Publish
updates the live public version and gives a public project page URL — that
link is the shareable game (multiplayer works; players sign in free).

Without publishing: `share_game` returns a temporary hosted play link
(expires ~30 days) — a page offering instant browser play or
open-in-desktop-app, where everyone on the link shares one live session.

## If something fails

- `submit_pending_world` reports no bound client: the Oriverse app/page is not
  open, not signed in, or signed into a different account than the MCP OAuth.
  Everything else works without a client; `share_game` still delivers a link.
- OAuth succeeded but tools don't appear: restart the agent or open a new
  session/task.
- Unsupported OS/arch for the desktop ZIP: use the web editor path.
- SHA-256 mismatch: delete the file and re-download; never run a mismatched
  binary.