Interactive Tutorials

Teach the game while it's being played. The SDK's tutorial overlay gives you fingers, highlight rings, swipe demos, and text pills, plus the gating that shows them to new players only.

What It Is#

The tutorial overlay is a DOM layer over your game that can point at things, demonstrate gestures, and (sparingly) say something.

It lives in the same UI entry point as the HUD toolkit:

import { shouldShowTutorial, createTutorialOverlay } from '@minit-games/sdk/ui'

No rendering library required: the overlay is pure DOM and works over any canvas, WebGL context, or DOM game. All artwork and sound effects are embedded in the package, so nothing is fetched at runtime.

Warning: Like the rest of @minit-games/sdk/ui, this is npm-package only: the Unity, Godot, Defold, and PlayCanvas facades do not expose it.

Always Gate on shouldShowTutorial() First#

Never show tutorial UI without checking shouldShowTutorial(): a returning player who sees the finger every launch leaves.

// Capture ONCE at boot; do not re-read mid-session.
const tutorialMode = shouldShowTutorial()

if (tutorialMode) {
  const tutorial = createTutorialOverlay({ container: gameRoot })
  // ... wire steps to game events
}

How the Decision Is Made#

Make sure @minit-games/sdk is at 1.15.0 or later in your package.json.

How the Host Decides First Play#

The Minit app decides whether a player is new, so your game stores nothing for the tutorial. Call shouldShowTutorial() and report results as you already must; that is all.

• A player counts as having played once they have a reported result on any Post of the same Game, not just the Post they're playing now.
• After a result is reported, the app marks the Game as played, so the tutorial is hidden from the next launch on.
• Only the Minit app supplies this. The web play page and the Studio preview never do, so the tutorial always shows there. Use ?tutorial=0 to hide it.
• Older app versions don't supply it either, so on those your game shows the tutorial on every launch.

Creating the Overlay#

const GAME_W = 960
const GAME_H = 1480

const tutorial = createTutorialOverlay({
  container: gameRoot,
  width: GAME_W,
  height: GAME_H,
})

Pass width and height for the recommended setup: a fixed logical canvas (e.g. the house 960×1480 design surface) that a single uniform CSS transform: scale(...) fits to the screen. Coordinates you give the primitives are then in that logical space, and the overlay scales gestures and pills to match. Omit both only when your (x, y) values are already in the container's displayed pixel space — i.e. your game isn't using a fixed logical canvas.

Call tutorial.destroy() to tear the whole overlay down, for example when the tutorial sequence finishes, or at game over.

The Primitives#

Each of highlight, showFinger, and showSwipe returns a handle with a remove() method. That's how a step ends:

const ring = tutorial.highlight({ x: tile.x, y: tile.y })
const finger = tutorial.showFinger({ x: tile.x, y: tile.y, gesture: 'tap' })

// later, when the player does the thing:
ring.remove()
finger.remove()

All coordinates are in game viewport space: the logical width/height you passed to createTutorialOverlay, or the container's own client size if you didn't. Pills are always centred by the SDK and take no position argument.

Design: Live Guide, Not a Briefing#

The overlay runs alongside the game and reacts to what the player actually does.

Step by Step, Never Upfront#

1. The game begins immediately: no paused "tutorial mode", no wall of text.
2. When the game reaches a state that calls for guidance, show one step: a highlight and/or a finger on the thing that matters right now.
3. Wait for the player to perform the action.
4. Only then reveal the next step.

A player should never be reading. They should be doing.

State-Reactive, Not Timed#

Wire every hint to game events and state, never to setTimeout or a linear script running independently of play:

• Show the finger on the first enemy when that enemy spawns, not two seconds after load.
• Remove the swipe hint the moment the player completes a swipe, not on a timeout.
• Advance to "now avoid the hazard" only when a hazard actually appears.
• If the player figures it out before the hint would appear, skip that step entirely.

The step machine lives in your game code. The SDK primitives are stateless tools you call and remove; deciding when is your job.

let step = 0
let pending = null                             // appeared before its step was live

function onEnemySpawned(enemy) {
  if (step !== 0) return                       // already past this step
  const ring = tutorial.highlight({ x: enemy.x, y: enemy.y })
  const finger = tutorial.showFinger({ x: enemy.x, y: enemy.y, gesture: 'tap' })

  enemy.once('tapped', () => {
    ring.remove()
    finger.remove()
    enterStep1()                               // next step waits for its own event
  })
}

function onBonusTileAppeared(tile) {
  if (step < 1) {
    // Too early. Hold it, and keep tracking it: input is open, so the player
    // can collect it before step 1 ever starts.
    pending = { tile, collected: false }
    tile.once('collected', () => { if (pending) pending.collected = true })
    return
  }
  hintBonusTile(tile)
}

function enterStep1() {
  step = 1
  if (!pending) return

  const { tile, collected } = pending
  pending = null
  if (collected) {
    step = 2                                   // already done; skip the step
    return
  }
  hintBonusTile(tile)                          // replay what arrived early
}

function hintBonusTile(tile) {
  const ring = tutorial.highlight({ x: tile.x, y: tile.y })
  tile.once('collected', () => { ring.remove(); step = 2 })
}

Hold an event that arrives early, keep tracking it, and settle it on step entry. The game doesn't wait for your tutorial. Two things can happen while the player is still on step 0, and both stall the tutorial if you ignore them:

• The tile appears. If the handler just returns because the step isn't live yet, the tile is already on screen when step 1 starts and no second appearance event is coming. The hint silently never shows.
• The tile gets collected. Input is open the whole time, so the player can finish the step before it begins. Attach the collected listener when you hold the event, not when you replay it; otherwise you install it after the event already fired and step never advances.

Settling on entry is what makes both safe: hint the tile if it's still there, skip the step outright if it's already done. That second branch is the gestures-first rule from earlier applied to your own state: if the player acts correctly before the hint appears, skip that step entirely.

Gestures First, Text Last, Never Both#

Every step is either a show step or a tell step:

Priority Order#

1. highlight: mark the important element (button, tile, target, hazard) without covering it. Use on every show step.
2. showFinger / showSwipe: demonstrate the exact gesture. Pair with a highlight on the same target whenever you can.
3. showPill: only when a rule genuinely isn't guessable from a gesture. One short sentence. Remove all gesture hints first.

A Typical Step#

// ── SHOW step: gesture + highlight, input open ─────────────────────────
const ring = tutorial.highlight({ x: targetX, y: targetY })
const finger = tutorial.showFinger({ x: targetX, y: targetY, gesture: 'tap' })

function onTargetTapped() {
  ring.remove()
  finger.remove()
  // advance: another show step, or a tell step if a rule must be stated
}

// ── TELL step (only if needed): clear gestures, then the pill ──────────
function showRuleStep() {
  ring.remove()
  finger.remove()
  tutorial.showPill('One wrong tap ends the run.', {
    onClose: () => {
      // start the next show step once the player dismisses
    },
  })
}

Use highlight Alone When…#

…the element should be noticed but not touched yet: a hazard appearing, a power-up slot, an exit tile the player will reach later. Add the finger once interaction is actually expected.

When Text Earns Its Place#

Arcade vs Puzzle#

• Arcade / reflex (tap, swipe, jump): gesture only, highlight + showFinger / showSwipe from the first frame. No intro pill. Optionally one short pill after the first successful action, to state the goal.
• Puzzle / strategy: one short intro pill may be needed to frame the rules, but follow it immediately with a highlight and finger on the first interactive element. The player should be acting within a second.

Fixed Styling: Don't Override It#

Pill colours, finger glyphs, ring sizes, fonts, and timings all come from the SDK's bundled theme, so tutorials look the same across every Game. Position things; leave the look alone.

Testing Locally#

The two URL params make both paths reachable without a host:

/?tutorial=0 gives the same result as a returning player (no tutorial, straight into gameplay), so use it to test that path.

Common Mistakes#

• Skipping the shouldShowTutorial() check: returning players get the tutorial forever.
• Testing gating only on the web play page or in Studio: neither reports whether the player has played the Game, so the tutorial always shows there. Check returning-player behaviour in the Minit app, or locally with /?tutorial=0.
• A wall of text or several pills before play begins: one step at a time, in the moment it's needed.
• Timer-driven steps: hints wired to setTimeout, or steps that advance automatically after N milliseconds instead of when the player acts.
• A gesture and a pill on screen at once: remove the highlight and finger before opening a pill.
• Opening with a pill when a finger would do.
• Text that narrates the obvious ("Tap the button!") while a finger already points at it.
• A start menu or a "Play again" screen: a Game is one session (load, play, result). See Reporting Results.
• Rolling your own HTML/CSS tutorial overlay: you lose the consistent look and the correct input blocking.

Deeper Dives#

• Game UI: HUD, Feedback & Rewards: the rest of @minit-games/sdk/ui
• Reporting Results: the result that marks the Game as played in the app
• Install the Minit SDK: installing the package