Gamble and collection

A gamble risks an existing win. Collection takes the available win when the engine permits it. Both actions belong to the current round.

Available actions

Read engineData.canCollect, playerChoice, inProgress, and the configuration's wager lists. A positive totalWin alone does not permit collection or gambling.

Apply gameSettings.gambleEnabled to elective slot gambles. If gambling is disabled, keep collection available. Do not automatically select a gamble to finish the round.

A mandatory bonus choice can also use playerChoice. Classify feature options against wagerFeatures and wagerStakeFeatures. Preserve cash awards and other mandatory choices.

Keep each option's original array index when hiding disallowed actions. Submit that original playerChoiceIndex, without a new stake or featureToBuy.

Two wager models

Model	Meaning
wagerFeatures	The selected outcome multiplies the currently at-risk win.
wagerStakeFeatures	The selected outcome specifies an absolute cashout multiplier of the original base stake.

The second model supports longer progressions such as Mines, Frogger, and Progressive. Their ordinary progression is a vertical-specific action. Do not assume the slot gamble permission disables the whole game.

The engine decides eligibility using configured win limits and current state. minWagerableWin and maxWagerableWin are authoring amounts subject to currency conversion in engine checks. Use the offered actions instead of calculating eligibility from those fields alone.

Built-in card gamble

Current engines synthesize card gamble when configured. They offer card_red, card_black, card_hearts, card_diamonds, card_clubs, and card_spades.

A fair 52-card draw determines the result. A correct colour pays 2× the at-risk win. A correct suit pays 4×. A miss loses the at-risk amount. Previously banked money remains protected.

The returned scenario contains suit and rank. Render that card. Do not draw a local random card. Older custom wager tables can use other feature names and scenario contracts.

After card entry, the engine can restrict later choices to the card family. Read the new options every time. Do not offer a cached ladder choice.

Ladder gamble

Read config.ladderMultipliers and config.ladderLives. Read current state from engineData.ladderState:

interface ILadderState {
  baseWin: number;             // Win multiplier captured at ladder entry.
  currentRungIndex: number;
  lives: number;
  previousRungIndex?: number;
}

The ladder choice advances one server step. Render the returned rung and lives. Rung payouts refer to baseWin and the original base stake. Do not multiply each new rung by the previous payout.

Reaching the top can auto-collect. A bust can also close the round while paying protected money. Inspect the returned flags and balance. Do not call collect again after automatic closure.

Full collection

When canCollect is true, call collect({ backendURL, token }). Omit amount to collect the full available sum.

Check the response. amountCredited is the amount credited when present. Replace the balance with the returned balance. amountToCollect in a collect reply is not a reliable new remainder; it can echo the requested amount.

Current replies can include result and gameRoundInfo. Use them to determine whether the round stays open. A collect reply can contain a compressed scenario. After reply.success, call decodeScenario(reply.result.result, config) when that result exists.

Bank part of a win

Gate this function with partialCollectEnabled. Explain it as protecting part of the win inside the round, not paying it immediately.

base stake = 100
outstanding win = 1000
bank request = collect({ amount: 500 })
returned bankedWin = 5
immediate wallet credit = none
outstanding win still includes the protected 500

engineData.bankedWin is a multiplier. Multiply it by engineData.baseStake for display. The remaining at-risk amount excludes that protected portion.

A later partial request adds to the protected amount. The engine rounds the protected multiplier down to two decimal places. Display the returned value, not your requested value.

Reject a partial amount that rounds to a zero multiplier. The engine credits only that small amount, stamps inProgress: false and canCollect: false on the reply, and leaves the rest of the win outstanding. Your frontend then shows a settled round while the RGS round is still open. Reject an amount that would protect the entire remaining win: that takes the full-collect path. Offer explicit full collection without amount instead. Offer explicit full collection without amount instead. The slot controller checks both cases.

Do not add the banked amount to balance. Do not subtract it from the amount sent for final collection. For final collection, omit amount.

If a collect response omits updated result or round state, use loadConfig before another action. Never assume success means the round closed. Never send a zero collect amount.

Required tests

Exercise both wager models, every card option, ladder top and bust, banking followed by win or loss, and reload during a choice. Test a bought round's base stake and a disabled-gamble session. Reconcile a lost collect reply before permitting another request.

See game flow, money, and recovery.