The mjai-manue-go project includes a suite of command-line tools designed to extract, aggregate, and process statistical data from Mjai-formatted game logs. These tools generate the structured JSON configuration files used by the AI engine to estimate win probabilities, evaluate Yamiten risk, and predict round-end outcomes.
The pipeline is divided into two main categories: Game-level statistics (overall frequencies and distributions) and Round-level statistics (score-based win probabilities).
The statistics generation follows a multi-stage process where raw logs are replayed to observe state transitions and outcomes. The tools/internal/archive package provides the foundational logic for replaying Mjson logs and updating the round.State during analysis tools/dump_game_stats/main.go179-202
The following diagram illustrates the transformation from raw mjson logs to the final configuration files consumed by the ManueAgent.
Title: Statistics Generation Pipeline
Sources: tools/README.md1-27 tools/dump_game_stats/README.md1-21 tools/dump_light_game_stats/README.md1-21 tools/postprocess_light_game_stats/README.md1-18
Game-level statistics focus on frequencies and probability distributions across thousands of games. These metrics are used by the AI to understand the "average" flow of a Mahjong round.
This tool replays game logs using multiple counters to compute metrics:
numTurnsDistribution (probability a round ends at a specific turn) and ryukyokuRatio tools/dump_game_stats/main.go27-54oyaFreqs) and non-dealer (koFreqs) status tools/dump_game_stats/main.go56-81A utility to format the game_stats.json file into a human-readable layout for developer inspection. It displays distributions and Yamiten rates in tabular form tools/print_game_stats/main.go81-85
The AI engine loads these via configs.LoadGameStats().
RyukyokuRatio and NumTurnsDistribution tools/dump_game_stats/main.go216-226YamitenStats to estimate the probability that an opponent is in Tenpai even if they haven't declared Riichi tools/dump_game_stats/main.go83-91Sources: tools/dump_game_stats/main.go27-154 tools/dump_game_stats/README.md3-13 tools/print_game_stats/main.go81-85 tools/print_game_stats/README.md23-45
The "light" statistics pipeline focuses specifically on score differentials to build the winProbsMap. This map allows the AI to estimate the probability of finishing ahead of an opponent based on the current score gap.
This tool extracts the score difference for every player at the end of every round.
roundSnapshot at the start of every Kyoku (StartKyoku) tools/dump_light_game_stats/main.go57-61EndGame, it calculates the difference between the final score and the snapshot score for each round tools/dump_light_game_stats/main.go89-101This tool converts raw score frequencies into pairwise win probabilities.
The tools use a specific string format for keys:
E1 through S4 tools/postprocess_light_game_stats/main.go620-3 representing the player's position relative to Chicha tools/dump_light_game_stats/main.go93-94"Round,SelfSeat,OtherSeat" (e.g., "E1,0,1") tools/postprocess_light_game_stats/main.go83Sources: tools/dump_light_game_stats/main.go21-101 tools/postprocess_light_game_stats/main.go39-104 tools/postprocess_light_game_stats/README.md32-45
The following diagrams associate the conceptual tools and data structures with their implementation in the codebase.
Title: Statistics Tool Implementation Map
Sources: tools/dump_game_stats/main.go23-26 tools/dump_game_stats/main.go210-244 tools/postprocess_light_game_stats/main.go106-116
Title: AI Consumption of Statistics
Sources: tools/dump_game_stats/main.go233-244 tools/postprocess_light_game_stats/main.go115-116
| Function/Type | Location | Description |
|---|---|---|
basicCounter | tools/dump_game_stats/main.go27-34 | Aggregates basic round outcomes and turn distributions. |
yamitenCounter | tools/dump_game_stats/main.go83-85 | Tracks Tenpai status for non-Riichi players. |
scoreCounter | tools/dump_light_game_stats/main.go26-30 | Manages score snapshots and calculates round-end differentials. |
computeWinProbs | tools/postprocess_light_game_stats/main.go59 | Derives pairwise win probabilities from score distributions. |
GameStats | tools/dump_game_stats/main.go233-244 | The final aggregated data structure for game-level metrics. |
Sources: tools/dump_game_stats/main.go27-110 tools/dump_light_game_stats/main.go26-30 tools/postprocess_light_game_stats/main.go59-60
Refresh this wiki