%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Documentation for the tikzlings package
% A package to bring cute little animals and other beings into tikz
% Maintained by samcarter
%
% Project repository and bug tracker:
% https://github.com/samcarter/tikzlings
%
% Released under the LaTeX Project Public License v1.3c or later
% See https://www.latex-project.org/lppl.txt
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% arara: latexmk
\documentclass{scrartcl}

\usepackage[
  themecolor=samviolet
]{\jobname-settings}

% meta %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\title{The \texorpdfstring{\tikzlings}{tikzlings} package}
\subtitle{drawing animals and beings in \TikZ}
\author{%
  \texorpdfstring{
    \begin{tikzpicture}
      \penguin
    \end{tikzpicture}\\[0.8em]
    \texttt{samcarter}\\
    \url{https://github.com/samcarter/tikzlings}\\
    \url{https://ctan.org/pkg/tikzlings}
  }{samcarter}}
\date{Version v2.3 \textendash{} 2025/03/23}
\packagename{tikzlings}

\selectcolormodel{rgb}
\colorlet{blue}{samlblue}

% packages %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\usepackage{tikzlings}
\usepackage{bearwear}
\usetikzlibrary{3d}
\usetikzlibrary{tikzlings}

% including commented lines from the .sty files %%%%%%%%%%%%%%%%%%%%%%
% thanks to Phelype Oleinik https://topanswers.xyz/tex?q=1861#a2092
\ExplSyntaxOn
\makeatletter
\iow_new:N \l__tikzlings_iow
\tl_new:N \l__tikzlings_file_name_tl
\NewDocumentCommand \CommentInput { m }
  { \tikzlings_comment_input:n {#1} }
\cs_new_protected:Npn \tikzlings_comment_input:n #1
  {
    \file_get_full_name:nNTF {#1} \l__tikzlings_file_name_tl
      { \__tikzlings_comment_input: }
      { \msg_error:nnn { tikzlings } { file-not-found } {#1} }
  }
\msg_new:nnn { tikzlings } { file-not-found } { File~'#1'~not~found. }
\cs_new_protected:Npn \__tikzlings_comment_input:
  {
    \group_begin:
      \cctab_select:N \c_other_cctab
      \int_set:Nn \tex_endlinechar:D { `\^^M }
      \use:x { \tex_everyeof:D { \exp_not:N \q_nil \char_generate:nn { 13 } { 13 } } }
      \char_set_active_eq:NN \^^M \__tikzlings_process_line:w
      \char_set_catcode_active:N \^^M
      \iow_open:Nn \l__tikzlings_iow { \c_sys_jobname_str . cif } % cif => comment input file
      \exp_after:wN \__tikzlings_process_line:w
        \tex_input:D { \l__tikzlings_file_name_tl }
      \iow_close:N \l__tikzlings_iow
    \group_end:
    \declare@file@substitution { \l__tikzlings_file_name_tl } { \c_sys_jobname_str . cif }
    \input { \l__tikzlings_file_name_tl }
    \undeclare@file@substitution { \l__tikzlings_file_name_tl }
  }
\group_begin:
\char_set_catcode_active:N \^^M
\char_set_active_eq:NN \^^M \scan_stop:
\cs_new_protected:Npx \__tikzlings_process_line:w #1 ^^M
  { \exp_not:N \__tikzlings_parse_line:w ^^M #1 ^^M \c_percent_str \s_stop }
\cs_set_protected:Npn \__tikzlings_tmp:w #1
  {
    \cs_new_protected:Npn \__tikzlings_parse_line:w ##1 ^^M #1 ##2 \s_stop
      {
        \tl_if_empty:nTF {##1}
          {
            \peek_charcode_remove:NTF #1
              { \__tikzlings_ignore_line:w }
              { \__tikzlings_output_line:w }
            ##2 \s_stop ^^M
          }
          {
            \tl_set:Nx \l_tmpa_tl { \tl_tail:n {##1} }
            \tl_if_eq:NNF \l_tmpa_tl \q_nil { ^^M }
          }
      }
    \cs_new_protected:Npn \__tikzlings_output_line:w ##1 ^^M #1 \s_stop
      { \iow_now:Nn \l__tikzlings_iow {##1} }
    \cs_new_protected:Npn \__tikzlings_ignore_line:w ##1 \s_stop { }
  }
\exp_args:No \__tikzlings_tmp:w { \c_percent_str }
\group_end:
\makeatother
\ExplSyntaxOff

% customisation %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\deftocheading{toc}{}%
\setcounter{tocdepth}{1}

\newcommand*\gobbleentrynumber[1]{}
\newcommand*\mytocformat[1]{#1}
\newcommand*\mytocpageformat[1]{#1}
\makeatletter
\RedeclareSectionCommand[
  toclinefill=\hyper@linkstart{link}{\Hy@tocdestname}\TOCLineLeaderFill\hyper@linkend,
  tocnumwidth=0pt,
  tocentrynumberformat=\gobbleentrynumber,
  tocentryformat=\mytocformat,
  tocpagenumberformat=\mytocpageformat,
  tocbeforeskip=0.8ex plus 1pt minus 1pt
]{section}

\renewcommand{\sectionlinesformat}[4]{%
\Ifstr{#1}{section}{%
    \parbox[t]{\linewidth}{%
      \raggedsection\@hangfrom{\hskip #2#3}{#4}\par%
      \kern-.75\ht\strutbox\rule{\linewidth}{.8pt}%
    }%
  }{%
    \@hangfrom{\hskip #2#3}{#4}}%
}
\makeatother

\renewcommand*{\subsectionformat}{}
\renewcommand*{\sectionformat}{}

\pgfmathsetseed{2}
\setlength{\footheight}{50pt}

\cfoot{\thepage}
\cfoot{%
  \begin{tikzpicture}[scale=0.5]
      \tikzling[signpost={\thepage}]
  \end{tikzpicture}
}
\pagestyle{scrheadings}

\tcbset{%
  tikz lower,
  height plus=3cm,
}

\AddToHook{tikzlings/coat/background}{\path (-1.63,0.1) rectangle (1.63,2.26);}
\AddToHook{tikzlings/mouse/background}{\path (-1.6,0.1) rectangle (0.905, 2.17);}
\AddToHook{tikzlings/cat/background}{\path (-1.6,0.1) rectangle (0.905, 2.17);}
\AddToHook{tikzlings/dog/background}{\path (-1.6,0.1) rectangle (0.905, 2.17);}

\begin{document}
\maketitle
\thispagestyle{scrheadings}

\section*{Introduction}
\label{intro}

The \tikzlings are a collection of little animals (and beings) drawn in \TikZ. It is the next evolutionary phase of the \tikzmarmots package, extending it with further animals (and beings) and also adding the ability to natively use many of the accessories known from the \tikzducks package.

I'd like to thank the friendly and helpful community of \TeX{} users for their suggestions, feedback and help to create this package and naming it. As a thank you, the \tikzlings all have names which are, in some way or another, connected to their creators, their inspiration or to users of \TeX{}.

\blurb

\clearpage
\section*{The \tikzlings}

The \tikzlings package is a collection of packages. It can either be loaded as a whole with \saminline|\usepackage{tikzlings}| or the subpackages containing the individual animals (and beings) can be used separately, e.g.\ by loading \saminline|\usepackage{tikzlings-marmots}|.

The basic usage is the same for all animals (and beings). Inside a \saminline|tikzpicture|, the \tikzlings can be added via \saminline|\<name_of_the_tikzling>|. For example

\begin{tcblisting}{title={Basic Ti\emph{k}Zling}}
\marmot
\end{tcblisting}

will produce a marmot. All usual \TikZ and \saminline|pgf| keys can be passed as optional argument to change the appearance. For example scaling and rotating the \tikzlings can be done by

\begin{tcblisting}{title={Ti\emph{k}Zling with options}}
\penguin[rotate=30,scale=0.5]
\end{tcblisting}

In addition to the standard options provided by \TikZ each \tikzlings also comes with some additional options which are listed in the following sections. If these additional options consist of multiple words they are available both with and without spaces, for example \saminline|askphil| and \saminline|ask phil| will be treated as the same.

To make customisation  of the \tikzlings easier, some hooks are provided, which can be utilised by the user in order to add commands at specific layers:
\begin{itemize}
  \item \saminline|\NewHook{tikzlings/<name_of_the_tikzling>/background}|
  \item \saminline|\NewHook{tikzlings/<name_of_the_tikzling>/belly}|
  \item \saminline|\NewHook{tikzlings/<name_of_the_tikzling>/body}|
  \item \saminline|\NewHook{tikzlings/<name_of_the_tikzling>/foreground}|
\end{itemize}

With regard to the individual components of the \tikzlings, they are located in the following z order:

\begingroup
  \centering
  \begin{tikzpicture}[scale=0.95]
    \newcommand{\planewidth}{2.6}
    \newcommand{\planeheight}{3.4}
    \newcommand{\planes}{\fill[gray!20!white,opacity=0.9]  (-\planewidth,-0.1) rectangle (\planewidth,\planeheight);}
    \newcommand{\hooks}{\draw[themecolor, rounded corners=3pt, line width=1pt]  (-\planewidth,-0.1) rectangle (\planewidth,\planeheight);}
    \newcounter{layer}
    \setcounter{layer}{0}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \hooks
      \node[font=\footnotesize\ttfamily,rotate=45] at (0,0.1) {background};
    \end{scope}
    \addtocounter{layer}{1}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \planes
      \newcommand{\rhinohookbelly}{
        \pgfsetfillopacity{0}
        \pgfsetstrokeopacity{0}
      }
      \rhino
    \end{scope}
    \addtocounter{layer}{1}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \hooks
      \node[font=\footnotesize\ttfamily,rotate=45] at (0,0.1) {belly};
    \end{scope}
    \addtocounter{layer}{1}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \planes
      \newcommand{\rhinohookbackground}{
        \pgfsetfillopacity{0}
        \pgfsetstrokeopacity{0}
      }
      \newcommand{\rhinohookbelly}{
        \pgfsetfillopacity{1}
        \pgfsetstrokeopacity{1}
      }
      \rhino
    \end{scope}
    \addtocounter{layer}{1}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \hooks
      \node[font=\footnotesize\ttfamily,rotate=45] at (0,0.1) {body};
    \end{scope}
    \addtocounter{layer}{1}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \planes
      \thing[magichat,magicwand]
    \end{scope}
    \addtocounter{layer}{1}
    \begin{scope}[canvas is zy plane at x=\thelayer*1.8]
      \hooks
      \node[font=\footnotesize\ttfamily,rotate=45] at (0,0.1) {foreground};
    \end{scope}
  \end{tikzpicture}
  \par
\endgroup

In addition, there are also hooks available which will effect all \tikzlings:
\begin{itemize}
  \item \saminline|\NewHook{tikzlings/background}|
  \item \saminline|\NewHook{tikzlings/belly}|
  \item \saminline|\NewHook{tikzlings/body}|
  \item \saminline|\NewHook{tikzlings/foreground}|
\end{itemize}

A short example how the hooks can be used:
\begin{tcblisting}{title={Hooks}}
\AddToHook{tikzlings/mouse/belly}{%
  \fill[red!80!black] (0.55, 1.35) --
    (0.65, 0.3) -- (-0.65, 0.3) --
    (-0.55, 1.35) -- (0.0, 0.9) -- cycle;
}

\mouse

% optionally
\RemoveFromHook{tikzlings/mouse/belly}
\end{tcblisting}

Another way to use the \tikzlings is the \TikZ library of the same name. By loading this library, all macros from the normal package can be used. In addition the \TikZ library also defines the \tikzlings as \saminline|pic|'s:
\begin{tcolorbox}[title={Ti\emph{k}z library and \texttt{\textbackslash pic}}]
\begin{samcode}
\documentclass{standalone}

\usepackage{tikz}
\usetikzlibrary{tikzlings}

\begin{document}
\begin{tikzpicture}
\path (1,0) pic{bear}
      (2,1) pic[
        coati/body=blue,
        scale=0.5
      ]{coati}
      (3,2) pic[
        thing/hat=red
      ]{penguin};
\end{tikzpicture}
\end{document}
\end{samcode}

\tcblower
\begin{tikzpicture}
\path (1,0) pic{bear}
       (2,1) pic[
         coati/body=blue,
         scale=0.5
       ]{coati}
       (3,2) pic[
         thing/hat=red!80!black
       ]{penguin};
\end{tikzpicture}
\end{tcolorbox}

\clearpage
\subsection*{List of all \tikzlings:}

\begingroup
  \hypersetup{hidelinks,linktoc=all}
  \tableofcontents
\endgroup

\makeatletter
\tikzlings@clistMapInlineNn{\tikzlings@packages@clist}{%
  \CommentInput{tikzlings-#1.sty}}
\makeatother

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Random Tikzling
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\section[Ti\emph{k}Zling]{Buffon, the random Ti\emph{k}Zling}

\emph{Buffon is named after the French scientist Georges-Louis Leclerc de Buffon. If the name sounds familiar, then maybe from his famous needle problem, which -- amongst other things -- can be used to approximate the value of~$\pi$.}

\subsection{Package name}

\begin{tcolorbox}[lower separated=false, lefthand width=.8\linewidth,title={Package usage}]
\vspace*{0.5cm}
\saminline|\usepackage{tikzlings}|
\vspace*{0.5cm}
\end{tcolorbox}

\subsection{Basic Usage}

\begin{tcblisting}{title={Basic Ti\emph{k}Zling}}
\tikzling
\end{tcblisting}

\subsection{Options}

Options common for all \tikzlings are supported for the \saminline|\tikzling|. These are the ability to change the body colour
\begin{tcblisting}{title={Body colour}}
\tikzling[body=blue]
\end{tcblisting}

to view the \tikzlings from behind
\begin{tcblisting}{title={Back view}}
\tikzling[back]
\end{tcblisting}

and the \saminline|3D| key, which will make the Ti\emph{k}Zlings 3-dimensional:
\begin{tcblisting}{title={3D view}}
\tikzling[3D]
\end{tcblisting}

And finally the \saminline|contour| key will only draw the outlines:
\begin{tcblisting}{title={Contours}}
\tikzling[contour=black]
\end{tcblisting}

If an option of a specific Ti\emph{k}Zling is used (for example \saminline|sleeping|, which only the koala and sloth can do) this option will only work for these \tikzlings. For all other \tikzlings, the option will be silently ignored.

In addition all usual \TikZ and \saminline|pgf| keys can be used in the optional argument as well as the accessories presented in the following section.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Accessories
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\clearpage
\section{Accessories}

To customise the \tikzlings the package provides a number of accessories which can be added to all the \tikzlings simply by adding the respective keyword as optional argument:

\begin{tcblisting}{title={Basic usage}}
\bear[
  hat
]
\end{tcblisting}

For most of these items, the colour can be customised:

\begin{tcblisting}{title={Customisation}}
\koala[
  crown=orange!50!yellow
]
\end{tcblisting}

Unfortunately it is very difficult to create accessories that will fit all the different shapes of the \tikzlings. Therefore it is also possible to add them separately as optional argument of the \saminline|\thing| macro, which allows more control of their size and placement:

\begin{tcblisting}{title={Further customisation}}
\owl
\thing[
  tophat,
  scale=1.5,
  yshift=-0.6cm,
  xshift=-0.05cm
]
\end{tcblisting}

A list of all available accessories is given below. For completeness the default colours for each key are shown, but actually it is unnecessary unless it should be changed. In case more than one key is shown, all but the first are optional.

\subsection{Hats}

\begin{tcblisting}{title={Hat}}
\penguin[
  hat=blue!40!black
]
\end{tcblisting}

\begin{tcblisting}{title={Top hat}}
\snowman[
  tophat=black!90!white
]
\end{tcblisting}

\begin{tcblisting}{title={Beret}}
\mouse[
  beret=black
]
\end{tcblisting}

\begin{tcblisting}{title={Strawhat}}
\anteater[
  strawhat=blue,
  ribbon=black
]
\end{tcblisting}

\begin{tcblisting}{title={Harlequin hat}}
\coati[
  harlequin=blue,
  niuqelrah=red
]
\end{tcblisting}

\begin{tcblisting}{title={Witch hat}}
\cat[
  witch=gray
]
\end{tcblisting}

\begin{tcblisting}{title={Magic hat}}
\bear[
  magichat=violet,
  magicstars=yellow!80!brown
]
\end{tcblisting}

\begin{tcblisting}{title={Crown}}
\sheep[
  crown=yellow!90!orange
]
\end{tcblisting}

\begin{tcblisting}{title={Queen crown}}
\bat[
  queencrown=yellow
]
\end{tcblisting}

\begin{tcblisting}{title={King crown}}
\marmot[
  kingcrown=gray
]
\end{tcblisting}

\begin{tcblisting}{title={Santa hat}}
\mouse[
  santa=red!80!black
]
\end{tcblisting}

\begin{tcblisting}{title={Chefs hat}}
\bear[
  chef=gray!20!white
]
\end{tcblisting}

\begin{tcblisting}{title={Graduate cap}}
\wolf[
  graduate=black,
  tassel=red
]
\end{tcblisting}

\begin{tcblisting}{title={Alien antennas}}
\penguin[
  alien=green
]
\end{tcblisting}

\begin{tcblisting}{title={Sombrero}}
\marmot[
  sombrero=orange!70!yellow,
  sombreroa= green!70!blue,
  sombrerob= red,
  sombreroc= blue
]
\end{tcblisting}

\subsection{Communication}

\begin{tcblisting}{title={Book}}
\coati[
  book={\tiny\TeX},
  bookcolour=brown
]
\end{tcblisting}

\begin{tcblisting}{title={Sign post}}
\pig[
  signpost={\TeX},
  signcolour= brown!50!black,
  signback=green!40!black
]
\end{tcblisting}

\begin{tcblisting}{title={Speech bubble}}
\bear[
  speech={\TeX},
  bubblecolour=gray!30!white
]
\end{tcblisting}

\begin{tcblisting}{title={Thinking bubble}}
\penguin[
  think={\TeX},
  bubblecolour=gray!30!white
]
\end{tcblisting}

\subsection{Food}

\begin{tcblisting}{title={Pizza}}
\koala[
  pizza
]
\end{tcblisting}

\begin{tcblisting}{title={Cheese}}
\mouse[
  cheese=yellow!30!orange!60!white
]
\end{tcblisting}

\begin{tcblisting}{title={Baguette}}
\bug[
  baguette=brown
]
\end{tcblisting}

\begin{tcblisting}{title={Cake}}
\moles[
  cake=violet
]
\end{tcblisting}

\begin{tcblisting}{title={Ice cream}}
\dog[
  icecream=brown!60!gray,
  flavoura=brown!50!black,
  flavourb=white!70!brown,
  flavourc=red!50!white
]
\end{tcblisting}

\begin{tcblisting}{title={Milk shake}}
\penguin[
  milkshake=red!20!white
]
\end{tcblisting}

\begin{tcblisting}{title={wine}}
\owl[
  wine=red!70!black
]
\end{tcblisting}

\begin{tcblisting}{title={Cocktail}}
\bear[
  cocktail
]
\end{tcblisting}

\begin{tcblisting}{title={Banana}}
\ape[
  banana=yellow!80!orange
]
\end{tcblisting}

\subsection{Sports}

\begin{tcblisting}{title={Cricket bat}}
\coati[
  cricket=brown
]
\end{tcblisting}

\begin{tcblisting}{title={Hockey stick}}
\bug[
  hockey=brown
]
\end{tcblisting}

\begin{tcblisting}{title={Football}}
\elephant[
  football=white
]
\end{tcblisting}

\subsection{Other items}

\begin{tcblisting}{title={Crystal ball}}
\meerkat[
  crystalball=cyan
]
\end{tcblisting}

\begin{tcblisting}{title={Magic wand}}
\bear[
  magicwand
]
\end{tcblisting}

\begin{tcblisting}{title={Rolling pin}}
\coati[
  rollingpin=brown
]
\end{tcblisting}

\begin{tcblisting}{title={Light sabre}}
\penguin[
  lightsaber=green
]
\end{tcblisting}

\begin{tcblisting}{title={Torch}}
\snowman[
  torch=gray
]
\end{tcblisting}

\begin{tcblisting}{title={Basket}}
\mouse[
  basket=brown!70!gray
]
\end{tcblisting}

\begin{tcblisting}{title={Easter Basket}}
\sloth[
  easter=brown!70!gray,
  egga=blue,
  eggb=green,
  eggc=red
]
\end{tcblisting}

\begin{tcblisting}{title={Crozier}}
\koala[
  crozier=brown
]
\end{tcblisting}

\begin{tcblisting}{title={Shovel}}
\snowman[
  shovel=gray
]
\end{tcblisting}

\begin{tcblisting}{title={Pick axe}}
\penguin[
  pickaxe=gray
]
\end{tcblisting}

\begin{tcblisting}{title={Straw broom}}
\bug[
  strawbroom=brown!50!white,
  strawbroomstick=brown,
  strawbroomribbon=red!50!black
]
\end{tcblisting}

\begin{tcblisting}{title={broom}}
\chicken[
  broom=brown,
  broomstick=gray!50!black
]
\end{tcblisting}

\begin{tcblisting}{title={Open umbrella}}
\rhino[
  umbrella=cyan
]
\end{tcblisting}

\begin{tcblisting}{title={Closed umbrella}}
\marmot[
  umbrellaclosed=cyan
]
\end{tcblisting}

\begin{tcblisting}{title={Handbag}}
\mouse[
  handbag=red!70!black
]
\end{tcblisting}

\begin{tcblisting}{title={Stick with leaf}}
\ape[
  stick=brown!50!black,
  leaf=green!70!red
]
\end{tcblisting}

\subsection{Random accessories}

Given the number of available accessories, it can be hard to decide which ones to use.
Luckily, one does not need to decide and pick random accessories instead.
There are two options for this purpose, \saminline|randomhead| and \saminline|randomaccessories|, which will choose a random headpiece and a random other accessories, respectively.
\begin{tcblisting}{title={Random accessories}}
\coati[
  randomhead,
  randomaccessories
]
\end{tcblisting}

\end{document}