#Cascade / Tumble — Presentation Module

Optional module for slot-presentation-flow-template.md. The server supplies the ordered cascade steps. The client may animate grid_before → grid_after, but must not detect winners, generate refills or calculate payout. Every unique phase below must link to a Visual Ref ID defined by the base template.

#1. Feature flow

flowchart TD
    A["Initial authoritative grid"] --> B["Read next tumble step"]
    B --> C["Show grid_before"]
    C --> D["Highlight authoritative wins/modifiers"]
    D --> E["Present step award"]
    E --> F["Remove authoritative vacated cells"]
    F --> G["Collapse survivors"]
    G --> H["Refill to exact grid_after"]
    H --> I{"Another authoritative step?"}
    I -- "Yes" --> B
    I -- "No" --> J["Terminal grid hold"]
    J --> K["Aggregate Total / Big Win"]
    K --> L["Bonus handover or Ready"]

#2. Wire-contract placeholders

[GAME TODO] Ordered step field:
[GAME TODO] grid_before field and orientation:
[GAME TODO] grid_after field and orientation:
[GAME TODO] wins/cell-addressing scheme:
[GAME TODO] removed/vacated cell field:
[GAME TODO] modifier/charge field:
[GAME TODO] step payout/pre-multiplier payout:
[GAME TODO] aggregate multiplier and total payout fields:
[GAME TODO] terminal-step representation:
[GAME TODO] final spin.grid relation to last grid_after:
[GAME TODO] Visual refs for win, modifier, remove, collapse, refill and terminal settle:

#3. Phase sheet

#4. Step invariants

• Steps are consumed in server order and exactly once.
• grid_before must match the currently displayed board before the step begins.
• grid_after is the only allowed target after removal/collapse/refill.
• Cell identity uses explicit row/reel coordinates or a documented index conversion; array order is never a binding contract.
• The client does not call local winner detection or RNG to fill holes.
• Every nonterminal step that vacates cells reaches a complete grid_after before the next step.
• A terminal step may contain wins/modifiers only if the backend contract explicitly defines how it settles them.

#5. Wins, modifiers and payout

• Highlight only authoritative wins from that step.
• Present step payout using the correct unit; do not add it to wallet locally.
• Modifier values come from receipts such as charges[], never from symbol IDs or visual labels.
• A modifier may affect aggregate payout without creating another cascade. The game-specific contract must say whether it is removed, remains visible, or is presentation-only on terminal step.
• Total Win and Big Win tiers use the authoritative final round payout, not a client sum of steps.

#6. Terminal-step rules

[GAME TODO] What makes a step terminal?
[GAME TODO] Can terminal grid_before differ from grid_after?
[GAME TODO] Can a terminal modifier be collected without causing refill?
[GAME TODO] Are empty cells ever legal? Default: no.
[GAME TODO] Does final spin.grid equal terminal grid_after?

Default presentation rule: if the terminal step has no removal/refill, show grid_before == grid_after, hold the final board and proceed to total. Never animate a fake drop merely because a modifier is visible.

#7. Cascade inside Free Spins

• Each Free Spin owns its own ordered cascade sequence and aggregate payout.
• Complete the current cascade before decrementing/advancing the visible FS counter.
• Retrigger presentation occurs at the exact step/round boundary declared by receipts.
• Modifiers do not carry to the next Free Spin unless durable feature state explicitly says so.
• Bonus outro waits until the last FS cascade and its total presentation are finalized.

#8. Skip, cancellation and failure

• First skip may accelerate the current step; full fast-forward may finalize all remaining steps as defined by the game-specific design.
• Finalize applies the last authoritative grid and total synchronously.
• A timed-out animation cannot later overwrite a finalized or newer board; use a generation/token guard in runtime implementation.
• On mismatch between displayed board and grid_before, stop presentation and reconcile; do not guess a collapse path.
• Required failure parks/reconciles the round and keeps paid Spin disabled.

#9. Deterministic DEV scenarios

• No-win, zero-step spin.
• One winning step then terminal.
• Two or more cascade steps.
• Multiple holes in one column and across columns.
• Modifier collected on a winning step.
• Terminal modifier with no new cascade, if supported.
• Cascade that triggers/retriggers a feature.
• Big Win reached across multiple steps.
• Reconnect between remove/collapse/refill presentation phases.
• Skip/cancel during every required phase.