SDK reference

TwiddlePlay.version // '1'

• Type: string. Always '1' for this SDK.
• When to use it: logging, if you want to know which SDK your game got. You never need to check it before calling anything.

TwiddlePlay.env // 'android' | 'host' | 'standalone'

• Type: string. See the three environments.
• When to use it: debugging, or showing a small "test mode" label during development.

TwiddlePlay.ready().then(function () {
  console.log('Running in', TwiddlePlay.env);
});

Common mistakes

• Reading env at the very top of your script, before ready(). In a frame it may still say 'standalone'.
• Changing gameplay based on env. Your game should behave the same everywhere. Let the SDK decide about ads.

TwiddlePlay.ready(): Promise<void>

Tells the platform your game has loaded.

• Returns: a promise that resolves with no value once the platform has answered, or after 5 seconds if it doesn't. It never rejects.
• When to call: once, when your game has finished loading and can be played. Calling it again returns the same promise.

loadImages().then(function () {
  return TwiddlePlay.ready();
}).then(function () {
  showTitleScreen();
});

Common mistakes

• Forgetting it. Your game still works, but call it anyway: it's how hosts and test tools know your game started.
• Waiting for ready() before drawing anything. Draw your loading screen first; ready() can take up to 400 ms in a frame.

TwiddlePlay.showInterstitial(): Promise<{ shown: boolean }>

Asks for a full-screen ad at a natural break, such as between levels.

• Returns: { shown: true } after an ad was shown and closed, or { shown: false } if no ad was shown. It never rejects.
• When to call: at natural breaks only, like after the player taps "Next level". Wait for the promise before you continue.
• Most calls return { shown: false }. The app limits interstitials (nothing in the first 60 s, at least 90 s apart, at most one per 3 minutes of play), so call it at every natural break and let the app decide. See Ad limits.
• While the ad is on screen, your game gets pause and mute, then resume and unmute when it closes.

async function onNextLevelTapped() {
  TwiddlePlay.gameplayStop();
  await TwiddlePlay.showInterstitial(); // shown or not, carry on
  startLevel(level + 1);
  TwiddlePlay.gameplayStart();
}

Common mistakes

• Calling it during play, on a timer, or when the game starts. Players hate it and reviewers reject it.
• Not waiting for the promise, so the next level starts behind the ad.
• Treating { shown: false } as an error. It's the normal answer most of the time.
• Calling it right after a tap that meant something else (like "Pause"), so the player taps the ad by accident.

TwiddlePlay.showRewarded(): Promise<{ rewarded: boolean }>

Plays an ad the player chose to watch, in exchange for a reward.

• Returns: { rewarded: true } if the player watched long enough to earn the reward, otherwise { rewarded: false } (no ad available, ads are off, another ad is on screen, or the player closed it early). It never rejects.
• When to call: only right after the player taps a button that clearly says what they'll get, like "+10 seconds" or "Double coins".
• Only one ad plays at a time. There's no other limit on rewarded ads.

continueBtn.addEventListener('click', async function () {
  continueBtn.disabled = true;
  const result = await TwiddlePlay.showRewarded();
  if (result.rewarded) {
    timeLeft += 10;          // give exactly what the button promised
    resumeRound();
  } else {
    showToast('No ad right now. Try again soon!');
    continueBtn.disabled = false;
  }
});

Common mistakes

• Giving the reward when rewarded is false, or not giving it when it's true.
• Calling it without a tap from the player (for example, automatically after a game over).
• A button that doesn't say what the reward is, or a reward that's smaller than promised.
• Letting the player tap the button twice. Disable it while the ad runs.

TwiddlePlay.hasRewarded(): Promise<boolean>

Tells you whether offering a rewarded ad makes sense right now.

• Returns: true if a rewarded ad can play now. false if ads are off for your game, an ad is already on screen, or (in the app) no rewarded ad is loaded yet. Gives up and returns false after 5 seconds.
• When to call: just before you show a rewarded button. Hide the button when it's false.

async function showTimeUpPanel() {
  timeUpPanel.hidden = false;
  continueBtn.hidden = !(await TwiddlePlay.hasRewarded());
}

Common mistakes

• Checking once at startup and caching the answer. Ads load and run out; check each time you show the button.
• Showing the button anyway when it's false. The tap would just answer { rewarded: false }.

TwiddlePlay.showBanner(opts?: { position?: 'bottom' | 'top' }): Promise<{ shown: boolean }>

Shows a banner: a small strip-shaped ad along the bottom (or top) of the screen, while your game shows a menu or sits between rounds.

• Returns: { shown: true } once a banner is on screen, or { shown: false } if none could be shown: your game's ads are off, Google had no banner to give right now, or there was no answer within 15 seconds. It never rejects.
• Options: position: 'bottom' (the default) or position: 'top'. Anything else means bottom.
• When to call: when a title screen, menu, level select, round-clear or game-over screen appears. Never during play.
• Safe to call again. While a banner is showing, another call keeps that one banner. If you ask for the other position, it moves there.
• In the app, your game shrinks to make room. The banner sits next to your game, never on top of it. Your page's viewport (the part of the screen it can draw in) gets shorter by the banner's height, about 50 to 90 pixels depending on the phone, and your page gets a normal resize event, the same one a phone rotation sends. Size your game from window.innerWidth and window.innerHeight (or its container) every time resize fires.
• A banner doesn't pause or mute your game, and it doesn't count toward the interstitial limits.
• In the preview, a test bar appears and your game's area shrinks the same way. In standalone mode, the test bar is fixed to the bottom (or top) of the page, on top of your game. See the three environments.

window.addEventListener('resize', fitCanvas); // fires when a banner appears, and again when it goes

function showGameOver() {
  state = 'over';
  TwiddlePlay.gameplayStop();
  gameOverPanel.hidden = false;
  TwiddlePlay.showBanner();                   // no need to wait: the screen works the same either way
}

playAgainBtn.addEventListener('click', function () {
  TwiddlePlay.hideBanner();                   // the banner goes before play starts
  gameOverPanel.hidden = true;
  startRound();
});

Common mistakes

• Showing it during play, or leaving it up when play starts.
• Reading the screen size once at startup. When the banner appears, the bottom of your game gets cut off. Re-fit on every resize.
• Putting your own buttons right next to the banner. Players tap the ad by accident; those clicks don't count, and too many get your game flagged.
• Showing and hiding it every second or so, for example on each page of a menu the player flicks through. Show it once when the menu opens and leave it there.
• Making the player wait for { shown: true }. Nothing in your game should depend on the answer.

TwiddlePlay.hideBanner(): Promise<void>

Takes the banner away.

• Returns: a promise that resolves with no value once the platform has answered, or after 5 seconds if it doesn't. It never rejects. You don't need to wait for it.
• When to call: as play starts, when the player taps Play, Next level, Try again or Continue.
• In the app, your game's viewport grows back to full size, and your page gets another resize event.
• Calling it with no banner on screen does nothing, so it's safe to call at the start of every round.

function startRound() {
  TwiddlePlay.hideBanner();
  state = 'playing';
  TwiddlePlay.gameplayStart();
}

Common mistakes

• Hiding it in only one of the places where play starts. If Play, Try again and a rewarded Continue all start play, call hideBanner() in the one function they share.

TwiddlePlay.gameplayStart(): void
TwiddlePlay.gameplayStop(): void

Optional hints that tell the platform when real play starts and stops.

• Returns: nothing. They're fire-and-forget.
• When to call: gameplayStart() when play begins or resumes after a menu. gameplayStop() when play stops: a menu, a level-clear screen, a game-over screen.
• What they do today: the app and the preview accept them, and the preview lists them in SDK activity. They don't change ads or limits. Calling them is good practice and costs nothing.

function startRound() {
  state = 'playing';
  TwiddlePlay.gameplayStart();
}
function endRound() {
  state = 'clear';
  TwiddlePlay.gameplayStop();
}

TwiddlePlay.on(evt: 'pause' | 'resume' | 'mute' | 'unmute', cb: () => void): () => void
TwiddlePlay.off(evt, cb): void

Listen for the platform asking your game to pause or go quiet.

• Returns: on() returns a function. Call it to stop listening (same as off(evt, cb)).
• When to call: once, at startup, before play begins.
• Your callback gets no arguments. If it throws, the SDK catches the error and logs it; other listeners still run.

Order is always pause then mute, and resume then unmute. If several reasons overlap (an ad starts while the app is in the background), you still get one pause and one resume.

let paused = false;
let platformMuted = false;
let playerMuted = loadSetting('muted');   // the player's own sound button

TwiddlePlay.on('pause', function () { paused = true; });
TwiddlePlay.on('resume', function () {
  paused = false;
  lastTime = performance.now();           // no giant time step after a long pause
});
TwiddlePlay.on('mute', function () { platformMuted = true; applyVolume(); });
TwiddlePlay.on('unmute', function () { platformMuted = false; applyVolume(); });

function applyVolume() {
  masterGain.gain.value = (platformMuted || playerMuted) ? 0 : 1;
}

Common mistakes

• Using one muted flag for both the platform and the player. Then unmute turns on sound the player switched off.
• Not resetting the frame timer on resume, so your character teleports or the round timer drops 30 seconds at once.
• Pausing only the drawing but not the timers (setTimeout, setInterval), so the round ends during an ad.

TwiddlePlay.exit(): void

Asks the app to close your game and go back to the store.

• Returns: nothing.
• When to call: only when the player taps your own "Quit" or "Exit" button.
• In the app it closes the game straight away, without the "Leave game?" question, so ask the player first if they could lose progress. In the preview it shows a message. In standalone it only logs.

quitBtn.addEventListener('click', function () {
  saveProgress();
  TwiddlePlay.exit();
});

Common mistakes

• Using window.close(), history.back() or a link to leave. Games can't navigate away; use exit().
• Forgetting to save before calling it.

You don't need an exit button at all: players can always leave with the phone's Back button.