# TipTap Games — SDK Guide for AI Agents

You are building a single-file HTML5 game for **TipTap Games** (https://tiptapgames.com), a
vertical swipe feed of instantly-playable browser games.

This document is the complete specification. Everything you need is here — do not
guess at the API and do not fetch anything else.

**Output requirement:** one self-contained `.html` file. All CSS and JavaScript inline.
No build step, no bundler, no dependencies.

---

## 1. Hard constraints — violating these silently breaks the game

Games run in a cross-origin iframe with `sandbox="allow-scripts"` and a strict CSP.
The document has an **opaque origin**. These are not style preferences; each one fails
silently or throws at runtime.

| Forbidden | Why |
|---|---|
| `fetch()`, `XMLHttpRequest`, `WebSocket`, `EventSource` | `connect-src 'none'` — every network call is blocked |
| `<script src="...">`, `<link href="...">` | Only inline `<script>` / `<style>` are allowed |
| External images, fonts, audio by URL | `img-src`/`media-src` allow **only** `data:` and `blob:` |
| `localStorage`, `sessionStorage`, `indexedDB` | Opaque origin — these throw on access |
| Cookies | Same reason |
| `<form>` submission, `<base>` | `form-action 'none'`, `base-uri 'none'` |
| `window.open`, `window.top` access, navigation | Sandboxed |

**Allowed and encouraged:** Canvas 2D, WebGL, Web Audio API, `requestAnimationFrame`,
`setTimeout`/`setInterval`, pointer/touch/keyboard events, CSS animations, inline SVG,
`data:` URIs for sprites and audio.

**Persistence:** keep all state in memory. If you need it to survive a reload, it must go
through `TipTap.submitScore()` or `TipTap.unlockAchievement()` — there is no other storage.

---

## 2. The SDK

`window.TipTap` is **injected automatically** into every game by the platform. Do not
define it, do not import it, do not add a script tag for it. It exists before your code
runs.

Always feature-detect (`if (window.TipTap)`) so the file still runs when opened directly
during development.

### Scoring

```js
TipTap.updateScore(score)   // live score in the platform's top bar. No DB write. Call freely.
TipTap.submitScore(score)   // write to the leaderboard. SILENT — shows no UI.
TipTap.submitScore(score, { showLeaderboard: true })  // submit and show the board in one call
TipTap.onResult(cb)         // cb({ rank, percentile, personalBest, ghostScore, ghostHandle })
```

> **Breaking change from SDK v1 — read this.**
> `submitScore()` used to pop the leaderboard automatically. **It no longer does.** It
> writes the score and returns; your game keeps running. You decide when to show the
> board. If you are porting old code, add a `showLeaderboard()` call after each
> `submitScore()` at a real game-over.

Scores are integers. Each game has a server-enforced `scoreMax`; submitting above it is
rejected with a 400.

### Leaderboard

```js
TipTap.showLeaderboard()        // raise the results overlay. Your game is paused underneath, not unloaded.
TipTap.hideLeaderboard()        // dismiss it programmatically
TipTap.onLeaderboardClose(cb)   // player dismissed it via Continue / X / Escape
```

The overlay offers the player three actions:

- **Continue** — closes the overlay and hands control straight back. **Your game is never
  reloaded and no state is lost.**
- **Play again** — remounts your game from scratch. All state is destroyed.
- **Next game** — moves on through the feed.

This is why the split exists. If your game has any progression — a roguelike run, a level,
a partially-filled board — submit the score and let the player Continue. Only treat a run
as over when it genuinely is.

### Audio and focus — REQUIRED

Players swipe between games constantly. Two games playing music at once is the single
worst bug on the platform. The platform pauses off-screen games, but **it cannot reach
inside your audio graph** — you must stop your own sound.

```js
TipTap.canPlayAudio()   // true only when on-screen AND not globally muted. Use this one.
TipTap.isFocused()      // is this game the one the player is looking at?
TipTap.isMuted()        // has the player muted all games with the platform toggle?
TipTap.isPaused()       // has the platform paused this game?

TipTap.onFocusChange(cb)   // cb(focused: boolean)
TipTap.onMuteChange(cb)    // cb(muted: boolean)
TipTap.onPauseChange(cb)   // cb(paused: boolean)
```

Gate **every** sound on `canPlayAudio()` and re-check it on `tiptap:focus`,
`tiptap:blur` and `tiptap:mutechange`. See the template in §3.

The platform has a global mute control. Respect it — if your game has its own mute
button, keep the two in sync.

### Loading

Only if your game needs more than a moment before it is playable (decoding audio,
generating levels, building sprite atlases):

```js
TipTap.setLoadProgress(0.4)   // 0..1 — opts into the platform loading screen
TipTap.ready()                // required once loading is done, or the game stays paused
```

If your game is playable immediately, call **neither**. The platform starts it as soon as
the document loads. If you call `setLoadProgress` and never call `ready()`, the platform
gives up after 20 seconds and starts the game anyway.

### Achievements

```js
TipTap.unlockAchievement('first_blood')   // safe to call every frame — only the first unlock counts
TipTap.onAchievement(cb)                  // cb({ key, name, description, icon }) on a genuine first unlock
```

Keys must be declared by the creator in the dashboard first (**My games → ⋯ →
Achievements**). Unknown keys are ignored server-side. Repeat unlocks are no-ops, so you
can put the call directly in a condition check without tracking whether it already fired.

Do not invent achievements unless the user asked for them.

### Arcade view

```js
TipTap.setArcade(true)      // request full-viewport, no feed chrome
TipTap.isArcade()
TipTap.onArcadeChange(cb)
```

Players can also toggle this themselves. Only request it if the game genuinely benefits.

### Sharing — SDK 2.1, optional

```js
TipTap.share({ score: 4120 })
TipTap.share({ score: 4120, text: 'Cleared floor 9 without taking a hit' })
TipTap.share({ score: 4120, imageDataUrl: snapshot })   // your own picture
```

Opens the platform's share sheet. Every field is optional. There is **no callback and
no result** — the game is never told whether the player actually shared, so never gate
a reward or progression on it.

With no `imageDataUrl` the platform generates a branded score card (score, game,
player). Pass your own only when the final frame says something a score cannot — a
finished maze, a tower the player built.

`imageDataUrl` must be a `data:` URL of type `png`, `jpeg` or `webp`, **at most 2 MB
decoded**. Anything else is dropped with a console warning and the sheet still opens
with the generated card, so a bad snapshot degrades rather than failing. Build it on a
separate offscreen canvas (~1080px long edge) rather than exporting the live one, which
is sized for a phone viewport. `toDataURL()` works because everything you drew came
from this document — there are no external images in the sandbox to taint it with.

**Offer it, don't fire it.** Put a Share button on your own end screen and light it up
after a personal best or a real achievement. Calling `share()` automatically at every
game over throws UI over the player and teaches them to dismiss your end screen.

### The player — SDK 2.1, optional

```js
TipTap.getPlayer(function (p) {
  // p.handle, p.displayName, p.avatarDataUrl
})
```

Also returns a Promise where one exists, so `await TipTap.getPlayer()` works. The reply
is cached for the life of the document — calling it again is free.

| Field | Type | |
|---|---|---|
| `handle` | `string \| null` | the player's handle, without the `@` |
| `displayName` | `string \| null` | their display name, if they have one |
| `avatarDataUrl` | `string \| null` | their avatar, downscaled to 96×96, as a `data:` URL |

**The anonymous contract — this is the part that breaks games.** The callback always
receives an object, so `p` itself never needs a null check. But `handle`, `displayName`
and `avatarDataUrl` are each **independently null**:

- A signed-out player has **no handle and no avatar**. Most of the feed is signed out,
  so this is the common case, not an edge case.
- A signed-in player may still have no avatar.
- If the host does not implement this (an old host, or your file opened directly during
  development) the callback still fires, with all three null, after a short timeout. It
  never hangs.

So write the null version of the screen first and treat the avatar as decoration on top
of it:

```js
var me = { handle: null, avatar: null };
if (window.TipTap && typeof TipTap.getPlayer === 'function') {
  TipTap.getPlayer(function (p) {
    me.handle = p.handle;
    if (!p.avatarDataUrl) return;              // the guard that matters
    var img = new Image();
    img.onload = function () { me.avatar = img; };
    img.src = p.avatarDataUrl;
  });
}
// at the draw site: me.avatar ? drawImage : me.handle ? first letter : silhouette
```

Never render a broken image, the word `null`, or a gap where a face should be. A
signed-out player must get the same game with less decoration, never a worse game.

**Why you are allowed this.** It is the same handle and picture already shown on every
leaderboard and profile page, so nothing private crosses the boundary. And your game
runs under `connect-src 'none'` — it has no network at all — so the data physically
cannot leave the frame it was drawn in.

Only call it if you use it. It costs the host a canvas draw and a base64 encode.

### Versions

`TipTap.version` is `2` — the wire version, which does not move for additive changes.
`TipTap.apiVersion` is the surfaced minor, currently `"2.1"`. Prefer detecting the
function itself:

```js
if (window.TipTap && typeof TipTap.share === 'function') { /* … */ }
```

Everything documented above `share` is SDK 2.0 and is present on every host. A v2 game
needs no changes to keep working.

### Window events

Every callback above has an equivalent `window` event. Use whichever style fits.

| Event | Meaning |
|---|---|
| `tiptap:focus` | On screen and being looked at. Safe to start audio. |
| `tiptap:blur` | Scrolled away, overlay up, or browser tab backgrounded. **Stop all audio.** |
| `tiptap:pause` | Stop game-loop timers and animations. |
| `tiptap:resume` | Restart them. |
| `tiptap:mutechange` | `event.detail.muted` — global mute toggled. |
| `tiptap:leaderboardclose` | Player pressed Continue. State intact — resume. |
| `tiptap:result` | `event.detail` is the `onResult` payload. |
| `tiptap:achievement` | `event.detail` is the unlocked achievement. |
| `tiptap:arcadechange` | `event.detail.arcade` |
| `tiptap:player` | `event.detail` is the `getPlayer` payload. Fires once, when it arrives. |

---

## 3. Template — start from this

This is a correct, complete integration. Copy it and build the game around it.

```html
<!doctype html>
<html>
<head><meta charset="utf-8"><title>My Game</title>
<style>
  html,body{margin:0;height:100%;background:#0f0f0f;color:#fff;overflow:hidden;
            font-family:system-ui,sans-serif;touch-action:none}
  canvas{display:block;width:100%;height:100%}
</style>
</head>
<body>
<canvas id="c"></canvas>
<script>
(function () {
  'use strict';

  // window.TipTap is injected by the platform. This shim keeps the file
  // runnable when opened directly — including a minimal end screen, so a run
  // can be restarted during local testing. On the platform the real SDK is
  // injected and showLeaderboard() raises the platform's own end screen.
  var T = window.TipTap || (function () {
    var onClose = null, last = 0;
    return {
      updateScore: function (v) { last = v; },
      submitScore: function (v, opts) { last = v; if (opts && opts.showLeaderboard) this.showLeaderboard(); },
      onResult: function () {}, hideLeaderboard: function () {},
      unlockAchievement: function () {}, canPlayAudio: function () { return true; },
      onLeaderboardClose: function (fn) { onClose = fn; },
      showLeaderboard: function () {
        var el = document.createElement('div');
        el.style.cssText = 'position:fixed;inset:0;z-index:9;display:grid;place-content:center;gap:10px;' +
          'text-align:center;cursor:pointer;background:rgba(0,0,0,.82);color:#fff;font:600 20px system-ui';
        el.innerHTML = '<div style="font-size:12px;opacity:.55">GAME OVER</div>' +
          '<div style="font-size:46px">' + last + '</div>' +
          '<div style="font-size:14px;opacity:.7">Tap to play again</div>';
        el.onclick = function () { el.remove(); if (onClose) onClose(); };
        document.body.appendChild(el);
      }
    };
  })();

  var score = 0, paused = false, running = true, music = null;

  // ---- Audio: gated on focus AND global mute -------------------------------
  function syncAudio() {
    if (T.canPlayAudio()) { if (!music) music = startMusic(); }
    else if (music) { stopMusic(music); music = null; }
  }
  window.addEventListener('tiptap:focus', syncAudio);
  window.addEventListener('tiptap:blur', syncAudio);
  window.addEventListener('tiptap:mutechange', syncAudio);

  function startMusic() { /* build and start your Web Audio graph, return a handle */ return null; }
  function stopMusic(h) { /* tear it down */ }

  // ---- Loop ----------------------------------------------------------------
  window.addEventListener('tiptap:pause',  function () { paused = true; });
  window.addEventListener('tiptap:resume', function () { paused = false; last = 0; requestAnimationFrame(frame); });

  var last = 0;
  function frame(t) {
    if (paused || !running) return;          // stop the rAF chain while paused
    var dt = last ? (t - last) / 1000 : 0; last = t;
    update(dt); render();
    requestAnimationFrame(frame);
  }

  function update(dt) { /* game logic */ }
  function render()   { /* draw */ }

  function addPoints(n) {
    score += n;
    T.updateScore(score);                    // live score in the platform top bar
  }

  // ---- End of a run --------------------------------------------------------
  function gameOver() {
    running = false;
    if (music) { stopMusic(music); music = null; }
    T.submitScore(score);                    // silent — writes to the leaderboard
    T.showLeaderboard();                     // and this is what the player sees
  }

  // Player pressed Continue. Nothing was reloaded — pick up where we left off,
  // or start a fresh run if this game has no persistent state.
  T.onLeaderboardClose(function () {
    restart();
  });

  T.onResult(function (r) {
    // r.rank, r.percentile, r.personalBest, r.ghostScore, r.ghostHandle
  });

  function restart() {
    score = 0; running = true; last = 0;
    T.updateScore(0);
    requestAnimationFrame(frame);
  }

  restart();
})();
</script>
</body>
</html>
```

---

## 4. Game design expectations

- **Instant.** Playable within ~2 seconds. No splash screen, no menu, no "press start"
  unless the game truly needs one. The player is mid-scroll.
- **Vertical/portrait first.** Most play happens on a phone in a feed. Handle resize and
  make the canvas fill its container.
- **Touch and keyboard.** Both, wherever it makes sense.
- **Dark background** (`#0f0f0f`, `#111827` or similar) — it sits on a dark feed.
- **Score always visible**, top-centre or top-left.
- **Short runs.** 30–90 seconds is the sweet spot for a feed.
- **A real game-over.** Every terminal state must call `submitScore()`.

---

## 5. Testing before upload

Open your `.html` directly in a browser. `window.TipTap` will be absent — the shim in the
template keeps it running. To exercise the real SDK, add this during development only:

```html
<script src="https://tiptapgames.com/tiptap-sdk.js"></script>
```

Remove it before uploading. (Leaving it in is harmless — the platform's CSP blocks
external scripts and the injected SDK is idempotent — but it does nothing.)

---

## 6. Pre-flight checklist

Before you hand the file over, verify every line:

- [ ] Single `.html` file, all CSS/JS inline, no external references of any kind
- [ ] No `fetch`, `XMLHttpRequest`, `WebSocket`, `localStorage`, `sessionStorage`, cookies
- [ ] Every `window.TipTap` use is feature-detected
- [ ] `updateScore()` called as the score changes
- [ ] `submitScore()` called at **every** terminal state
- [ ] `showLeaderboard()` called after `submitScore()` at a real game-over
  — **`submitScore` alone shows the player nothing**
- [ ] All audio gated on `canPlayAudio()`, re-checked on `tiptap:focus` / `tiptap:blur` /
      `tiptap:mutechange`
- [ ] Game loop stops on `tiptap:pause` and restarts on `tiptap:resume`
- [ ] `onLeaderboardClose` handled — the game was **not** reloaded
- [ ] Canvas resizes correctly; playable in portrait on a phone
- [ ] Playable within ~2 seconds of load
- [ ] If you used `getPlayer`: the screen still reads correctly with `handle`,
      `displayName` **and** `avatarDataUrl` all null — that is the signed-out majority
- [ ] If you used `share`: it is behind a button the player presses, not fired
      automatically, and any `imageDataUrl` is under 2 MB

---

Full human-readable docs: https://tiptapgames.com/docs/sdk
Upload: https://tiptapgames.com/create/upload

Building through TipTap's MCP server rather than handing the file over yourself?
https://tiptapgames.com/llms-full.txt is this document plus the complete tool
reference, the build workflow, the validation error codes and the prompt cookbook.