Big Typing Quiz: the Game Bible

The complete design and reference document for Big Typing Quiz. It is two things at once, on purpose: the specification a developer works from, and the manual a player reads when they want to know what a Railgun actually does. Every number in it is the number the code uses.

About this document#

Who it is for. A developer changing a system, a designer arguing with a balance decision, and a player who has just been told that splash rolls off plating and wants to know by how much. Those three readers want the same facts at different depths, so each system is described in the same order: what it is for, how it behaves, then the exact parameters in a table.

Where the truth lives. The code is the truth, this document describes it. Every table here was read out of the modules under js/, and the derived figures (XP per minute, level costs, characters to kill a word) were computed by running those modules rather than by hand. When the two disagree the code wins and this file is stale: fix it in the same commit that moved the number.

How to read a parameter table. Anything named as a multiplier is applied to a base value rather than replacing it. Anything in milliseconds is a real clock. Positions and speeds in the arcade are FRACTIONS of the playfield and playfield heights per second, never pixels, because what matters is how long a threat takes to arrive and not how big the screen is.

A note on units. One word is five characters, everywhere, without exception (CHARS_PER_WORD in js/util.js). Words per minute means correct characters divided by five, over the minutes actually spent typing. Every WPM in this document is net WPM unless it says otherwise.

Conventions. File paths point at the module that owns a rule. A number in code style is a constant you can find by that name. Sections are anchored, so any heading in this document can be linked to directly.

The other documents. ART_DIRECTION.md covers the art: how it was made, what each family has to look like, and the compositing contracts this document only summarises. CLAUDE.md is the guide for AI editors and carries the same reasoning in a different order. FILE_MANIFEST.md describes every file in the repo. FIREBASE_SETUP.md has the Firestore rules. This file is the one that carries the numbers.

1. The brief#

A complete beginner and a 130 words per minute typist have to open the same page and both find it worth playing.

That sentence is the whole design problem, and almost every decision in this document is an answer to it. It is harder than it sounds, because the two audiences want opposite things:

• A beginner needs short material, visible progress, forgiveness, and a reason to come back tomorrow before they are any good.
• An expert needs material that is actually hard, a number that moves fast enough to respect their speed, and no tutorial standing between them and the game.

Sites that pick one audience are common and they are all the same site. Sites that try to serve both usually do it with a difficulty menu, which fails because a difficulty menu asks a beginner to self-assess before they have any idea what the scale is.

Big Typing Quiz answers it four ways at once, and the four are deliberately different shapes so that no single player can be at the bottom of all of them:

And two mechanisms remove the need to self-assess at all:

• The measured field. The arcade picks its word tier from the rolling skill model, so a beginner meets three-letter home row words and an expert meets code tokens on wave one of the same game.
• The placement. A 60 second Flight Check on the first visit grants the level that performance already deserves, so an experienced typist starts around level 22 instead of at the home row.

1.1 The rules the design will not break#

These are load bearing. Everything else is negotiable.

1. Nothing is ever gated. Every game, drill, curriculum node, Academy group, sector and vendor is reachable in the first minute. Progression is shown as a score, a star count or a badge, never as a lock. A sector states a recommended power and lets you in regardless.
2. Gear buys access, skill buys rate. Gear reduces failure so you survive deeper. It never multiplies XP.
3. Assistance costs score. Every item that types for you carries a score penalty, so running with no help at all is the highest scoring build in the game.
4. Accuracy is paid in time. A threat's health is its word length, so being accurate literally means typing fewer characters. Nothing is ever deducted for a mistake in the arcade: you spend time instead.
5. Only complete runs count. A run walked out of is discarded everywhere except the per-key model, which keeps the keystrokes because they are still real evidence about your fingers.
6. One funnel. finishRun() in js/run.js is the only thing in the codebase that grants XP, chips, cores, badges, loot, bests, History entries or leaderboard posts. A game reports what happened; the funnel decides what it was worth.

2. How to play#

This section is the manual. Everything in it is expanded later.

2.1 The first ten minutes#

1. The Flight Check offers itself once. One minute of ordinary words. It measures you, grants the level you have already earned, seeds the per-key model with real evidence, and tells the Academy which key groups you have already proved. Declining costs nothing and it never nags again, but the offer stands on the Arcade card and in Progress until you take it.
2. Open the Arcade and play Starfall Keys. Craft descend carrying words. Type a word and the turret fires on whatever is carrying it. Miss and the heat builds. Every fifth wave a boss broadcasts a paragraph at you.
3. Spend chips in the Armory. Chips accrue from time played, so you will have some. Buy a hull or a coolant first: staying alive longer is what makes everything else pay.
4. If the keyboard is not yet under your fingers, open Training. The Academy teaches two keys at a time and never scores you on speed.

2.2 Controls#

On a phone the keyboard is raised by a single hidden input (#kbCatch) that the app never rebuilds, so it stays up for the whole run.

2.3 Reading the arcade HUD#

2.4 Ten things worth knowing early#

1. Typing the first letter of a word locks the LOWEST threat carrying it. The lowest one is the one about to land.
2. A wrong key never deducts anything. It costs heat, the combo, and (in Strict mode) the lock.
3. Power-ups are typed like anything else. They are the short words in capitals.
4. A boss is not a wave with a health bar. It broadcasts prose at you, and while it does, your typing is the only weapon that fires at the escorts.
5. Being accurate with a precision weapon kills a word before you finish typing it. That saved time is the reward.
6. Fumbling with a precision weapon means the target survives and takes a fresh short word. Nothing is deducted, you just meet it twice.
7. Gambits are opt-in handicaps that pay a multiplier. They are how you make the game hard again after your gear has made it easy.
8. Cores only ever drop from bosses and mini-bosses. Nothing else in the game produces one.
9. The Academy never measures speed. Certifying the whole keyboard is the largest single XP award in the game.
10. Contracts, the streak and the Salvager's shelf all roll over at your local midnight.

3. The loops#

A game that only has one reward cycle only holds one kind of player. Five run at once, and each is a different length:

The middle loop is the one most typing sites do not have at all, and it is why the loot system exists: XP is continuous and predictable, chips accrue by the second, and a badge fires once. None of those produce the moment where something falls out of a boss and you do not yet know what it is.

4. Progression#

4.1 Axis 1: level XP, absolute skill#

XP counts correct characters produced under pressure, which is what typing skill is. The pace half of a run's XP is:

words   = correct characters / 5
paceXp  = words * paceFactor(netWpm) * accFactor(acc) * difficultyMultiplier

with

paceFactor(w) = clamp((w / 40) ^ 1.35, 0.35, 8)
accFactor(a)  = clamp((a / 100) ^ 2, 0, 1)

Accuracy is squared, so speed bought with sloppiness does not pay: 95% keeps 90% of the XP, 85% keeps 72%, 70% keeps 49%.

The reference pace is 40 WPM, where paceFactor is exactly 1. Because a faster typist also produces more words in the same minute, the compounded rate is steeper than the exponent alone suggests:

Both clamps matter. The floor of 0.35 keeps a genuine beginner earning something rather than nothing, which would read as broken. The ceiling of 8 stops a freak measurement (a stuck key, a paste, a three character run with a tiny denominator) from minting a level.

Flat bonuses are the beginner's engine. They are fixed amounts, so they dominate the XP of somebody hitting firsts constantly and are a rounding error to an expert:

Defined in BONUS, js/xp.js.

The level curve costs round(60 + 40 * level^1.28) XP for the step from level to level + 1, capped at level 100. The exponent is gentle enough early that a beginner sees levels move in one session, and steep enough later that level 60 means something.

Ranks follow the level, so the number and the word never disagree:

4.2 Axis 2: mastery, relative to yourself#

Curriculum nodes and Academy drills are judged against your OWN rolling baseline, never against a fixed target. That is the mechanism that keeps a beginner progressing, and it is the thing most star-based typing sites get wrong: fixed WPM targets give the beginner who needs encouragement most none at all, and let the expert clear everything on day one.

How a node is starred (scoreNode in js/skill.js):

Because the steps are RATIOS, 18 to 24 WPM (plus 33%) and 100 to 115 WPM (plus 15%) are the same kind of event, and the beginner's is in fact the larger one. The baseline falls at roughly a sixth of the rate it rises, so it is a floor you have to walk back down to rather than a punishment for one good night.

4.3 Axis 3: chips, time and consistency#

Chips are the Armory currency and they are deliberately NOT speed-scaled:

chips = correctCharacters / 5 * 0.5 + minutes * 8
        + 10 if accuracy >= 97
        + 25 if the run was a personal best

then multiplied by the salvage multiplier from gear and the sector, and by any ascension bonus.

This is the counterweight to XP's speed bias, and the numbers show it working:

A slow typist who plays for twenty minutes out-earns a fast one who plays for five (410 chips against 340), while the fast one has earned forty times the XP. Both are progressing, on different axes, and neither route is a trap.

4.4 Axis 4: gear, access rather than rate#

Stated as one line, because it is the thing to protect if you change anything in js/gear.js:

Gear buys ACCESS. Skill buys RATE.

Almost every stat in the catalogue reduces FAILURE: more health, less damage taken, more heat before a jam, a combo that survives a slip, a charge that swats the thing about to land, a field that descends slower. Good gear lets a 30 WPM player survive to wave 18 in a sector that would have ended them at wave 6, and carries them into the Rift, which is exactly what it is for.

The only two stats that touch earning are scoreMult and salvageMult, and both are clamped hard: score to 0.75x..1.45x, salvage to 0.8x..1.6x. Compare that to paceFactor, which spans 0.35x to 8x on typing speed alone. A fully kitted 30 WPM player reaches the Rift and earns steadily; a fast player in starting gear out-earns them several times over while dying earlier.

The full gear system is section 10.

4.5 The placement#

The Flight Check is the skip-ahead. It runs a 60 second sprint and then grants a lump sum equal to the level that performance deserves.

placementLevel(w, acc) = clamp(round(((w - 18) / 3.6) * (acc / 100) ^ 1.5), 1, 42)
                         (and exactly 1 below 20 WPM)
placementGrant(...)    = max(0, totalXpFor(placementLevel) - currentTotalXp)

Four rules make it safe to re-take:

1. It only ever raises. The grant is the difference between what you have and what the measurement is worth, floored at zero.
2. The profile keeps the BEST placement, not the latest. Rewriting "placed at level 22 from 96 WPM" with a slower re-take would replace a true sentence with a misleading one.
3. It seeds the per-key model, and that seeding also only ever raises. This is what makes the curriculum immediately recommend symbols and code to a proficient typist rather than the home row.
4. It hands the Academy a head start. Any key group whose keys the measurement already proved (12 or more samples at 90% or better) is marked as evidence rather than starting from zero.

The dialog offers itself once per profile and then never again. placed records a completed check; placeOffered is stamped the moment the dialog opens, because closing it is an answer and re-opening a modal on every load until a one minute test is finished is nagging. The offer itself does not go away: the Arcade's "Start here" card and the Progress re-take button stand for as long as the profile is unplaced. tools/check-app.py guards this.

4.6 Per-game ranks#

Each mini-game keeps its own XP, rank, plays, bests and badges in state.games[<id>], so playing Starfall levels up Starfall AND the account, and being level 40 does not make a game you have never opened look finished.

The per-game curve is flatter than the account one, at round(120 + 70 * rank^1.15) per rank, capped at rank 50. A game rank is a familiarity measure, not a skill measure.

4.7 Ascension#

At level 100 you may reset the level and XP, keeping EVERYTHING else: gear, cosmetics, badges, the Academy, History, the boards. Each ascension grants a permanent +6% to XP and salvage (compounding by count), a visible mark, and 5 cores so the first hour back is not a wasteland.

It is opt-in and never suggested twice. It exists so the ceiling is a door rather than a wall.

5. Measurement#

5.1 Speed and accuracy#

There is exactly one definition of each, in js/util.js, and every surface in the app uses it:

CHARS_PER_WORD = 5
wpm      = (characters / 5) / minutes
netWpm   = (CORRECT characters / 5) / minutes
accuracy = correct / typed * 100

What counts as a minute. The arcade measures typing time as wall clock minus the time the game spent showing you a card rather than a wave (the countdown and the between-wave breather). The wall clock still counts for chips and History, because that IS time played, but calling a four second breather zero WPM and averaging it into a leaderboard row would be dishonest.

Backspace. In the arcade a mistyped key is spent and there is nothing to delete. In sprints, drills and boss transmissions backspace is allowed, because a paragraph you cannot correct is a punishment rather than a test. It restores the text and the character counts toward net WPM, but the keystroke that got it wrong stays in the accuracy denominator forever. That is the standard convention and the only one that stops "type garbage and repair it" scoring 100%.

5.2 The plausibility gate#

plausible() in js/run.js drops a run that claims something no human did. The Cloudflare Worker holds the same line independently on the leaderboard side.

5.3 The per-key model#

One record per character and per typed pair, holding how often it was hit, how often it was right, and how long the finger took. This is what makes the site personal: the arcade builds asteroid chunks from your worst keys, the drills target them by name, and the Progress heat map is a picture of your own hands.

Timing is keyed by the character that was EXPECTED, not the one that was pressed: knowing you typed k when l was wanted says something about l.

Account-level skill is an exponential moving average of recent runs rather than a best, because a best is a story about one lucky minute and this number has to decide what to put in front of you next. The first run is adopted whole (a new player should see a real number, not a fifth of one), then the weight falls off as runs accumulate and settles at a floor of 0.12 for a veteran. Run length weighs in as well: a 15 second burst is not the same evidence as a five minute haul (RUN_FULL_MS is 30 seconds).

5.4 Word tiers#

The lexicon is ten tiers of hand-written real words, each staying strictly inside its own character set, plus a prose tier for sentences and paragraphs.

Plus 20 quotes for the sprint's Quote mode.

tierForWpm in js/xp.js maps the rolling skill number onto that ladder, and it is the single reason the same arcade game is right for both audiences. Difficulty and sector multiply on top; they never replace it. A fixed table would mean picking an audience.

5.5 Weak keys#

weakKeys(n) returns the worst keys the model is confident about (at least 12 presses), scored on accuracy first and latency second. They are used for:

• asteroid chunks in the arcade, which are the one thing in the game that is not a real word, because there is no English word made of the four keys you are worst at,
• the Meteor Shower event, which is built entirely from them,
• the Hive Mind boss, which speaks in them on its last phase,
• the sprint's Weak keys mode and the curriculum's two adaptive nodes.

Your weak keys are the one thing a Versus room does NOT share.

6. Modes and surfaces#

The app is six tabs. Two of them hold games, the rest are where the game is read, spent and compared.

The router mirrors the active tab into location.hash, so app.html#arcade deep-links. The ids are stable even if a caption is renamed.

6.1 The game catalogue#

js/games/registry.js is the only list of what games exist.

An announced card is not a lock. It is a game that has not been BUILT yet, it says so in those words, and it must never show a padlock, a level or any implication that the player fell short. Nothing on this site is gated; the only thing standing between a player and an announced game is us.

7. Starfall Keys#

The flagship. Your base sits on the lower edge, craft descend carrying words, typing a word destroys the thing carrying it.

7.1 The field#

Simulation units are FRACTIONS of the playfield, so nothing depends on canvas size and a phone turned over mid-run never moves a threat relative to the base.

Descent speed is in playfield heights per second, which is the honest unit: what matters is how long a threat takes to arrive.

7.2 The wave cycle#

countdown (2200 ms, skippable after 700 ms)
  -> wave: spawn queue drains, threats descend, encounters fire
  -> wave ends when the queue is empty and nothing but power-ups is flying
  -> breather (4200 ms, skippable by any key), hull regen applies
  -> next wave

What a wave is built from (waveBase, fillQueue):

pace     = clamp(currentWpm() / 40, 0.55, 2.4)
speed    = 0.026 * (1 + (wave - 1) * 0.055) * pace * difficulty.speed * sector.speed * fieldSlow
interval = clamp(2900 / (1 + (wave - 1) * 0.17) / pace, 520, 3400) ms
wordLen  = 1 + (wave - 1) * 0.03
queue    = min(46, round(6 + wave * 1.7)) threats

Each spawn then jitters its own gap by interval * (0.75 + rnd * 0.5).

The adaptive part is the pace term. It is the measured player, so the field moves at the speed of the hands playing it. Difficulty and sector multiply on top rather than replacing it: a beginner on Nightmare is still reading short words, they are simply arriving quickly.

Word tier per wave climbs off the MEASURED tier, not the wave number:

waveTier(wave) = TIER_ORDER[ clamp(indexOf(tierNow()) + floor((wave - 1) / 4), 0, last) ]

So an expert who starts on punctuation is reading code by wave twenty, and a beginner who starts on the home row has reached whole words.

7.3 Enemy catalogue#

A threat's HEALTH IS ITS WORD LENGTH. With the starter weapon that is one point of damage per correct character, so finishing the word kills it and the game reads exactly as it would with no gear system at all. That baseline is deliberate and must stay true.

Word length ranges are multiplied by the wave's wordLen and by any live event's length multiplier, then floored at 2.

Threat behaviour is deliberately simple, and that is a design decision rather than an omission: everything interesting in this game happens in the text, so a threat that jinked or shot back would compete with the words for the player's eyes. What a threat does is descend at its speed, drift sideways by up to +/-0.006 per second, and land.

A splitter's children do not split, and neither splits when killed by a blast (a nuke or an emergency charge), because a panic button that seeded two fresh drones would be worse than useless against exactly the wave it exists for.

Arrival. A threat crossing BASE_Y deals its damage, scaled by the sector's toughness and your hull's damage multiplier, absorbed by any shield first. A power-up that arrives simply leaves.

7.4 Targeting and the lock#

Strict mode default follows the difficulty (auto): strict from Ace upward, which is where the difficulty blurbs already promise it. The player can override to on or off in settings.

7.5 Damage and the accuracy axis#

Every correct character deals damageFor() to the locked target:

d = clean ? dmgClean : dmgFoul
d = d * profile.clean or profile.foul     (the encounter's vulnerability, if any)
d = d * (1 + min(0.6, comboDmg * combo))  (comboDmg weapons only)
d = d * pierce * profile.pierce           (against a boss or mini-boss only)
d = d * swapDamageMult(msSinceSwap)       (0.5 rising to 1 over 600 ms)
floor at 0.05

clean is whether the CURRENT TARGET has been fumbled, not whether the run has. The bargain is per engagement: a slip costs you that kill and nothing else, which keeps it a cost rather than a spiral.

What this feels like. With a Lance (1.55 clean, 0.45 foul) a clean seven-letter word dies on the fifth character and the last two simply vanish. Fumble the same word and it takes sixteen characters. Nothing is deducted and nothing scolds you: you spend the one thing you cannot get back.

Splash deals splash * targetMaxHp to the nearest other threat within a squared distance of 0.35 (with x scaled by 1.4 for aspect), and is drawn as an arc so it never reads as the game killing things at random. Splash cannot chain-trigger power-ups and does not reach the encounter's own craft.

7.6 Heat and jams#

A jam drops the lock, shakes the screen and takes NO input at all while it lasts. It deliberately does not count the ignored keys as mistakes: the mistake that caused the jam has already been paid for, and charging again for the second you cannot fire would make heat a spiral rather than a lesson.

7.7 Combo, score and the Zone#

Combo is consecutive correct characters. A mistype takes it to floor(combo * comboKeep), where comboKeep is 0 without gear (lose it all) and up to 0.85 with it.

Score is small numbers multiplied by everything:

scoreMultiplier = comboStep * zone * focus * sectorAndLoadout * difficulty
  comboStep = min(4, 1 + floor(combo / 10) * 0.25)
  zone      = 1.25 while lit
  focus     = 2 while a FOCUS power-up is live

The Zone is the flow channel, named and paid for:

It pays PER SECOND HELD rather than per entry, so it rewards sustaining flow rather than tapping into it. A boss transmission is its natural home, because it is the longest unbroken stretch of typing the game offers. The visual treatment is deliberately calm: the Zone is the player concentrating, and the worst thing the game could do at that moment is interrupt them to celebrate.

7.8 Power-ups and charges#

Power-ups are ordinary lockable threats that happen to do something good when they die, which is why they are typed exactly like everything else. They are uppercase so they read as a command rather than as another word to clear.

Drop rules. Exactly one roll per kill: 85% from a cruiser (which is what power-ups are for, since a cruiser is slow, long and worth engaging), 3% from anything else, and never from a power-up itself.

Emergency charges (Ctrl + Space) destroy whatever is closest to your base, skipping power-ups, because spending a panic button on the thing you were about to collect would be the worst possible outcome of pressing it. Charges come from the module slot and are capped at 8.

7.9 Difficulties and sectors#

Difficulty scales speed and pays a multiplier on XP and score:

Sectors are where gear turns into access. Every one is enterable at any power: the recommendation is advice, not a lock.

The sector's damage column multiplies what reaches your hull AND the health of a boss phase (a phase's health is the length of the transmission that opens it, times this number).

Skill substitutes for gear, at SKILL_POWER_PER_WPM = 1.2 points of power per WPM above the 40 WPM reference. So roughly every 10 WPM is worth 12 points of power, because a threat destroyed early never tests your hull at all. sectorAdvice() says this in words rather than blocking anybody.

7.10 The end of a run#

A run ends when the hull reaches zero, or when an optional duration expires (a timed Versus round, which counts as complete because the player played the whole thing). Leaving the tab or navigating away calls stop(), which abandons: no score, no XP, no History, no board, and only the keystrokes go to the skill model.

What Starfall reports to finishRun():

The game computes NO rewards. It reports facts, and js/run.js decides what they were worth.

7.11 The two renderers#

Starfall has two views and they are interchangeable: the flat one (a hand-drawn 2D canvas with the sprite layer of section 7.12 over it) and a 3D scene built on the vendored Three.js. Which one is running is a question about the picture and never about the game.

The flat view is the site. It is what every ordinary visit gets. The 3D renderer is still being worked through, so it does not ride along with the home page: it has its own address.

Following the link sets settings.render3d and PERSISTS it, so the URL is an entry point rather than something to keep in the address bar, and the Settings switch does the same thing and is the way back for anybody who arrived by link. The redirects live in _redirects, a Cloudflare Pages file that a plain local serve does not reproduce; the query parameter it lands on is what actually does the work.

The rules that keep the two views one game:

The 3D view's own rules: every shape is generated in code (no model files, no textures), the glow is emissive material plus ACES tone mapping rather than a bloom pass (bloom is roughly thirteen fullscreen passes over eleven render targets, which is the exact bandwidth pattern that ruins tile-based mobile GPUs), a word is held at a constant fraction of viewport height however far away its craft is, craft are modelled to be read from ABOVE, and the camera distance is solved per resize rather than hard-coded.

7.12 Art, and what happens when it is missing#

The flat view draws generated sprites over its hand-drawn shapes, and the Arcade and Armory are staged with rendered backdrops. js/art.js is the one module that knows where any of it lives; everything else asks by key and never hard-codes a path. ART_DIRECTION.md is the companion document that says how the art itself was made and what it has to look like.

Two families, with two different compositing contracts:

Vector fallback is law. Nothing that draws a sprite may assume it loaded: every caller checks spriteOk() and falls back to the hand-drawn shapes that shipped before any of this art existed. The app must play identically with assets/art/ deleted, the same way it already must play without webfonts and without Firebase. Every function in js/art.js is best-effort and silent, so a missing file downgrades the look and changes nothing else.

Two consequences worth knowing:

• An asteroid picks one of two rocks from its own seed, so a field of them is not one rock stamped twenty times, and the pick is a pure function of the threat rather than a fresh roll (a roll would desynchronise a race).
• The player's craft is a cosmetic, so the sprite is tinted at runtime. Five neutral base renders are recoloured from the equipped cosmetic's own hull and trim hex and cached per combination, which keeps cosmetics purely cosmetic while still letting them change what you look at.

The weapon you are firing is visible. weaponVisual() derives the turret's look from what the weapon actually DOES rather than from its id: a splash weapon sprays, a combo feeder fires tracers, a precision weapon lances, and everything else fires the honest bolt. It is recomputed on every swap, so pressing Tab visibly changes the gun.

7.13 Music#

Four tracks, played by scene and crossfaded over 900 ms so a scene change is a dissolve rather than a cut:

Music is on by default at half volume, and both are in Settings. js/music.js creates no element and fetches no byte until music is enabled AND a scene is set AND the browser has seen a user gesture, so a visitor who never plays never pays for it. Every play() is best-effort: an autoplay refusal parks the intent and the first real gesture retries it, and nothing in the module throws, because a music failure must never cost a frame or a keystroke.

This is the one deliberate exception to "no audio assets". Keystroke-rate SOUND EFFECTS stay synthesized in js/audio.js, because they fire from keydown handlers and must never wait on a decode. Music is long-form and streamed, so files are the right tool for it and the wrong tool for a keypress.

8. Encounters: events, mini-bosses and bosses#

A wave counter that only ever spawns faster is a difficulty curve, not a rhythm. Encounters are the rhythm: three tiers of escalation that interrupt the ordinary run at different scales, each worth more than the minute before it.

8.1 The director#

makeDirector() decides what fires and when. It owns no rendering and no spawning: the game asks it for numbers and draws the banner itself.

Every choice is drawn from the run's seeded generator, so two players in a Versus room meet the same events on the same waves with no server dealing them. Nothing in js/games/events.js reads Math.random.

8.2 Events#

Short and frequent. A modifier plus a reward multiplier. The spawn block is a patch applied over the game's own numbers for the duration, so the game never branches on an event id.

An event is CLEARED by surviving it: the modifier was the challenge.

8.3 Mini-bosses#

An event that fights back. One tougher craft with an escort, a small health bar and a SENTENCE to answer, on a clock. Kill it before the clock and the whole encounter pays; let it reach the base and it does not.

A mini-boss's escort and shield are attached to its first line only. Its transmissions run 38 to 63 characters at the short band, 171 to 195 at medium.

8.4 Bosses#

The milestone, every fifth wave (every fourth in the Rift). Named, multi-phase, with shields only a command word breaks and a health bar across the top.

A boss is not a wave with a health bar, and the difference is the text. An ordinary threat carries a WORD, a mini-boss a SENTENCE, a boss a TRANSMISSION that grows from one sentence to a whole paragraph by its last phase.

That changes the texture of play, which is the actual job of a boss. Waves are staccato (lock, burst, release, find the next target) and the skill under test is target acquisition. A transmission is sustained, with no switching and no hunting, and the skill under test is stamina and composure.

Phase tables. Each phase is a gate: an optional command word that drops the shield, then one transmission to strip the phase. The escort arrives with the phase.

The Oracle also hides what it has not said yet, and that applies to what it sends as well as to what it says: its escorts arrive hidden.

Phase health is the length of the transmission that opens it, times the sector's toughness, floored at 8. With the starter weapon that is one character of damage each, so reading the passage out strips the plate exactly: the same honest baseline an ordinary word keeps.

A fumbled transmission costs a second, shorter one, exactly as a fumbled word costs a second engagement. Backspace is allowed, but a corrected character still counts against accuracy and the damage it never dealt is not refunded: only a character that landed correctly the first time it was answered ever deals damage, so retyping cannot deal it twice.

Transmission lengths, measured across all four bosses:

A slow typist meets the same boss saying shorter things. bandForWpm caps the band: under 30 WPM everything is short, under 55 WPM nothing exceeds medium, and only above that does a boss reach for a paragraph. A phase's own length is the ceiling, this is the floor a beginner is protected by, and it is the same adaptation the word tiers already make.

Your typing is the weapon. While a transmission is live the turret has no target list: every CHARS_PER_SHOT (6, scaled by the weapon's fire rate, minimum 2) correct characters fires a round that destroys whatever is closest to your base. Type well and the escorts never arrive. Stall, or spray mistakes, and your guns fall silent exactly when the screen is filling up. The answer to "the boss is overwhelming me" is always "type better", which is the answer this whole site is built to reward.

A boss that reaches your base deals its damage and leaves. It is not cleared, so it drops nothing: that is what gives the fight stakes past the health bar.

8.5 Vulnerability profiles#

The reason a loadout is a counter-pick rather than a preference. A weapon choice that is simply "how I like to play" is a personality quiz; a weapon choice that is right for the Dreadnought and wrong for the Hive Mind is a decision.

The profile belongs to whatever encounter owns the field, so the Dreadnought's plating shrugs off a Flak Battery even while you are shooting its escorts.

Nothing enforces the counter-pick. loadoutAdvice() tells you in one sentence whether what you are carrying suits what is coming, and bossSchedule() puts the rota on the pre-flight screen so you can choose before the run. Bringing the wrong thing makes a fight harder, never impossible, which is the same stance sectors take about power.

8.6 Laps: the roster cycles#

Bosses arrive in order and the roster repeats. Each full lap raises the boss:

So wave 25 is the Sentinel again but meaner, rather than a boss nobody has met.

8.7 What an encounter pays#

Two shapes of reward, and the difference matters.

A timed encounter pays a MULTIPLIER on the work done WHILE IT WAS LIVE. That is why the ledger counts characters PER ENCOUNTER rather than merely noting that one happened:

eventBonusXp = (xpMult - 1) * (charactersTypedUnderIt / 5) * paceFactor * accFactor * difficulty

A blackout you fought through pays; a blackout you hid from does not, and a game cannot inflate the bonus by idling under a banner because there is nothing to multiply.

A boss pays FLAT, because a boss fight can run a long time and paying it by the character would make the reward a function of how SLOWLY it was killed. The director's multiplier returns 1 during a boss for the same reason.

Chips follow the same split and stay speed-blind: an encounter pays (chipMult - 1) * characters / 5 * 0.5, plus 18 per event cleared, 40 per mini-boss, and 120 + 40 * phases for a boss.

9. Gear, weapons and builds#

Nine mounts, seven categories, fifty-three items. The catalogue is SIDEGRADES, not a ladder: every top-end item is better at what it does and worse at something else. Remove the downsides and the build system collapses into a shopping list where the best item is simply the most expensive one, which tools/check-modules.mjs checks for.

9.1 The slots#

A fresh profile owns and wears the starter of every slot, and the second hardpoint defaults to EMPTY rather than to the starter weapon: a one-weapon build is the default and the second mount is something you choose to fit.

9.2 The stat sheet#

The game reads the aggregate, never the items, so a new stat is one entry here plus one use in the game.

The two bold clamps are the ones that keep the central claim true. The floor on dmgFoul is the other important one: a fumbled target must always still be killable, or a slip with a Railgun would mean standing there typing forever, which is a punishment rather than a cost.

How stats combine. Plain numbers add. scoreMult and salvageMult multiply. dmgMult and fieldSlow are reductions (a +1 upgrade makes a 0.9 into a slightly stronger 0.886, never a larger number). comboKeep takes the best rather than stacking. Only the LIVE hardpoint's weapon and attachment contribute, so carrying two weapons is never a way to add their numbers together.

9.3 Weapons#

The accuracy axis, running from "devastating while clean, useless after a slip" at one end to "never punished, never spectacular" at the other. Read the pairs as bargains, not as a ladder.

What those numbers actually do. With no attachment and no upgrades:

Read the last two columns together: that is the whole design. A Railgun kills a clean word in four characters and needs twenty eight after a slip. A Flak Battery needs eight either way. At a steady 40 WPM with no mistakes they kill the same drone on the same word, and the power ratings say they are the same class of item, because power is a statement about gear and not about the pilot.

9.4 Attachments#

One socket per hardpoint, and its whole job is to move the weapon along the axis. The obvious play is to double down (a Lance with a Focusing Lens); the interesting one is to correct (a Railgun with a Recoil Damper, which is still sharper than anything else and no longer catastrophic when you slip).

The Gyro Mount is the rule in miniature: assistance costs DAMAGE here, exactly as it costs SCORE in the targeting slot. The Resonator is the one attachment that asks for nothing back, which is why it is priced in cores.

9.5 Hulls#

9.6 Targeting#

The assistance slot, and therefore the slot where the score penalty lives. An empty sight is the highest scoring option in the game, on purpose.

A skilled typist deliberately flies with an Open Reticle because assists would cost ten percent of a score they do not need help earning. A learner takes every assist on offer and reaches content they could not otherwise see. Both are correct. That is what a build is.

9.7 Coolant, reactor and module#

9.8 Upgrades#

Every owned item goes to +5. Each level is worth UPGRADE_STEP (14%) of the item's base stats, and an item's DOWNSIDES scale too: a +5 Glasswing is even more fragile, which keeps a sidegrade a sidegrade at every level.

chips for the step from +n = round(basePrice * (0.45 + n * 0.35))
basePrice for a core item  = cores * 420
the last two steps (+4, +5) also cost 1 core each

Upgrading a good item competes with buying the next one up rather than being strictly worse, and the core cost on the last two steps means the very best loadout still has a boss fight standing behind it rather than an afternoon of drills.

9.9 Power#

One number for "how kitted am I", the way an ARPG shows item level. It is compared against a sector's recommendation and shown on the loadout screen. A bare call rates the BETTER of the two hardpoints, because a player who brought the right weapon for half the fight is equipped for the place.

Survivability is weighted heaviest because that is what sector difficulty actually tests. dmgClean and dmgFoul are weighted almost equally on purpose: a Lance is only more powerful than a Scatter Array in the hands of somebody who stays clean, and if precision alone raised power the Rift would look gated behind a weapon rather than behind a decision.

9.10 Two hardpoints#

A loadout frozen for a whole run makes vulnerability profiles a gotcha: you meet the Dreadnought's plating with a Flak Battery in your hands and there is nothing to do but remember for next time. Carrying two weapons and swapping with Tab turns that into a decision made DURING the fight.

Three things stop it from being free:

So the purist running one weapon still scores highest, and the interesting question is two specialists (answer everything, score less) against one specialist and an empty mount (answer one thing perfectly).

9.11 Gambits#

Opt-in handicaps, taken before a run, that pay a multiplier on XP and salvage. They stack multiplicatively. This is the pressure valve for a player who has out-geared their sector: rather than nerfing their gear, let them BET it.

Gambits OVERRIDE gear rather than subtracting from it, so "no assists" means none regardless of what is bolted on. Taking all six multiplies rewards by 3.94x, and js/run.js clamps the applied multiplier to 4x.

9.12 Four builds that work#

Worked examples, because a stat table does not teach a build. Every number below is what loadoutStats() actually returns for that set of items at +0.

The Purist. Railgun, Match Actuator, empty second mount, Open Reticle, Glasswing, Run-Hot Manifold, Overcharged Cell, Empty Mount.

Power 5 in the Rift, which recommends 92. That is the point: this build is not under-geared, it is geared for a pilot who does not intend to be hit. Add gambits until it stops being easy.

The Long Haul. Bulwark Repeater, Recoil Damper, Titan Frame, Oracle Sight, Zero-Point Sink, Flux Capacitor, Charge Battery.

Nearly twice the Rift's recommendation, and it earns 45% less score per point. That is gear buying access, exactly as designed.

The Counter-picker. Lance with an Armour Piercer for the Dreadnought on the primary, Flak Battery with a Splitter Prism for the Hive Mind on the secondary, Combo Governor, Mender Frame.

The Prospector. Scatter Array, Recoil Damper, Aegis Plating, Assist Module, Cryo Loop, Salvage Magnet, Prospector's Rig, flown in the Rift.

Cores still only come from bosses, so even the farming build is about surviving to fight more of them.

10. Loot and the economy#

10.1 Two currencies#

Cores being boss-only is what makes a boss structurally worth starting rather than merely worth more points, and it is what the Archivist's stock is priced in. A contract that any run could finish must never pay one for nothing: the two contracts that do pay cores ask for a boss, a wave 15, or three clean runs.

10.2 Rarity#

Rarity is DERIVED from what an item costs and what it asks of you, rather than being a field on all 56 cosmetic entries. That keeps one source of truth: if an item is expensive or gated behind level 40, it IS rare, and the two can never disagree.

An item may override this by carrying its own rarity, which is how a cheap thing can be made special deliberately.

10.3 Drop tables#

rolls is how many cosmetic cards the source turns over; chips and cores are inclusive ranges; floor forces every roll to at least that rarity.

All drop quantities are then multiplied by the sector's loot multiplier, the loadout's salvage multiplier and any gambit multiplier.

Only a CLEARED encounter drops. A boss that reached your base takes its salvage with it.

10.4 The three anti-frustration rules#

1. A duplicate is never nothing. It converts to chips at the rarity's rate and the reveal card says so. "You got something you already have, and it was worth nothing" is the fastest way to make a loot system feel hostile. Rolling also PREFERS items you do not own, so the duplicate path is a fallback rather than the common case.
2. A pity counter guarantees an Elite or better within PITY_AT (6) rolls, applied to the FIRST roll of a batch so a guarantee does not become three. It is re-derived from what was actually GRANTED, so a roll that found nothing to give does not quietly eat a step of protection.
3. A first kill floors at Rare. The first time you beat something should never pay out worse than the tenth.

10.5 The vendors#

Three shopfronts over the two catalogues, because a single undifferentiated shop is a spreadsheet and a shop with a face is a place you visit.

The Salvager's five are drawn from a generator seeded on the DATE, so everybody sees the same five things on the same day with no server dealing them, and the countdown to the restock is the reason to look in tomorrow.

purchase() is the one payment path: it takes payment and grants in one block with nothing between the two lines that can throw, because "paid, not granted" is the one failure a player would never forgive.

10.6 Cosmetics#

Five purely decorative slots, 56 items. Nothing here affects gameplay. "Does this affect the game" is answered by which file an item lives in (js/cosmetics.js or js/gear.js), so the two are never blurred.

A cosmetic gated behind level 40 is legal precisely because it is a RECORD of reaching level 40 and changes nothing about play.

Ships (12)

Trails (10)

Keycaps (10)

Name plates (10)

Titles (14)

Every title is free: a title is a record of something, so charging for it would make it a purchase instead.

11. The Training Grounds#

The Training tab is two ladders stacked. The Academy on top teaches the keyboard; Flight School below it is the curriculum, which teaches speed. They are scored on deliberately different axes and neither gates the other.

11.1 The Academy#

"Slow is smooth, and smooth is fast."

Coverage and accuracy, never speed. A player who certifies the whole keyboard at 22 WPM has done exactly as well as one who did it at 90, because what is being measured is whether every key is under your fingers and whether you hit it correctly, which is the thing speed is built on top of later. There is no WPM, no latency and no time anywhere in js/academy.js. If you find yourself adding a speed term to that file, it belongs in js/skill.js.

Twenty one groups across four stages. The key pool is CUMULATIVE: a group's drill material may use its own new keys plus everything earlier in the ladder, which is why the drills turn into real words surprisingly early and why nothing already learned goes stale.

Drill material. Real words wherever the cumulative pool can spell them, because a beginner typing "dad" and "flask" is learning something a beginner typing "fjfj djdj" is not. Roughly half the items in a drill must contain one of the group's NEW keys, or a wide pool would quietly stop teaching the group it is named after. The earliest groups fall back to short alternating chunks, because there is no English word in "f j" alone. Nothing repeats twice in a row: a repeat reads as a stutter and stops testing the transition into the key.

Certification is judged from the SHARED per-key model, and that is what makes testing out honest:

The per-key floor is what "completeness" means: not "the group averaged 95" but "there is no key in here you are still missing". And the evidence is read out of state.keys rather than kept locally, so a key drilled in the arcade, or measured by the Flight Check, counts exactly as much as one drilled here.

That is the whole route a proficient typist takes. The placement seeds real per-key data, testOutCandidates() lists every group whose keys already clear the bar, and one clean drill certifies each. They are through in a few minutes and into the arcade, where their time is better spent.

A beginner walks the ladder, and groupStatus().blockers tells them in plain words what is still missing ("3 keys not practised enough", "q, p below 90%", "a drill at 95% or better"), because a beginner should never read a bare "not certified".

Nothing here is gated and graduation unlocks nothing. Every group is startable on the first visit, in any order. Certifying one is worth 300 XP, the largest flat award outside a boss. Graduating the whole keyboard is worth 3,000 XP, the largest flat award anywhere, because that is the one big number a slow typist can reach on their first evening. What graduation produces is a diploma(): recognition, a date and a duration. Not a key.

11.2 Flight School: the curriculum#

Twenty nodes in five groups, an ordered walk rather than a set of locks. Every node is playable from minute one; what the walk provides is an ORDER and a recommendation, which is a different service from a gate.

The signpost pace is not a gate and not what stars are measured against. Stars come from beating your own baseline (section 4.2). The goal number is there so the card can say what this material is usually comfortable at, and so the recommender can tell that a 110 WPM typist has no business being sent to the home row (OUTGROWN, 1.3x measured speed).

The two adaptive nodes are never skipped. Your Trouble Keys and Awkward Pairs build their material from the model, so their difficulty tracks whoever is typing: a 120 WPM typist still has a weakest key and a pair their fingers argue about, and drilling those is exactly what is left to do at that speed.

12. Flight Check: the sprint#

One surface doing three jobs.

12.1 The three jobs#

1. The sprint. A timed typing test, a quote, or a drill on your own weakest keys. It reports through finishRun() like every other game, and the two timed modes carry leaderboards.
2. The drill surface. Every Academy lesson and every curriculum node runs here. The Training Grounds hands it an explicit word list plus a meta tag, and that tag rides into the RunResult so the funnel scores the right thing. An Academy drill leads its results screen with accuracy and the per-key breakdown rather than a WPM number, because that is what it was judged on.
3. The placement. See section 4.5. It runs a 60 second sprint and then grants, seeds and reports, and it deliberately does NOT go through finishRun().

12.2 The modes#

Why the timed passage is NOT adaptive, when everything else on the site is: a board where each player typed material chosen for them is a board that compares nothing. So the timed modes and the placement all draw the same mixed passage of everyday words. Personal material lives in the Weak keys mode and in the Training Grounds, where nothing is ranked against anybody else.

Passage length for a timed run is sized at 22 characters per second, which is 264 WPM: comfortably past the fastest human on record, so nobody can reach the end of it.

12.3 Reading and the caret#

Three lines are visible and the caret rides the second one, so there is always a line of what is coming next below it. A fast typist reads ahead instead of typing into a wall.

A gap longer than 2,000 ms is treated as somebody answering the door rather than a slow reach, and is not folded into a key's mean latency.

13. Versus#

Head to head racing, for signed-in players with a claimed screen name.

13.1 Why Firestore and not the worker#

Everything else on this site talks to a Cloudflare Worker whose store is KV: eventually consistent, which is exactly right for a leaderboard and exactly wrong for a race. Two people typing against each other need each other's progress inside a few hundred milliseconds and they need it PUSHED. Firestore gives both, on the identity pool the site already authenticates against, so Versus costs no new service.

Four collections, no composite indexes: typePlayers (a presence card per account), typeLobbies (the room code IS the document id, so a shared link is a direct lookup), typeGames and typeChats.

13.2 The two formats#

Nobody referees. Both formats are built from a SEED in the game document and every client builds the identical race from it through mulberry32.

A threat's position is a pure function of the shared clock (spawn moment, descent rate) rather than something integrated frame by frame, so a phone that dropped ten frames is still looking at exactly the same sky as the laptop it is racing. A client that reloads mid-race meets everything that fell while it was away in one frame: those words really did land on its base, so they cost what they cost, but they are not drawn or sounded.

Each client grades itself, which is safe because there is nothing secret here: the word lists ship in js/words.js either way, so a server holding the answers would be guarding a door with no wall attached. What the design DOES guarantee is that nobody can write anybody else's numbers, and that is enforced by the Firestore rules (a seat is a key in a map and only its owner may touch it) rather than by good manners.

13.3 Race tuning#

13.4 What a race never touches#

Not the skill model, not the curriculum, not state.games, not the Academy, not History, not a solo leaderboard, and it does not go through finishRun() at all. A race is a different measurement (a shared seed, other people's pressure, nothing chosen by the player) and letting it feed the same numbers would quietly make two things one.

The only account-level trace is state.mp:

Four versus badges read that tally on the next completed SOLO run, and a win may post to the versus wins board if the player has opted into leaderboards.

13.5 The four reliability rules#

Each was a bug first on the sibling site, and every one is load bearing:

1. A listener's first snapshot comes from the local cache and can be a version behind (a transaction never lands locally), so nothing destructive may act on a snapshot until vsFresh() says the server confirmed it.
2. A dotted updateDoc CREATES the map it writes into, so every seat write goes through vsTouchSeat, a transaction that only writes a seat that still exists. Because that is a server read every fifteen seconds it doubles as the backstop for a wedged lobby listener.
3. Firestore's error callback is TERMINAL, so every long-lived listener is attached through vsWatch, which re-opens with backoff and never gives up on a connection error (only on a rules one). Everything re-opens at once on visibilitychange and online, because backoff measured against a sleeping clock is the wrong shape.
4. A result is banked exactly once per account, guarded by state.mp.banked and persisted.

14. The meta layer#

The loops below the run. Everything in js/run.js closes inside a single run; everything here is what makes tomorrow worth turning up for. Each piece is a named idea rather than decoration, and nothing in it is a lock: a contract you ignore costs you nothing, a broken streak takes nothing away that you already had, and ascension is opt-in.

14.1 Contracts#

The Zeigarnik effect: an unfinished, clearly stated task nags in a way an open-ended one does not. Three daily and one weekly, each a single sentence with a number in it, seeded from the date so everybody gets the same set with no server dealing them. The three dailies are drawn without replacement and never two that track the same thing, because three "type N characters" contracts is one contract wearing three hats.

Wave and combo contracts take the BEST single run rather than a sum, which is what the wording promises. A finished contract waits to be CLAIMED: collecting a reward you can see is worth more than one that lands silently, and the claim is the reason to open the panel tomorrow.

14.2 The streak#

Loss aversion, deliberately blunted. A streak that shatters after one missed day punishes exactly the person who was ill, and they do not come back.

The bonus flattens because a bonus that keeps growing turns a game into an obligation.

14.3 The comeback bonus#

The likeliest moment to lose somebody is the run after a long gap, so that run pays extra instead of showing them how much they missed. After 5 days away, the first completed run pays clamp(round(120 * min(days, 30) / 5), 120, 700) XP.

14.4 The Zone and ascension#

Covered in sections 7.7 and 4.7. Total time in the Zone accumulates in state.meta.zoneMsTotal and feeds the weekly Flow State contract.

15. Achievements#

Sixty two badges, each a single pure predicate over the state and the run that just finished. checkBadges() stamps state.badges itself, so a badge can never be granted twice, and badge XP lands on the ACCOUNT only, never on a game's own XP: a game rank is a measure of how much of that game you have played, not of how many account-wide milestones happened to fall while you were playing it.

Mileage

Levels

Speed

Accuracy

The arcade

Learning

Everything else

16. Leaderboards, accounts and identity#

16.1 The boards#

Nine boards, served by the shared Cloudflare Worker at /typing/board and /typing/score.

Strictly opt-in. Nothing is ever posted until the player ticks the box and picks a signature. A run must also be complete and plausible, and the worker holds that line independently.

Every post carries evidence: accuracy, correct characters, characters typed, duration, net WPM, and (when the game timed its keystrokes) the median gap between them, which is what tells a human hand from a script holding a key down. The one exception is the account level board, which is an account number rather than one run's work, so hanging a run's accuracy off it would put a meaningless percentage on the row.

One run can feed more than one board: a deep Starfall run is both a score and a survival record.

Never render un-escaped remote data. Every screen name goes through escapeHtml and every number through Number() before it is interpolated, because the worker is not the only thing that could answer that fetch.

16.2 One identity, three save files#

The same Firebase project authenticates Big World Quiz, Big Piano Quiz and Big Typing Quiz, so one account and one verified screen name work everywhere. Progress does NOT: this site syncs to its own collection.

Screen names come from the shared registry at /name on the worker, which is the source of truth. SN_NAME_RE and SN_RESERVED in js/state.js mirror the worker's rules and are mirrored a third time in big-piano-quiz; the worker will refuse anything they let slip.

Everything works signed out. Firebase is lazily imported on first use, the account area is hidden entirely when it is not configured, and a fully local profile loses nothing except cross-device sync and Versus.

17. Data model and persistence#

Everything the player owns lives in ONE localStorage blob under typingQuiz.v1, and the whole blob is what syncs to Firestore.

Three rules hold this together:

1. normalizeState() is the only source of shape guarantees. Any path that replaces state wholesale (boot, cloud adopt, clear all data) runs it, it is safe to run twice over the same object, and every new field is added there as well as in freshState().
2. saveState() is the ONE writer. It stamps updatedAt and pokes the cloud through a hook, so a mutation can never quietly skip the sync.
3. The blob has to stay small, because it syncs. That is why History, keys, bigrams and banked race ids are all capped.

Per-identity slots. A signed-in account stores under typingQuiz.v1:u:<uid>, so two people sharing a browser do not share a save file, and signing out returns you to the local one.

18. For developers#

18.1 The shape of the repo#

No build step, no bundler, no test suite, no package.json. The deployable output IS the repo root, served as-is by Cloudflare Pages. There is exactly one third-party dependency and it is committed rather than installed: Three.js and troika-three-text under vendor/, bound by an import map in app.html and loaded only by the arcade's 3D renderer, lazily.

The one thing that is generated rather than hand-written is bible.html, and it is committed too, so nothing has to be run before a deploy. Media lives under assets/ (art in assets/art/, the four music tracks in assets/music/) and none of it is load-bearing: both are skins over a game that plays without them.

Three pages, sharing one design language and no stylesheet:

The isolation is the point: a broken module cannot take down the landing page or the manual.

18.2 The module graph#

js/ is one module per concern, acyclic. js/app.js is the entry point: it imports every module, holds the router and init(), and wires the cross-module hooks. Nothing imports it back.

Because modules run in strict mode with their own scope, the few shared mutable bindings are reassigned through exported setters (setState, setCurrentStorageKey, setApplyingRemote, setCurrentTab), and the subsystem cycles are broken by hooks that app.js wires at init():

18.3 The invariants#

These are the ones an edit breaks by accident. Each is stated as the thing that must remain true.

1. finishRun() is the one funnel. It is the only writer of XP, chips, cores, the skill model, badges, gear grants, per-game bests, History, contracts and leaderboard submissions. If a game needs a reward it does not grant, add it there.
2. Only complete runs count. abandonRun() is the single exception and it takes ONLY the keystrokes.
3. normalizeState() owns the state shape, and saveState() is the one writer.
4. #kbCatch is persistent and must never be rebuilt or re-parented. A phone raises its keyboard only for a focused input.
5. Nothing is ever gated.
6. The skill model is the only thing that decides word tiers.
7. The Academy never scores speed.
8. The placement and the Academy head start only ever RAISE.
9. Gear must never multiply XP.
10. Every strong gear item keeps a downside.
11. Cores come from bosses and mini-bosses and nowhere else.
12. The events ledger counts characters PER ENCOUNTER.
13. Loot rolls only on CLEARED encounters.
14. Cosmetics never affect gameplay.
15. The seeded PRNG is what lets Versus work without a referee. Introducing a bare Math.random into a seeded path silently desynchronises a race.
16. Never render un-escaped user data. The rule is about the PATH a string takes, not about who wrote it, so authored catalogue strings go through escapeHtml too.
17. _headers names every origin the page may reach. A new external dependency is two edits, not one.
18. Sound effects are synthesized, music is streamed, and the line between them is the point. Every effect is made at runtime in js/audio.js on one compressor bus, created on the first user gesture and never at import time, because a typing game fires a sound on every keystroke and a decoded buffer per hit would stall exactly the sound that must never stall. The four music tracks are real files, fetched only once music is on and a scene is set. Do not add an audio FILE for anything that fires from a keydown handler.
19. The Google Fonts stylesheets must stay async. A pending cross-origin stylesheet blocks script execution, and this has shipped as a bug on a sibling site where it read as "every link is broken".
20. A renderer reads the run and never writes to it, and the flat view may not be deleted: it is the default, the no-WebGL path and the context-lost path all at once.
21. The art is a skin, never a requirement. Every sprite call is gated on spriteOk() with the hand-drawn shape behind it, and the game must play identically with assets/art/ deleted.
22. vendor/ is pinned, version in the directory name, and an upgrade is its own deliberate commit.
23. The registry is the only list of what games exist.

18.4 How to add things#

A new mini-game. Write a module under js/games/ exporting meta, start(host, opts), stop() and ideally isRunning() and snapshot(). Add one entry to js/games/registry.js. Report the result through finishRun(). Nothing about the panel, the router or the scoring funnel changes. A soon entry is an announcement and must read as one.

A new sprite. Drop the file under assets/art/ in the directory its prefix implies and it resolves through artPath() with no code change; a key that needs a different home goes in the SPECIAL map in js/art.js. Draw it through sprite()/spriteOk(), never through a raw Image, and leave the vector shape behind it working. ART_DIRECTION.md states what it has to look like.

A new threat. One entry in KINDS in js/games/starfall.js (radius, damage, word length range, kill score, spawn weight, first wave, and any of the weak, splits or drops behaviour flags). If it needs a behaviour none of those cover, add the flag next to them rather than branching on the id in the step loop.

A new gear item. One entry in GEAR in js/gear.js with slot, cost or cores, an optional req, and stats as deltas from BASE_STATS. Give it a downside, or tools/check-modules.mjs is entitled to fail. If it needs a stat that does not exist, add it to BASE_STATS, give it a clamp in loadoutStats(), a weight in POWER_WEIGHTS, and one use in the game.

A new event or boss. One entry in EVENTS, MINI_BOSSES or BOSSES in js/games/events.js, plus its lines in TRANSMISSIONS or MINI_LINES. A boss needs a profile from PROFILES and a brief explaining the counter-pick, because the pre-flight screen shows both. Never read Math.random in that file.

A new badge. One row in BADGES in js/achievements.js: an id, a name, a description, an XP value and a pure predicate. It is stamped automatically and can never be granted twice.

A new word tier. One entry in TIERS in js/words.js whose words stay strictly inside the tier's own chars, plus its place in TIER_ORDER. tools/check-modules.mjs asserts every tier the curriculum names exists.

18.5 Verifying a change#

Serve the repo over http (the file protocol will not do: a browser refuses a module script from an opaque origin) and drive it with Playwright against the pre-installed Chromium. Two checkers stand in for a test suite, and both exit non-zero on the first failure:

Module bindings are not global, so page.evaluate(() => state) cannot reach them. Two doors exist instead: window.BTQ in js/app.js is the deliberate test seam (state(), finishRun, switchTab, openFlightCheck, games, nodes, skill(), level(), cloud(), probe3d()), read by nothing in the app, and localStorage.getItem('typingQuiz.v1') is the persistence path.

A 3D frame needs a different kind of check. A scene whose shader will not compile, whose camera is aimed at nothing, or whose material is fully transparent throws nothing and logs nothing, and renderer.info still cheerfully counts the draw calls it made for triangles nobody can see. So the renderer reads its own pixels back and the checker asserts that objects were actually drawn. Do not replace that with an assertion about draw calls: draw calls are exactly the thing that lies.

18.6 Deploying, and the build stamp#

Two deployables, and only one of them is in this repo:

Adding or changing a /typing/* endpoint is a commit in that other repo. Neither deploy implies the other is live.

Two files in the repo root are read by Cloudflare Pages rather than by a browser, and neither is reproduced by a plain local serve, so both have to be tested by deploying them or by serving with an equivalent handler:

Every deploy is stamped. All three pages carry a short content hash in the footer, written by node tools/stamp.mjs and visible as plain text (no JavaScript involved, so it still reads when the JavaScript is the broken thing). It is a hash of the DEPLOYABLE OUTPUT rather than a git commit, because a stamp recording the current commit cannot be committed: writing it changes the tree, which changes the commit.

Before committing:

node tools/build-bible.mjs     # if GAME_BIBLE.md changed
node tools/stamp.mjs           # always
node tools/check-modules.mjs
python3 tools/check-app.py

Both checkers fail on a stale stamp, deliberately: a stamp somebody forgot to regenerate is worse than none at all, because it states confidently that a stale deploy is fresh.

18.7 This document's own pipeline#

GAME_BIBLE.md is the source. tools/build-bible.mjs renders it into bible.html, which is committed like everything else, so the site still has no build step at serve time. The generator owns the page shell, the contents sidebar and the anchors; css/bible.css and js/bible.js own the look and the search. node tools/build-bible.mjs --check exits non-zero when the page is out of date with the markdown, and tools/check-modules.mjs runs that check so a stale page cannot ship quietly, exactly as with the stamp.

19. Balance reference#

Quick answers to the questions balance arguments actually start with.

19.1 How long does a level take?#

Assuming continuous play at the stated pace and 95% accuracy, pace XP only (no flat bonuses, no events, no gambits):

In practice a beginner reaches level 10 far faster than that table suggests, because flat bonuses dominate their early runs: a first run, a first day, a first node clear, a first Academy certification and a couple of wave milestones is over 1,000 XP before any pace XP is counted, and level 10 costs 3,508.

That gap is the design working. Read the two columns together: the expert's XP is almost all pace, the beginner's is almost all flat, and neither is being paid for something they did not do.

19.2 What does the placement save?#

A 100 WPM typist is placed at level 22, which is 20,398 XP, which is about 65 minutes of continuous play at their own pace. A 130 WPM typist is placed at level 30, which is 41,115 XP, or about 70 minutes at theirs. That is the whole argument for the Flight Check existing: without it, the first hour of an expert's time is spent re-proving something one minute already proved.

19.3 Does gear out-earn skill?#

No, and the margin is deliberately enormous.

tools/check-modules.mjs asserts that the skill ratio between 120 WPM and 40 WPM is more than three times the best gear multiplier, and it is: 4.4x against 1.45x.

19.4 How much does accuracy cost?#

Two separate penalties, applied in different currencies:

20. Glossary#

21. Constants appendix#

Every tuning number, with the file that owns it. If a value here disagrees with the code, the code is right.

Progression, js/xp.js

The run funnel, js/run.js

The arcade, js/games/starfall.js

Encounters, js/games/events.js

Gear, js/gear.js

Salvage, js/loot.js

The meta layer, js/meta.js

The Academy, js/academy.js

The skill model, js/skill.js

Versus, js/versus.js

Presentation, js/art.js, js/music.js and js/state.js

State, js/state.js