#Messages and manifest

The exact shapes OGS and a game exchange. The tables on this page are generated from the zod schemas in packages/ogs-protocol when the site is built, so they match the code. When anything here and the code disagree, the code wins.

With profile-kit you do not post or parse these by hand: see profile-kit reference. This page is for games that do, for tests that fake the launcher, and for agents that want the precise contract.

#Transport

• The launcher and the TV page talk with window.postMessage. Each message is a plain object with a type field.
• The launcher posts to your iframe's contentWindow. Your page posts to window.parent (profile-kit uses target origin "*"; the launcher checks the origin instead).
• The launcher accepts game messages only from the origin of the current game's TV URL, and drops anything that fails GameToLauncherSchema. An ogs:instance without a title labels nothing.
• Validate what you receive: ignore anything whose event.source is not window.parent, and parse with the schema (LauncherToGameSchema.safeParse(event.data)). Unknown messages are ignored, never errors.
• Every message is optional for the game. A game that answers nothing still runs.

#Launcher → game

LauncherToGameSchema in frame.ts.

#ogs:start

The sitting starts or continues. Sent on the frame's load, and again after each ogs:ready.

#ogs:suspend

The launcher parked the frame (Home, or another game). It stays loaded: go silent.

No payload: { type: "ogs:suspend" }.

#ogs:resume

Continue: the same parked frame is shown again, no reload. Resume sound.

No payload: { type: "ogs:resume" }.

#Game → launcher

GameToLauncherSchema in frame.ts.

#ogs:ready

The page is listening; the launcher re-sends ogs:start for the current sitting.

No payload: { type: "ogs:ready" }.

#ogs:resume-point

The sitting's label (older form of ogs:instance).

#ogs:room

The room the TV page shows (multiCouch games): the couch session keeps it on the sitting.

#ogs:instance

The sitting's report; the launcher uses report.title as its label.

#Phone page → app

In the OGS app's WebView a game page talks to the app over the app bridge, not postMessage to a parent. profile-kit uses two bridge stores:

Room games declare their TV page with cast-kit's useCastViewUrl(url); the app forwards it to the launcher. See the contract, §3.

#A typical sequence

launcher                                   your TV page (iframe)
   |  load iframe (allow="autoplay; fullscreen")  |
   |--- ogs:start {instanceId, mode, roster, token, players} --->|
   |<-------------------------- ogs:ready ---------------------- |  (profile-kit, on start-up)
   |--- ogs:start (again, for the current sitting) ------------> |
   |<---------- ogs:instance {report: {title: "Mission 1"}} ---- |
   |              ... the couch plays ...                        |
   |--- ogs:suspend -------------------------------------------> |  Home: go silent, stay loaded
   |--- ogs:resume --------------------------------------------> |  Continue: sound back, no reload

#Manifest

A game is config, not code: one Manifest (ManifestSchema in manifest.ts). Fields with a default may be left out.

An example:

{
  "appId": "space-bakery",
  "name": "Space Bakery",
  "tagline": "Bake for aliens, together.",
  "shape": "couch",
  "tv": "required",
  "startUrl": "https://space-bakery.example.com/",
  "roles": [
    { "id": "chef", "label": "Chef", "audience": "grownup" },
    { "id": "helper", "label": "Helper", "audience": "kid" }
  ],
  "art": {
    "icon": "/art/space-bakery/icon.png",
    "cover": "/art/space-bakery/cover.jpg",
    "logo": "/art/space-bakery/logo.png",
    "heroClean": "/art/space-bakery/hero-clean.jpg",
    "tile": "/art/space-bakery/tv.jpg"
  },
  "shop": { "ages": "4+", "minutes": [10, 20], "players": "2-4" }
}

No tvUrl: this is a room game whose phone page declares the room's TV page at runtime. A game with one TV page for everyone adds "tvUrl": "https://space-bakery.example.com/tv".

#Shared types

#GamePlayer

Someone on the couch (ogs:start.players, GameToken.players).

#RosterEntry

Who sits where (ogs:start.roster).

#InstanceReport

What a game reports about a sitting (ogs:instance, reportOgsSitting). Only instanceId, appId and status are needed.

#InstanceStatus

One of lobby, active, suspended, waiting, completed, expired.

#GameToken

The claims of a game token, as verifyOgsToken returns them.

#CouchClaim

The couch a token was issued for.

#Role

One of the manifest's roles.

#RoomId

A string matching ^[A-Za-z0-9_-]{1,64}$: the game's own room code.