#Magic Vault 5×3 — Presentation and Game Flow

draft-v0.1 — DEV ONLY. NOT FOR PRODUCTION. NOT FOR CERTIFICATION.

This document defines presentation order, animation concurrency, skip behavior, speed modes, audio cues, recovery and visual hierarchy. It does not change the mathematics, payout evaluation, RNG, wallet behavior or the authoritative backend lifecycle described by the GDD and Math Spec.

Implementation is split into a prioritized frontend backlog in magic-vault-5x3-frontend-backlog.md.

#1. Design principles

• The game is fast by default; no presentation exists only to delay the next action.
• Backend grid, wins, payout, balance and feature state are authoritative.
• Presentation reveals a known result in phases but never calculates or changes it.
• Skip completes the current presentation phase; it never skips a backend step.
• An active feature settles before another paid spin can begin.
• Important state remains readable in Normal, Fast, Turbo, reduced-motion and low-performance modes.
• At any moment there is one primary visual idea. Parallel effects support that idea instead of competing with it.

#2. Phase machine

BOOT
  → SESSION_BOOTSTRAP
  → RECOVERY_CHECK
  → IDLE
  → SPIN_REQUEST
  → REELS_SPINNING
  → ANTICIPATION?
  → REELS_STOPPING
  → RESULT_REVEAL
      ├─ NO_WIN
      ├─ LINE_WIN
      ├─ WIN_TIER
      └─ FEATURE_TRIGGER
  → FEATURE_TRANSITION?
  → FEATURE_STEP_LOOP?
  → FEATURE_SETTLEMENT?
  → BALANCE_SETTLEMENT
  → IDLE

The phase machine owns order. Independent animation tracks may run concurrently inside a phase:

#3. Speed modes

The three modes share identical state transitions. Only timings and secondary-effect density vary.

Turbo retains every important effect: reel stops, anticipation, triggering COIN, newly landed prizes, respin changes and final settlement remain visible, only shorter.

#4. Global skip contract

One tap or click completes the current presentation phase:

Skip never cancels a request, creates a new wager, hides a newly landed prize, advances a feature without a server response, changes payout or closes a feature before authoritative settlement. There is no whole-feature skip in Draft v0.1. A player may accelerate each individual step.

#5. Boot and recovery

BOOT
  → LOAD ASSETS
  → CREATE OR REUSE DEMO SESSION
  → READ RECOVERY CHECKPOINT
      ├─ open feature → RESTORE FEATURE
      └─ none → IDLE

Asset loading, session bootstrap, audio preparation and recovery storage read may run in parallel. Spin is enabled only after session and recovery checks finish.

If a Hold & Win checkpoint exists, the frontend replays the exact recorded request, hydrates the authoritative snapshot and enters the bonus screen without replaying the full trigger introduction. Use a short board pulse or FEATURE RESTORED message. Old coin prize reveals and settlement sounds must not replay.

#6. Idle

• Reels are sharp and stationary.
• Spin and Bet controls are enabled.
• The last authoritative Balance and Win remain visible.
• Background particles and symbol idles are subtle.
• WILD may carry a weak magical shimmer.
• COIN may receive an occasional metallic glint, not a constant trigger-like pulse.

#7. Starting a paid spin

Within the first 80 ms after Spin:

• lock Spin and Bet controls;
• clear old paylines and result effects;
• reset the visible Win meter;
• create one new Idempotency-Key;
• freeze and send the backend request;
• start reel acceleration without waiting for the response.

Reel acceleration, HUD lock, previous-result cleanup, API request and spin audio run in parallel. Each reel begins 30–50 ms after the preceding reel. Symbols squash briefly before acceleration, then become unreadable under vertical motion blur.

The reels observe a minimum spin time. If the response is delayed, they remain in a neutral loop; the frontend never invents stop positions.

#8. Reel stopping

After the authoritative response is validated, reels stop from left to right. Each stop combines:

• blur removal;
• a small overshoot and return bounce;
• symbol landing squash/stretch;
• a reel-stop tick;
• a short reel-frame light;
• a metallic accent for COIN;
• a magical accent for WILD.

The final reel has a slightly stronger mechanical impact. Reel animation, stop sound, symbol landing and frame light run in parallel.

#9. Hold & Win anticipation

Anticipation begins when the first four stopped reels show at least five COIN and the final reel can provide the sixth.

In parallel:

• slow the final reel;
• dim stopped non-COIN symbols by about 20%;
• scale visible COIN to 105–108% with a synchronized pulse;
• illuminate the vault frame;
• draw background particles toward the board;
• raise an audio riser.

On a miss, release the riser softly and remove the glow within 150–250 ms. Do not play a punitive failure sound. On a trigger, resolve the riser into the feature sting and flash every triggering COIN. Turbo uses the same signals compressed to 250–350 ms.

#10. Base result presentation

#10.1 No win

Hold the final grid for approximately 250 ms, restore idle brightness, show WIN 0 and unlock the controls. Never show a negative LOSE animation.

#10.2 Line win

Line Win presentation exists only for the base game.

First show every winning line together:

• keep winning symbols fully lit;
• dim other symbols to 40–50%;
• trace all winning paylines from left to right;
• pulse winning symbols once;
• count the authoritative round payout into the Win meter;
• play a short win chord.

Then cycle through individual lines, showing the line number and its display amount. This cycle is informational and never changes Total Win. Turbo may omit the individual cycle. Skip completes the count-up, shows the final Total Win and holds all winning symbols for 300–400 ms.

#10.3 Line win and feature trigger together

1. Stop every reel.
2. Present the base line payout briefly.
3. Fix the base amount in the Win meter.
4. Fade the paylines.
5. Bring triggering COIN forward.
6. Begin the feature transition.

The base presentation is capped at 700–900 ms in Normal, 400–550 ms in Fast and 200–300 ms in Turbo. The base win remains visible, but the feature receives the stronger emphasis.

#11. Win tiers

Presentation tiers use the complete round win divided by total bet:

These are presentation thresholds, not new payouts. The authoritative payout remains unchanged.

#Big Win

Dim the reels slightly, pulse the source symbols, emit restrained gold particles, push the camera in lightly and count quickly to the final amount. Target duration: 1.8–2.2 s Normal, 1.1–1.4 s Fast, 650–850 ms Turbo.

#Mega Win

Add a translucent overlay, radial burst, foreground coins and a stronger chord while keeping the result grid visible. Target duration: 2.5–3.0 s Normal, 1.5–1.9 s Fast, 850–1100 ms Turbo.

#Ultra Win

Use two impacts—tier title and final amount—plus a light ring, short fanfare and controlled camera movement. Target duration: 3.2–3.8 s Normal, 1.9–2.3 s Fast, 1.1–1.35 s Turbo.

#Epic Win

Use a 100–150 ms dim, a strong central burst, two-stage title, layered coins and crystals, one short camera impact and a final amount hold. Target duration: 4.0–4.8 s Normal, 2.3–2.8 s Fast, 1.3–1.6 s Turbo.

#Max Win / Grand

Grand is a dedicated ending, not merely a longer Epic presentation. Pulse all 15 cells, illuminate the vault, show GRAND, transition to MAX WIN, fix the amount at 500× and finish with a controlled coin shower. Target duration: 5–6 s Normal, 3–3.5 s Fast, 1.8–2.2 s Turbo.

After Skip, retain the final title for at least 350 ms Big, 400 ms Mega, 450 ms Ultra, 500 ms Epic and 700 ms Max/Grand.

#12. Hold & Win trigger and transition

After base presentation:

1. Dim non-COIN symbols.
2. Flash all triggering COIN together.
3. Illuminate the board in the bonus palette.
4. Play the trigger sting and briefly show HOLD & WIN.
5. Lift triggering COIN above the reel-symbol layer.
6. Apply the backend-provided prize overlays.
7. Crossfade to bonus-background.png.
8. Replace base controls with the feature HUD and show RESPINS 3.

Background crossfade, frame illumination, COIN lift, title, HUD switch and audio may overlap. Prize values reveal in cell-index order with a short stagger: 70–90 ms Normal, 40–55 ms Fast and 20–30 ms Turbo. Skip reveals every prize immediately and retains the complete locked grid for at least 300 ms.

#13. Hold & Win step loop

Before each step, send the documented expected step index. There is no additional wager. Locked cells remain fixed while only empty cells spin. The request, empty-cell spin, locked-cell idle and feature ambience run in parallel.

Empty cells use a lighter vertical motion than the base reels. Turbo retains a minimum 250–350 ms spin so a landing does not look like teleportation.

#13.1 Miss

• stop empty cells into their empty state;
• play a neutral cue;
• pulse locked coins weakly;
• animate the respin counter down by one;
• reduce frame brightness slightly.

Do not use a red flash or failure buzzer. On 1 → 0, hold for 250–400 ms before settlement.

#13.2 One new COIN

In order:

1. stop the coin in its authoritative cell;
2. apply landing squash and a local impact ring;
3. reveal its backend-provided prize;
4. move it to locked idle;
5. reset the counter to 3.

Landing, ring, prize reveal, reset animation, metallic impact and a brief background brightness bump may overlap.

#13.3 Multiple new COIN

Stop every new coin together, then reveal prizes with a short cell-index stagger. Use a group impact plus light individual accents rather than stacking identical full-volume sounds.

#13.4 Fixed prize landing

• Mini 10×: short turquoise ring and local label.
• Minor 25×: violet burst, 250–350 ms cell focus and local label.
• Major 100×: gold impact, short board pause, cell zoom and unique sting.

Skip still shows the final locked prize. Major retains its label for at least 450 ms.

#13.5 Last respin

At one remaining respin, enlarge and pulse the counter, brighten empty cells and synchronize a short tension pulse with the frame. Do not alter the mathematical duration or create fake near misses. Turbo retains a compressed version.

#14. Hold & Win settlement

#14.1 Ordinary settlement

Keep every locked coin visible. Pulse prize values and move collection trails from groups of coins into Feature Win. Use 3–4 waves Normal, two Fast and one Turbo. Count to the authoritative award, then apply the appropriate win-tier presentation.

The visible feature meter before settlement is informational. It never modifies wallet state. Balance changes only from the authoritative settlement response.

#14.2 Full grid

When all 15 cells are locked:

1. stop all empty-cell motion;
2. pulse the complete grid;
3. dim individual values slightly;
4. connect the grid with gold lines;
5. close the frame like a vault;
6. show GRAND 500×;
7. continue to Max Win presentation.

Grand replaces the sum of individual coin prizes. Never display or calculate coin sum + 500×.

#14.3 Return to base

After authoritative settlement, clear the recovery checkpoint, crossfade to the base background, dissolve the locked overlay, restore reel symbols and controls, copy the server Balance into the HUD and retain the final Win. Autoplay may continue after 500–700 ms Normal, 300–450 ms Fast or 180–250 ms Turbo.

#15. Controls and autoplay

Paid autoplay pauses while a feature is active. Feature steps may proceed automatically after their minimum presentation hold, but every backend step is still executed and shown. Paid autoplay resumes only after authoritative settlement.

Stop autoplay on insufficient balance, session expiry, unresolved recovery, idempotency conflict, unsupported feature, state conflict, Max Win or explicit player stop. Mega, Ultra and Epic may pause autoplay until their presentation completes; Max always pauses it.

#16. Network and error flow

#16.1 Delayed response

Keep reels or empty cells in a neutral loop. After approximately three seconds, show a subtle WAITING FOR SERVER. Do not update the respin counter, Balance or result before the response.

#16.2 Ambiguous paid spin

Replay the exact frozen request with the same Idempotency-Key. On successful replay, continue from result reveal without restarting the paid-spin anticipation. On conflict, stop autoplay and the scenario queue. Never generate a replacement key for the ambiguous operation.

#16.3 Feature-step timeout

Keep locked cells visible, show RESTORING FEATURE, replay the exact step-index request and hydrate the returned snapshot. Do not animate the same landed coin or settlement twice.

#16.4 Error presentation

Never expose SQL constraints, internal sequence IDs, bearer tokens, storage implementation, stack traces or raw backend diagnostics in player-facing UI.

#17. Audio direction

• Base ambience is a restrained magical-vault hum.
• Reel stop pitch rises slightly from reel 1 to reel 5.
• COIN and WILD accents layer over, rather than replace, reel-stop ticks.
• Anticipation uses a pulse-synchronized riser and resolves cleanly on miss or trigger.
• Hold & Win uses a lighter empty-cell spin, metallic landings, ascending reset cue, neutral miss cue, last-respin pulse and collection rhythm.
• Mini, Minor, Major and Grand have distinct signatures.
• Important stings duck ambience by 25–40%.
• Turbo uses deliberately shorter samples rather than cutting longer samples abruptly.

#18. Visual hierarchy and camera

Use local impacts for single COIN, weak board shake for multiple landings, a short zoom for Major, controlled push-ins for upper win tiers and one stronger impact for Max Win. Never use continuous screen shake.

Particles have three layers: behind-reel ambience, board-local effects and foreground celebration. They must not cover prize values, respin counter, Total Win, controls or errors.

#19. Accessibility and performance

Reduced-motion mode removes camera shake and strong zoom, reduces particles and replaces bounce with opacity/scale transitions. It retains highlights, counters, prizes and state changes.

When performance degrades, reduce in this order:

1. foreground particles;
2. ambient particles;
3. blur filters;
4. complex glow.

Never remove reel motion, locked cells, prize values, respin state or authoritative settlement. Even in Turbo/low-performance mode every stop, trigger, newly landed coin and final payout remains readable.

#20. Master happy path

BOOT
→ SESSION READY
→ IDLE
→ PAID SPIN
→ REELS
→ STOPS
→ LINE WIN?
→ BIG / MEGA / ULTRA / EPIC?
→ HOLD & WIN TRIGGER?
    → INTRO
    → INITIAL COINS + PRIZES
    → RESPIN STEP
       ├─ MISS → RESPINS -1
       ├─ LAND → LOCK + PRIZE + RESET 3
       ├─ FULL GRID → GRAND 500×
       └─ RESPINS 0 → SETTLEMENT
    → FEATURE WIN
    → WIN TIER
    → RETURN TO BASE
→ BALANCE SETTLED
→ IDLE / NEXT AUTOPLAY SPIN

#21. Non-negotiable invariants

• The backend supplies every grid, win, payout, balance and feature state.
• One new paid spin uses one new Idempotency-Key; replay uses the same key and frozen request.
• Hold & Win steps have no additional wager.
• Skip changes presentation time only.
• Full Grid pays exactly Grand 500×, replacing the prize sum.
• Line Win presentation appears only in the base game.
• An active feature settles before the next paid spin.
• Speed mode never changes state order or mathematics.