Blackjack Math Specification

Card Valuation

Card	Value
2-9	Face value (2-9)
10, J, Q, K	10
A	1 or 11 (soft)

Hand Scoring

A hand's score is the best valid total less than or equal to 21. Aces contribute either 1 or 11, whichever produces the best valid score.

Definitions

Term	Definition
Soft Hand	Contains at least one Ace counted as 11 (e.g., A+7 = soft 18)
Hard Hand	All Aces counted as 1, or no Aces present (e.g., K+7 = hard 17)
Bust	All possible scores exceed 21 (e.g., K+Q+5 = 25)
Natural Blackjack	Exactly 2 cards: Ace + 10-value card

Scoring Algorithm

total_without_aces = sum of all non-Ace card values
ace_count = number of Aces in hand
base = total_without_aces + ace_count       (all Aces = 1)

FOR each Ace:
    IF base + 10 <= 21:
        base += 10   (count one Ace as 11)
        soft = true

score = base
bust = (total_without_aces + ace_count) > 21

Examples:

Hand	Calculation	Score	Soft?	Bust?
K♠ + 7♦	10 + 7	17	No	No
A♥ + 7♣	1+7=8 -> +10->18	18	Yes	No
A♣ + K♥ + A♦	10+1+1=12 -> +10->22(bust)->12	12	No	No
K♠ + Q♦ + 5♥	10+10+5=25	25	No	Yes

State Machine

DEALING -> [Natural BJ?] -> Completed
       -> [Insurance?] -> InsuranceDecision -> PlayerTurn
       -> PlayerTurn
           |-> HIT (loop until bust/21/stand)
           |-> STAND -> DealerTurn -> Completed
           |-> DOUBLE -> DealerTurn -> Completed
           |-> SPLIT -> SplitTurn -> DealerTurn -> Completed

State Definitions

State	Description
Dealing	Initial 4-card deal from provably fair deck
InsuranceDecision	Dealer shows Ace, player decides whether to take insurance
PlayerTurn	Player may: Hit, Stand, Double, Split
SplitTurn	Two independent hands played sequentially
DealerTurn	Dealer draws to completion per fixed drawing rules
Completed	Game resolved, winnings calculated

Dealer Drawing Rules

The dealer is fully automated and follows fixed, non-discretionary rules with no decision-making capability:

WHILE true:
    IF score.is_bust                -> STOP (dealer busts)
    IF score.value > 17             -> STOP (stand)
    IF score.value == 17:
        IF score.is_soft AND config.hits_soft_17:
            draw_card() -> CONTINUE
        ELSE:
            STOP (stand)
    IF score.value < 17:
        draw_card() -> CONTINUE

Rule	Value
Hit threshold	score <= 16
Stand threshold	score >= 17
Hit Soft 17	Configurable (default: false)

Split Rules

Eligibility

• Exactly 2 cards in hand
• Both cards share the same value (e.g., 8+8, K+Q, A+A)

Execution

1. Separate the pair into two independent hands
2. Deal one new card to each hand (from positions 5 and 6)
3. Duplicate the bet: bet_1 = bet_2 = original bet
4. Player plays each hand sequentially

Split Aces Rule

When Aces are split:

• Each Ace receives exactly one additional card
• The hand immediately stands, no further actions allowed
• Split Aces do NOT qualify for natural blackjack (pay 1:1, not 3:2)
• Double After Split is never allowed on split Aces

Double After Split (DAS)

Controlled by allow_double_after_split configuration flag.

DAS Setting	Double on Split Hand	Double on Split Aces
false (default)	Not allowed	Not allowed
true	Allowed (if balance >= bet)	Never allowed

Payout Multipliers

Outcome	Multiplier	Formula	Example ($100 bet)
Natural Blackjack	2.5×	win = bet × 2.5	$250
Standard Win	2.0×	win = bet × 2.0	$200
Push (tie)	1.0×	win = bet × 1.0	$100 (returned)
Insurance Win	3.0×	win = ins_bet × 3.0	$150 on $50 ins
Lose	0×	win = 0	$0

Configurable Parameters

Parameter	Default	Description
blackjack_multiplier	2.5	Natural blackjack payout
win_multiplier	2.0	Standard win payout
insurance_multiplier	3.0	Insurance win payout
dealer_hits_soft_17	false	Dealer behavior on soft 17
allow_double_after_split	false	DAS rule