tgame/docs/13-reveal-choreography.md

Reveal Choreography

The card-flip moment after a craft (and other reward reveals) is the highest-leverage dopamine in the game. Designed around one principle:

Length scales with magnitude. Buildup is the signal, not manufactured suspense.

Players learn the visual/audio language quickly ("oh, it's spinning, that's at least Fine") and never get baited-and-disappointed. Reference: Vampire Survivors chest opens — simple, honest, scales gracefully with the actual reward.

Anti-pattern we're avoiding

The slot-machine pattern: long buildup → suspenseful flourish → common item flops → player feels cheated. We're doing the opposite — a Common item gets a quick honest reveal so the player isn't promised more than they're getting. The reveal is the result, not a teaser for one.

The five band tiers

Crude

• Card sits on the station, faint dust puff
• Single quick flip
• Lands face-up with a soft thud
• Brief result text, no glow, no particles
• Total: ~0.5s. Sound: soft thump

Common

• Card on station, slight tremble
• One flip with a satisfying crunch
• Settles with a small wobble
• Subtle highlight on the quality border
• Total: ~0.8s. Sound: hammer-crunch

Fine

• Card on station, harder tremble
• Silver shimmer along the edges
• Two flips, metallic ring on the second
• "Fine" ribbon appears with a small particle burst
• Total: ~1.5s. Sound: hammer + chime

Masterwork

• Card vibrates with a low resonant hum
• Golden glow brightens, particles begin drifting up
• Three rotations, increasing speed
• Lands with a metallic clang
• Burst of golden particles, "Masterwork" ribbon flies in
• Holographic foil shader kicks in and stays
• Total: ~2.5s. Sound: hum → rising chime → clang → soft choir flourish

Legendary

• Screen subtly darkens around the card
• Low rumble, vibration intensifies
• Radiant white-gold light pillars from underneath
• Multiple rotations (5+) with motion blur
• Time briefly slows (~0.7×) for the apex — reserved exclusively for Legendary
• Bursts in a flare of radiant light, screen flash
• "Legendary" ribbon arrives with a deeper sound
• Bespoke hand-finished art piece revealed (Legendaries get the bespoke treatment per 07-item-cards.md)
• Holo foil + ambient glow + drifting particles continue after settle
• Total: ~4–5s. Sound: rumble → slow rising swell → crack of light → choir + organ swell

Special cases

Critical success (band promotion mid-reveal)

The choreography starts at the expected band, then mid-flip kicks up to the next band:

• A "wait — no" beat: particles intensify, light shifts
• Reveal upgrades to one band higher than expected
• "Critical Success!" ribbon arrives with the upgraded reveal sequence
• Player thought Common, got Fine. Player thought Fine, got Masterwork. Best feeling in the game after Legendary itself.

Critical success can be earned two ways: lucky engineer rolls, or hitting both Master's Touch meters perfectly (16-engagement-layers.md). Same choreography either way, different earnings paths. The forced crit in onboarding (12-onboarding.md) is the player's first encounter with this moment — earned by their meter timing on impossibly forgiving meters.

New Discovery (recipe unlock, parallel layer)

Stacks on top of the quality reveal — runs concurrent on a separate channel:

• Card flutters before settling
• Scroll/parchment animation overlays
• "New Discovery!" ribbon
• Recipe added to book with a whoosh + book-shut sound
• ~3s

Design principles

• Length scales with reward magnitude. This is the signal. Eliminates the disappointment problem.
• Honesty over manufactured suspense. No fake-outs. A Common reveal doesn't pretend to be a Legendary.
• Audio carries equal weight to visual. Each band has an audio signature players learn quickly.
• Time slowing is reserved for Legendary. Rarest cue for the rarest moment. Don't dilute by using elsewhere.
• Skippable after the first. Long-press skips to end-state after ~0.5s. The first of each tier the player ever sees shouldn't be skippable; every subsequent one should be. Veteran players' time matters.
• Bespoke Legendary art revealed at the apex. Hand-finished one-of-a-kind art is part of why Legendary is Legendary.

Implementation sketch

Choreography is a state machine layered on top of the static card composition system. On craft result:

1. Receive result {quality_band, was_critical, was_discovery, components, maker, ...}
2. Pick choreography preset by band (or one band lower if was_critical=true)
3. Run sequence: tremble → buildup → flips/spins → reveal → settle
4. Audio + particles + shaders sync to sequence beats
5. If was_critical, mid-sequence break to the upgraded preset
6. If was_discovery, fire the parallel discovery overlay
7. On settle, card slides into the vault

Performance:

• Single focused card, full shader stack is fine
• Particles cheap (small counts, short-lived)
• Time-slow via tween scaling, not actual game time
• Choreography assets (audio clips, particle definitions, shader configs) preloaded per session

Same framework, other reveals

The pattern extends to other reward moments — same toolkit, different presets:

Reveal moment	Preset analog
Expedition return — small haul	Common-tier choreography
Expedition return — rare drop	Masterwork-tier swell
Expedition return — Legendary relic	Full apex treatment
New applicant — common	Quick portrait fade-in
New applicant — rare trait or class	Fine/Masterwork-tier flourish
Patron reward payment	Scales with payout magnitude
Guild Rank up	Apex variant — meta-progression milestone

Each variant reuses the same shader / particle / audio toolkit; just different sequence presets.

Open questions

• Skip-after-first per tier vs. per session vs. per install — when does the "first time" lock release?
• Do we play screen flash on Legendary reveals, or is that too aggressive on mobile? (Accessibility: photosensitivity opt-out should exist regardless.)
• Do crit-promotion sequences happen visibly on the way up the band ladder, or do we shortcut straight to the upgraded band's preset?
• Audio mixing — does music duck during reveals so the choreography sounds occupy full headroom?
• Haptic feedback (vibration patterns per band) — yes for Masterwork+, none for Common/Crude?