# 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](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](16-engagement-layers.md)). Same choreography either way, different earnings paths. The forced crit in onboarding ([12-onboarding.md](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?