% File: rpgicons-doc.tex
% Copyright 2024-2026 Jasper Habicht (mail(at)jasperhabicht.de).
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License version 1.3c,
% available at http://www.latex-project.org/lppl/.
%
% This file is part of the `rpgicons'  package (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% This work has the LPPL maintenance status `maintained'.
%
\documentclass[a4paper]{article}
\def\rpgiconsfileversion{2.6.0}
\def\rpgiconsfiledate{25 February 2026}

\usepackage[T1]{fontenc}
\usepackage{Alegreya}
\usepackage{AlegreyaSans}
\usepackage{FiraMono}

\usepackage{geometry, collcell, longtable, booktabs, tcolorbox, hyperref}
\geometry{margin=25mm, left=45mm}
\urlstyle{same}

\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\renewcommand{\headrulewidth}{0pt}
\fancyfoot[R]{\thepage}

\linespread{1.1}\selectfont
\addtolength{\skip\footins}{1em plus 5pt}
\makeatletter
\renewcommand*{\thefootnote}{\fnsymbol{footnote}}
\renewcommand{\@makefntext}[1]{%
    \noindent\hbox to 0.75em{\normalfont\@thefnmark\hss}~#1%
}
\makeatother

\tcbuselibrary{listings}
\lstdefinestyle{rpgiconsdocmacro}{
    basicstyle=\small\ttfamily,
    literate={<}{{{\color{black!50}\guilsinglleft}}}{1}
        {>}{{{\color{black!50}\guilsinglright}}}{1}
        {<<}{{{\bfseries\color{black!50}\guilsinglleft}}}{1}
        {>>}{{{\bfseries\color{black!50}\guilsinglright}}}{1},
    keywords={},
    moredelim=[is][\bfseries]{|}{|},
    moredelim=[is][\color{black!50}]{!}{!},
}
\lstdefinestyle{rpgiconsdoccodeexample}{
    basicstyle=\small\ttfamily,
    literate={\%}{{{\color{black!50}\%}}}{1},
    keywords={},
}

\hypersetup{colorlinks}

\ExplSyntaxOn
\int_new:N \l_rpgicons_doc_change_int
\NewDocumentCommand{\changes}{ m m m }{
    \int_incr:N \l_rpgicons_doc_change_int
    \prop_new:c { l_rpgicons_doc_change_
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop }
    \prop_put:cnn { l_rpgicons_doc_change_
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop } { version } {#1}
    \prop_put:cnn { l_rpgicons_doc_change_
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop } { date } {#2}
    \prop_put:cnn { l_rpgicons_doc_change_
        \int_to_roman:n { \l_rpgicons_doc_change_int } _prop } { changes } {#3}
}
\NewDocumentCommand{\printchanges}{ }{
    \section{Changes}
    \begin{description}
        \setlength\itemsep{0pt}
        \int_step_inline:nn { \l_rpgicons_doc_change_int } {
            \item[
                \prop_item:cn {
                    l_rpgicons_doc_change_ \int_to_roman:n { ##1 } _prop
                } { version } ~
                \normalfont{ (
                    \prop_item:cn { l_rpgicons_doc_change_
                    \int_to_roman:n { ##1 } _prop } { date }
                ) }
            ]
            \prop_item:cn {
                l_rpgicons_doc_change_ \int_to_roman:n { ##1 } _prop
            } { changes }
        }
    \end{description}
}

\tl_new:N \l_rpgicons_doc_doctitle_tl
\NewExpandableDocumentCommand{\makedoctitle}{ o m o m m o m }{
    \hypersetup{
        pdfauthor={#5},
        pdftitle={\IfValueTF{#1}{#1}{#2}},
        pdfsubject={\IfValueTF{#3}{#3}{#4}}
    }
    \tl_set:Nn \l_rpgicons_doc_doctitle_tl {
        \group_begin:
            \tcbset{
                title ~ style ~ hook/.style={
                    boxrule=2pt,
                    fontupper=\huge\ttfamily
                }
            }
            \setlength{\parindent}{0pt}\sffamily
            \Huge{\bfseries #2}\par\bigskip
            \Large #4\par\bigskip
            \large #5
            \IfValueT{#6}{
                \,\footnote{#6}\par\bigskip
            }
            #7\par\bigskip
            \rule{\textwidth}{.08em}
        \group_end:
    }
}

\NewExpandableDocumentCommand{\printdoctitle}{ }{
    \tl_use:N \l_rpgicons_doc_doctitle_tl
}
\ExplSyntaxOff

\tcbset{
    size=small,
    arc=2.5pt,
    outer arc=2.5pt,
    colframe=black!10,
    colback=black!10,
    title style hook/.style={}
}

\NewTCBListing{macrodef}{ }{
    listing only,
    listing style={rpgiconsdocmacro},
    grow to left by=2cm,
    boxrule=0pt,
    after={\par\smallskip\noindent}
}

\NewTCBListing{codeexample}{ }{
    listing only,
    listing style={rpgiconsdoccodeexample},
    after={\par\smallskip\noindent}
}

\NewTCBListing{codeexamplecolumns}{ }{
    text side listing,
    lefthand width=4.5cm,
    listing style={rpgiconsdoccodeexample},
    after={\par\smallskip\noindent}
}

\NewTotalTCBox{\macro}{ O{} v }{
    verbatim,
    size=tight,
    arc=1pt,
    outer arc=1pt,
    top=0.5pt,
    bottom=0.5pt,
    left=2pt,
    right=2pt,
    boxrule=0pt,
    colframe=black!10,
    colback=black!10,
    fontupper=\small\ttfamily,
    #1
}{\vphantom{/g}\lstinline^#2^}

\NewTotalTCBox{\titlemacro}{ s O{} m }{
    verbatim,
    size=tight,
    arc=1pt,
    outer arc=1pt,
    top=0.5pt,
    bottom=0.5pt,
    left=2pt,
    right=2pt,
    boxrule=0pt,
    colframe=black!10,
    colback=black!10,
    fontupper=\small\ttfamily,
    title style hook,
    #2
}{\vphantom{/g}\IfBooleanT{#1}{\textbackslash}#3}

\usepackage{rpgicons-l3}
\usepackage[pics]{rpgicons-pgf}

\ExplSyntaxOn
\clist_new:N \l_rpgicons_doc_logo_icons_clist
\clist_new:N \l_rpgicons_doc_logo_colors_clist
\cs_generate_variant:Nn { \color_set:nnn } { nne }

\clist_set:Nn \l_rpgicons_doc_logo_colors_clist {
    264653 , 287271 , 2a9d8f , e9c46a , f4a261 , e76f51
}
\int_step_inline:nn { \clist_count:N \l_rpgicons_doc_logo_colors_clist } {
    \color_set:nne { rpgiconslogo \int_to_roman:n {#1} } { HTML } {
        \clist_item:Nn \l_rpgicons_doc_logo_colors_clist {#1}
    }
}
\clist_set:Nn \l_rpgicons_doc_logo_icons_clist {
    twentyside , charisma , armour , buff , ranged , proficiency
}

\NewDocumentCommand{\rpgiconslogo}{ O{1} }{
    \draw_begin:
        \draw_transform_scale:n {#1}
        \int_step_inline:nn { \clist_count:N \l_rpgicons_doc_logo_icons_clist } {
            \hcoffin_set:Nn \l_tmpa_coffin {
                \draw_suspend_begin:
                    \RPGIconsAbility[negative]{
                        \clist_item:Nn \l_rpgicons_doc_logo_icons_clist {##1}
                    }[color=rpgiconslogo \int_to_roman:n {##1} ]
                \draw_suspend_end:
            }
            \draw_scope_begin:
                \draw_transform_shift:n {
                    % fix bug in older l3draw version
                    \cs_if_exist:NTF \__draw_transform_shift:nnnn {
                        \draw_point_polar:nn { 0.33cm } { 60 * ##1 + 10 }
                    } {
                        \draw_point_transform:n { \draw_point_polar:nn { 0.33cm } { 60 * ##1 + 10 } }
                    }
                }
                \draw_coffin_use:Nnn \l_tmpa_coffin { hc } { vc }
            \draw_scope_end:
        }
    \draw_end:
}
\ExplSyntaxOff

\ExplSyntaxOn
\cs_generate_variant:Nn \property_record:nn { e }
\cs_generate_variant:Nn \property_ref:nn { e }

\int_new:N \g_rpgicons_doc_iconlist_rowc_int
\tl_new:N \l_rpgicons_doc_iconlist_this_tl
\tl_new:N \g_rpgicons_doc_iconlist_last_tl
\NewDocumentCommand { \FirstRowOnly } { O{} m } {
    \mode_leave_vertical:
    \int_gincr:N \g_rpgicons_doc_iconlist_rowc_int
    \tl_analysis_log:N \g_rpgicons_doc_iconlist_last_tl
    \tl_set:Nn \l_rpgicons_doc_iconlist_this_tl {#2}
    \tl_if_head_eq_meaning:VNT \l_rpgicons_doc_iconlist_this_tl \relax {
        \tl_remove_once:Nn \l_rpgicons_doc_iconlist_this_tl { \relax }
    }
    \tl_if_head_eq_meaning:VNF \l_rpgicons_doc_iconlist_this_tl \FirstRowOnlySkip {
        \property_record:en { rpgicons.iconlist.row. \int_use:N \g_rpgicons_doc_iconlist_rowc_int } { page }
    }
    \bool_lazy_or:nnTF {
        \tl_if_blank_p:V \l_rpgicons_doc_iconlist_this_tl
    } {
        \tl_if_eq_p:NN \g_rpgicons_doc_iconlist_last_tl \l_rpgicons_doc_iconlist_this_tl
    } {
        \int_compare:nNnF {
            \property_ref:en { rpgicons.iconlist.row. \int_use:N \g_rpgicons_doc_iconlist_rowc_int } { page }
        } = {
            \property_ref:en { rpgicons.iconlist.row. \int_eval:n { \g_rpgicons_doc_iconlist_rowc_int - 1 } } { page }
        } { \tl_use:N \g_rpgicons_doc_iconlist_last_tl #1 }
    } {
        #2
    }
    \tl_if_blank:VF \l_rpgicons_doc_iconlist_this_tl {
        \tl_gset:Nn \g_rpgicons_doc_iconlist_last_tl {#2}
    }
}
\NewDocumentCommand { \FirstRowOnlySkip } { } { }
\ExplSyntaxOff

\NewDocumentEnvironment{rpgiconsiconlist}{ }{
    \begin{longtable}{
        @{}
        >{\collectcell{\FirstRowOnly[ (cont.)]}} p{20em} <{\endcollectcell}
        p{2.5em}
        >{\raggedright\arraybackslash} p{\dimexpr\linewidth-27.5em-6\tabcolsep}
        p{5em}
        @{}
    }
    \toprule
    \FirstRowOnlySkip\textbf{Command} & \textbf{Icon} & \textbf{Shape} & \textbf{Variant} \\
    \midrule\endhead
}{
    \bottomrule
    \end{longtable}
}

\makedoctitle
    [The rpgicons package]
    {The \titlemacro{rpgicons} package}
    {A set of high-quality icons for use in notes for tabletop role-playing games}
    {Jasper Habicht}[E-mail: \href{mailto:mail@jasperhabicht.de}{mail@jasperhabicht.de}. I am grateful to Joseph Wright who fixes bugs at an astonishing speed, to Ulrike Fischer and David Carlisle for their help in adding tagging support to this package, to Max Chernoff for inspiring and guiding me in using Lua and to all other contributors to this package.]
    {Version \rpgiconsfileversion, released on \rpgiconsfiledate}

\changes{v1.1.0}{2023/08/15}{First public release.}
\changes{v1.1.1}{2023/11/15}{Fudge dice icon added.}
\changes{v1.1.2}{2023/11/16}{Bug fixed that caused wrong spacing when using dice icons without quantifier.}
\changes{v1.2.0}{2023/11/20}{Corrections in the manual. Icons for six-sided dice with one to nine pips, plus sign and minus sign added.}
%\changes{v1.2.1}{2023/11/20}{Documentation of lengths for spacing added.}
%\changes{v1.2.2}{2023/11/21}{Corrections in the manual.}
\changes{v1.3.0}{2023/11/21}{Option to set background color added. Renamed global option.}
\changes{v1.3.1}{2024/02/18}{Correction of initializing code. Correction of default value of after sep. Addition of pics.}
%\changes{v1.3.2}{2024/02/19}{Reformatting of the manual.}
%\changes{v1.3.4}{2024/02/20}{Minor corrections of some shapes.}
\changes{v1.4.0}{2024/02/21}{L3 variant added.}
%\changes{v1.4.1}{2024/02/21}{Corrections in L3 variant.}
\changes{v1.4.2}{2024/02/21}{Alternative set of commands in L3 variant defined.}
%\changes{v1.4.3}{2024/02/22}{Added option to L3 variant to enable upward compatibility.}
\changes{v1.4.4}{2024/02/24}{Added styles for every instance of command or shape, implementation of recent changes to \titlemacro{l3draw} code.}
\changes{v1.5.0}{2024/02/25}{Alternative set of commands defined, added support of styles in pics.}
\changes{v1.5.1}{2024/02/28}{Addition of opacity to L3 variant.}
%\changes{v1.5.2}{2024/02/29}{Unification of scaling, minor corrections.}
%\changes{v1.5.3}{2024/03/03}{Optimisation of code in L3 variant.}
\changes{v1.5.4}{2024/03/06}{Correction of baseline settings in L3 variant, added accessibililty support for L3 variant.}
%\changes{v1.5.5}{2024/03/07}{Optimsation of accessibililty support for L3 variant.}
\changes{v1.6.0}{2024/03/15}{Four attribute icons added, minor correction of styles.}
\changes{v1.6.1}{2024/03/16}{Unified size of negative attribute icon.}
\changes{v1.7.0}{2024/03/16}{Macro for easy typesetting using roll dice syntax added in L3 variant, compatibility mode updated.}
\changes{v1.8.0}{2024/03/24}{Unified wrapper to load either package variant.}
\changes{v1.8.2}{2024/04/28}{Roll dice syntax for PGF variant.}
%\changes{v1.8.3}{2024/05/15}{Minor compatibility fix. Example of how to use pics added to documentation.}
\changes{v1.8.4}{2024/08/08}{Bug fix in evocation spellschool shape. Unification of frames in PGF and L3 variants.}
%\changes{v1.8.6}{2024/11/13}{Fixes in the documentation.}
\changes{v1.8.8}{2025/06/15}{Adjustments to support next release of \titlemacro{l3draw} package.}
\changes{v1.9.0}{2025/06/30}{Improve check for PDF management, deprecate compatibility mode, improve accessibility support.}
\changes{v2.0.0}{2025/09/25}{Change accessibility support to automatic tagging support.}
%\changes{v2.0.1}{2025/10/05}{Fixes of bugs related to tagging support in PGF variant, added key to customize replacement text in L3 variant.}
%\changes{v2.0.2}{2025/10/10}{Improvements and fixes of PGF shapes.}
%\changes{v2.0.3}{2025/10/13}{Fixes of bugs related to tagging support in L3 variant.}
\changes{v2.0.4}{2025/10/21}{Added key to append styles for every shape or type.}
\changes{v2.1.0}{2025/10/27}{Added alignment and currency shapes.}
\changes{v2.2.0}{2025/11/05}{Added shapes for ritual spell, gems and jewellery as well as for classes. Fixes in alignment shapes and in pic definitions.}
\changes{v2.2.1}{2025/11/06}{Added alternative shapes for cleric, druid, sorcerer and necrotic. Update of class and alignment frames. Fixes in transformation keys in L3 variant.}
\changes{v2.3.0}{2025/11/16}{Added key to define custom keys in L3 variant. Added shape for emanation.}
%\changes{v2.3.1}{2025/11/25}{Updated shapes and frame for alignment.}
%\changes{v2.3.2}{2025/12/10}{Added explanation about how to combine frames and shapes.}
\changes{v2.3.3}{2025/12/15}{Added variant for wisdom shape.}
\changes{v2.4.0}{2026/01/15}{Added key to access variants for class shapes.}
\changes{v2.4.1}{2026/01/21}{Added variant for psion shape.}
\changes{v2.5.0}{2026/01/27}{Added variants for paladin, monk and wizard shapes. Standardization of key names.}
\changes{v2.5.1}{2026/02/06}{Added key to generate alias for shapes in L3 variant. Update documentation.}
\changes{v2.5.2}{2026/02/15}{Added variant for melee, bard and jewellery shape. Update documentation.}
\changes{v2.6.0}{2026/02/25}{Added functionality to precompose icons in L3 variant. Update accessibility support.}

\begin{document}

\vspace*{-1cm}
\noindent\rpgiconslogo[4]

\bigskip

\printdoctitle

\bigskip

\section{Introduction}

The \macro{rpgicons} package provides a set of high-quality icons for use in notes for tabletop role-playing games. The icons are meant to be used in the body text, but they can also be used in other contexts such as graphics or diagrams.

The package comes in two variants, a L3 variant based on the \macro{l3draw} package which is loaded per default and a PGF variant based on PGF/Ti\emph{k}Z.

\section{Loading the package}

To install the package, copy the relevant package files \macro{rpgicons.sty}, \macro{rpgicons-l3.sty} and \macro{rpgicons-pgf.sty} into the working directory or into the \macro{texmf} directory. You may want to use a TeX package manager for this. After the package has been installed, the \macro{rpgicons} package is loaded by calling \macro{\usepackage{rpgicons}} in the preamble of the document.

The package can be loaded with one of the following options.

\begin{macrodef}
|l3|
\end{macrodef}
The L3 variant of the package is loaded by default. To load it explicitly, the package can be loaded using the option \macro{l3}. Alternatively, \macro{\usepackage{rpgicons-l3}} can be called instead.

\begin{macrodef}
|pgf|
\end{macrodef}
To load the PGF variant of the package the package needs to be loaded with the option \macro{pgf}. Alternatively, \macro{\usepackage{rpgicons-pgf}} can be called instead.

\subsection{Dependencies}

The L3 variant of the package loads the \macro{l3draw} package.

The PGF variant of the package loads the \macro{tikz} package which in turn loads the \macro{xcolor} package. To make use of specific options these packages provide, you need to load the packages with the relevant options beforehand or explicitly pass the relevant options to the package using a command such as \macro{\PassOptionsToPackage{svgnames}{xcolor}}.

\subsection{Generating SVG icons}

To generate an SVG from the LaTeX source, use \macro{\documentclass[dvisvgm]{standalone}} and compile with \macro{latex} and then run \macro{dvisvgm -b papersize} on the compiled DVI file.

The below code example can be compiled with \macro{latex} and \macro{dvisvgm -b papersize -p 1-} applied to the resulting DVI file to generate one SVG file for each graphic inside the \macro{icon} environment:

\begin{codeexample}
\documentclass[dvisvgm, multi=icon]{standalone}
\usepackage{rpgicons}

\begin{document}
    \begin{icon}%
        \ability{charisma}%
    \end{icon}
    \begin{icon}%
        \class{barbarian}%
    \end{icon}
\end{document}
\end{codeexample}

\section{Main user commands}

Regardless of the variant of the package, a set of user commands is always available. These are described in the following. Depending on the use of the L3 or the PGF variant, certain specific commands or options are available that are explained in the following sections in further detail.

Because of the way the package defines the icons, each of the user commands below described can actually be used together with every shape. However, the combinations of shapes and commands as described in the following subsections are preferable.

Note that shape names ending with \macro{alt} have been deprecated. Instead, use the \macro{variant} key to select variants of icon shapes as described below.

\subsection[Command \textbackslash die]{Command \titlemacro*{die}}

\begin{macrodef}
|\die|[<style>]{<shape>}[<options>]{<integer>}
\end{macrodef}
The command \macro{\die} typesets an icon to depict a die with a certain number of sides. Additionally, icons exist for a two-sided die (which would be equivalent to a coin) and for a hundred-sided die (which typically comes in the shape of a sphere). There is also a special icon for a fudge die.

For the six-sided die, nine additional shapes exist representing the values one to nine as pips. Also, additional shapes exist representing the plus or minus side of a fudge die.

The command takes two mandatory arguments, the first of which describes the shape (see the lists below) and the second taking an integer that is placed in front of the shape. For example, \macro{\die{eightside}{2}} results in \die{eightside}{2} (meaning two eight-sided dice are rolled). If tagging is enabled, the default replacement text of this command is ``2 eightside''.

The command also takes two optional arguments, the second of which can take additional options to style the icon or to select different variants of the icon shape. The options affect the shape, but not the integer when it is typeset before the icon. The usable options differ depending on the package variant. See the relevant sections below.

The first optional argument can take the value \macro{normal} or \macro{large}, \macro{normal} being the default value. With \macro{large} given as argument, the icon is drawn larger and the integer is typeset inside the shape. As an example, \macro{\die[large]{eightside}{2}} results in \die[large]{eightside}{2}. Note that the integer will always be placed on top of the shape, even if the shape does not have an open center which is the case with the \macro{fudge} shapes or the shapes featuring pips.

\begin{rpgiconsiconlist}
\titlemacro*{die}
    & \die{twoside}{} & \macro{twoside} \\
    & \die{fourside}{} & \macro{fourside} \\
    & \die{sixside}{} & \macro{sixside} \\
    & \die{eightside}{} & \macro{eightside} \\
    & \die{tenside}{} & \macro{tenside} \\
    & \die{twelveside}{} & \macro{twelveside} \\
    & \die{twentyside}{} & \macro{twentyside} \\
    & \die{hundredside}{} & \macro{hundredside} \\
    & \die{fudge}{} & \macro{fudge} \\
    & \die{sixside one}{} & \macro{sixside one} \\
    & \die{sixside two}{} & \macro{sixside two} \\
    & \die{sixside three}{} & \macro{sixside three} \\
    & \die{sixside four}{} & \macro{sixside four} \\
    & \die{sixside five}{} & \macro{sixside five} \\
    & \die{sixside six}{} & \macro{sixside six} \\
    & \die{sixside seven}{} & \macro{sixside seven} \\
    & \die{sixside eight}{} & \macro{sixside eight} \\
    & \die{sixside nine}{} & \macro{sixside nine} \\
    & \die{fudge plus}{} & \macro{fudge plus} \\
    & \die{fudge minus}{} & \macro{fudge minus} \\
\end{rpgiconsiconlist}

\subsection[Commands \textbackslash ability and \textbackslash saving]{Commands \titlemacro*{ability} and \titlemacro*{saving}}

\begin{macrodef}
|\ability|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\ability} typesets an icon depicting an ability of a character. The abilities are represented by animal-like shapes. The relevant shape should be given as mandatory argument to the command. The second optional argument can take additional options to style the icon.

The first optional argument can take the value \macro{positive} or \macro{negative}, \macro{positive} being the default value. With \macro{negative} given as argument, the icon is drawn negative inside a circle. As an example, \macro{\ability[negative]{charisma}} results in \ability[negative]{charisma}.

\begin{macrodef}
|\saving|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\saving} typesets an icon with the relevant \macro{\ability} icon inside a small shield. It can take the same values for the mandatory argument as the \macro{\ability} command. The optional argument can take additional options to style the icon.

The first optional argument can take the value \macro{normal} or \macro{empty}, \macro{normal} being the default value. With \macro{empty} given as argument, the icon inside the shield is not typeset. In this case, the mandatory argument can be left empty. As an example, \macro{\saving[empty]{}} results in \saving[empty]{}.

\begin{rpgiconsiconlist}
\titlemacro*{ability}
    & \ability{strength} & \macro{strength} \\
    & \ability{dexterity} & \macro{dexterity} \\
    & \ability{dexterity}[variant=1] & \macro{dexterity} & 1 \\
    & \ability{constitution} & \macro{constitution} \\
    & \ability{intelligence} & \macro{intelligence} \\
    & \ability{wisdom} & \macro{wisdom} \\
    & \ability{wisdom}[variant=1] & \macro{wisdom} & 1 \\
    & \ability{charisma} & \macro{charisma} \\
    & \ability{resilience} & \macro{resilience} \\
    & \ability{sanity} & \macro{sanity} \\
    & \ability{perception} & \macro{perception} \\
    & \ability{luck} & \macro{luck} \\
    & \ability{armour} & \macro{armour} or \macro{armor} \\
    & \ability{proficiency} & \macro{proficiency} \\
\midrule
\titlemacro*{saving}
    & \saving{strength} & \macro{strength} \\
    & \saving{dexterity} & \macro{dexterity} \\
    & \saving{dexterity}[variant=1] & \macro{dexterity} & 1 \\
    & \saving{constitution} & \macro{constitution} \\
    & \saving{intelligence} & \macro{intelligence} \\
    & \saving{wisdom} & \macro{wisdom} \\
    & \saving{wisdom}[variant=1] & \macro{wisdom} & 1 \\
    & \saving{charisma} & \macro{charisma} \\
    & \saving{resilience} & \macro{resilience} \\
    & \saving{sanity} & \macro{sanity} \\
    & \saving{perception} & \macro{perception} \\
    & \saving{luck} & \macro{luck} \\
    & \saving{armour} & \macro{armour} or \macro{armor} \\
    & \saving{proficiency} & \macro{proficiency} \\
\end{rpgiconsiconlist}

\subsection[Command \textbackslash spell]{Command \titlemacro*{spell}}

\begin{macrodef}
|\spell|{<shape>}[<options>]
\end{macrodef}
The command \macro{\spell} typesets an icon depicting the effect of a spell or how it is to be effected. The optional argument can take additional options to style the icon.

\begin{rpgiconsiconlist}
\titlemacro*{spell}
    & \spell{linear} & \macro{linear} \\
    & \spell{conic} & \macro{conic} \\
    & \spell{quadratic} & \macro{quadratic} \\
    & \spell{cubic} & \macro{cubic} \\
    & \spell{spheric} & \macro{spheric} \\
    & \spell{cylindric} & \macro{cylindric} \\
    & \spell{emanation} & \macro{emanation} \\
    & \spell{verbal} & \macro{verbal} \\
    & \spell{somatic} & \macro{somatic} \\
    & \spell{material} & \macro{material} \\
    & \spell{ritual} & \macro{ritual} \\
    & \spell{focus} & \macro{focus} \\
\end{rpgiconsiconlist}

\subsection[Command \textbackslash spellschool]{Command \titlemacro*{spellschool}}

\begin{macrodef}
|\spellschool|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\spellschool} typesets an icon that represents the school a spell belongs to. The second optional argument can take additional options to style the icon.

The first optional argument can take the value \macro{negative} or \macro{positive}, \macro{negative} being the default value. Per default the icon is drawn in white inside a filled escutcheon. With \macro{positive} given as argument, the icon as well as the escutcheon are drawn in the currently selected color. As an example, \macro{\spellschool[positive]{evocation}} results in \spellschool[positive]{evocation}.

\begin{rpgiconsiconlist}
\titlemacro*{spellschool}
    & \spellschool{abjuration} & \macro{abjuration} \\
    & \spellschool{conjuration} & \macro{conjuration} \\
    & \spellschool{divination} & \macro{divination} \\
    & \spellschool{enchantment} & \macro{enchantment} \\
    & \spellschool{evocation} & \macro{evocation} \\
    & \spellschool{illusion} & \macro{illusion} \\
    & \spellschool{necromancy} & \macro{necromancy} \\
    & \spellschool{transmutation} & \macro{transmutation} \\
\end{rpgiconsiconlist}

\subsection[Commands \textbackslash damage, \textbackslash attack and \textbackslash condition]{Commands \titlemacro*{damage}, \titlemacro*{attack} and \titlemacro*{condition}}

\begin{macrodef}
|\damage|{<shape>}[<options>]
\end{macrodef}
The command \macro{\damage} typesets an icon depicting the damage of an attack. The icon is printed inside a circle. The optional argument can take additional options to style the icon.

\begin{macrodef}
|\attack|{<shape>}[<options>]
\end{macrodef}
The command \macro{\attack} typesets an icon depicting the kind of an attack. The optional argument can take additional options to style the icon.

\begin{macrodef}
|\condition|{<shape>}[<options>]
\end{macrodef}
The command \macro{\condition} typesets an icon depicting a condition of a character. The optional argument can take additional options to style the icon.

\begin{rpgiconsiconlist}
\titlemacro*{damage}
    & \damage{acid} & \macro{acid} \\
    & \damage{bludgeoning} & \macro{bludgeoning} \\
    & \damage{cold} & \macro{cold} \\
    & \damage{fire} & \macro{fire} \\
    & \damage{force} & \macro{force} \\
    & \damage{lightning} & \macro{lightning} \\
    & \damage{necrotic} & \macro{necrotic} \\
    & \damage{necrotic}[variant=1] & \macro{necrotic} & 1 \\
    & \damage{piercing} & \macro{piercing} \\
    & \damage{poison} & \macro{poison} \\
    & \damage{psychic} & \macro{psychic} \\
    & \damage{radiant} & \macro{radiant} \\
    & \damage{slashing} & \macro{slashing} \\
    & \damage{thunder} & \macro{thunder} \\
    & \damage{healing} & \macro{healing} \\
\midrule
\titlemacro*{attack}
    & \attack{melee} & \macro{melee} \\
    & \attack{melee}[variant=1] & \macro{melee} & 1 \\
    & \attack{ranged} & \macro{ranged} \\
    & \attack{magic} & \macro{magic} \\
    & \attack{singlehanded} & \macro{singlehanded} \\
    & \attack{doublehanded} & \macro{doublehanded} \\
\midrule
\titlemacro*{condition}
    & \condition{buff} & \macro{buff} \\
    & \condition{blinded} & \macro{blinded} \\
    & \condition{charmed} & \macro{charmed} \\
    & \condition{deafened} & \macro{deafened} \\
    & \condition{exhausted} & \macro{exhausted} \\
    & \condition{frightened} & \macro{frightened} \\
    & \condition{grappled} & \macro{grappled} \\
    & \condition{incapacitated} & \macro{incapacitated} \\
    & \condition{invisible} & \macro{invisible} \\
    & \condition{paralyzed} & \macro{paralyzed} \\
    & \condition{petrified} & \macro{petrified} \\
    & \condition{poisoned} & \macro{poisoned} \\
    & \condition{prone} & \macro{prone} \\
    & \condition{restrained} & \macro{restrained} \\
    & \condition{restrained}[variant=1] & \macro{restrained} & 1 \\
    & \condition{stunned} & \macro{stunned} \\
    & \condition{unconscious} & \macro{unconscious} \\
    & \condition{hearing} & \macro{hearing} \\
    & \condition{seeing} & \macro{seeing} \\
\end{rpgiconsiconlist}

\subsection[Commands \textbackslash class and \textbackslash alignment]{Commands \titlemacro*{class} and \titlemacro*{alignment}}

\begin{macrodef}
|\class|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\class} typesets an icon depicting a class of a character. The optional argument of the command can take additional options to style the icon.

The first optional argument can take the value \macro{negative} or \macro{positive}, \macro{positive} being the default value. With \macro{positive} given as argument, the icon is drawn in white inside a filled frame. As an example, \macro{\class[negative]{barbarian}} results in \class[negative]{barbarian}.

\begin{macrodef}
|\alignment|[<style>]{<shape>}[<options>]
\end{macrodef}
The command \macro{\alignment} typesets an icon depicting an alignment of a character. The optional argument of the command can take additional options to style the icon.

The first optional argument can take the value \macro{negative} or \macro{positive}, \macro{positive} being the default value. With \macro{positive} given as argument, the icon is drawn in white inside a filled frame. As an example, \macro{\alignment[negative]{lawful good}} results in \alignment[negative]{lawful good}.

\begin{rpgiconsiconlist}
\titlemacro*{class}
    & \class{artificer} & \macro{artificer} \\
    & \class{artificer}[variant=1] & \macro{artificer} & 1 \\
    & \class{barbarian} & \macro{barbarian} \\
    & \class{bard} & \macro{bard} \\
    & \class{bard}[variant=1] & \macro{bard} & 1 \\
    & \class{cleric} & \macro{cleric} \\
    & \class{cleric}[variant=1] & \macro{cleric} & 1\\
    & \class{cleric}[variant=2] & \macro{cleric} & 2 \\
    & \class{druid} & \macro{druid} \\
    & \class{druid}[variant=1] & \macro{druid} & 1 \\
    & \class{druid}[variant=2] & \macro{druid} & 2 \\
    & \class{fighter} & \macro{fighter} \\
    & \class{gunslinger} & \macro{gunslinger} \\
    & \class{monk} & \macro{monk} \\
    & \class{monk}[variant=1] & \macro{monk} & 1 \\
    & \class{paladin} & \macro{paladin} \\
    & \class{paladin}[variant=1] & \macro{paladin} & 1 \\
    & \class{psion} & \macro{psion} \\
    & \class{psion}[variant=1] & \macro{psion} & 1 \\
    & \class{ranger} & \macro{ranger} \\
    & \class{ranger}[variant=1] & \macro{ranger} & 1 \\
    & \class{rogue} & \macro{rogue} \\
    & \class{rogue}[variant=1] & \macro{rogue} & 1 \\
    & \class{sorcerer} & \macro{sorcerer} \\
    & \class{sorcerer}[variant=1] & \macro{sorcerer} & 1 \\
    & \class{warlock} & \macro{warlock} \\
    & \class{wizard} & \macro{wizard} \\
    & \class{wizard}[variant=1] & \macro{wizard} & 1 \\
\midrule
\titlemacro*{alignment}
    & \alignment{lawful good} & \macro{lawful good} \\
    & \alignment{neutral good} & \macro{neutral good} \\
    & \alignment{chaotic good} & \macro{chaotic good} \\
    & \alignment{lawful neutral} & \macro{lawful neutral} \\
    & \alignment{true neutral} & \macro{true neutral} \\
    & \alignment{chaotic neutral} & \macro{chaotic neutral} \\
    & \alignment{lawful evil} & \macro{lawful evil} \\
    & \alignment{neutral evil} & \macro{neutral evil} \\
    & \alignment{chaotic evil} & \macro{chaotic evil} \\
\end{rpgiconsiconlist}

\subsection[Command \textbackslash currency]{Command \titlemacro*{currency}}

\begin{macrodef}
|\currency|{<shape>}[<options>]{<integer>}
\end{macrodef}
The command \macro{\currency} typesets an icon depicting a value of a coin. The optional argument can take additional options to style the icon.

The command provides a second mandatory argument that accepts an integer that is placed in front of the shape. For example, \macro{\currency{gold}{7}} results in \currency{gold}{7}. If tagging is enabled, the default replacement text of this command is ``7 gold''.

\begin{rpgiconsiconlist}
\titlemacro*{currency}
    & \currency{copper}{} & \macro{copper} \\
    & \currency{silver}{} & \macro{silver} \\
    & \currency{gold}{} & \macro{gold} \\
    & \currency{electrum}{} & \macro{electrum} \\
    & \currency{platinum}{} & \macro{platinum} \\
    & \currency{gem}{} & \macro{gem} \\
    & \currency{jewellery}{} & \macro{jewellery} or \macro{jewelry} \\
    & \currency{jewellery}[variant=1]{} & \macro{jewellery} or \macro{jewelry} & 1 \\
\end{rpgiconsiconlist}

% l3 variant

\section{Specifics of the L3 package variant}

The L3 variant of the package which uses the \macro{l3draw} package is loaded by default or explicitly by either calling \macro{\usepackage[l3]{rpgicons}} or \macro{\usepackage{rpgicons-l3}} in the preamble of the document after having installed the files \macro{rpgicons.sty} and \macro{rpgicons-l3.sty}. The \macro{l3draw} package is an experimental package that provides only basic drawing functionality. The L3 variant thus only supports a certain set of options for styling the icons.

The L3 variant of the package does not load the \macro{xcolor} package but makes use of the \macro{l3color} module which uses a similar syntax like the \macro{xcolor} package. Color definitions made using the \macro{l3color} module are not directly usable via commands provided by the \macro{xcolor} package. Therefore, setting a color using the \macro{\color} macro provided by the \macro{xcolor} package won't affect the color of the icons.

It is possible, however, to call \macro{\DocumentMetadata{}} before \macro{\documentclass} and then use \macro{\definecolor} provided by the \macro{xcolor} package to define a color which can then be used by the L3 variant of the package.

Transparency requires the management of certain PDF settings. Therefore, it is necessary to call \macro{\DocumentMetadata{}} before \macro{\documentclass} when using the L3 variant of the package.

It is also possible to call \macro{\RequirePackage{pdfmanagement}} before \macro{\documentclass} instead of \macro{\DocumentMetadata{}} to enable the above described color and transparency management.

\subsection{Icon commands}

\begin{macrodef}
|variant|
|variant|={<integer>}
\end{macrodef}
The main user commands (as well as the underlying commands on which these commands are based as described below) accept as option the key \macro{variant} which accepts an integer as value to select variants for the relevant shape. See the icon lists above for the respective variants. For example, the command \macro{\ability{dexterity}[variant=1]} results in \ability{dexterity}[variant=1].

Setting the key \macro{variant} without value is equivalent to setting its value to \macro{1}. Selecting a non-existent variant selects the default shape.

With the following setting, all occurrences of the \macro{necrotic} shape are set to the relevant variant.

\begin{codeexample}
\rpgiconsset{
    every necrotic={
        variant=1
    }
}
\end{codeexample}

\begin{macrodef}
|\RPGIconsUseIcon|[<options>][<integer>]{<shape>}
|\RPGIconsUseIcon*|[<options>][<integer>]{<shape>}
\end{macrodef}
\macro{\RPGIconsUseIcon} is the primary command to typeset icons using the L3 variant of the package. The commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack}, \macro{\condition}, \macro{\class}, \macro{\alignment} and \macro{\currency} are based on this command. This command allows to combine all shapes with all frames and with either a positive or a negative color scheme.

For example, \macro{\RPGIconsUseIcon[scale=.675, stroke=blue][2]{tenside}} is equivalent to and thus results in the same output as \macro{\die[large]{tenside}[stroke=blue]{2}} and \macro{\RPGIconsUseIcon*[frame=ability, scale=.333, fill=red]{charisma}} results in the same output as \macro{\ability[negative]{charisma}[fill=red]}. On the other hand, it is also possible to create icons that can't be typeset using the above standard commands, such as \macro{\RPGIconsUseIcon*[frame=saving, scale=.333, fill=blue]{barbarian}} which will result in \RPGIconsUseIcon*[frame=saving, scale=.333, fill=blue]{barbarian}.

The \macro{\RPGIconsUseIcon} command has a starred version and two optional arguments as well as one mandatory argument. The mandatory argument holds the shape of the icon. The second optional argument can be used to add an integer (or any text) that is placed on top of the icon, for example when used with shapes for dice.

The starred version of the command is used to fill a frame with color instead of drawing its outline. Frames can be put around the shape via the relevant \macro{frame} option.

The \macro{\RPGIconsUseIcon} command supports PDF tagging. If tagging is activated by using \macro{\DocumentMetadata{tagging=on}}, a replacement text is automatically added to the relevant icon which can be copied to the clipboard and can be read by screen readers. Note that tagging support depends on the used PDF reader.

\begin{macrodef}
|\RPGIconsDie|[<style>]{<shape>}[<options>]{<integer>}
|\RPGIconsAbility|[<style>]{<shape>}[<options>]
|\RPGIconsSaving|[<style>]{<shape>}[<options>]
|\RPGIconsSpell|{<shape>}[<options>]
|\RPGIconsSpellschool|[<style>]{<shape>}[<options>]
|\RPGIconsDamage|{<shape>}[<options>]
|\RPGIconsAttack|{<shape>}[<options>]
|\RPGIconsCondition|{<shape>}[<options>]
|\RPGIconsClass|[<style>]{<shape>}[<options>]
|\RPGIconsAlignment|[<style>]{<shape>}[<options>]
|\RPGIconsCurrency|{<shape>}[<options>]
\end{macrodef}
The L3 variant of the package defines a set of commands on which the user commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack}, \macro{\condition}, \macro{\class}, \macro{\alignment} as well as \macro{\currency} are based. This set of commands can be used in cases where another package defines one of these user commands. These user commands are exact copies of this set of commands.

\subsection{Icon options}

The \macro{\RPGIconsUseIcon} command and the commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack}, \macro{\condition}, \macro{\class}, \macro{\alignment} and \macro{\currency} can be used with certain options that each consist of a key-value pair and can be combined. These options should be used directly without wrapping them inside the \macro{style} option, when used with the \macro{\RPGIconsUseIcon} command or the other commands based on this command.

For example, \macro{\die{eightside}[color=blue, line width=0.8pt]{2}} would result in \die{eightside}[color=blue, line width=0.8pt]{2}.

\begin{macrodef}
|frame|={<string>}
\end{macrodef}
With the \macro{frame} option, one of six different frames can be selected that are drawn around the shape of the icon. The values \macro{ability} and \macro{damage} draw a circle around the shape. The value \macro{saving} draws a rounded shield and the value \macro{spellschool} draws an angular shield around the shape. The value \macro{class} dtaws a square and the value \macro{alignment} a hexagon around the shape. The commands \macro{\ability}, \macro{\saving}, \macro{\spellschool}, \macro{\damage}, \macro{\class}, \macro{\alignment} and \macro{\currency} make use of the relevant frame. Because the regular commands already implicitly select the relevant frame (or no frame), using the \macro{frame} option is only recommended together with the \macro{\RPGIconsUseIcon} command.

For example, \macro{\RPGIconsUseIcon[frame=class, scale=0.333]{charisma}} would result in \RPGIconsUseIcon[frame=class, scale=0.333]{charisma}.

\begin{macrodef}
|color|={<color>}
|stroke|={<color>}
|fill|={<color>}
|text|={<color>}
|background|={<color>}
\end{macrodef}
\begin{macrodef}
|opacity|={<float>}
|stroke opacity|={<float>}
|fill opacity|={<float>}
|text opacity|={<float>}
|background opacity|={<float>}
\end{macrodef}
The \macro{color} option sets the color of strokes, fills and text in general while the \macro{stroke} option, the \macro{fill} option and the \macro{text} option set the color only for strokes, fills or text respectively.

Similarly, the \macro{opacity} macro sets the opacity generally, while the options \macro{stroke opacity}, \macro{fill opacity} and \macro{text opacity} allow for setting the opacity of strokes, fill and text separately.

Some icons can be used with a negative color scheme where the icon is drawn negatively inside a filled shape. Per default, the icons are drawn in white in such cases, but it might be desirable that the icons are in the same color as the background. To this end, the \macro{background} option sets the color of the shape when it is printed over a filled frame which can be achieved by setting the \macro{negative} option for the \macro{\ability}, \macro{\spellschool}, \macro{\class} or the \macro{\alignment} command or using the starred version of the \macro{\RPGIconsUseIcon} command.

\begin{codeexamplecolumns}
\colorbox{blue!50}{%
    \ability[negative]{charisma}
        [scale=2]%
}

\colorbox{blue!50}{%
    \ability[negative]{charisma}
        [scale=2, background=blue!50]%
}
\end{codeexamplecolumns}

\begin{macrodef}
|line width|={<dimension>}
\end{macrodef}
\begin{macrodef}
|scale|={<float>}
|scale inner|={<float>}
|rotate|={<float>}
\end{macrodef}
The option \macro{line width} sets the line width for strokes.

Using the \macro{scale} and \macro{rotate} options, the shape can be scaled and rotated (in degrees).

The \macro{scale inner} option can be used to change the scaling of the icon placed inside a frame when using the \macro{\ability}, \macro{\saving}, \macro{\spellschool}, \macro{\damage}, \macro{\class}, \macro{\alignment} and \macro{\currency} macros. The default value is 0.675.

\begin{codeexamplecolumns}
\damage{petrified}
    [scale=2]

\damage{petrified}
    [scale=2, scale inner=0.5]
\end{codeexamplecolumns}

Note that the keys related to transformation, that is \macro{scale}, \macro{scale inner} and \macro{rotate}, add to the current value and do not replace it. For example, \macro{scale=0.5, scale=0.5} results in a scale factor of 0.25 and \macro{rotate=10, rotate=10} results in a rotation of 20~degrees.

\begin{macrodef}
|every die|={<options>}
|every ability|={<options>}
|every saving|={<options>}
|every spell|={<options>}
|every spellschool|={<options>}
|every damage|={<options>}
|every attack|={<options>}
|every condition|={<options>}
|every class|={<options>}
|every alignment|={<options>}
|every currency|={<options>}
|every <<shape>>|={<options>}
\end{macrodef}
Styles following the pattern \macro{every} followed by a space and the name of the command or the shape can be used to apply styles to every instance of this command or shape.

For example, \macro{\rpgiconsset{every die={color={red}}}} can be used to draw in red all icons created using the \macro{\die} command.

Calling \macro{\rpgiconsset{every charisma={color={red}}}} will draw every instance of the \macro{charisma} shape in red.

\begin{macrodef}
|every die add|={<options>}
|every ability add|={<options>}
|every saving add|={<options>}
|every spell add|={<options>}
|every spellschool add|={<options>}
|every damage add|={<options>}
|every attack add|={<options>}
|every condition add|={<options>}
|every class add|={<options>}
|every alignment add|={<options>}
|every currency add|={<options>}
|every <<shape>> add|={<options>}
\end{macrodef}
Styles following the pattern \macro{every} followed by a space and the name of the command or the shape followed by another space and \macro{add} work in the same way as the styles described above, but instead of overwriting existing styles, they append the relevant styles.

\subsection{Setting options globally}

\begin{macrodef}
|\rpgiconsset|
\end{macrodef}
Apart from setting the options to the commands directly, it is also possible to set them globally using the \macro{\rpgiconsset} command. Globally set options are overridden by options that are set directly.

\begin{codeexamplecolumns}
\rpgiconsset{
    color=blue
}

\ability{charisma}
\ability{charisma}[color=red]
\ability{charisma}
\end{codeexamplecolumns}

\begin{macrodef}
|style set|={<options>}
|style add|={<options>}
\end{macrodef}
To simplify styling, custom keys can be defined via the keys \macro{style set} and \macro{style add}. Both keys accept as value a key-value list consisting of one or multiple custom keys whose relevant value consists of another key-value list describing the relevant style. It is possible to use \macro{#1} as placeholder for one argument. It is also possible to reference to an already define custom key in the definition of another custom key.

The key \macro{style set} defines custom keys and sets their values. The key \macro{style add} appends the relevant key-value list to the existing custom key as defined by \macro{style set}. Note that it is not checked whether a custom key already exists and its definition will be overwritten without a warning.

\begin{codeexamplecolumns}
\rpgiconsset{
    style set={
        foo={rotate=45, fill=blue},
        bar={foo, fill=red, scale=#1}
    }
}

\ability[negative]{charisma}[foo]
\class[negative]{warlock}[bar=2]
\end{codeexamplecolumns}

Note that the key \macro{style appemd} has been deprecated and the key \macro{style add} should be used instead.

\begin{macrodef}
|alias|={<string>}{<string>}
\end{macrodef}
The key \macro{alias} accepts exactly two (braced) arguments that represent names of shapes. A shape with the name given in the first argument is created as an exact copy of the shape with the name given in the second argument. If a shape with the name given in the first argument already exists, it will become a copy of the other shape without warning.

\begin{macrodef}
|before sep|={<dimension>}
|after sep|={<dimension>}
|baseline|={<dimension>}
\end{macrodef}
The spacing before and after the icons can be set using the options \macro{before sep} and \macro{after sep}. The option \macro{baseline} can be used to adjust the baseline of the icons. These options can also be applied to the icon commands directly. The default value of \macro{before sep} and \macro{after sep} is 0.05\,em. The default value of \macro{baseline} is \textminus 3.5\,pt.

\begin{codeexamplecolumns}
Roll\die{eightside}{}a die!

\rpgiconsset{
    before sep={1cm}
}
Roll\die{eightside}{}a die!
\end{codeexamplecolumns}

\begin{macrodef}
|actualtext|={<string>}
\end{macrodef}
The option \macro{actualtext} can be used to change the default replacement text that is used for example by screen readers in a tagged PDF. It expects as string that represents the relevant replacement text. 

It is possible to change the replacement texts for specific icon types. For example, setting the key \macro{every saving={every charisma={actualtext={charisma saving}}}} will set the replacement text for every instance of \macro{\saving{charisma}} to \macro{charisma saving}.

Note that the possibility to provide a key-value list to \macro{actualtext} taking shape names as keys and the relevant replacement texts as values has been removed. Instead, use the keys to set the style for all macros or shapes as shown in the previous paragraph.

\subsection{Precompose icons}

A lot of icons in a document can affect compilation time. If one or several icons are used several times, compilation time can be increased by precomposing these icons. In the precomposing process, the relevant icons are compiled into an external PDF file from which they are then loaded into the document. This not only decreases compilation time, because every icon is only created once, but it also reduces the file size, because every icon is only embedded into the file once and further uses just reference to the first embedded instance.

In order to be able to compile an external PDF file during compilation (which required LaTeX to call another instance of LaTeX), the compilation needs to run with enabled shell escape.

In order to be able to include the external PDF file into the document, a backend that supports PDF inclusion (such as PDFLaTeX, LuaLaTeX or XeLaTeX) needs to be used.

\begin{macrodef}
|\RPGIconsPrecomposeIcon|[<options>][<reference>]{<shape>}
|\RPGIconsPrecomposeIcon*|[<options>][<reference>]{<shape>}
\end{macrodef}

Using the macro \macro{\RPGIconsPrecomposeIcon} icons can be precomposed. This macro should be used in the preamble of the document. It takes one mandatory argument that expects as string the name of the shape of the icon. The first optional argument can be used to provide opions for styling the icon. The second optional argument can be used to define a reference for this comcrete styled icon. If no reference is defined, the name of the shape is used as reference. The starred version of the command is used to fill a frame with color instead of drawing its outline (see the macros \macro{\RPGIconsUseIcon} and \macro{\RPGIconsUseIcon*} for comparison).

For example, to precompose an icon that uses the \macro{charisma} shape in black and another icon with the \macro{charisma} shape in red with the reference \macro{charisma-red}, the following two lines can be placed in the preamble of the document:

\begin{codeexample}
\RPGIconsPrecomposeIcon[scale=.333]{charisma}
\RPGIconsPrecomposeIcon[scale=.333, color=red][charisma-red]{charisma}
\end{codeexample}

\begin{macrodef}
|precompose|
|precompose|={<string>}
\end{macrodef}

Once an icon has been precomposed, it can be called by adding the \macro{precompose} option to the relevant macro. For example, \macro{\ability{charisma}[precompose]} would load the shape from the external PDF that has been generated using the shape name as reference. To call an icon using a specific reference, this reference can be given as value to the \macro{precompose} option. For example, the above described red variant of the \macro{\ability{charisma}} shape could be called using \macro{\ability{charisma}[precomppse=charisma-red]}.

Due to the fact that options that set colors, transformations or other styles have already been applied when the external PDF was generated, they won't have any effect when used together with the option \macro{precompose}.

\subsection{Roll dice syntax}\label{sec:roll-dice-syntax}

\begin{macrodef}
|\roll|{<roll syntax>}
|\RPGIconsRoll|{<roll syntax>}
\end{macrodef}
The \macro{\roll} macro can be used to quickly typeset dice rolls with the relevant icons using the established dice rolling syntax. This syntax consists of a sequence of dice and numbers concatenated by mathematical operators (plus, minus or times). Typically, the letter \macro{d} is used to denote a die with a certain number of sides. For example \macro{d6} denotes a six-sided die. A number can be added to specify the number of such dice that are rolled together. The letter to denote the die can be changed using the option \macro{roll syntax}.

For example, \macro{2d6 + 3d4 - 1} means ``roll two six-sided dice and three four-sided dice and subtract one from the result''. The command \macro{\roll{2d6 + 3d4 - 1}} results in \roll{2d6 + 3d4 - 1}.

The die notations \macro{d2}, \macro{d4}, \macro{d6}, \macro{d8}, \macro{d10}, \macro{d12}, \macro{d20} and \macro{d100} are defined. To denote a fudge die, \macro{dF} can be used. To denote that the lowest or highest die should be removed from the result, the letters \macro{L} and \macro{H} can be used. The syntax \macro{2d6 x 2} or \macro{2d6 * 2} can be used to denote several rolls with the same set of dice.

If the \macro{rpgicons} package is to be loaded together with some other package that defines the command \macro{\roll}, the command \macro{\RPGIconsRoll} can be used. This alternative command is an exact copy of the \macro{\roll} command.

\begin{macrodef}
|roll syntax|={<comma-separated list>}
\end{macrodef}
The option \macro{roll syntax} can be used to change the character that denotes a die in the dice rolling syntax. Multiple characters can be given using a comma separated list. The default setting is \macro{d,D} which allows notations such as \macro{2d6} or \macro{2D6}.

With \macro{\rpgiconsset{roll syntax={w,W}}}, for example, notations such as \macro{2w6} or \macro{2W6} could be used.

% PGF variant

\RenewCommandCopy\die\rpgiconsdie
\RenewCommandCopy\ability\rpgiconsability

\section{Specifics of the PGF package variant}

The PGF variant of the package is loaded by either calling \macro{\usepackage[pgf]{rpgicons}} or \macro{\usepackage{rpgicons-pgf}} in the preamble of the document after having installed the files \macro{rpgicons.sty} and \macro{rpgicons-pgf.sty}.

Since the commands to typeset the icons with the PGF variant of the package use \macro{tikzpicture} environments, these commands should not be used inside another \macro{tikzpicture}. However, because the package defines the icons as Ti\emph{k}Z shapes, it is possible to use the icons in \macro{tikzpicture} environments directly.

Apart from that, the PGF variant of the package provides a way to define custom commands to typeset the icons as boxed material which is safe to use in a \macro{tikzpicture} context. Furthermore, the icons can be used as Ti\emph{k}Z pics.

Once loaded, the PGF variant of the package defines a set of node shapes that can be used inside a \macro{tikzpicture} environment.

\begin{macrodef}
|pics|
\end{macrodef}
The PGF variant of the package provides the option \macro{pics}. If the package is loaded with this option, every icon is also available as Ti\emph{k}Z pic. On the use of pics, see section \ref{sec:pics} below.

\subsection{Icon commands}

\begin{macrodef}
!rpg icons/!|variant|
!rpg icons/!|variant|={<integer>}
\end{macrodef}
The main user commands (as well as the underlying commands on which these commands are based as described below) accept as option the key \macro{rpg icons/variant} which accepts an integer as value to select variants for the relevant shape. See the icon lists above for the respective variants. For example, the command \macro{\ability{dexterity}[rpg icons/variant=1]} results in \ability{dexterity}[rpg icons/variant=1].

Setting the key \macro{rpg icons/variant} without value is equivalent to setting its value to \macro{1}. Selecting a non-existent variant selects the default shape.

With the following setting, all occurrences of the \macro{necrotic} shape are set to the relevant variant.

\begin{codeexample}
\tikzset{
    rpg icons/every necrotic/.append style={
        rpg icons/variant=1
    }
}
\end{codeexample}

\begin{macrodef}
|\rpgiconsdie|[<style>]{<shape>}[<options>]{<integer>}
|\rpgiconsability|[<style>]{<shape>}[<options>]
|\rpgiconssaving|[<style>]{<shape>}[<options>]
|\rpgiconsspell|{<shape>}[<options>]
|\rpgiconsspellschool|[<style>]{<shape>}[<options>]
|\rpgiconsdamage|{<shape>}[<options>]
|\rpgiconsattack|{<shape>}[<options>]
|\rpgiconscondition|{<shape>}[<options>]
|\rpgiconsclass|[<style>]{<shape>}[<options>]
|\rpgiconsalignment|[<style>]{<shape>}[<options>]
|\rpgiconscurrency|{<shape>}[<options>]
\end{macrodef}
The PGF variant of the package defines a set of commands on which the user commands \macro{\die}, \macro{\ability}, \macro{\saving}, \macro{\spell}, \macro{\spellschool}, \macro{\damage}, \macro{\attack}, \macro{\condition}, \macro{\class}, \macro{\alignment} as well as \macro{\currency} are based. This set of commands can be used in cases where another package defines one of these user commands. These user commands are exact copies of this set of commands.

\subsection{Icon styles}

Using the PGF variant of the package, all icons can by styled using arbitrary Ti\emph{k}Z styles in general. As an example, \macro{\die{eightside}[blue, thick]{2}} results in \die{eightside}[blue, thick]{2}.

If PDF tagging is activated by using \macro{\DocumentMetadata{tagging=on}}, it is possible to add a replacement text to an icon using the \macro{actualtext} key.

\begin{macrodef}
!rpg icons/!|every die|/.style={<options>}
!rpg icons/!|every ability|/.style={<options>}
!rpg icons/!|every saving|/.style={<options>}
!rpg icons/!|every spell|/.style={<options>}
!rpg icons/!|every spellschool|/.style={<options>}
!rpg icons/!|every damage|/.style={<options>}
!rpg icons/!|every attack|/.style={<options>}
!rpg icons/!|every condition|/.style={<options>}
!rpg icons/!|every class|/.style={<options>}
!rpg icons/!|every alignment|/.style={<options>}
!rpg icons/!|every currency|/.style={<options>}
!rpg icons/!|every <<shape>>|/.style={<options>}
\end{macrodef}
Using Ti\emph{k}Z styles, all instances of a certain command or a certain shape can be styled at once. These styles all follow the pattern \macro{rpg icons/every} followed by a space and the name of the command or the shape. For example, \macro{\tikzset{rpg icons/every die/.append style={red}}} can be used to draw in red all icons created using the \macro{\die} command. To draw every instance of the \macro{charisma} shape in red, \macro{\tikzset{rpg icons/every charisma/.append style={red}}} can be used.

\subsection{Setting styles globally}

\begin{macrodef}
|rpg icons|/.style={<options>}
\end{macrodef}
All icons share the Ti\emph{k}Z style \macro{rpg icons} that is empty per default but can be used to style all icons at once. For example, if \macro{\tikzset{rpg icons/.append style={draw=red}}} is placed at the beginning of the document, all icons will be drawn in red. Per default, the icons are drawn in the color of the surrounding text.

Note that it may be necessary to add the Ti\emph{k}Z option \macro{transform shape} when applying transformations to the icons, because the icons are constructed as Ti\emph{k}Z nodes which are not affected by some transformations per default.

\begin{macrodef}
!rpg icons/!|background|={<color>}
\end{macrodef}
Some icons can be used with a negative color scheme where the icon is drawn negatively inside a filled shape. Per default, the icons are drawn in white in such cases, but it might be desirable that the icons are in the same color as the background. To this end, the color can be changed using the Ti\emph{k}Z option \macro{rpg icons/background} in the following way:

\begin{codeexamplecolumns}
\colorbox{blue!50}{%
    \ability[negative]{charisma}
        [scale=2, transform shape]%
}

\tikzset{
    rpg icons/background={blue!50}
}
\colorbox{blue!50}{%
    \ability[negative]{charisma}
        [scale=2, transform shape]%
}
\end{codeexamplecolumns}
This feature can, of course, also be used to change the color of the icon independently from the color of the background.

Note that the key \macro{rpg icons/background color} has been deprecated and the key \newline \macro{rpg icons/background} should be used instead.

\begin{macrodef}
!rpg icons/!|before sep|={<dimension>}
!rpg icons/!|after sep|={<dimension>}
!rpg icons/!|baseline|={<dimension>}
\end{macrodef}
The Ti\emph{k}Z options \macro{rpg icons/before sep} and \macro{rpg icons/after sep} are used to define the width of the space that is added before and after the icons respectively. The default value of both lengths is 0.05\,em. For example, setting the space before icons to 1\,cm can be achieved as follows:

\begin{codeexamplecolumns}
Roll\die{eightside}{}a die!

\tikzset{
    rpg icons/before sep={1cm}
}
Roll\die{eightside}{}a die!
\end{codeexamplecolumns}

The option \macro{baseline} can be used to adjust the baseline of the icons. A larger value for the baseline will shift the icon downwards relative to the baseline of the surrounding text. The default value of the baseline is \textminus 3.5\,pt.

\subsection{Direct use of shapes}

Because the icons are defined as Ti\emph{k}Z shapes, they can directly be applied to Ti\emph{k}Z nodes. However, the shapes don't have a shape border and no anchors defined, except for the \macro{center} anchor that sits exactly in the center of the shape. Therefore, if nodes with these shapes are connected using edges, the \macro{center} anchor will be used to connect the nodes. If nodes with these shapes are being positioned, only the \macro{center} anchor is available. Text content of these nodes is simply printed on top of the center of the node. Compare the following example.

\begin{codeexamplecolumns}
\begin{tikzpicture}
    \node[eightside, draw, blue, thick]
        at (0,0) (A) {A};
    \node[charisma, draw]
        at (2,0) (B) {B};
    \draw[red] (A) -- (B);
\end{tikzpicture}
\end{codeexamplecolumns}

The variant shapes are accessible by adding the variant number as small roman numeral to the shape name. For example, to access the second variant of the \macro{druid} shape, use \macro{druid ii}. This is also possible for boxed icons and icons as pics as described below.

\subsection{Boxing of icons}

Because the icons cannot simply be used inside \macro{tikzpicture} environments, the PGF variant of the package provides a workaround to place icons inside boxes for later use. Icons that are boxed this way can safely used inside \macro{tikzpicture} environments. This might be necessary, if an icon should be used in inline text that sits inside a node.

\begin{macrodef}
|\provideprotectedrpgicon|{<command>}[<style>]{<shape>}[<options>]{<box name>}
\end{macrodef}
The command \macro{\provideprotectedrpgicon} creates a box containing the icon that would be created using one of the regular commands this package provides.

\macro{\provideprotectedrpgicon{die}[large]{eightside}[blue, thick]{mybox}}, for example, stores the icon of an eight-sided die with the relevant style and Ti\emph{k}Z options in a new box named \macro{mybox}. Note that no integer can be added to the macros \macro{die} or \macro{currency} in this context.

\provideprotectedrpgicon{die}[large]{eightside}[blue, thick]{mybox}

\begin{macrodef}
|\useprotectedrpgicon|{<box name>}
\end{macrodef}
Using the command \macro{\useprotectedrpgicon}, the previously defined box can be used to place the relevant icon. With the above definition, \macro{\useprotectedrpgicon{mybox}} would result in \useprotectedrpgicon{mybox}.

Having created a boxed icon, it is safe to use it, for example, inside a Ti\emph{k}Z node:

\begin{codeexamplecolumns}
\begin{tikzpicture}
    \node[circle, draw, align=center] {
        \useprotectedrpgicon{mybox} \\
        Roll a die!
    };
\end{tikzpicture}
\end{codeexamplecolumns}

\subsection{Icons as pics}\label{sec:pics}

If the PGF variant of the package is loaded with the option \macro{pics}, every icon is also available as Ti\emph{k}Z pic. The names of the pics always start with \macro{rpg icons} followed by a space and the name of the relevant icon (see the lists above). For abilities, savings, spellschools, damages, classes and alignments, additional pics containing the relevant frame exist where the name has the suffixes \macro{ability}, \macro{saving}, \macro{spellschool}, \macro{damage}, \macro{class}, and \macro{alignment} respectively.

The icon is embedded as a node in the pic which has the name \macro{-node}. Thus, it is possible to name the pic and refer to the node inside. Due to the fact that the icon is a node, the option \macro{transform shape} has to be used if transformations on the pic should affect the node as well. It is possible to apply styles to the node using the Ti\emph{k}Z option \macro{every node} as shown in the following example.

\begin{codeexamplecolumns}
\begin{tikzpicture}
    \pic[
        transform shape,
        scale=2,
        fill=blue,
        draw=red,
        every node/.append style={
            white,
            thick
        }
    ] (p) {rpg icons charisma ability};
    \draw[red] (p-node) -- +(2,0);
\end{tikzpicture}
\end{codeexamplecolumns}

\begin{macrodef}
!rpg icons/!|create pic from shape|={<string>}
!rpg icons/!|create pic from ability shape|={<string>}
!rpg icons/!|create pic from saving shape|={<string>}
!rpg icons/!|create pic from spellschool shape|={<string>}
!rpg icons/!|create pic from damage shape|={<string>}
!rpg icons/!|create pic from class shape|={<string>}
!rpg icons/!|create pic from alignment shape|={<string>}
!rpg icons/!|create every style|={<string>}
\end{macrodef}
The PGF variant of the package defines five Ti\emph{k}Z keys that are used to create pics using the relevant node shapes. Another key is defined to create keys that can be used to style all instances of a command or shape. In normal circumstances, it is not necessary to use these keys. They are mentioned here only for reference. These keys expect as value a string representing the relevnat shape name. It is possible to use the \macro{/.list} handler provided by PGF to apply the key to multiple values at once.

The following example shows how to create the drawing on the first page of this documentation using Ti\emph{k}Z pics. We need to call \macro{rpg icons/create pic from ability shape} for the shapes \macro{twentyside}, \macro{buff} and \macro{ranged}, because per default no pics are defined for these shapes in combination with ability. Note the use of \macro{\space} to ensure correct use of spaces in the pic name as spaces are gobbled after commands in TeX.

\begin{codeexamplecolumns}
\tikzset{
    rpg icons%
    /create pic from ability shape%
    /.list={
        twentyside,
        buff,
        ranged
    },
    rpg icons/every ability/.style={
        ultra thick,
        draw=white,
        line join=round,
        line cap=round
    }
}

\begin{tikzpicture}[scale=4]
    \foreach \x/\c [count=\i] in {
        twentyside/264653,
        charisma/287271,
        armour/2a9d8f,
        buff/e9c46a,
        ranged/f4a261,
        proficiency/e76f51
    } {
        \definecolor{color}{HTML}{\c}
        \pic[
            fill=color,
            draw=none,
            transform shape
        ] at ({60*\i+10}:{0.33cm})
            {rpg icons \x\space ability};
    }
\end{tikzpicture}
\end{codeexamplecolumns}

\subsection{Roll dice syntax}

\begin{macrodef}
|\roll|{<roll syntax>}
|\rpgiconsroll|{<roll syntax>}
\end{macrodef}
Please refer to section \ref{sec:roll-dice-syntax} about how to use the \macro{\roll} macro in general. Differences to the L3 variant of the package are described in the following.

The letter to denote the die can be changed using the Ti\emph{k}Z style \macro{rpg icons/roll syntax}.

If the \macro{rpgicons} package is to be loaded together with some other package that defines the command \macro{\roll}, the command \macro{\rpgiconsroll} can be used. This alternative command is an exact copy of the \macro{\roll} command.

\begin{macrodef}
!rpg icons/!|roll syntax|={<comma-separated list>!}
\end{macrodef}
The Ti\emph{k}Z style \macro{rpg icons/roll syntax} can be used to change the character that denotes a die in the dice rolling syntax. Multiple characters can be given using a comma separated list. The default setting is \macro{d,D}.

% =====

\printchanges

\end{document}

%% End of file `rpgicons-doc.tex`.
