Onboarding: the first minute

The goal and first move without reading, previews, cause and effect, strategy that reads, shot --story.

Nobody reads rules before playing a browser game. A player who doesn't know what to do within about ten seconds of play starting leaves, and one who loses without knowing why doesn't play again. The first round (or the first minute of a world or a run) is the tutorial: teach by having them do it, with the game showing them what matters at the moment it matters.

The rules of a good first minute

• The goal and the first move without reading. At the first beat of round 1 the screen says what to do by itself: the one thing to touch glows, an arrow or a ghost points at it, everything else is quieter. Two to five words at most, gone once done.
• Teach through round 1, not before it. No tutorial screens, rule cards or paragraphs in the lobby (the lobby's hint is one line). Make the first beat slower or safer (ctx.round === 1 in the round's rules; a first-time flag in a defineSave for a player who has never finished a match), so the first move succeeds. Then let go: hints stop once the player has done the thing.
• Preview before committing. Every choice that matters shows its consequence before it is made: where the shot goes (an arc), where the piece lands (a ghost), which cells a unit reaches, the points a move would score, which way the table would tip. The player picks between outcomes they can see, not numbers they must work out.
• Cause and effect, every time. When something big happens, show why, pointed at the cause: who knocked whom (a streak from the hit, the hitter's colour on the victim), what tipped (the heavy side glowing before it goes), where points came from (they fly from there to the score). The round's result says the reason in a line: "MIA'S BOULDER TIPPED THE TABLE".
• Show what the others are doing. Their aim, their choice made (a tick, not its content when hiding it is the point), their threat to you. A move the player could not have seen coming feels like luck, not like losing to a better player.
• Readable strategy. Depth comes from choices whose trade-offs are visible: greed against risk where both show on screen, a counter to the leader that everyone can see is available. If finding the best move needs a calculation the screen doesn't show, show it (the risk meter, the number) or simplify the rule.
• Short decision windows with clear stakes. A decision gets enough time to read what's shown (2 to 5 seconds for a quick read, 10 to 15 to plan), a visible clock, and an obvious "what's at stake now". Simultaneous hidden moves on a 3-second timer with nothing to read are a lottery.

Design it before building it

DESIGN.md (onceworlds new writes one) has "The first minute": a storyboard, second by second, of a player who has never seen the game, from the title to their first result, and a pre-build check (the design topic) to answer before writing the rules. If an answer is "no", change the design first: no amount of UI fixes a game whose choices can't be read.

Look at it the way a new player would

npx @onceworlds/cli shot --story (the MCP tool screenshot with story: true) plays the first minute and lays it out on one sheet: the title, the lobby, the countdown, the round's goal, play at +1, +5 and +12 seconds, and the first result. Look at the sheet as someone who has never seen the game, frame by frame:

1. Title: from the picture alone, what is the game and what will I do in it?
2. Lobby, if it has one: does it look like this game (its world, type and colours), not a kit? Who am I playing with?
3. Countdown and goal: at most one 3-2-1, then the goal in a few words?
4. First beats: is the one thing to do shown (highlighted, pointed at, previewed) so a first-timer does it without reading?
5. Play: can I see what the others are doing, and what my last move did?
6. First result: who won, and could I say why (what caused it)?
7. Every frame: one art direction, no stock panels, no "1/3" in a corner, no name pills with BOT tags (the ui-design topic).

Fix what fails, then shoot it again. check notes a game whose first round is the same as every other (onboarding), and warns about a second countdown (own-countdown).

A guided first beat, in code

// Round 1 only: the one thing to do, pointed at, until the player has done it once.
const Coach = defineResource('Coach', { done: t.bool(false) });

ui.view('coach', ({ flow, world }) => {
  if (world.resource(Coach).done) return null;
  return UI.label('TAP THE TABLE', { size: 34, outline: true });     // 2 to 5 words, big, where the thumb goes
}, { anchor: 'bottom', offset: [0, 120], when: ({ flow }) => flow?.phase === 'playing' && flow.round === 1 });

// In the system that handles the move: world.resource(Coach).done = true; and draw the ghost of where it lands until then.