% mahjonggame.tex -- User manual for the mahjonggame package
% Copyright 2026 Clignniis
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of the license is in
%   https://www.latex-project.org/lppl.txt
%
% This work has the LPPL maintenance status `maintained'.
% The Current Maintainer of this work is Clignniis.

\documentclass[a4paper,11pt]{article}
\usepackage{mahjonggame}
\usepackage[a4paper,margin=22mm]{geometry}
\usepackage{hyperref}
\usepackage{booktabs}
\usepackage{array}
\usepackage{enumitem}
\usepackage{microtype}
\usepackage{listings}

\hypersetup{
  colorlinks=true,
  linkcolor=blue!55!black,
  urlcolor=blue!55!black,
  pdftitle={The mahjonggame Package},
  pdfauthor={Clignniis}
}

\lstset{
  basicstyle=\ttfamily\small,
  columns=fullflexible,
  frame=single,
  framerule=.4pt,
  breaklines=true,
  showstringspaces=false
}

\newcommand{\pkg}{\textsf{mahjonggame}}
\newcommand{\cmd}[1]{\texttt{\textbackslash#1}}
\newcommand{\opt}[1]{\texttt{#1}}

\title{The \pkg{} Package\\[2mm]\large Drawing Mahjong Tiles and Game Layouts with LaTeX3 and TikZ}
\author{Clignniis}
\date{Version 0.7.0}

\begin{document}
\maketitle
\tableofcontents

\section{Introduction}

\pkg{} is a LaTeX package implemented with LaTeX3 and TikZ for drawing Mahjong tiles and complete Mahjong game layouts. It is intended for game records, teaching materials, articles, notes, and other documents in which Mahjong tiles need to appear as real graphics rather than as plain text.

The package is designed primarily for Chinese-language Mahjong documentation. It loads \texttt{ctex} with a plain scheme so that Chinese text can be used in commands such as \cmd{aWind}, while the surrounding document can retain ordinary English headings and table-of-contents labels.

The most important public interfaces are:
\begin{itemize}[nosep]
  \item \cmd{tile}: draw a tile sequence, with an optional overall scale;
  \item \cmd{tail}: convenient shorthand for a tile sequence without a separate scale argument;
  \item the \texttt{game} environment: draw a complete Mahjong table;
  \item \cmd{aWind}--\cmd{dWind}, \cmd{aScore}--\cmd{dScore}: player information;
  \item \cmd{aDiscard}--\cmd{dDiscard}, \cmd{aHand}--\cmd{dHand}, \cmd{aClaim}--\cmd{dClaim}, \cmd{aFlower}--\cmd{dFlower}: game components;
  \item \cmd{round}, \cmd{dora}, \cmd{totaltiles}, and \cmd{info}: game-state information.
\end{itemize}

\section{Installation}

Place \texttt{mahjonggame.sty} in the same directory as your document or in a directory searched by TeX. Then load the package with:

\begin{lstlisting}
\usepackage{mahjonggame}
\end{lstlisting}

XeLaTeX or LuaLaTeX is recommended, especially when Chinese text is present.

\section{Tile notation}

A tile is written as one digit followed by one letter. The current package provides the following tile faces:

\begin{center}
\begin{tabular}{>{\ttfamily}c l l}
\toprule
Code & Meaning & Values \\
\midrule
m & Manzu & 0--9 \\
s & Souzu & 0--9 \\
p & Pinzu & 0--9 \\
z & Honor tiles & 0--7 \\
f & Flower tiles & 1--8 \\
\bottomrule
\end{tabular}
\end{center}

The three codes \texttt{0m}, \texttt{0s}, and \texttt{0p} are red fives. The code \texttt{0z} is used as the tile back when the Dora indicator is padded to five tiles.

The physical tile is one unit wide and 1.4 units high before rotation. Tile sequences are tightly packed according to the actual axis-aligned size of each tile.

\subsection{Basic examples}

\begin{lstlisting}
\tile{1m}
\tile{5s}
\tile{7z}
\tile{0p}
\tile{123456m}
\end{lstlisting}

The corresponding output is shown below.

\begin{center}
  \tile{1m}\quad
  \tile{5s}\quad
  \tile{7z}\quad
  \tile{0p}

  \medskip
  \tile{123456m}
\end{center}

\section{The \cmd{tile} command}

The general form is:

\begin{lstlisting}
\tile[<scale>]{<tile sequence>}
\end{lstlisting}

The optional argument scales the complete sequence. Scaling is therefore applied to the whole tile drawing rather than to individual tile options.

\begin{lstlisting}
\tile{123m;456s;789p}
\tile[0.7]{123456789m}
\tile[1.4]{123m}
\end{lstlisting}

\begin{center}
  \tile{123m;456s;789p}

  \medskip
  \tile[0.7]{123456789m}

  \medskip
  \tile[1.4]{123m}
\end{center}

The individual-tile \opt{scale} option is deliberately not supported. For example, use \texttt{\string\tile[2]\{1m\}} rather than attaching \opt{scale=2} to the tile itself.

\section{Compact notation and \cmd{tail}}

The same compact parser is used by the drawing interfaces, not only by \cmd{tail}. For example, the following can be used directly in a game command:

\begin{lstlisting}
\aHand{123456m}
\aDiscard{123m;456s;789p}
\end{lstlisting}

\subsection{Ordinary shorthand}

A sequence of digits followed by a suit letter expands into individual tiles.

\begin{lstlisting}
\tail{123m}
\tail{456s}
\tail{00555z}
\end{lstlisting}

\begin{center}
  \tail{123m}\qquad
  \tail{456s}\qquad
  \tail{00555z}
\end{center}

\subsection{Directional shorthand}

A single marker can be placed after a digit. It applies to the immediately preceding digit.

\begin{center}
\begin{tabular}{>{\ttfamily}c l}
\toprule
Marker & Meaning \\
\midrule
`   & \opt{direction=left} \\
``  & \opt{direction=left} followed by \opt{direction=add} \\
'   & \opt{direction=right} \\
''  & \opt{direction=right} followed by \opt{direction=add} \\
\(*\)   & \opt{direction=reach} \\
\bottomrule
\end{tabular}
\end{center}

For example:

\begin{lstlisting}
\tail{123`45m}
\tail{123''45m}
\tail{1*2345m}
\end{lstlisting}

\begin{center}
  \tail{123`45m}

  \medskip
  \tail{123''45m}

  \medskip
  \tail{1*2345m}
\end{center}

The keyboard-independent aliases \cmd{lq}, \cmd{rq}, and \cmd{star} are also accepted in the shorthand parser:

\begin{lstlisting}
\tile{12\lq34m}
\tile{12\rq34s}
\tile{12\star34p}
\end{lstlisting}

\subsection{The \cmd{tail} command}

\cmd{tail} is a convenience command for tile sequences. It uses the same tile parser and drawing engine as \cmd{tile}, but it does not have a separate optional scale argument.

\begin{lstlisting}
\tail{123m;456s}
\end{lstlisting}

This is equivalent in effect to:

\begin{lstlisting}
\tile{123m;456s}
\end{lstlisting}

\section{Tile options}

A complete tile can carry options in square brackets:

\begin{lstlisting}
1s[direction=left]
5m[color=yellow]
1s[function={emph,flash,take}]
\end{lstlisting}

\subsection{direction}

The available directions are:
\begin{description}[style=nextline,leftmargin=1.5cm]
  \item[\opt{normal}] upright tile;
  \item[\opt{left}] rotate the tile 90 degrees counterclockwise;
  \item[\opt{right}] rotate the tile 90 degrees clockwise;
  \item[\opt{reach}] rotate the tile counterclockwise and raise it by 0.2 units;
  \item[\opt{add}] place a second tile above the previous horizontally placed tile. The previous tile must have \opt{left} or \opt{right} direction.
\end{description}

\begin{lstlisting}
\tile{1m;2m[direction=left];3m}
\tile{1m;2m[direction=right];3m}
\tile{1m;2m[direction=reach];3m}
\tile{1m;2m[direction=left];2m[direction=add];3m}
\end{lstlisting}

\begin{center}
  \tile{1m;2m[direction=left];3m}\quad
  \tile{1m;2m[direction=right];3m}\quad
  \tile{1m;2m[direction=reach];3m}\quad
  \tile{1m;2m[direction=left];2m[direction=add];3m}
\end{center}

\subsection{color}

The \opt{color} option changes the background colour of the selected tile.

\begin{lstlisting}
\tile{5m[color=yellow];5s[color=blue];5p[color=green!35]}
\end{lstlisting}

\begin{center}
  \tile{5m[color=yellow];5s[color=blue];5p[color=green!35]}
\end{center}

\subsection{function}

The \opt{function} option accepts a comma-separated list, so several effects may be applied to the same tile.

\begin{lstlisting}
\tile{1s[function={emph,flash,take}]}
\tile{2s[function={flash}]}
\tile{3s[function={take}]}
\end{lstlisting}

\begin{center}
  \tile{1s[function={emph,flash,take}]}\qquad
  \tile{2s[function={flash}]}\qquad
  \tile{3s[function={take}]}
\end{center}

The functions are deliberately attached to a tile item; they are not independent drawing objects.

\section{Spacing}

A half-unit gap can be inserted with \texttt{-}. Arbitrary spacing can be introduced with \texttt{gap=<number>}.

\begin{lstlisting}
\tile{123m;-;456m}
\tile{123m;gap=0.75;456m}
\end{lstlisting}

\begin{center}
  \tile{123m;-;456m}

  \medskip
  \tile{123m;gap=0.75;456m}
\end{center}

Spacing items do not count as Mahjong tiles.

\section{The \texttt{game} environment}

The \texttt{game} environment provides a 28 by 28 unit coordinate system from \((-14,-14)\) to \((14,14)\). Its default scale is 1, so one game unit corresponds to 1\,cm.

It is best treated as a graphical object and placed inside a normal floating figure when an appropriate layout is desired.

\begin{figure}[p]
  \centering
  \begin{game}[0.58]
    \aWind{北}
    \bWind{東}
    \cWind{南}
    \dWind{西}
    \aScore{32000}
    \bScore{25900}
    \cScore{18100}
    \dScore{23000}
    \round{東2局}
    \aDiscard{3z;1p;9p;2m;4z[color=gray];6z;7m[color=gray];4s[color=gray];8m[color=gray];7s[color=gray];0s[color=gray];22s}
    \bDiscard{7z;2m;4p[color=gray];9s;3p[color=gray];5s;4z[color=gray];3z[color=gray];5z[color=gray];3m;7p;5m;3s}
    \cDiscard{4z;9p;2z[color=gray];3z[color=gray];4z[color=gray];5z;1p;1z[color=gray];28m;2*s;9m[color=gray];1s[color=gray]}
    \dDiscard{9m[color=gray];3s[color=gray];6s[color=gray];6s[color=gray];8p[color=gray];8s[color=gray];4s[color=gray];4m[color=gray];1m[color=gray];1z[color=gray];1z[color=gray]}
    \aHand{89p;22z;-;8m}
    \bHand{45666m;267p;789s;66z}
    \cHand{67899m;24p;345678s}
    \dHand{117m;133578p;12s;23z}
    \aClaim{4`06p;3`45m;777'z}
    \dora{7s}
    \info[][0][1]
  \end{game}
  \caption{A complete four-player Mahjong game layout.(A)}
\end{figure}

\begin{figure}[p]
  \centering
  \begin{game}[0.58]
    \aWind{東}
    \bWind{南}
    \cWind{西}
    \dWind{北}
    \aScore{0}
    \bScore{0}
    \cScore{0}
    \dScore{0}
    \round{東风南}
    \aDiscard{62z;6m;6z;1m;1z;3s;5m;7z;9p;5z;7p;9p[function={emph}]}
    \bDiscard{2788m;28s;62m;45s;5z;2s;1m}
    \cDiscard{9m;9s;2m;9s;33z;3s;7m;5z;6p;63z;1p}
    \dDiscard{532p;49m;7p;8m;98s;18p}
    \aHand{445p;6678s}
    \bHand{0000000000z}
    \cHand{0000000000000z}
    \dHand{0000000000000z}
    \aClaim{4`56s;2`13s}
    \bClaim{2`13p}
    \aFlower{64f}
    \bFlower{1f}
    \dFlower{82f}
    \totaltiles{144}
  \end{game}
  \caption{A complete four-player Mahjong game layout.(B)}
\end{figure}

\subsection{Player-relative commands}

The four player prefixes represent four rotations of the same local layout:
\begin{center}
\begin{tabular}{>{\ttfamily}c l}
\toprule
Prefix & Rotation \\
\midrule
a & 0 degrees \\
b & 90 degrees counterclockwise \\
c & 180 degrees \\
d & 270 degrees counterclockwise \\
\bottomrule
\end{tabular}
\end{center}

The wind labels, scores, discards, hands, claims, and flowers follow the corresponding player orientation.

\subsection{Wind and score}

\begin{lstlisting}
\aWind{东}
\bWind{南}
\cWind{西}
\dWind{北}
\aScore{25000}
\bScore{24000}
\cScore{26000}
\dScore{26000}
\end{lstlisting}

Optional overlay keys such as \opt{color} may be supplied when needed. In normal use the defaults are recommended because the game table is designed around a coordinated colour scheme.

\subsection{Discards}

Discards are expanded before they are grouped and positioned.

\begin{lstlisting}
\aDiscard{123456m;789s;123p}
\bDiscard{456m;789p;123s}
\end{lstlisting}

Compact notation therefore works directly inside game commands.

\subsection{Hand}

The hand is centered in the local player coordinate system with its baseline at the bottom of the table.

\begin{lstlisting}
\aHand{123456m;789s;11z}
\end{lstlisting}

\subsection{Claims and flowers}

Claims are right-aligned and flowers are displayed in the dedicated flower area.

\begin{lstlisting}
\aClaim{111z;555m}
\aFlower{1f;2f}
\end{lstlisting}

\section{Game-state information}

\subsection{Round}

The round is written directly on the central wind panel:

\begin{lstlisting}
\round{東1局}
\end{lstlisting}

\subsection{Total tile count}

\cmd{totaltiles} specifies the total number of tiles used by the game. The package then subtracts the valid tiles placed by discard, hand, claim, and flower commands.

\begin{lstlisting}
\totaltiles{136}
\end{lstlisting}

Spacing tokens and Dora indicators are not included in the automatic counter.

\subsection{Riichi information}

\cmd{info} combines the remaining-tile count with kyotaku and honba information for Riichi Mahjong.

\begin{lstlisting}
\info
\info[122]
\info[122][2][1]
\end{lstlisting}

The arguments are total tiles, kyotaku, and honba. When the total is omitted, the package uses 122 by default for four occupied player positions and 94 when exactly three player positions have been supplied.

The optional fourth style argument exists for advanced colour customization. In normal use it is recommended to keep the default colour, because the same colour is used for the remaining-tile display, the kyotaku/honba markers, and the point-stick graphics.

\section{Dora indicator}

Dora is normally drawn inside \texttt{game}:

\begin{lstlisting}
\dora{123m}
\dora{55z}
\dora{123456m}
\end{lstlisting}

\begin{figure}[ht]
  \centering
  \begin{game}[0.42]
    \dora{123m}
  \end{game}
  \caption{Dora indicator with automatic padding.}
\end{figure}

Only ordinary compact notation such as \texttt{123m} and \texttt{55z} is intended for \cmd{dora}. Up to five actual tiles are shown; if fewer than five are supplied, the remaining positions are padded with \texttt{0z}, which is the tile back. Dora indicators are not included in the game tile counter.

\section{Table styling}

The \texttt{game} environment accepts these table-level options:

\begin{center}
\begin{tabular}{>{\ttfamily}p{3.8cm} p{6.8cm}}
\toprule
Option & Meaning \\
\midrule
edge-color & outer table edge \\
cloth-color & main table cloth \\
wind-color & central wind panel \\
wind-pattern-color & central panel pattern \\
text-color & default colour of game information \\
\bottomrule
\end{tabular}
\end{center}

For example:

\begin{lstlisting}
\begin{game}[0.58][
  edge-color=mahogany,
  cloth-color=mahnavyblue,
  wind-color=mahindigo,
  wind-pattern-color=mahtaupe,
  text-color=white
]
  ...
\end{game}
\end{lstlisting}

The default colours are recommended unless the wind-panel colour is changed to a sufficiently light colour.

\section{Complete compact example}

The following example demonstrates the intended style of use:

\begin{lstlisting}
% Riichi Mahjong
\begin{game}[0.58]
  \aWind{北}
  \bWind{東}
  \cWind{南}
  \dWind{西}
  \aScore{32000}
  \bScore{25900}
  \cScore{18100}
  \dScore{23000}
  \round{東2局}
  \aDiscard{3z;1p;9p;2m;4z[color=gray];6z;7m[color=gray];4s[color=gray];8m[color=gray];7s[color=gray];0s[color=gray];22s}
  \bDiscard{7z;2m;4p[color=gray];9s;3p[color=gray];5s;4z[color=gray];3z[color=gray];5z[color=gray];3m;7p;5m;3s}
  \cDiscard{4z;9p;2z[color=gray];3z[color=gray];4z[color=gray];5z;1p;1z[color=gray];28m;2*s;9m[color=gray];1s[color=gray]}
  \dDiscard{9m[color=gray];3s[color=gray];6s[color=gray];6s[color=gray];8p[color=gray];8s[color=gray];4s[color=gray];4m[color=gray];1m[color=gray];1z[color=gray];1z[color=gray]}
  \aHand{89p;22z;-;8m}
  \bHand{45666m;267p;789s;66z}
  \cHand{67899m;24p;345678s}
  \dHand{117m;133578p;12s;23z}
  \aClaim{4`06p;3`45m;777'z}
  \dora{7s}
  \info[][0][1]
\end{game}

% Chinese Standard Mahjong
\begin{game}[0.58]
  \aWind{東}
  \bWind{南}
  \cWind{西}
  \dWind{北}
  \aScore{0}
  \bScore{0}
  \cScore{0}
  \dScore{0}
  \round{東风南}
  \aDiscard{62z;6m;6z;1m;1z;3s;5m;7z;9p;5z;7p;9p[function={emph}]}
  \bDiscard{2788m;28s;62m;45s;5z;2s;1m}
  \cDiscard{9m;9s;2m;9s;33z;3s;7m;5z;6p;63z;1p}
  \dDiscard{532p;49m;7p;8m;98s;18p}
  \aHand{445p;6678s}
  \bHand{0000000000z}
  \cHand{0000000000000z}
  \dHand{0000000000000z}
  \aClaim{4`56s;2`13s}
  \bClaim{2`13p}
  \aFlower{64f}
  \bFlower{1f}
  \dFlower{82f}
  \totaltiles{144}
\end{game}
\end{lstlisting}

\section{Feedback and repository}

The development repository is:

\url{https://github.com/Clignniis/latex3-mahjong}

Bug reports and feature requests can be submitted at:

\url{https://github.com/Clignniis/latex3-mahjong/issues}

The package is maintained under the name \textbf{Clignniis}.

\section{License}

\pkg{} is distributed under the LaTeX Project Public License, version 1.3c or later. The complete license text is included in the distribution as \texttt{LICENSE} and is also available from the LaTeX Project at \url{https://www.latex-project.org/lppl.txt}.

\end{document}