\documentclass{article}

\usepackage[a4paper,margin=24mm]{geometry}
\usepackage{array}
\usepackage{booktabs}
\usepackage{longtable}
\usepackage{hyperref}
\usepackage{float}
\hypersetup{
  pdftitle={The mahjong-tiles Package},
  pdfauthor={Lilia Chen May Wither},
  pdfsubject={Typesetting Riichi Mahjong hands, flower tiles, discard rivers, and score sticks},
  pdfkeywords={LaTeX, Mahjong, Riichi, MPSZF, flower tiles, score sticks, CTAN}
}
\usepackage{mahjong-tiles}

\setlength\parindent{0pt}
\setlength\parskip{6pt}
\newcommand\pkg[1]{\textsf{#1}}
\newcommand\cmd[1]{\texttt{\string#1}}
\newcommand\meta[1]{\ensuremath{\langle}\textit{#1}\ensuremath{\rangle}}
\newcommand\code[1]{\texttt{\detokenize{#1}}}
\newcolumntype{L}[1]{>{\raggedright\arraybackslash}p{#1}}

\title{The \pkg{mahjong-tiles} Package\\\large Typesetting Riichi Mahjong Hands, Flower Tiles, Discard Rivers, and Score Sticks}
\author{Lilia Chen May Wither}
\date{Version 2.6.2, 2026-09-05}

\begin{document}
\maketitle

\begin{abstract}
\pkg{mahjong-tiles} typesets Japanese/Riichi Mahjong tiles from compact MPSZF notation.
It provides a document command, \cmd{\mahjong}, for hands and melds, and
\cmd{\mahjongriver} for discard rivers, and \cmd{\stick} for score-stick
images.  It supports red fives, flower tiles, face-down and blank tiles, rotated
and stacked tiles, concealed-kong shorthand, overlay notes, local and global size
options, and recolouring of tile backs.
\end{abstract}

\section{Loading the package}

A minimal document looks like this.

\begin{verbatim}
\documentclass{article}
\usepackage{mahjong-tiles}
\begin{document}
\mahjong{111m456s111p11122z}
\end{document}
\end{verbatim}

If you are working from the CTAN source archive, generate the runtime package file first:

\begin{verbatim}
latex mahjong-tiles.ins
\end{verbatim}

The distributed user manual is \path{doc/mahjong-tiles-doc.pdf}, and its
source is \path{doc/mahjong-tiles-doc.tex}.  The documented implementation is
split between the top-level driver \path{mahjong-tiles.dtx} and the fragments in
\path{dtx/}; \path{mahjong-tiles.ins} extracts the runtime style file from those
fragments.

With the default artwork paths, install these items together in the same
TeX-searchable package directory:

\begin{verbatim}
mahjong-tiles.sty
tiles/
assets/stick/
\end{verbatim}

\section{Package options}

Options can be supplied when loading the package or changed later with
\cmd{\mahjongtilessetup}.

\begin{verbatim}
\usepackage[
  height=1.5\baselineskip,
  scale=0.75,
  color=blue!70!black,
  aka=1
]{mahjong-tiles}

\mahjongtilessetup{height=1.5\baselineskip,scale=0.75,color=teal!65!black,aka=1}
\end{verbatim}

\begin{longtable}{@{}L{0.25\linewidth}L{0.22\linewidth}L{0.45\linewidth}@{}}
\toprule
Option & Default & Description \\
\midrule
\texttt{height} & \verb|\baselineskip| & Height of one upright tile. \\
\texttt{scale} & \texttt{0.75} & Scale factor for the tile symbol relative to the tile face. \\
\texttt{tile-dir} & \texttt{tiles} & Directory containing the tile PDF files. \\
\texttt{color} & \texttt{none} & Recolour the tile back.  Use any \pkg{xcolor} colour expression, or \texttt{none} for the embedded artwork. \\
\texttt{aka} & \texttt{1} & Red-five mode: \texttt{0} disables red fives and maps \texttt{0m}, \texttt{0p}, and \texttt{0s} to regular fives; \texttt{1} renders them normally; \texttt{2} also makes \texttt{55555p} show an extra red five pin in concealed-kong shorthand. \\
\texttt{river-cols} & \texttt{6} & Number of tiles per discard-river row. \\
\texttt{river-row-gap} & \texttt{0pt} & Vertical gap between discard-river rows. \\
\texttt{overlay-style} & TikZ node options & Style applied to overlay notes. \\
\texttt{stick-dir} & \texttt{assets/stick} & Directory containing the score-stick PDF files. \\
\texttt{stick-height} & \verb|\baselineskip| & Height of one upright score-stick image. \\
\texttt{stick-scale} & \texttt{.5} & Scale factor applied to score-stick images. \\
\texttt{stick-sep} & \texttt{.6em} & Horizontal space between different score-stick groups. \\
\bottomrule
\end{longtable}

\section{The \cmd{\mahjong} command}

\begin{verbatim}
\mahjong{<tiles>}
\mahjong[<height>][<scale>][<back-colour>][<local-keys>]{<tiles>}
\mahjong[<local-keys>]{<tiles>}
\end{verbatim}

The first optional argument also accepts a key-value list.  This allows compact
local overrides such as:

\begin{verbatim}
\mahjong[height=1.5\baselineskip,scale=0.75,color=teal!65!black,aka=0]{x 0m0p0s}
\end{verbatim}

\section{MPSZF notation}

A tile is written as one or more digits followed by a suit letter.  The suits are
\texttt{m} for manzu, \texttt{p} for pinzu, \texttt{s} for souzu, \texttt{z}
for honors, and \texttt{f} for flower tiles.
\begin{table}[H]
  \centering
  \caption[MPSZF reference]{MPSZF notation reference. Each tile is identified by its column's number and its row's letter.}
  \label{tab:mpszfref}
  \begin{tabular}{ccccccccccc}
     & \textbf{0} & \textbf{1} & \textbf{2} & \textbf{3} & \textbf{4} & \textbf{5} & \textbf{6} & \textbf{7} & \textbf{8} & \textbf{9} \\
     \textbf{s} & \raisebox{-.75\baselineskip}{\mahjong{0s}} & \mahjong{1s} & \mahjong{2s} & \mahjong{3s} & \mahjong{4s} & \mahjong{5s} & \mahjong{6s} & \mahjong{7s} & \mahjong{8s} & \mahjong{9s} \\
     \textbf{p} & \mahjong{0p} & \mahjong{1p} & \mahjong{2p} & \mahjong{3p} & \mahjong{4p} & \mahjong{5p} & \mahjong{6p} & \mahjong{7p} & \mahjong{8p} & \mahjong{9p} \\
     \textbf{m} & \mahjong{0m} & \mahjong{1m} & \mahjong{2m} & \mahjong{3m} & \mahjong{4m} & \mahjong{5m} & \mahjong{6m} & \mahjong{7m} & \mahjong{8m} & \mahjong{9m} \\
     \textbf{z} & & \mahjong{1z} & \mahjong{2z} & \mahjong{3z} & \mahjong{4z} & \mahjong{5z} & \mahjong{6z} & \mahjong{7z} & & \\
     \textbf{f} & \mahjong{0f} & \mahjong{1f} & \mahjong{2f} & \mahjong{3f} & \mahjong{4f} & \mahjong{5f} & \mahjong{6f} & \mahjong{7f} & \mahjong{8f} & \\
  \end{tabular}
\end{table}

The table below shows some examples of combinations.

\begin{longtable}{@{}L{0.32\linewidth}L{0.58\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{111m456s111p11122z} & \mahjong{111m456s111p11122z} \\
\code{1112345678999p} & \mahjong{1112345678999p} \\
\code{19m19s19p1234567z} & \mahjong{19m19s19p1234567z} \\
\code{012345678f} & \mahjong{012345678f} \\
\code{123m55p12f} & \mahjong{123m55p12f} \\
\bottomrule
\end{longtable}

\subsection{Special tokens}

\begin{longtable}{@{}L{0.18\linewidth}L{0.72\linewidth}@{}}
\toprule
Token & Meaning \\
\midrule
\texttt{0m}, \texttt{0p}, \texttt{0s} & Red fives: \mahjong{0m0p0s} \\
\texttt{x} & Face-down tile: \mahjong{x} \\
\texttt{?} & Unknown blank tile: \mahjong{?} \\
\texttt{-} & Full visual gap between groups. \\
\texttt{N-} & Proportional gap of \texttt{N/7} of one tile width, for example \texttt{2-}. \\
\bottomrule
\end{longtable}

\subsection{Rotated and stacked tiles}

The marker \texttt{*} or an apostrophe rotates the preceding tile sideways.  For
ordinary tiles, the marker \texttt{+} or a double quote stacks two sideways
copies of the preceding tile, which is useful for kan notation.

There is also red-five edge syntax for upgraded-kan notation.  With \texttt{aka}
enabled, \texttt{0m"}, \texttt{0p"}, and \texttt{0s"} produce a mixed sideways
stack with the red five at the bottom and the regular five at the top.  Repeating
the stack marker twice, as in \texttt{0p""} or \texttt{0p++}, flips the red five
to the top.  Three markers, \texttt{0p"""} or \texttt{0p+++}, force two red fives
and deliberately ignore \texttt{aka}.  The same rule applies to \texttt{m},
\texttt{p}, and \texttt{s}.

\begin{longtable}{@{}L{0.36\linewidth}L{0.54\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{111m111s111p22z2-3*333z} & \mahjong{111m111s111p22z2-3*333z} \\
\code{123m-xx?4p'5p"0s} & \mahjong{123m-xx?4p'5p"0s} \\
\code{0p" 0p"" 0p"""} & \mahjong{0p" 0p"" 0p"""} \\
\code{0p+ 0p++ 0p+++} & \mahjong{0p+ 0p++ 0p+++} \\
\code{aka=0: 0p" 0p"" 0p"""} & \mahjong[aka=0]{0p" 0p"" 0p"""} \\
\bottomrule
\end{longtable}

\subsection{Red fives and the \texttt{aka} option}

Red fives are controlled by the integer \texttt{aka} option.  The default
\texttt{aka=1} renders \texttt{0m}, \texttt{0p}, and \texttt{0s} as red fives.
Set \texttt{aka=0} to suppress red fives and render those inputs as regular
fives.  Set \texttt{aka=2} to keep normal red fives and add one more red five
pin in the \texttt{55555p} concealed-kong shorthand.

\begin{longtable}{@{}L{0.36\linewidth}L{0.54\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{0m0p0s55555m} & \mahjong{0m0p0s55555m} \\
\code{\mahjong[aka=0]{0m0p0s55555p}} & \mahjong[aka=0]{0m0p0s55555p} \\
\code{\mahjong[aka=2]{55555p}} & \mahjong[aka=2]{55555p} \\
\bottomrule
\end{longtable}

\subsection{Concealed kongs}

Five identical consecutive digits followed by a suit are rendered as a concealed
kan: a face-down tile, two visible tiles, and a face-down tile.  For suited fives,
the visible pair is controlled by \texttt{aka}: \texttt{aka=0} gives two regular
fives, \texttt{aka=1} gives a red five plus a regular five, and \texttt{aka=2}
gives \texttt{55555p} two red five-pin tiles.

\begin{longtable}{@{}L{0.36\linewidth}L{0.54\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{55555p} & \mahjong{55555p} \\
\code{33333z} & \mahjong{33333z} \\
\code{\mahjong[aka=0]{55555s}} & \mahjong[aka=0]{55555s} \\
\code{\mahjong[aka=2]{55555p}} & \mahjong[aka=2]{55555p} \\
\bottomrule
\end{longtable}

For compatibility with older documents, the deprecated option
\texttt{no-aka} is still accepted and emits a package warning.
\texttt{no-aka=1} is equivalent to \texttt{aka=0}; \texttt{no-aka=0} is
equivalent to \texttt{aka=1}.  New documents should use \texttt{aka} directly.

\begin{verbatim}
\mahjong[aka=0]{0m0p0s}
% Deprecated:
\mahjong[no-aka=1]{0m0p0s}
\end{verbatim}

\section{Tile-back recolouring}

The tile-back colour can be set globally or locally.  The colour value is passed
to \pkg{xcolor}.  The special value \texttt{none} restores the embedded back tile.

\begin{verbatim}
\mahjongtilessetup{color=purple!70!black}
\mahjong{x x x}

\mahjong[color=teal!65!black]{x x x}
\mahjong[color=none]{x x x}
\end{verbatim}

\begin{center}
\mahjongtilessetup{color=purple!70!black}
\mahjong{x x x}\quad
\mahjong[color=teal!65!black]{x x x}\quad
\mahjong[color=none]{x x x}
\end{center}
\mahjongtilessetup{color=none}

\section{Discard rivers}

The \cmd{\mahjongriver} command uses the same notation as \cmd{\mahjong}, but it
breaks tiles into rows.  The row length is controlled by \texttt{river-cols}.

\begin{verbatim}
\mahjongriver{1m9m2z5z3s6s1s1m8p4z87m}
\mahjongriver[river-cols=6]{1m9m2z5z3s6s1s*1m8p4z87m}
\end{verbatim}

\begin{center}
\mahjongriver{1m9m2z5z3s6s1s1m8p4z87m}

\mahjongriver[river-cols=6]{1m9m2z5z3s6s1s*1m8p4z87m}
\end{center}

\section{Score sticks}

The \cmd{\stick} command typesets Japanese Mahjong score sticks.  The argument
may be a three-digit shorthand amount, or a manual specification of stick
counts.

A three-digit input is interpreted as hundreds of points.  For example,
\texttt{305} represents \texttt{30500} points.  The package decomposes the value
into an optimal combination of \texttt{10k}, \texttt{5k}, \texttt{1k}, and
\texttt{100} sticks.

The default artwork directory is \texttt{assets/stick/}.  It should contain
\texttt{10k.pdf}, \texttt{5k.pdf}, \texttt{1k.pdf}, and \texttt{100.pdf}.

\begin{longtable}{@{}L{0.42\linewidth}L{0.48\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{\stick{305}} & \stick{305} \\
\code{\stick{089}} & \stick{089} \\
\code{\stick{250}} & \stick{250} \\
\bottomrule
\end{longtable}

For \texttt{305}, the automatic decomposition is:

\begin{verbatim}
10k \ctimes 3
100 \ctimes 5
\end{verbatim}

Manual input is also supported.  The key-value form names each stick type
explicitly.

\begin{longtable}{@{}L{0.42\linewidth}L{0.48\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{\stick{10k=3,100=5}} & \stick{10k=3,100=5} \\
\code{\stick{5k=1,1k=2,100=4}} & \stick{5k=1,1k=2,100=4} \\
\bottomrule
\end{longtable}

The compact comma-list form gives the counts in the order
\texttt{10k}, \texttt{5k}, \texttt{1k}, \texttt{100}.

\begin{longtable}{@{}L{0.42\linewidth}L{0.48\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{\stick{3,0,0,5}} & \stick{3,0,0,5} \\
\code{\stick[manual]{0,1,2,4}} & \stick[manual]{0,1,2,4} \\
\bottomrule
\end{longtable}

The command accepts local options.  These options affect only the current
\cmd{\stick} call.

\begin{longtable}{@{}L{0.42\linewidth}L{0.48\linewidth}@{}}
\toprule
Input & Output \\
\midrule
\code{\stick[height=2em,scale=1]{305}} &
  \stick[height=2em,scale=1]{305} \\
\bottomrule
\end{longtable}

The score-stick defaults can also be changed globally:

\begin{verbatim}
\mahjongtilessetup{
  stick-dir=assets/stick,
  stick-height=1.2em,
  stick-scale=1,
  stick-sep=.6em
}
\end{verbatim}

If the artwork is installed somewhere else, set \texttt{stick-dir} accordingly:

\begin{verbatim}
\mahjongtilessetup{stick-dir=path/to/assets/stick}
\end{verbatim}

\section{Overlay notes}

The \cmd{\mahjong} command supports text annotations.  Use \texttt{[]} in
\cmd{\mahjong} to attach a note above the previous tile.

Annotations may contain ordinary \TeX{} material.  Mahjong tiles inside an
annotation are rendered only when they are explicitly wrapped in \cmd{\mj}.
For example, \code{[waiting \mj{3m}]} prints the text "waiting" followed by a
small mahjong tile in the annotation.  The \cmd{\mj} command is parsed only one
level deep inside annotations.

The \cmd{\mj} command may also be used directly inside \cmd{\mahjong}.  In
that case, its argument must contain exactly one tile.  The tile is typeset
as a normal-size rotated tile above the hand, which is useful for showing a
drawn tile.

\begin{longtable}{@{}L{0.48\linewidth}L{0.48\linewidth}@{}}
  \toprule
  Input & Output \\
  \midrule
  \code{111m111s111p2z2-3*333z7-2z[waiting]} &
    \mahjong{111m111s111p2z2-3*333z7-2z[waiting]} \\
  \code{123m456p789s\mj{2z}11z} &
    \mahjong{123m456p789s\mj{2z}11z} \\
  \code{111m113s111p2z2-3*333z7-2z[discard \mj{3s},\\ waiting \mj{1s2-2z}]} &
    \mahjong{111m113s111p2z2-3*333z7-2z[discard \mj{3s},\\ waiting \mj{1s2-2z}]} \\
  \code{3333z[note]} &
    \mahjong{3333z[note]} \\
  \bottomrule
  \end{longtable}

When a note is added to the fifth tile of a concealed kong shorthand, a
warning
\texttt{Overlay text '<overlay text>' is attached to the final back tile of
a concealed kong.}
will be triggered.  Since a concealed kong is rendered as four tiles, the
note is moved to the fourth rendered tile, namely the final back tile.


\section{Expl3 interface}

For package authors who prefer an expl3-style interface, mahjong-tiles also exposes:

\begin{verbatim}
\ExplSyntaxOn
\mahjongtiles_typeset_hand:n  {111m456s111p11122z}
\mahjongtiles:n               {111m456s111p11122z}
\mahjongtiles_typeset_river:n {1m2m3m4m5m6m7m8m9m}
\mahjongtilesriver:n          {1m2m3m4m5m6m7m8m9m}
\ExplSyntaxOff
\end{verbatim}

\section{Attribution and licence}

The LaTeX package code is distributed under the MIT Licence.  Portions are based
on Daniel Schmitz's \pkg{mahjong} package, copyright 2021 Daniel Schmitz, also
under the MIT Licence.

The tile artwork in \texttt{tiles/} is derived from FluffyStuff's
\texttt{riichi-mahjong-tiles} project.  The upstream licence file places that
work in the public domain/CC0.  Attribution is retained here and in the README.

Additional flower-tile artwork in \texttt{tiles-tmp/} and score-stick assets in
\texttt{assets/} were created by Lilia Chen May Wither and are also used under
public domain/CC0 terms.

\end{document}