Win Estimation via Monte Carlo Simulation

Relevant source files

• internal/domain/ai/call_candidates.go
• internal/domain/ai/call_candidates_test.go
• internal/domain/ai/candidate.go
• internal/domain/ai/candidate_builder.go
• internal/domain/ai/candidate_builder_test.go
• internal/domain/ai/self_turn_candidates.go
• internal/domain/ai/self_turn_candidates_test.go
• internal/domain/ai/stats.go
• internal/domain/ai/stats_test.go
• internal/domain/ai/win_estimator.go
• internal/domain/ai/win_estimator_test.go
• internal/domain/ai/win_goals.go
• internal/domain/ai/win_trials.go

The win estimator is a core component of the AI decision engine that calculates the probability of winning and the expected points for a given action candidate. It utilizes a Monte Carlo simulation approach, running 1,000 trials per candidate to sample possible future game states based on unseen tiles.

Overview of the Estimation Pipeline

The estimation process begins after legal actions are transformed into actionCandidate objects internal/domain/ai/candidate.go14-36 For each candidate, the AI simulates the remainder of the round to determine how likely that candidate is to result in a win.

Key Components

• Monte Carlo Trials: 1,000 independent simulations per candidate to estimate probabilities internal/domain/ai/win_estimator.go31-32
• Unseen Wall: A collection of tiles not currently visible to the AI (not in hand, not discarded, and not in visible melds) internal/domain/ai/win_trials.go32-48
• Shanten Goals: Pre-calculated hand structures (sequences, triplets, pairs) that represent a winning hand reachable from the current state internal/domain/ai/win_goals.go12-15
• Scoring (Fu/Han): Evaluation of the point value for each sampled winning hand using the engine's scoring service internal/domain/ai/win_goals.go80-89

Code Entity Map: Win Estimation Flow

The following diagram maps the logical steps of win estimation to the specific functions and structs in the ai package.

"Win Estimation Flow"

Sources: internal/domain/ai/win_estimator.go62-80 internal/domain/ai/win_trials.go50-63 internal/domain/ai/win_goals.go66-98 internal/domain/ai/self_turn_candidates.go13-79 internal/domain/ai/call_candidates.go15-58

Unseen Wall Construction

Before running trials, the AI identifies which tiles are "unseen." It starts with a full set of 4 copies for each of the 34 tile types and subtracts every tile visible from the current player's perspective (their own hand, all discards on the table, and all open melds).

• Function: unseenWallFromVisibleTiles internal/domain/ai/win_trials.go32-48
• Logic: It iterates through visibleTiles and decrements counts in a TileCounts34 structure. If a tile appears more than 4 times, it returns an error internal/domain/ai/win_trials.go43-45
• Result: A slice of tile.Tile representing the pool from which future draws will be sampled internal/domain/ai/win_trials.go47

Monte Carlo Trials

The simulation runs numTries iterations internal/domain/ai/win_estimator.go31 In each iteration, it performs the following:

1. Wall Shuffling and Sampling

The AI determines the number of draws remaining in the round using expectedRemainingTurns internal/domain/ai/win_estimator.go71 It then shuffles the unseenWall and picks the top numDraws tiles.

• Function: shuffledTrialTileCounts internal/domain/ai/win_trials.go50-63
• Data Structure: The sampled tiles are converted into trialTileCounts (a TileCounts34 type) for efficient comparison against winning requirements internal/domain/ai/win_trials.go15-21

2. Goal Achievement Check

For a specific candidate, the AI checks its shantenGoals against the sampled trialTileCounts.

• Goal Structure: Each service.Goal contains a RequiredVector, which specifies exactly how many of each tile type are needed to complete the hand.
• Logic: canAchieveGoalWithTrialTiles returns true if the trial counts meet or exceed the required counts for every tile in the goal internal/domain/ai/win_trials.go65-72

3. Point Selection

If multiple goals are achieved in a single trial, the AI selects the one with the highest point value.

• Function: trialWinPts internal/domain/ai/win_trials.go74-86

Sources: internal/domain/ai/win_estimator.go26-60 internal/domain/ai/win_trials.go88-112

Win Goal Scoring (Fu/Han)

Before the simulation begins, the AI pre-calculates the point value for every possible winning goal associated with a candidate via scoredWinEstimateGoalsByKey internal/domain/ai/win_goals.go129-150

• Filtering: filteredWinEstimateGoals prunes goals that are irrelevant, such as goals requiring more shanten than the base hand (if baseShanten > 3) or goals that require a tile the candidate just discarded internal/domain/ai/win_goals.go46-64
• Riichi Logic: If a candidate allows riichi (scoreAsRiichi), the AI includes the riichi yaku in the point calculation, provided the hand is closed internal/domain/ai/win_goals.go80-89
• Hand Construction: scoringHandForGoal builds a full 14-tile hand by combining the candidate's afterDiscardHand with the blocks defined in the goal. It handles Red Five tiles by prioritizing them if they were in the afterDiscardHand internal/domain/ai/win_goals.go102-127
• Scoring: It calls service.CalculateFuHan and service.RonPoints to determine the point value based on the current winEstimateGoalContext internal/domain/ai/win_goals.go81-90

Resulting Win Estimate

The results of the trials are aggregated into a winEstimate struct for each candidate.

Field	Description	Calculation
Probability	The likelihood of winning.	Number of successful trials / Total trials
Average Points	The expected value of points upon winning.	Sum of points in successful trials / Number of successful trials

These values are calculated by the winEstimateAccumulatorSet and are used by the final selection policy to weigh the benefit of winning against other factors like deal-in risk internal/domain/ai/win_estimator.go45-60

Data Flow: From State to Estimate

"Data Transformation Map"

Sources: internal/domain/ai/win_estimator.go21-24 internal/domain/ai/win_estimator.go45-60 internal/domain/ai/win_trials.go50-63 internal/domain/ai/win_goals.go12-15