Red Mahjong
Usage
or load the environment class directly:
from mahjax.mahjong_4p.config import RED
from mahjax.mahjong_4p.env import Mahjong4p
env = Mahjong4p(
round_mode="half",
observe_type="dict",
game_config=RED,
)
Description
red_4p is the full red-five riichi mahjong environment in MahJax. It is the environment intended to track modern online riichi mahjong more closely.
This implementation is designed to follow Tenhou as closely as practical, and we validate it against downloaded Tenhou game logs. We do not describe the log-test details here, but this is the main correctness target for the environment.
Rules
The environment implements 4-player riichi mahjong with red fives. By default, the rule configuration enables:
- red fives
- double ron
- special abortive draws
- pao
The detailed external rule reference is:
GameConfig
The rule behavior is controlled through GameConfig, a frozen dataclass of Python bools. The env holds one config and compiles its functions for it, so a config cannot change inside a jitted or vmapped run.
| Field | Default | Meaning |
|---|---|---|
use_red_fives |
True |
Enable red 5m / 5p / 5s tiles. |
allow_double_ron |
True |
Allow two players to win simultaneously on the same discard. |
enable_special_abortive_draw |
True |
Enable 九種九牌 / 四風連打 / 四家立直 / 三家和 / 四開槓. |
enable_pao |
True |
Enable 包 (responsibility payment) for 大三元 / 大四喜. |
enable_ippatsu |
True |
Award 一発 (ippatsu) to a riichi that wins within one go-around, with no call in between. |
enable_kan_dora |
True |
Turn over a new dora indicator for each kan (槓ドラ). |
enable_ura_dora |
True |
Count 裏ドラ for a riichi winner, including the kan dora's ura when kan dora is on. |
Two presets are provided: RED (the default) turns every rule above on, and NO_RED turns off the first four and keeps the rest. Other combinations are built field by field, e.g. GameConfig(enable_pao=False), and dataclasses.asdict(env.game_config) records the rules of a run.
State
red_4p's state, which no_red_4p shares, is a nested layout:
- top-level RL handles (
current_player,terminated,rewards, …) state.players— per-player arrays (PlayerStateArrays)state.round_state— round-level arrays (RoundState)
The shared field list and the round-transition style (auto / confirm) are documented once in API. red_4p adds the following red-five-aware fields on top of the shared PlayerStateArrays:
| Field | Shape | Type | Meaning |
|---|---|---|---|
hand_with_red |
(4, 37) |
int8 |
Hand histogram in the 37-tile-type space (34 tile types + 3 red fives). |
hand_ids |
(4, 14) |
int16 |
Reserved for the tile ids in the hand ([0, 135]). Not populated yet: every slot is sentinel. Read the hand from hand_with_red. |
has_nagashi_mangan |
(4,) |
bool |
Whether each player is still eligible for 流し満貫. |
The shared hand array (tile-type histogram in [0, 33] space) is also still kept for backward compatibility with code paths that do not need red-five resolution.
Specs
| Name | Value |
|---|---|
| Version | beta |
| Number of players | 4 |
| Number of actions | 87 |
| Observation types | dict, 2D |
| Reward shape | (4,) |
| Reward semantics | score deltas in hundreds of points |
Action
The action space (87 actions):
| Range | Meaning |
|---|---|
0-36 |
Discard a tile, including red-five tile ids |
37-70 |
Closed kan / added kan |
71 |
TSUMOGIRI |
72 |
RIICHI |
73 |
TSUMO |
74 |
RON |
75 |
PON |
76 |
PON_RED |
77 |
OPEN_KAN |
78-83 |
Chi variants including red-five-aware actions |
84 |
PASS |
85 |
KYUUSHU |
86 |
DUMMY (only legal under round_end="confirm") |
Dict Observation
The current training-oriented observation is dict. It is the format we recommend if you need a structured observation today, though we still reserve the right to revise it in future releases.
The returned dictionary contains:
The full per-key table — shapes, ranges and the reasoning behind each field — lives in api.md. It is kept in one place on purpose: two copies of a 25-key table drift apart. The keys specific to this env are:
| Key | Shape | Meaning |
|---|---|---|
is_red |
(34,) |
Whether the concealed hand holds the RED five of that type (indices 4 / 13 / 22 only). Always False under NO_RED (no_red_4p). |
Tile ids are red-aware [0, 36] wherever a tile appears (last_draw, target,
dora_indicators, the meld and history channels). Tile types stay [0, 33], with red
fives folded into their type, so hand, discard_shanten, can_win, discard_can_win and
tiles_seen are all 34-wide. The action space is 87 wide (discards 0-36, self-kan 37-70,
calls 75-83 including *_RED variants).
Action History
action_history is stored as:
- Row
0: acting player index, converted to the current player's relative view - Row
1: action payload - Row
2: tsumogiri flag
The semantics are:
- For discards, row
1stores the actual discarded tile - For non-discard actions, row
1stores the raw action id - Row
2is1for tsumogiri,0for a non-tsumogiri discard, and-1for non-discard actions PASSis not recorded: a declined call or ron is not publicRONis recorded once everyone who can ron the tile has answered, one entry per winner in turn order from the discarder
For red_4p, discard tiles are in [0, 36] because red fives have dedicated tile ids in the action space, while raw action ids are in [0, 86].
2D Observation
observe_type="2D" is available, but we do not consider its design finalized yet. If you need a representation whose semantics are less likely to move, prefer dict.
Rewards
Rewards are 4-player score deltas, represented in hundreds of points.
This includes:
- ron and tsumo score transfers; a double ron pays both winners on the step that closes it, the last candidate's
RONorPASS - honba and kyotaku handling
- exhaustive draw payments
- pao when enabled in
GameConfig - illegal-action termination penalties
For how to consume these rewards in turn-based MARL training (per-player reward accumulator + GAE), see the API → Using auto rewards in RL section.
Termination
round_mode="single"terminates after the first round ends.round_mode="east"runs East-only progression withround_limit=3(East-1 to East-4).round_mode="half"runs East-South progression withround_limit=7(East-1 to South-4).- If nobody holds 30000 points or more when the last kyoku ends, the deal runs on into the extra rounds (西入) and stops as soon as somebody does, or after four extra kyoku.
In multi-round modes, the next-round transition behavior is controlled by round_end (see API).
red_mahjong is the env used by mahjax_tenhou_test, which validates round trajectories against real tenhou mjlogs using next_round_style="dummy_share". The state-level equivalence between auto and dummy_share at round boundaries is asserted by the parity tests in tests/red_mahjong/test_env.py, so the same correctness target also covers auto mode end-to-end.
env.observe_privileged(state) returns the same dict plus others_hand (3, 34) and others_is_red (3, 34) — the other three players' concealed hands in seat-relative order (right / across / left). That is hidden information: use it for centralised critics and analysis, never for a policy that will face real opponents.