Tile, Wind, and Seat Primitives

Relevant source files

• internal/domain/game/round/event_applier_chii_test.go
• internal/domain/game/round/player/meld/called_kan.go
• internal/domain/game/round/player/meld/concealed_kan.go
• internal/domain/game/round/player/meld/pon.go
• internal/domain/game/round/player/meld/promoted_kan.go
• internal/domain/game/seat/seat.go
• internal/domain/game/seat/seat_test.go
• internal/domain/game/tile/tile.go
• internal/domain/game/tile/tile_test.go
• internal/domain/game/tile/tiles.go
• internal/domain/game/tile/tiles_test.go
• internal/domain/game/wind/wind.go
• internal/domain/game/wind/wind_test.go

This section describes the foundational value types used across the mjai-manue-go domain. These primitives define how tiles are encoded, how player positions (seats) are calculated, and how winds are managed.

Tile System

The codebase employs a multi-tiered tile identification system to handle standard tiles, red-five variants, and unknown tiles (used in state masking).

Tile ID Encoding

Tiles are represented by a Tile struct containing an int8 ID internal/domain/game/tile/tile.go99-101 The system supports three levels of type counts:

• 34 Types: Standard tiles without red fives internal/domain/game/tile/tile.go7-8
• 37 Types: Standard tiles plus three red-five variants (5mr, 5pr, 5sr) internal/domain/game/tile/tile.go10-11
• 38 Types: All above plus an "unknown" tile (?) internal/domain/game/tile/tile.go13-14

Tile Properties and Classification

The tile package provides static lookup tables for tile attributes based on their ID:

• Colors: ManzuColor ('m'), PinzuColor ('p'), SouzuColor ('s'), HonorsColor ('t'), and UnknownColor ('?') internal/domain/game/tile/tile.go16-20
• Yaochuhai: A fixed set of 13 IDs representing terminals and honors internal/domain/game/tile/tile.go22
• Dora Logic: NextForDora() uses a circular mapping (doraIndicatorToDora) to determine the effective dora tile from an indicator internal/domain/game/tile/tile.go90-200

Tile Mapping Logic

Title "Tile ID and Code Mapping"

Sources: internal/domain/game/tile/tile.go38-160

Tile Collections (Tiles)

The Tiles type is a slice of Tile objects with helper methods for common mahjong operations internal/domain/game/tile/tiles.go16

• Sorting: Uses tileSortKeyTable to ensure a standard hand order: Manzu -> Pinzu -> Souzu -> Honors. Red fives are sorted immediately after their black counterparts (e.g., 5m then 5mr) internal/domain/game/tile/tiles.go7-33
• Deduplication: Distinct() returns a sorted slice of unique tiles, with an optional filter to exclude specific tiles (like red fives) internal/domain/game/tile/tiles.go57-70
• Symbol Matching: HasSameSymbol() and CountSameSymbol() ignore the red-five status, comparing only the number and color internal/domain/game/tile/tile.go

Seats and Winds

Seat

The Seat struct represents a player's physical position at the table (0 to 3) internal/domain/game/seat/seat.go5-7

• Relative Positioning: DistanceFrom(base) calculates the gap between two seats (0=Self, 1=Shimocha, 2=Toimen, 3=Kamicha) internal/domain/game/seat/seat.go34-36
• Shimocha Detection: IsShimochaOf(target) specifically checks if the current seat is to the immediate left of the target internal/domain/game/seat/seat.go39-41

Wind

Winds are represented as an int enum: East, South, West, North internal/domain/game/wind/wind.go7-14

• Rotation: Next() handles the wind progression during dealer rotations internal/domain/game/wind/wind.go46-59
• Mapping: Supports conversion from MJAI strings ("E", "S", "W", "N") internal/domain/game/wind/wind.go16-29

Title "Seat and Wind Domain Entities"

Sources: internal/domain/game/seat/seat.go

Implementation Details

Red Five Conversions

The system provides explicit methods to transition between red and black variants of tiles.

• AddRed(): Converts 5m, 5p, or 5s to their red versions (IDs 34, 35, 36). Returns the original tile if no red version exists internal/domain/game/tile/tile.go202-213
• RemoveRed(): Converts red fives back to standard black tiles (IDs 4, 13, 22) internal/domain/game/tile/tile.go215-226

Meld Integration

Tile primitives are heavily used in the meld package to enforce mahjong rules during calls:

• Pon: Validates that three tiles have the same symbol via CountSameSymbol and limits red fives to one per meld internal/domain/game/round/player/meld/pon.go17-27
• Kan Variants:
  • ConcealedKan: Ensures four-of-a-kind and handles red five placement internal/domain/game/round/player/meld/concealed_kan.go14-31
  • CalledKan: Validates four identical symbols including exactly one red five for numerical 5s internal/domain/game/round/player/meld/called_kan.go17-27
  • PromotedKan: Validates the addition of a fourth tile to an existing Pon internal/domain/game/round/player/meld/promoted_kan.go23-33

Swap Call (Kuikae) Support

The SwapCallTiles() method in meld.Pon provides the tiles that are restricted for discard immediately after a call to prevent illegal swap calls (kuikae). For numerical 5s, it returns both the black and red variants internal/domain/game/round/player/meld/pon.go70-76

Sources:

• internal/domain/game/tile/tile.go1-231
• internal/domain/game/tile/tiles.go1-70
• internal/domain/game/seat/seat.go1-42
• internal/domain/game/wind/wind.go1-60
• internal/domain/game/round/player/meld/pon.go10-76
• internal/domain/game/round/player/meld/concealed_kan.go10-31
• internal/domain/game/round/player/meld/called_kan.go10-39
• internal/domain/game/round/player/meld/promoted_kan.go10-47