Overview

Relevant source files

• .agents/design.md
• .devcontainer/Dockerfile
• .devcontainer/devcontainer.json
• AGENTS.md
• README.md
• THIRD-PARTY-NOTICES.md
• go.mod
• go.sum
• internal/domain/game/round/service/shanten.go
• test/original_vs_port/README.md
• test/original_vs_port/gen_log/manue/Dockerfile

mjai-manue-go is a high-performance Go port of mjai-manue a Japanese Mahjong AI originally developed by Hiroshi Ichikawa. The project implements a sophisticated decision engine that communicates via the Mjai protocol to play Mahjong on automated servers or against other AI clients README.md6-13

The AI logic is ported from the CoffeeScript version of the original project, while the surrounding infrastructure—including the game state machine, protocol handling, and statistical analysis tools—has been reimplemented in Go to ensure type safety and execution efficiency README.md58-60 .agents/design.md3-4

Key Features

• Protocol Flexibility: Supports both standard TCP connections (mjsonp://) and standard I/O (stdio) streams for integration with various simulators and match servers README.md37-39 .agents/design.md17-20
• State-Driven Logic: Unlike many Mjai clients, mjai-manue-go does not rely on the possible_actions field from the server. It maintains its own internal game state and derives legal actions independently using round.State and round.LegalActions README.md41-46 .agents/design.md101
• Self-Contained: Configuration files, including danger estimation trees and game statistics, are embedded directly into the binary at build time using go:embed README.md47-49 .agents/design.md108
• Deterministic Execution: Uses deterministic random number generation controlled by a --seed flag to ensure reproducible AI decisions README.md63 .agents/design.md48

System Architecture

The project follows a layered architecture inspired by Domain-Driven Design (DDD) and Hexagonal Architecture principles. This separation ensures that the core Mahjong rules and AI logic remain isolated from the specifics of the Mjai JSON protocol.

High-Level Component Map

The following diagram illustrates how external protocol messages flow through the system layers to trigger AI decisions.

Diagram: System Flow and Code Entities

Sources: .agents/design.md66-91 .agents/design.md100-105 AGENTS.md22-26

Architecture Layers

Layer	Package Path	Responsibility
Cmd	cmd/	Entry points (e.g., cmd/mjai-manue), CLI flag parsing, and runtime initialization .agents/design.md60
Adapter	internal/adapter/	Translation between the Mjai JSON protocol and internal domain events/actions using an Anti-Corruption Layer (ACL) .agents/design.md59 .agents/design.md64-65
Application	internal/application/	Orchestrating the game loop, managing the Bot lifecycle, and coordinating state updates with AI queries .agents/design.md58
Domain	internal/domain/	The "source of truth" for Mahjong rules, including tile types, score calculation, and the ManueAgent decision logic .agents/design.md57

For a detailed breakdown of these layers and their dependency rules, see Architecture Overview.

AI Decision Engine

The ManueAgent selects actions by evaluating candidates across several statistical dimensions. It aims to maximize the expected final rank rather than just the immediate score README.md120-123

Diagram: Decision Pipeline

Sources: README.md95-124 .agents/design.md132-133 internal/domain/game/round/service/shanten.go91-140

The evaluation includes:

• Win Probability (myHoraProb): Estimated via Monte Carlo simulation of 1000 trials per decision README.md102-106
• Deal-in Risk (hojuProb): Calculated using a pre-trained decision tree trained from tile-safety features such as honors, suji, and dora README.md110-112
• Rank Evaluation (avgRank): Combines win/loss probabilities with current scores and statistical distributions to predict the final game outcome README.md120-124

Navigation

To explore the codebase and its documentation further, refer to the following child pages:

• Getting Started: Instructions for building the project, running the agent in different modes (TCP vs. Stdio), and setting up the development environment using DevContainers .devcontainer/devcontainer.json1-43
• Architecture Overview: Deep dive into the DDD layers, the Anti-Corruption Layer (ACL) for protocol handling, and how the round.State machine processes events .agents/design.md51-91
• Developer Tools: Overview of the tools suite (e.g., estimate_danger, dump_game_stats) for generating the statistical models embedded in the AI .agents/design.md109
• Testing and Quality Assurance: Details on the testing strategy, including unit tests, golden-file integration tests, and the Original-vs-Port comparison framework test/original_vs_port/README.md1-4

Sources: README.md1-124 .agents/design.md1-133 AGENTS.md1-54 test/original_vs_port/README.md1-101