This page provides technical instructions for building and running the mjai-manue-go agents. It covers the CLI interface, the runtime modes (TCP vs. stdio), and the development environment.
The project requires Go 1.26.1 or later go.mod3 A critical requirement for building or running the agents is the enablement of the jsonv2 experiment for JSON processing .devcontainer/devcontainer.json38
To install the agents to your $GOPATH/bin:
Unlike the original CoffeeScript implementation, mjai-manue-go embeds its configuration files (game statistics and danger estimation trees) directly into the binary using go:embed. To customize the AI's behavior, one must replace the JSON files in the configs/ directory before running go install cmd/mjai-manue/README.md35-42
Sources: go.mod1-4 cmd/mjai-manue/README.md33-49
The project provides two main executables: mjai-manue (the AI) and mjai-tsumogiri (a baseline agent that always discards the drawn tile) cmd/README.md7-10
Both commands share a similar CLI structure defined in their respective run functions cmd/mjai-manue/main.go29-35 cmd/mjai-tsumogiri/main.go27-33
| Flag | Default | Description |
|---|---|---|
--name | Manue030 / tsumogiri | The player name sent in the Mjai join message cmd/README.md37 cmd/mjai-manue/main.go17 |
--id | 0 | Fallback player ID (0-3) used if the server's start_game message omits the id field cmd/README.md41-43 cmd/mjai-manue/main.go33 |
--seed | 0 | (mjai-manue only) Random seed for Monte Carlo simulations to ensure determinism cmd/mjai-manue/main.go18 |
The mjai-manue agent uses the --seed flag to initialize the ai.ManueAgent via ai.NewManueAgent cmd/mjai-manue/main.go57 This ensures that given the same input stream and seed, the AI will produce identical Monte Carlo simulation results and decisions.
Sources: cmd/mjai-manue/main.go16-45 cmd/mjai-tsumogiri/main.go27-44 cmd/README.md37-43
The agents detect the runtime mode based on the presence of a positional URL argument cmd/mjai-manue/main.go66-84
Triggered when no URL is provided. The agent communicates via stdin and stdout using the Mjai JSON Lines protocol cmd/README.md46-48
EOF on stdin. It can handle multiple games sequentially as long as new start_game messages are received after end_game cmd/README.md52stdout; all logs and AI trace information go to stderr cmd/README.md64-65mjairuntime.RunStdio internal/adapter/mjai/runtime/stdio.go19-21Triggered when a URL with the mjsonp:// scheme is provided (e.g., mjsonp://localhost:11600/default) cmd/README.md54-56
mjairuntime.RunTCP cmd/mjai-manue/main.go67 It is strictly synchronous: it sends one response for every message that expects one cmd/README.md58end_game message cmd/README.md60parseMjsonpURL, which requires a scheme, host, port, and room path internal/adapter/mjai/runtime/tcp.go66-88The mjairuntime package abstracts these modes. RunTCP and RunStdio set up the connection and then hand off to a Driver internal/adapter/mjai/runtime/driver.go14-22 which manages the lifecycle of the game session by dispatching messages to an application.Bot internal/adapter/mjai/runtime/driver.go48
System Logic to Code Entity Mapping The following diagram illustrates how CLI arguments lead to the initialization of specific runtime drivers and domain agents.
Title: CLI Initialization Flow
Sources: cmd/mjai-manue/main.go47-84 cmd/README.md44-62 internal/adapter/mjai/runtime/driver.go34-74 internal/adapter/mjai/runtime/tcp.go33-59
The repository includes a DevContainer configuration to ensure a consistent environment for development and testing.
.devcontainer/Dockerfile .devcontainer/devcontainer.json6-8GOEXPERIMENT=jsonv2 in the container environment .devcontainer/devcontainer.json37-39The mjairuntime package includes golden-file tests (TestGoldenStdout) that verify agent output against known inputs internal/adapter/mjai/runtime/golden_test.go16-133 These tests use newManueAgentForGoldenTest with a fixed seed of 0 to ensure reproducible results during CI internal/adapter/mjai/runtime/golden_test.go145-153
Entity Relationship: Driver and Dependencies This diagram maps the protocol handling entities to their code implementations and data dependencies.
Title: Runtime Driver Architecture
Sources: .devcontainer/devcontainer.json1-43 cmd/mjai-manue/main.go47-84 internal/adapter/mjai/runtime/golden_test.go145-153 internal/adapter/mjai/runtime/driver.go24-32