Protocol
<cl-mini-game> implements this protocol for you. Read on if you build your own host, such as a
native app, or a new game.
https://mini-games.cresclab.com/v1/<game>/?theme=<theme>&lang=<lang>https://mini-games.cresclab.com/v1/random/?theme=<theme>&lang=<lang>https://mini-games.cresclab.com/v1/manifest.jsontheme:lightordark. Unknown or missing values fall back tolight.lang:zh-TW,en,jaorth. Unknown or missing values fall back toen.randompicks a game and replaces itself with it, keeping the query.manifest.jsonlists the game ids and their titles in each language.
A game works with the URL alone. Messages are optional.
Messages
Section titled “Messages”Hosts and games exchange postMessage data of this shape:
{ source: "cl-mini-games", version: 1, type: string, payload?: object }Anything else is ignored.
| Direction | type |
payload |
Meaning |
|---|---|---|---|
| game → host | ready |
none | The game is playable. |
| game → host | error |
{ message } |
The game cannot start. |
| game → host | escape |
none | Escape was pressed inside the game. |
| host → game | config |
{ theme?, lang? } |
Change the theme or language. |
| host → game | pause |
none | Pause the game. |
| host → game | resume |
none | Allow the game to continue. |
Security
Section titled “Security”- Frame games with
sandbox="allow-scripts"and withoutallow-same-origin. - A sandboxed game has the origin
"null", so a host recognizes its messages byevent.source === iframe.contentWindow, not by origin, and posts to it with target"*". - A game accepts messages only from
window.parentand never sends anything sensitive. - Without
allow-same-origina game has nolocalStorage; scores last until the page closes. - Do not judge success by the frame’s
loadevent: it also fires for an error page. Wait forready.
Versions
Section titled “Versions”A breaking change ships under a new path, /v2/, and /v1/ keeps working for hosts that were built
against it.