Round State Machine

Relevant source files

• internal/domain/game/event/start_round.go
• internal/domain/game/round/event_applier.go
• internal/domain/game/round/event_applier_concealed_kan_test.go
• internal/domain/game/round/event_applier_consecutive_kan_test.go
• internal/domain/game/round/event_applier_discard_test.go
• internal/domain/game/round/event_applier_dora_test.go
• internal/domain/game/round/event_applier_draw_round_test.go
• internal/domain/game/round/event_applier_draw_test.go
• internal/domain/game/round/event_applier_pon_test.go
• internal/domain/game/round/event_applier_riichi_test.go
• internal/domain/game/round/event_applier_terminal_test.go
• internal/domain/game/round/event_applier_test.go
• internal/domain/game/round/event_applier_win_test.go
• internal/domain/game/round/state.go

The Round State Machine is the core logic engine that manages the lifecycle of a single Mahjong round. It is primarily implemented via the round.State struct and the EventApplier interface. It ensures that every transition (drawing a tile, discarding, calling a meld, etc.) follows the legal rules of the game and correctly updates the internal representation of the board and players.

The State Struct

The round.State struct encapsulates the complete status of a round, including the wall size, dora indicators, scores, and the status of all four players.

Field	Description
roundWind, roundNumber	Current round identifiers (e.g., East 1).
numLeftTiles	Number of tiles remaining in the wall.
doraIndicators	Collection of revealed dora indicator tiles.
kanProgress	Enum tracking the multi-step sequence of Kan actions.
pendingDiscard	Pointer to the seat expected to perform the next discard.
players	Array of player.Player objects (Visible or Invisible).
legalActionsCache	Map of seat to valid actions to avoid redundant calculations.

Sources: internal/domain/game/round/state.go37-66

Event Application Lifecycle

State transitions are driven by the Apply(ev event.Event) method. This function acts as a dispatcher, validating the incoming event against the current state before delegating to specific application logic.

State Transition Dispatch

The Apply method follows a strict sequence:

1. Terminal Check: Prevents applying events if the round has already ended, except for additional Win events in double/triple Ron scenarios internal/domain/game/round/event_applier.go20-24
2. Dispatch: Routes the event to the appropriate applyXXX method (e.g., applyDraw, applyDiscard, applyChii, applyPon, applyWin) internal/domain/game/round/event_applier.go30-57
3. Post-Processing: Flushes temporary safety flags and invalidates the legalActionsCache. It also sets legalActionsSuppressed for intermediate states like event.Dora internal/domain/game/round/event_applier.go63-68

Round State Entity Mapping

The following diagram illustrates how the EventApplier bridges the gap between high-level game events and the internal state modifications.

Diagram: Event to State Mapping

Sources: internal/domain/game/round/event_applier.go19-57 internal/domain/game/round/state.go37-66

Key Transition Logic

Kan Lifecycle and kanProgress

Managing Kans is complex due to varying rules regarding when the replacement tile is drawn and when the Dora is revealed. The state machine uses kanProgress to enforce these sequences.

• noKanProgress: Normal play.
• waitingReplacementBeforeDora: Used after CalledKan (Daiminkan) or PromotedKan (Kakan). The actor must draw a replacement tile before the next Dora is revealed internal/domain/game/round/state.go32
• waitingReplacementAfterDora: Used after ConcealedKan (Ankan). The Dora indicator is revealed before the replacement tile is drawn internal/domain/game/round/state.go34

The implementation supports various protocol orders (Tenhou vs Mahjong Soul) by tracking pendingDoraReveals separately from kanProgress internal/domain/game/round/event_applier.go81-83 internal/domain/game/round/event_applier_consecutive_kan_test.go15-31

Riichi Lifecycle

Riichi is a multi-event process:

1. event.Riichi: The player declares Riichi. The state updates the player's internal status to RiichiDeclared internal/domain/game/round/event_applier.go273-277
2. event.Discard: The player discards a tile. If their status is RiichiDeclared, the seat is stored in pendingRiichiAcceptance internal/domain/game/round/event_applier.go124-126
3. event.RiichiAccepted: The Riichi is finalized. The deposit is added to the table (riichiDeposit), and the player's state moves to RiichiAccepted internal/domain/game/round/event_applier.go279-301

Double/Triple Ron and Extra Safe Tiles

The engine supports multiple winners. When a Win (Ron) occurs, roundEnded is set to true, but the state machine allows subsequent Win events for the same target tile to handle double or triple Ron internal/domain/game/round/event_applier.go20-24

Additionally, if a player declines a Ron (Pass), the tile becomes "extra safe" for that player. The pendingExtraSafeDiscard struct tracks this until the next non-win event occurs internal/domain/game/round/event_applier.go28-29 internal/domain/game/round/event_applier.go63-65

Player Visibility

The state machine handles both fully known and partially known hands:

• VisiblePlayer: Used for the "self" player or when hands are revealed. Contains full TileCounts34 internal/domain/game/round/state.go135-139
• InvisiblePlayer: Used for opponents whose hands are hidden. Only tracks their river and melds internal/domain/game/round/state.go131-133

Diagram: Player State Implementation

Sources: internal/domain/game/round/state.go64 internal/domain/game/round/state.go130-140

Validation Rules

The EventApplier performs rigorous checks during every transition:

• Turn Order: applyDraw verifies that ev.Actor() == s.nextDraw internal/domain/game/round/event_applier.go84-86
• Tile Availability: applyDraw and Kan methods check s.numLeftTiles > 0 internal/domain/game/round/event_applier.go88-90 internal/domain/game/round/event_applier.go202-204
• Kan Limits: No more than 4 Kans are allowed per round (maxNumKan) internal/domain/game/round/event_applier.go174-176
• Kyushukyuhai: The ability to declare a 9-terminal draw is enabled only on the first turn (canKyushukyuhai) and disabled once any player makes a call internal/domain/game/round/event_applier.go150 internal/domain/game/round/state.go109-111
• Robbing a Kan: applyPromotedKan sets pendingRobbedKanTile to allow other players to declare Ron on the added tile internal/domain/game/round/event_applier.go250-252

Sources: internal/domain/game/round/event_applier.go1-350 internal/domain/game/round/state.go1-147