Score Distribution and Rank Evaluation

Relevant source files

• internal/domain/ai/ahead_vector_prob_dist.go
• internal/domain/ai/candidate_score.go
• internal/domain/ai/candidate_test.go
• internal/domain/ai/deal_in_score.go
• internal/domain/ai/evaluator.go
• internal/domain/ai/evaluator_test.go
• internal/domain/ai/exhaustive_draw_score.go
• internal/domain/ai/exhaustive_draw_score_test.go
• internal/domain/ai/round_end_prob.go
• internal/domain/ai/round_end_prob_test.go
• internal/domain/ai/round_end_score.go
• internal/domain/ai/round_end_score_test.go
• internal/domain/ai/score_delta_prob_dist.go
• internal/domain/ai/score_delta_prob_dist_test.go
• internal/domain/ai/win_estimate_score.go
• internal/domain/ai/win_estimate_score_test.go
• internal/domain/ai/win_score.go
• internal/domain/ai/win_score_test.go

The final stage of the Manue decision lifecycle involves synthesizing various probabilistic estimates into a unified candidateScore. This process transforms win probabilities, deal-in risks, and exhaustive draw projections into a scoreDeltaProbDist (Score Delta Probability Distribution), which is then mapped to an averageRank based on current game scores and historical statistics.

Evaluation Overview

The core evaluation logic resides in evaluateCandidateFromComponents internal/domain/ai/candidate_score.go44-56 This function takes the discrete outputs from the win estimator and danger estimator and combines them with global game statistics to project the state of the game at the end of the current round.

The candidateScore Structure

The result of this evaluation is encapsulated in the candidateScore struct, which contains the metrics used to compare different actionCandidate objects.

Field	Description
averageRank	The primary metric for decision making; lower is better.
expectedPoints	The expected point change for the self player.
winProb / dealInProb	Probabilities of winning or dealing-in.
exhaustiveDrawProb	Probability of the round ending in an exhaustive draw.
otherWinProb	Probability of any other player winning.
averageWinPoints	Mean points gained if a win occurs.
exhaustiveDrawAveragePoints	Mean points gained if the round ends in exhaustive draw.

Sources: internal/domain/ai/candidate_score.go9-26

Data Flow Diagram: Component Synthesis

The following diagram illustrates how raw estimates are transformed into the final score through the candidateEvaluator.

"Synthesis of Candidate Score"

Sources: internal/domain/ai/candidate_score.go44-95 internal/domain/ai/evaluator.go122-167

---

Probability Distribution Modeling

Manue uses a specialized type system to handle the uncertainty of Mahjong outcomes.

Score Delta Probability Distribution

The scoreDeltaProbDist type represents a map where keys are scoreDelta (an array of floats representing point changes for all 4 players) and values are the probabilities of those changes occurring.

• replace: This is a critical function for temporal chaining. It takes an "immediate" distribution (e.g., "did I deal in on this tile?") and replaces the "no-event" outcome with a "future" distribution (e.g., "what happens if the round continues?") internal/domain/ai/candidate_score.go83
• expected: Calculates the expected value vector for all players internal/domain/ai/evaluator.go209

Sources: internal/domain/ai/score_delta_prob_dist.go5-12 internal/domain/ai/score_delta_prob_dist.go51-69

Win Score Calculation

Win outcomes are modeled using winScoreFactor internal/domain/ai/win_score.go18-45 This logic accounts for the complex point-shifting rules of Mahjong (Ron vs. Tsumo, Dealer vs. Non-Dealer).

• Ron: The discarder pays the full points to the winner.
• Dealer Tsumo: All three non-dealers pay 1/3 of the total (dealerSelfDrawPaymentFactor) internal/domain/ai/win_score.go10
• Non-Dealer Tsumo: The dealer pays 1/2, and other non-dealers pay 1/4 (nonDealerSelfDrawOtherPaymentFactor) internal/domain/ai/win_score.go11

Sources: internal/domain/ai/win_score.go9-45

---

Exhaustive Draw Evaluation

When a round ends in an exhaustive draw (Ryukyoku), players are rewarded or penalized based on whether they are in Tenpai (ready to win).

Tenpai Probability Estimation

The AI estimates the likelihood of each player being in Tenpai at the end of the round using two main functions:

1. tenpaiProb: Estimates current Tenpai probability based on the number of melds and turns remaining using YamitenCounts internal/domain/ai/exhaustive_draw_score.go12-22
2. notenExhaustiveDrawTenpaiProb: Estimates the probability that a currently Noten player will reach Tenpai before the deck is exhausted, using historical ExhaustiveDrawTenpaiTurnFreq internal/domain/ai/exhaustive_draw_score.go27-42

Sources: internal/domain/ai/exhaustive_draw_score.go12-42

Ryukyoku Score Dists

The exhaustiveDrawScoreDeltaDist function calculates all possible combinations of Tenpai/Noten states for the four players, weights them by probability using an aheadVectorProbDist, and maps them to the standard point exchanges via ryukyokuScoreDelta internal/domain/ai/exhaustive_draw_score.go77-91

Sources: internal/domain/ai/exhaustive_draw_score.go77-91 internal/domain/ai/exhaustive_draw_score.go58-65

---

Rank Evaluation and Selection

The final averageRank is calculated by applying the scoreChanges distribution to the current game scores.

Rank Prediction

The averageRank function (called in evaluateCandidateFromComponents) uses RankStats to predict the final rank distribution internal/domain/ai/candidate_score.go87-93 It considers:

1. Current scores of all players (state.Scores()).
2. The distance from the starting dealer (to break ties).
3. The scoreDeltaProbDist projected for the end of the current round.

Sources: internal/domain/ai/candidate_score.go87-93

Candidate Comparison

When selecting the best action, the AI follows a strict priority order implemented in compareCandidateScore internal/domain/ai/candidate_score.go28-42 and chooseBestCandidate:

1. Lower Average Rank: The primary goal is to maximize the final position.
2. Higher Expected Points: Used as a tie-breaker if the average rank is identical.
3. Black Tile Preference: In chooseBestCandidate, if two discard actions are identical in value, the AI prefers discarding a "black" tile over a "red" tile to preserve the red dora in hand internal/domain/ai/candidate_test.go13-46

"Candidate Comparison Logic"

Sources: internal/domain/ai/candidate_score.go28-42 internal/domain/ai/candidate_test.go98-151

---

Behavioral Differences and Porting Notes

The Go port includes several bug fixes and refinements compared to the original CoffeeScript implementation.

• Reach Evaluation: The Go port separates pruning candidates from scoring them. The original implementation sometimes conflated these, leading to over-evaluation of visible yaku over efficiency.
• Target Probability: In the original, when calculating score changes for other players' wins, the self-draw probability was incorrectly assigned to the self player instead of the winner. The Go port correctly assigns tsumo probability to the winner in winScoreFactorDist internal/domain/ai/win_score.go51-64
• Red Dora Preservation: The Go port ensures that when evaluating a discard of a red 5, that red 5 is removed from the hand used for future win estimation internal/domain/ai/candidate_test.go13-46

Sources: internal/domain/ai/win_score.go51-64 internal/domain/ai/candidate_test.go13-46