Tutorial: build Firefly Jar

// ---------- Fireflies ----------
const TOP = 90;        // fireflies stay below the score line...
const BOTTOM = 150;    // ...and above the jar at the bottom
let fireflies = [];
let speed = 50;        // pixels per second
let blinkSpeed = 1.7;  // how fast the glow cycles

function makeFirefly() {
  return {
    x: 30 + Math.random() * (W - 60),
    y: TOP + Math.random() * Math.max(1, H - TOP - BOTTOM),
    angle: Math.random() * Math.PI * 2, // the direction it flies
    blink: Math.random() * Math.PI * 2, // where it is in its glow cycle
  };
}

function isLit(f) {
  return Math.sin(f.blink) > 0.3;
}

function moveFirefly(f, dt) {
  f.angle += (Math.random() - 0.5) * 4 * dt; // wander a little
  f.x += Math.cos(f.angle) * speed * dt;
  f.y += Math.sin(f.angle) * speed * dt;
  f.blink += blinkSpeed * dt;
  // turn back at the edges of the play area
  if (f.x < 20 || f.x > W - 20) f.angle = Math.PI - f.angle;
  if (f.y < TOP || f.y > H - BOTTOM) f.angle = -f.angle;
  f.x = Math.max(20, Math.min(W - 20, f.x));
  f.y = Math.max(TOP, Math.min(H - BOTTOM, f.y));
}

function drawFirefly(f) {
  const glow = Math.max(0, Math.sin(f.blink)); // 0 = dark, 1 = brightest
  ctx.globalCompositeOperation = 'lighter'; // add light instead of paint
  ctx.globalAlpha = glow * 0.35;
  ctx.fillStyle = '#ffdc6e';
  ctx.beginPath();
  ctx.arc(f.x, f.y, 10 + glow * 14, 0, Math.PI * 2);
  ctx.fill();
  ctx.globalAlpha = 1;
  ctx.globalCompositeOperation = 'source-over';
  ctx.fillStyle = isLit(f) ? '#fff3b0' : '#56607e';
  ctx.beginPath();
  ctx.arc(f.x, f.y, 5, 0, Math.PI * 2);
  ctx.fill();
}

// ---------- The game loop ----------
let lastTime = 0;

function update(dt) {
  for (const f of fireflies) moveFirefly(f, dt);
}

function draw() {
  drawBackground();
  for (const f of fireflies) drawFirefly(f);
}

function frame(time) {
  // dt = seconds since the last frame, capped so one slow frame can't make things jump
  const dt = lastTime ? Math.min((time - lastTime) / 1000, 0.05) : 0;
  lastTime = time;
  update(dt);
  draw();
  requestAnimationFrame(frame);
}

// ---------- Start ----------
resize();
window.addEventListener('resize', resize);
fireflies.push(makeFirefly());
requestAnimationFrame(frame);

// ---------- Sparkles ----------
let sparks = [];

function burst(x, y) {
  for (let i = 0; i < 12; i++) {
    const a = Math.random() * Math.PI * 2;
    const v = 60 + Math.random() * 120;
    sparks.push({ x: x, y: y, vx: Math.cos(a) * v, vy: Math.sin(a) * v, life: 0.5 });
  }
}

function updateSparks(dt) {
  for (const s of sparks) {
    s.x += s.vx * dt;
    s.y += s.vy * dt;
    s.life -= dt;
  }
  sparks = sparks.filter(function (s) { return s.life > 0; });
}

function drawSparks() {
  ctx.fillStyle = '#ffe27a';
  for (const s of sparks) {
    ctx.globalAlpha = s.life / 0.5;
    ctx.fillRect(s.x - 2, s.y - 2, 4, 4);
  }
  ctx.globalAlpha = 1;
}

// ---------- Catching ----------
let score = 0;

// Pointer events cover touch, mouse and pen with one listener.
canvas.addEventListener('pointerdown', function (e) {
  const rect = canvas.getBoundingClientRect();
  tryCatch(e.clientX - rect.left, e.clientY - rect.top);
});

function tryCatch(x, y) {
  // Find the nearest firefly within a finger's reach (44 px).
  let nearest = null;
  let nearestDist = 44;
  for (const f of fireflies) {
    const d = Math.hypot(f.x - x, f.y - y);
    if (d < nearestDist) {
      nearest = f;
      nearestDist = d;
    }
  }
  if (!nearest || !isLit(nearest)) return; // empty sky or a sleeping firefly
  fireflies.splice(fireflies.indexOf(nearest), 1); // into the jar it goes...
  fireflies.push(makeFirefly());                   // ...and a new one flies in
  score += 10;
  burst(nearest.x, nearest.y);
}

function update(dt) {
  for (const f of fireflies) moveFirefly(f, dt);
  updateSparks(dt);
}

function draw() {
  drawBackground();
  for (const f of fireflies) drawFirefly(f);
  drawSparks();
  ctx.fillStyle = '#ffffff';
  ctx.font = '700 22px system-ui, sans-serif';
  ctx.textAlign = 'center';
  ctx.fillText(String(score), W / 2, 34);
}

for (let i = 0; i < 8; i++) fireflies.push(makeFirefly());

    .panel {
      position: fixed;
      inset: 0;
      display: flex;
      flex-direction: column;
      align-items: center;
      justify-content: center;
      gap: 16px;
      padding: 24px;
      text-align: center;
      background: rgba(6, 9, 30, 0.6);
    }
    .panel[hidden] { display: none; }
    .panel h1 { margin: 0; font-size: 34px; color: #ffe27a; }
    .panel p { margin: 0; max-width: 300px; font-size: 17px; line-height: 1.45; }
    button {
      min-width: 200px;
      min-height: 52px;
      padding: 0 24px;
      border: 0;
      border-radius: 26px;
      font: 700 18px system-ui, sans-serif;
      color: #1a1440;
      background: #ffe27a;
      cursor: pointer;
    }
    button:disabled { opacity: 0.5; }

  <div id="panel" class="panel">
    <h1 id="panel-title">Firefly Jar</h1>
    <p id="panel-text"></p>
    <button id="panel-main" type="button">Play</button>
  </div>

// ---------- Rounds ----------
const ROUND_TIME = 20; // seconds per round
let state = 'title';   // 'title', 'play', 'clear' or 'timeup'
let round = 1;
let goal = 0;          // fireflies to catch this round
let caught = 0;
let timeLeft = 0;      // seconds
let roundStartScore = 0;
let flash = 0;         // red flash after tapping a sleeping firefly

function spawnFireflies(count) {
  fireflies = [];
  for (let i = 0; i < count; i++) fireflies.push(makeFirefly());
}

function startRound() {
  goal = 4 + round * 2;           // 6, 8, 10...
  speed = 40 + round * 10;        // faster every round
  blinkSpeed = 1.4 + round * 0.3; // shorter glows every round
  caught = 0;
  timeLeft = ROUND_TIME;
  roundStartScore = score;
  spawnFireflies(Math.min(4 + round, 12));
  state = 'play';
  hidePanel();
}

function roundClear() {
  const bonus = Math.ceil(timeLeft) * 5;
  score += bonus;
  round += 1;
  state = 'clear';
  showPanel('Round ' + (round - 1) + ' clear!', 'Time bonus +' + bonus + '. Score: ' + score + '.', 'Next round', startRound);
}

function timeUp() {
  state = 'timeup';
  showPanel('Out of time!', 'You caught ' + caught + ' of ' + goal + '.', 'Try again', retryRound);
}

function retryRound() {
  score = roundStartScore; // take back this round's points
  startRound();
}

function showTitle() {
  state = 'title';
  speed = 50;
  blinkSpeed = 1.7;
  spawnFireflies(8);
  showPanel('Firefly Jar', 'Tap the fireflies while they glow. Tapping a dark one costs 2 seconds.', 'Play', startRound);
}

// ---------- Screens ----------
const panel = document.getElementById('panel');
const panelTitle = document.getElementById('panel-title');
const panelText = document.getElementById('panel-text');
const mainButton = document.getElementById('panel-main');
let mainAction = null;

mainButton.addEventListener('click', function () {
  if (mainAction) mainAction();
});

function showPanel(title, text, buttonLabel, action) {
  panelTitle.textContent = title;
  panelText.textContent = text;
  mainButton.textContent = buttonLabel;
  mainAction = action;
  panel.hidden = false;
}

function hidePanel() {
  panel.hidden = true;
}

function tryCatch(x, y) {
  if (state !== 'play') return;
  // Find the nearest firefly within a finger's reach (44 px).
  let nearest = null;
  let nearestDist = 44;
  for (const f of fireflies) {
    const d = Math.hypot(f.x - x, f.y - y);
    if (d < nearestDist) {
      nearest = f;
      nearestDist = d;
    }
  }
  if (!nearest) return; // tapped empty sky
  if (isLit(nearest)) {
    fireflies.splice(fireflies.indexOf(nearest), 1); // into the jar it goes...
    fireflies.push(makeFirefly());                   // ...and a new one flies in
    score += 10;
    caught += 1;
    burst(nearest.x, nearest.y);
  } else {
    timeLeft = Math.max(0, timeLeft - 2); // a sleeping firefly costs 2 seconds
    flash = 0.3;
  }
}

// ---------- HUD and jar ----------
function drawHud() {
  ctx.fillStyle = '#ffffff';
  ctx.font = '700 18px system-ui, sans-serif';
  ctx.textAlign = 'left';
  ctx.fillText('Round ' + round, 16, 34);
  ctx.font = '700 22px system-ui, sans-serif';
  ctx.textAlign = 'center';
  ctx.fillText(String(score), W / 2, 34);
  // the timer bar
  const barWidth = W - 32;
  ctx.fillStyle = 'rgba(255, 255, 255, 0.15)';
  ctx.fillRect(16, 62, barWidth, 8);
  ctx.fillStyle = timeLeft < 5 ? '#ff6b81' : '#ffe27a';
  ctx.fillRect(16, 62, barWidth * Math.min(1, timeLeft / ROUND_TIME), 8);
}

function drawJar() {
  const w = 64;
  const h = 84;
  const x = W / 2 - w / 2;
  const y = H - h - 24;
  const fill = Math.min(caught / goal, 1);
  // the light inside
  ctx.globalAlpha = 0.85;
  ctx.fillStyle = '#ffdc6e';
  ctx.fillRect(x + 4, y + 4 + (h - 8) * (1 - fill), w - 8, (h - 8) * fill);
  ctx.globalAlpha = 1;
  // the glass and the lid
  ctx.strokeStyle = 'rgba(255, 255, 255, 0.8)';
  ctx.lineWidth = 3;
  ctx.strokeRect(x, y, w, h);
  ctx.fillStyle = '#9b7344';
  ctx.fillRect(x - 5, y - 12, w + 10, 12);
  // how many so far
  ctx.fillStyle = '#ffffff';
  ctx.font = '700 16px system-ui, sans-serif';
  ctx.textAlign = 'center';
  ctx.fillText(caught + ' / ' + goal, W / 2, y - 22);
}

function update(dt) {
  for (const f of fireflies) moveFirefly(f, dt);
  updateSparks(dt);
  flash = Math.max(0, flash - dt);
  if (state !== 'play') return;
  timeLeft -= dt;
  if (caught >= goal) {
    roundClear();
  } else if (timeLeft <= 0) {
    timeLeft = 0;
    timeUp();
  }
}

function draw() {
  drawBackground();
  for (const f of fireflies) drawFirefly(f);
  drawSparks();
  if (state === 'play') {
    drawJar();
    drawHud();
  }
  if (flash > 0) {
    ctx.globalAlpha = flash;
    ctx.fillStyle = '#ff4d6d';
    ctx.fillRect(0, 0, W, H);
    ctx.globalAlpha = 1;
  }
}

// ---------- Start ----------
resize();
window.addEventListener('resize', resize);
showTitle();
requestAnimationFrame(frame);

    #sound {
      position: fixed;
      top: 10px;
      right: 10px;
      min-width: 0;
      min-height: 44px;
      padding: 0 16px;
      font-size: 14px;
      color: #fff;
      background: rgba(255, 255, 255, 0.14);
    }

  <button id="sound" type="button">Sound: on</button>

// ---------- Sound ----------
let audio = null;        // the Web Audio context, created on the first tap
let master = null;       // the master volume knob
let playerMuted = false; // the player's own Sound on/off choice

function unlockAudio() {
  // Browsers only allow sound after the player has touched the page.
  if (!audio) {
    const AudioCtx = window.AudioContext || window.webkitAudioContext;
    if (!AudioCtx) return;
    audio = new AudioCtx();
    master = audio.createGain();
    master.connect(audio.destination);
    applyVolume();
  }
  if (audio.state === 'suspended') audio.resume();
}
window.addEventListener('pointerdown', unlockAudio);

function applyVolume() {
  if (master) master.gain.value = playerMuted ? 0 : 0.5;
}

// A short synth note: no sound files needed.
function beep(freq, duration, delay, type) {
  if (!audio) return;
  const t = audio.currentTime + (delay || 0);
  const osc = audio.createOscillator();
  const env = audio.createGain();
  osc.type = type || 'sine';
  osc.frequency.setValueAtTime(freq, t);
  env.gain.setValueAtTime(0.4, t);
  env.gain.exponentialRampToValueAtTime(0.001, t + duration);
  osc.connect(env);
  env.connect(master);
  osc.start(t);
  osc.stop(t + duration);
}

const soundButton = document.getElementById('sound');
soundButton.addEventListener('click', function () {
  playerMuted = !playerMuted;
  soundButton.textContent = playerMuted ? 'Sound: off' : 'Sound: on';
  applyVolume();
});

function tryCatch(x, y) {
  if (state !== 'play') return;
  // Find the nearest firefly within a finger's reach (44 px).
  let nearest = null;
  let nearestDist = 44;
  for (const f of fireflies) {
    const d = Math.hypot(f.x - x, f.y - y);
    if (d < nearestDist) {
      nearest = f;
      nearestDist = d;
    }
  }
  if (!nearest) return; // tapped empty sky
  if (isLit(nearest)) {
    fireflies.splice(fireflies.indexOf(nearest), 1); // into the jar it goes...
    fireflies.push(makeFirefly());                   // ...and a new one flies in
    score += 10;
    caught += 1;
    burst(nearest.x, nearest.y);
    beep(880, 0.12);
  } else {
    timeLeft = Math.max(0, timeLeft - 2); // a sleeping firefly costs 2 seconds
    flash = 0.3;
    beep(150, 0.25, 0, 'triangle');
  }
}

function roundClear() {
  const bonus = Math.ceil(timeLeft) * 5;
  score += bonus;
  round += 1;
  state = 'clear';
  beep(660, 0.15);
  beep(880, 0.15, 0.12);
  beep(1320, 0.3, 0.24);
  showPanel('Round ' + (round - 1) + ' clear!', 'Time bonus +' + bonus + '. Score: ' + score + '.', 'Next round', startRound);
}

function timeUp() {
  state = 'timeup';
  beep(330, 0.3);
  beep(220, 0.45, 0.25);
  showPanel('Out of time!', 'You caught ' + caught + ' of ' + goal + '.', 'Try again', retryRound);
}

  <!-- Twiddle Play SDK: the platform's copy first, then the copy in your zip (whichever loads first wins) -->
  <script src="/sdk/v1/twiddleplay.js"></script>
  <script src="twiddleplay-sdk.js"></script>
  <script src="game.js"></script>

let playerMuted = false; // the player's own Sound on/off choice
let platformMuted = false; // Twiddle Play mutes the game during ads and in the background

function applyVolume() {
  if (master) master.gain.value = playerMuted || platformMuted ? 0 : 0.5;
}

let lastTime = 0;
let paused = false; // true while an ad shows or the app is in the background

function frame(time) {
  // dt = seconds since the last frame, capped so one slow frame can't make things jump
  const dt = lastTime ? Math.min((time - lastTime) / 1000, 0.05) : 0;
  lastTime = time;
  if (!paused) update(dt);
  draw();
  requestAnimationFrame(frame);
}

// ---------- Twiddle Play ----------
// Before an ad, and when the app goes to the background, the game gets pause + mute.
// After, it gets resume + unmute.
TwiddlePlay.on('pause', function () {
  paused = true;
});
TwiddlePlay.on('resume', function () {
  paused = false;
});
TwiddlePlay.on('mute', function () {
  platformMuted = true;
  applyVolume();
});
TwiddlePlay.on('unmute', function () {
  platformMuted = false;
  applyVolume();
});

// ---------- Start ----------
resize();
window.addEventListener('resize', resize);
requestAnimationFrame(frame);
TwiddlePlay.ready().then(function () {
  console.log('Twiddle Play is ready. Environment: ' + TwiddlePlay.env);
  showTitle();
});

function startRound() {
  goal = 4 + round * 2;           // 6, 8, 10...
  speed = 40 + round * 10;        // faster every round
  blinkSpeed = 1.4 + round * 0.3; // shorter glows every round
  caught = 0;
  timeLeft = ROUND_TIME;
  roundStartScore = score;
  spawnFireflies(Math.min(4 + round, 12));
  state = 'play';
  hidePanel();
  TwiddlePlay.gameplayStart();
}

  showPanel('Round ' + (round - 1) + ' clear!', 'Time bonus +' + bonus + '. Score: ' + score + '.', 'Next round', nextRound);
}

async function nextRound() {
  // A natural break: the app may show an ad here. Shown or not, the game carries on.
  mainButton.disabled = true;
  await TwiddlePlay.showInterstitial();
  mainButton.disabled = false;
  startRound();
}

    button.secondary { color: #fff; background: #343a6e; }

  <div id="panel" class="panel">
    <h1 id="panel-title">Firefly Jar</h1>
    <p id="panel-text"></p>
    <button id="panel-main" type="button">Play</button>
    <button id="panel-extra" type="button" class="secondary" hidden></button>
  </div>

// ---------- Screens ----------
const panel = document.getElementById('panel');
const panelTitle = document.getElementById('panel-title');
const panelText = document.getElementById('panel-text');
const mainButton = document.getElementById('panel-main');
const extraButton = document.getElementById('panel-extra');
let mainAction = null;
let extraAction = null;

mainButton.addEventListener('click', function () {
  if (mainAction) mainAction();
});
extraButton.addEventListener('click', function () {
  if (extraAction) extraAction();
});

function showPanel(title, text, buttonLabel, action) {
  panelTitle.textContent = title;
  panelText.textContent = text;
  mainButton.textContent = buttonLabel;
  mainAction = action;
  extraButton.hidden = true; // a second button only when we ask for one
  panel.hidden = false;
}

function showExtra(buttonLabel, action) {
  extraButton.textContent = buttonLabel;
  extraAction = action;
  extraButton.hidden = false;
}

function hidePanel() {
  panel.hidden = true;
}

let continueUsed = false; // one rewarded continue per round

function startRound() {
  goal = 4 + round * 2;           // 6, 8, 10...
  speed = 40 + round * 10;        // faster every round
  blinkSpeed = 1.4 + round * 0.3; // shorter glows every round
  caught = 0;
  timeLeft = ROUND_TIME;
  roundStartScore = score;
  continueUsed = false;
  spawnFireflies(Math.min(4 + round, 12));
  state = 'play';
  hidePanel();
  TwiddlePlay.gameplayStart();
}

function timeUp() {
  state = 'timeup';
  TwiddlePlay.gameplayStop();
  beep(330, 0.3);
  beep(220, 0.45, 0.25);
  showPanel('Out of time!', 'You caught ' + caught + ' of ' + goal + '.', 'Try again', retryRound);
  offerContinue();
}

async function offerContinue() {
  if (continueUsed) return;
  // Only offer the button when an ad can actually play.
  const available = await TwiddlePlay.hasRewarded();
  if (available && state === 'timeup') showExtra('+10 seconds (watch an ad)', watchAdToContinue);
}

async function watchAdToContinue() {
  extraButton.disabled = true;
  const result = await TwiddlePlay.showRewarded();
  extraButton.disabled = false;
  if (result.rewarded && state === 'timeup') {
    // The player watched to the end: give exactly what the button promised.
    continueUsed = true;
    timeLeft = 10;
    state = 'play';
    hidePanel();
    TwiddlePlay.gameplayStart();
  } else {
    panelText.textContent = "The ad didn't finish, so no extra time. You can try again.";
  }
}

// ---------- Saving progress ----------
// Each game in the app has its own storage, kept when the game updates.
const SAVE_KEY = 'firefly-jar.v1';
let best = 0;

function save() {
  try {
    localStorage.setItem(SAVE_KEY, JSON.stringify({ round: round, score: score, best: best, muted: playerMuted }));
  } catch (e) {
    // Storage can be full or switched off. The game still works; it just won't remember.
  }
}

function load() {
  try {
    const data = JSON.parse(localStorage.getItem(SAVE_KEY));
    if (data) {
      round = data.round || 1;
      score = data.score || 0;
      best = data.best || 0;
      playerMuted = !!data.muted;
    }
  } catch (e) {
    // Nothing saved yet, or the save is broken: start fresh.
  }
}

// ---------- Start ----------
resize();
window.addEventListener('resize', resize);
load();
updateSoundButton();
requestAnimationFrame(frame);
TwiddlePlay.ready().then(function () {
  console.log('Twiddle Play is ready. Environment: ' + TwiddlePlay.env);
  showTitle();
});

function roundClear() {
  const bonus = Math.ceil(timeLeft) * 5;
  score += bonus;
  round += 1;
  best = Math.max(best, score);
  save(); // a finished round is a safe point to come back to
  state = 'clear';
  TwiddlePlay.gameplayStop();
  beep(660, 0.15);
  beep(880, 0.15, 0.12);
  beep(1320, 0.3, 0.24);
  showPanel('Round ' + (round - 1) + ' clear!', 'Time bonus +' + bonus + '. Score: ' + score + '.', 'Next round', nextRound);
}

function showTitle() {
  state = 'title';
  speed = 50;
  blinkSpeed = 1.7;
  spawnFireflies(8);
  if (round > 1) {
    showPanel('Firefly Jar', 'Welcome back! Round ' + round + ', score ' + score + '. Best: ' + best + '.', 'Continue', startRound);
    showExtra('New game', newGame);
  } else {
    showPanel('Firefly Jar', 'Tap the fireflies while they glow. Tapping a dark one costs 2 seconds.', 'Play', startRound);
  }
}

function newGame() {
  round = 1;
  score = 0;
  save();
  startRound();
}

const soundButton = document.getElementById('sound');

function updateSoundButton() {
  soundButton.textContent = playerMuted ? 'Sound: off' : 'Sound: on';
}

soundButton.addEventListener('click', function () {
  playerMuted = !playerMuted;
  updateSoundButton();
  applyVolume();
  save();
});

firefly-jar/
├── index.html
├── game.js
└── twiddleplay-sdk.js