Published 2026-09-12
REELS shipped with a five page tutorial where every figure checked out against the engine. It still left new players guessing how you win, because the win condition had changed four days earlier and nobody told the tutorial. Here is the audit, the iPhone SE truncation that made it worse, and the three step first descent that replaced it.
A tutorial can be correct on every single number and still teach a player nothing. I know this because I shipped one, audited it line by line in August, found not a single wrong figure, and then deleted four fifths of it anyway. This is what the audit actually found, and what I replaced it with.
REELS is a roguelite built on a slot machine. The reels drop on their own, your weapons fire on whatever they land on, and a toll comes due at the end of every floor. The first thing a new player ever saw was five full screen pages: a hiring notice, then four lessons with looping animated demos.
Until that day a toll had two conditions. You had to survive sixty seconds, and you had to have collected a quota of souls when the clock ran out. On 15 August I took the quota out of Adventure and out of the daily challenge.
The argument that convinced me is short. You have to survive the sixty seconds either way, so demanding a quota on top of that judged the same minute twice, and the second judgment rested on a number the player does not steer. You kill what comes at you. You do not choose how much comes. The threshold stayed in Endless mode, where it has a real job: there the clock decides nothing, the threshold *is* the level.
One flag, `leQuotaDecide`, and everything followed from it. The quota bar disappeared, because a gauge you cannot fail is scenery. The soul counter lost its denominator. "You are N souls short" became "hold until the clock runs out". The draft started announcing a duration instead of a quota. One charm that granted a ten second reprieve on a missed toll became literally impossible to trigger in Adventure and had to be given a new job, so I pointed it at the only remaining way to fail: you get back up at half health, once per run.
The in game rules screen was updated the same day. "110 souls at the first toll" became "surviving is enough."
The tutorial was not updated, because the tutorial did not mention the quota at all. That is the whole trap. Nothing in it became false. It just became silent about the single most important sentence in the game.
So the next day I checked the three lessons figure by figure against the engine.
"The machine spins every 3 seconds" matches the default machine's `spinBase` of 3.0 exactly. "12 projectiles, ricochet times 2" is exact for a star jackpot: rung three fires 12 shots, and a jackpot adds 2 bounces. Nothing to correct. The lessons taught the gestures, the thumb, the machine, the luck gauge, and taught them accurately.
And they never said two things that had become central.
How you clear a toll. Since 15 August it is the clock and nothing else. A tutorial that does not teach the win condition leaves the player to infer it, and the inference available on screen was wrong: there is a soul counter ticking up in the corner, so a reasonable person concludes there is a score to beat.
What the shards are for. Souls fall into the counter by themselves when something dies. Shards do not. They are the only thing in the entire game you have to physically go and pick up, and nothing told anyone that.
So a fourth lesson, "Hold sixty seconds": the clock is the condition, there is no soul quota, the next toll starts you at full health, and the shards fill a gauge that levels you up.
Writing it caught an older display bug, which is the usual reward for reading your own screen carefully. The lesson titles are two lines, "The thumb, / that is all", and they were rendering as "The thumb,..." with an ellipsis. Without a vertical `fixedSize`, SwiftUI compresses the block and truncates instead of wrapping down. And the progress bar was still drawing three segments underneath a counter that now read 1/4.
Two days later I put the thing on an iPhone SE.
The five lessons carried their animated demos in rigid frames, 340 points for the thumb lesson, 300 for the luck lesson, on a screen that has 667 points of height in total. There was not enough room left underneath to lay down the rule, and SwiftUI did exactly what it was told to do: it cut the text.
What a new player on an SE actually read was "Contact with an enemy = damag...", "It is the only way...", and, on the one example that exists to name the reward, "STAR RAI...".
A truncated tutorial teaches nothing, and this is the first screen of the game.
The fix is that demonstrations yield space to sentences, and sentences claim their height. With one exception that I only found by checking my own fix: the line "12 projectiles, ricochet times 2", left free to take the height it wanted, stacked onto three lines inside the narrow example column and pushed the GOT IT button off the bottom of the screen.
So there are two different rules and I had been applying one of them to both cases:
Confusing them produced the same defect twice, in opposite directions.
Then the feedback from the fourth test build arrived, and it was not about any of this. It was: you download the game, and you do not know where to look.
That is when I stopped patching the slideshow and moved it.
On a first launch you now see exactly one page: the hiring notice. The progress bar shows 1/1, the button says SIGN AND LEARN, and pressing it starts a run. The four lessons are not skipped, they are not shown, and they are not gone: they remain on the rules screen, where they render as 5/5 with a CLOSE button in the corner, because someone rereading a rule is not a captive audience.
Four fifths of the first launch experience was deleted from the first launch and kept as reference material. That is the whole change, and everything below is the consequence.
The first descent now carries a small three step training, labelled FORMATION 1/3 on a plaque placed high in the arena so the entire thumb zone stays free.
Each step has two distinct phases, and separating them was the part that mattered.
Read. The engine is paused. The plaque shows the sentence and a button. Nothing restarts on a timer, ever. The action button is the only door out.
Do. The engine runs until the gesture actually happens.
Before I split those two phases they overlapped, and the result was miserable: monsters kept attacking underneath the instruction, and the instruction disappeared the moment the action occurred by accident, which teaches the player that text on screen is noise.
The three gestures, and what the engine is really waiting for:
There are two seconds of ordinary play between one step completing and the next one appearing, so success is legible before the next plaque lands. Changing the plaque's contents in place instead made step 3 appear on top of step 2 and read as a screen flickering.
The state is deliberately not persisted. Quit the app mid training and the next Adventure starts again at 1/3, cleanly. But the signature on the hiring notice *is* permanent: someone who abandons that first descent is not asked to accept the job a second time.
The other half of "I do not know where to look" was the menu, which offered four modes and eight tiles the moment you got back from your first run.
It now opens in three stages. Before the first descent, two modes. On the first return, one single door, the locker room, so the player recognises their own character before anyone talks to them about economy or meta progression. The full cabinet, four modes and eight tiles, needs the training done and at least two runs on the counter.
The rest is signage, written the way a fairground booth is signed, as notes left behind by the previous owner rather than a character taking you by the hand.
Three stops on the first visit to the menu: the ticket office, the machine, the rest of the booth. Then eleven contextual placards, each fired at the first moment its subject becomes true and never before: the draft, the chest, the counter, the pact, the doors, the payout, your first tokens, a completed contract, the difficulty note, a found paper, the campaign.
Two rules make them work, and I got the first one wrong initially.
A placard says what to do. My first pass at these was atmospheric and evasive, and I rewrote all of them. The rule now sits in a comment at the top of the file: real screen labels in capitals, TAKE, CASH IN, WORKSHOP, and real engine numbers, six charms and two weapons, three symbols roughly every three seconds, times 1 or times 1.5 or times 3 at the payout. Two or three short sentences. The atmosphere lives elsewhere, in the machine's voice and in the papers you find. A placard explains.
A placard you leave without touching is not marked read. Only the button that dismisses it writes to the seen list. Walk away, get interrupted, background the app, and it comes back at the next opportunity. Nothing in this game is missable, and a piece of teaching is the last thing that should be.
Every placard read emits one analytics event, `tutorial_step`. It is the closest thing I have to a measurement of "the player is lost", and it is the only reason I can ever tell whether any of this worked.
On 20 August I found that the entire playable training was still speaking French inside the English and Spanish builds.
The four properties feeding that plaque return `String` values rather than literals. Handed to SwiftUI as a variable, a string is treated as verbatim text: the framework only localises what it can see written in plain sight in the view. The translation keys existed. They were simply never looked up.
That was part of a larger sweep, 133 texts displaying in French in the non French builds, from three unrelated causes. The one worth repeating here is this one, because it has a nasty shape: moving text into a more dynamic structure is exactly the move that silently opts it out of localisation, and the tutorial is the text where nobody who could report the bug is watching. A French speaker testing the French build sees nothing wrong. A new American player sees a fairground booth speaking French and closes the app.
The five pages were never wrong. They were in the wrong place.
A tutorial page is a document, and a document is something you agree to stop playing in order to read. A first descent is a place. The sentence "shards are the only thing you have to go and pick up" was true on page four of a slideshow and it was inert, because at that moment there were no shards, no arena and no reason to care. The same sentence, seventy seconds later, with a shard actually glowing on the floor two inches from your thumb, does the entire job in eleven words.
Nothing about the writing improved. I moved it next to the moment it describes, and cut everything that could not make that move.
REELS is on the App Store. The trial runs through toll 5, training and placards included, and one purchase unlocks everything permanently. No ads, no lives, no continues. Get REELS.