Mindblown

View saved version →

---
name: mindblown
description: "Publish browser games and interactive pages to the web with Mindblown. Use when the person wants a game or page they built hosted at a link anyone can open, a new version of something they already published, rolled back, listed on their public profile, or a list of what they published. Mindblown checks it in a real browser before it goes live."
---
<!-- GENERATED by scripts/build-plugin-skills.py from mindblown-api/internal/httpapi/skillapi/skill.md. DO NOT EDIT. -->

# mindblown

## How to reach mindblown from here

Use the first way that is available. Everything else in this file applies to
both.

1. **The mindblown tools are connected** (`publish`, `publish_status`,
   `get_page_files`, `list_projects`, `list_versions`, `release_version`,
   `set_listed`, `create_test_seats`, `get_page_errors`, `get_page_stats`).
   Use them. The host signs the person in when a tool asks for it, so skip
   [Sign in](#sign-in) and never ask for or keep a token. Each tool is one
   call below:

   | HTTP call in this file | Tool |
   |---|---|
   | `POST /publish` | `publish` with `files: [{path, content, encoding}]`, `title`, `page_id` |
   | `GET /publish/<job>` | `publish_status` with `job_id` |
   | `GET /me/games` | `list_projects` |
   | `GET /me/games/GAME_ID/versions` | `list_versions` |
   | `POST /me/games/GAME_ID/release` with `sha` | `release_version` with `version` |
   | `PATCH /me/games/GAME_ID` with `listed` | `set_listed` |
   | `POST /me/test-seats/GAME_ID` | `create_test_seats` |
   | `GET /me/games/GAME_ID/errors` with `sha` | `get_page_errors` with `version` |
   | `GET /me/insights` with `game_id` | `get_page_stats` with `page_id` |

   A publish is three calls: `publish`, then `publish_status` until it is
   done, then `open_page` with the `page_id` to show the person the live page.

   Every tool takes the publish `page_id` where the HTTP call takes
   `GAME_ID`; the tool finds the page itself. Send text files with
   `encoding: "utf8"` and every other file with `encoding: "base64"`.

   **To change a page that is already published**, you do not have its files
   from an earlier turn. Call `get_page_files` with its `page_id`, edit the
   files, then `publish` ALL of them with the same `page_id`, poll
   `publish_status` until it is done, and call `open_page`. The file objects
   go back into `publish` unchanged. Leave the tags mindblown put in the HTML (a script tag, `og:`
   meta, the favicon); publishing puts them back by itself. If the answer says
   `complete: false`, the files in `omitted` were too large to send, and a
   publish without them removes them from the page: tell the person, and do
   not publish until they agree.

   **To put an older version back**, call `list_versions`, confirm the page and
   the version with the person, then call `release_version` with that `sha` as
   `version`.

2. **No mindblown tools, or the tools cannot sign the person in.** Use the
   HTTP API exactly as this file shows, with `curl` and the device flow.

You make visual content. mindblown gives it a URL.

Send a directory of files. If the page renders in a real browser, it goes live
at an address you can share, and you get play counts for it. If it does not
render, we tell you what broke and publish nothing.

**API base:** `https://api.mindblown.ai`

## What you can publish

Anything that is a web page. A scene, a tool, a simulation, a story, a toy, a
visualisation, a page that is just very good to look at. Any style, any
fidelity, any subject.

We do not judge whether the content is good. That is between you and the person
you are building for. We check one thing, and we check it honestly: **does the
page load and draw something.**

## Sign in

mindblown uses the OAuth 2.0 device flow (RFC 8628). You never handle a
password. An API key exists for assets only (see "Make assets"); it cannot
publish.

### 1. Ask for a code

```bash
curl -X POST https://api.mindblown.ai/auth/device/code
```

``

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 4 — file references are metadata, not package contents.

View saved version →

---
name: mindblown-multiplayer
description: "Build multiplayer browser games with Mindblown: live rooms with a lobby, seats, and rules.js running on the server at twenty ticks a second. Use when a game or page has two or more players at once, a shared board, turns, or needs a test seat for a second player. Publish it with the Mindblown skill."
---
<!-- GENERATED by scripts/build-plugin-skills.py from mindblown-web/src/pod/multiplayer.md. DO NOT EDIT. -->

> Publish with the `mindblown` skill. When the mindblown tools are connected,
> ask for a test seat with `create_test_seats` (`page_id`, `count`, `seats`):
> it answers the same JSON as `POST /me/test-seats/<game_id>` below, and you
> need no token. Without the tools, use that HTTP call with the token the
> `mindblown` skill's sign-in gave you.

# Playing together on mindblown

A page where more than one person is in the same place at once -- a table, a
match, a shared board, everybody moving at once or one at a time. This is the
part of the SDK (`references/sdk.md` in the `mindblown` skill) for that, and only that. Everything here is
`window.mindblown` (`mb` below), the same object the SDK describes.

**Read this whole file before writing the first line of a page that seats two
people.** Two things are different from every other page: the rules of your
page run in a file that runs on the server, and your page draws what the
server says rather than what it worked out itself. The rules in here are the
ones the server enforces, and a refusal will name this file.

## Contents

| Section | What it settles |
| --- | --- |
| [The shape](#the-shape) | what runs where |
| [The lobby and the match](#the-lobby-and-the-match) | `play`, `lobby`, `match` -- how people get to the table |
| [The room is the authority](#the-room-is-the-authority) | where every fact about a room comes from |
| [Seats](#seats) | numbering, and who goes first |
| [The invitation](#the-invitation) | the name, the link, `shareUrl` |
| [Accounts](#accounts) | why a seat needs one, and what your page does about it |
| [Testing it](#testing-it) | a second person, so you can open a page for two |
| [`rules.js`](#rulesjs) | the five exports, their arguments, what they may not do |
| [`mb.live`](#mblive) | the channel: sending, hearing ticks, closing |
| [The tick](#the-tick) | what every seat receives, twenty times a second |
| [Turns on live](#turns-on-live) | a turn-based match, whole |
| [Drawing between ticks](#drawing-between-ticks) | interpolate what the room moves, carry forward what a seat moves |
| [What we decide](#what-we-decide) | and what is yours |
| [What we keep](#what-we-keep) | how a round becomes a record, and why `places` |
| [What happened in a room](#what-happened-in-a-room) | every tick, kept; run your rules against it again |
| [Who is watching](#who-is-watching) | presence |
| [Names on screen](#names-on-screen) | `mb.recording.mask`, for names you draw in 3D |
| [Refusals](#refusals) | every `reason` |
| [A whole page](#a-whole-page) | the smallest complete example |
| [The old wire](#the-old-wire-until-31-december-2026) | deprecated, and still answering |

## The shape

Your page ships two things:

- **`rules.js`** at the root of your bundle, served at `https://<your-host>/rules.js`.
  The room fetches it when a room opens and runs it. It has no DOM, no
  network, no clock of its own. It is the rules, and nothing else.
- **The page**, which draws the lobby and the match, and sends the seat's
  input. It decides nothing about the match, and nothing about how people get
  to it: which room, the join and the start are ours.

The room runs `step` twenty times a second and sends each seat what `view`
says that seat may see. Everybody draws the same match because everybody is
drawing the room's answer.

**Send one input per tick, which is twenty a second.** The room keeps the LAST
input per seat and clears them as the tick runs, so a second message in the
same tick replaces the first and anything

Preview of the first 4,000 characters. Read full instructions →