TipTap SDK
Scores, leaderboards, achievements and audio focus — in minutes.
- Auto-injected
- Zero dependencies
- Live leaderboards
Building with an AI agent? Give it this link.
A single self-contained spec written for coding agents — sandbox constraints, the complete API, a working template, and a pre-flight checklist. Paste the URL into Claude Code, Cursor, or any agent and it has everything it needs to produce an uploadable game in one pass.
https://tiptapgames.com/sdk-agents.mdNo import needed
The SDK is pre-loaded into every game — window.TipTap is available the moment your script runs. No import, no CDN link needed.
Quick start
A complete minimal game using the hooks that matter. Copy, paste, and extend.
<!doctype html>
<html><head><meta charset="utf-8">
<title>My Game</title>
</head><body>
<script>
// window.TipTap is injected automatically — no import needed.
var score = 0;
var paused = false;
var music = null;
// ---- Audio: respect focus AND the global mute ----
function syncAudio() {
if (TipTap.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);
// ---- Game loop ----
window.addEventListener('tiptap:pause', function() { paused = true; });
window.addEventListener('tiptap:resume', function() { paused = false; });
// ---- Results ----
TipTap.onResult(function(result) {
console.log('Rank #' + result.rank + ' — beat ' + result.percentile + '% of players!');
});
// The player closed the leaderboard — the game was never unloaded, so just
// carry on from exactly where it was.
TipTap.onLeaderboardClose(function() {
paused = false;
});
function onScorePoint(points) {
score += points;
TipTap.updateScore(score); // live score in the platform top bar
}
// A run ended for good — bank the score AND show the board.
function onGameOver() {
TipTap.submitScore(score);
TipTap.showLeaderboard();
score = 0;
}
// A "Leaderboard" button in your own pause menu — bank progress without
// ending the run. Continue hands control straight back.
function onLeaderboardButton() {
TipTap.submitScore(score);
TipTap.showLeaderboard();
}
</script>
</body></html>The API
- Scores & leaderboardSubmitting a score, raising the leaderboard, the onResult payload, shared-score challenges and the per-day seed every TipTap game gets.
- AchievementsUnlocking achievements by key, showing progress towards a locked one, and reacting to a first unlock.
- Game lifecycleLoading, pause, focus and mute for a game living in a swipeable feed — plus arcade view, the window events and the share sheet.
- The playerPlayer identity, saved progress, input class, reduced motion, keyboard focus and haptics.
- Custom eventsCounting the things you want to know about your own game, and the key, rate and retirement limits that apply to them.
- MultiplayerRooms, peers, replicated state, turn order, messaging, time and randomness that agrees — the module injected only into games flagged multiplayer.
- Typed schemasThe closed field-type set, what is excluded and why, how a schema's maximum encoded size is computed, and why declaring a schema is not the same as having it approved.
- Multiplayer — advancedThe parts a multiplayer game reaches for after rooms and state: agreeing time and randomness, host authority, resilience, friends and invites, quick chat, the current gaps, and testing.
- Real-time simulationTipTap.sim: declaring one of the four platform-authored simulation modules, defining and stepping it, querying the host, and where the write-it-yourself creator-logic tier stands.
- Full referenceEvery member of the TipTap SDK and TipTap.net on one page, generated from the same source as the subject pages. For Ctrl-F.
Versions
TipTap.version is 2 — the wire version, which does not move for additive changes. TipTap.apiVersion is the surfaced minor, currently "2.3". Prefer detecting the function itself over comparing that string — it is one check and it cannot get out of step:
if (window.TipTap && typeof TipTap.saveState === 'function') { /* … */ }Everything on this page is live on the platform right now, so a game built today needs none of this. It matters when your game may also run somewhere older, and when you are reading code written against an earlier SDK.
One breaking change, in v2: submitScore() no longer shows the leaderboard. It writes the score silently and leaves your game running, so a game with progression can bank a score without being torn down. For the old end-screen behaviour, follow it with TipTap.showLeaderboard(). Everything since has been additive.
Local development tip ↓
When testing your game outside the platform, window.TipTap is not present because the injection only happens inside the feed. You can load a stub manually during local dev:
<script src="/tiptap-sdk.js"></script>
Remove it before uploading. The platform injects the real SDK automatically — including the tag in your uploaded file will cause a duplicate script error.