% \section{VASSAL module}
% \label{sec:vassal}
%
% As already mentioned several times in this tutorial, we can use the
% definitions of maps, counters, and charts to generate a VASSAL
% module.
%
% \begin{quote}
%   VASSAL\footnote{\url{https://vassalengine.org}} is a
%   cross-platform\footnote{It is written in Java, meaning it runs
%   almost everywhere, except on iOS and Android} tool for playing
%   wargames against other humans or solitaire.  One can do
%   Play-By-E-Mail (PBEM) or online. 
% \end{quote}
%
% The trick is to prepare a separate \LaTeX{} document, say
% \texttt{export.tex} as in this tutorial, which exports the images as
% single pages.   Then, the Python script \texttt{export.py}
% distributed with the \textsf{wargame} package picks up this output
% (\texttt{export.pdf} and \texttt{export.json}) and generates a draft
% VASSAL module.
%
% In addition, you can supply a Python script, say \texttt{patch.py},
% which will be run on the draft module so that you fix things up in
% the VASSAL module.  In this way, your VASSAL module will likely need
% very little hand editing (if at all), and will be robust against
% changes in the \LaTeX{} code\footnote{Assuming you keep your Python
% \texttt{patch.py} script up to date.}.  This of course requires a
% bit of familiarity with Python, which is time well spent.
%
% Let us get into it.
%
% \subsection{The \texttt{export.tex} file}.
% \label{sec:export:tex}
%
% This file will output all the images to a PDF,
% \meta{export}\texttt{.pdf} along with meta information to a
% JSON\footnote{JavaScript Object Notation} file
% \meta{export}\texttt{.json}.  This is relatively simple to do.
%
% We need to use the document class \texttt{wgexport}, so lets go a
% head and load that.
%
%    \begin{macrocode}
\documentclass[11pt]{wgexport}      
%    \end{macrocode}
%
% Make sure you give the right font size as argument.
%
% This is where it pays off that we put all our definitions of
% counters, board, charts, etc. into a separate package.  To import
% these, we simply use that package here\footnote{If we hadn't made
% that package, we would have to repeat the definitions in some
% way. Very error prone}.  So we load the package and start our
% document. 
%
%    \begin{macrocode}
\usepackage{game}
\begin{document}
%    \end{macrocode}
%
% Now the body of the document will simply consist of a list of
% images, one for each side of each counter, the board, charts, and so
% on.  We need to put everything into the environment
% \texttt{imagelist} which will keep track of our meta data.
%
%    \begin{macrocode}
\begin{imagelist}      
%    \end{macrocode}
%
% So far so good.  The first thing we will output are the counters.
% For that we will use the macro \verb+\doublechitimages+ (if we had
% single sided counters, we would use \verb+\chitimages+).  This macro
% takes two arguments: The list of counter definitions and the faction
% of the chits.  So lets go ahead and make those for factions A and B,
% and the special faction ``Markers'' which will only be the game turn
% counter.
%
%    \begin{macrocode}
\doublechitimages[A]{\alla}
\doublechitimages[B]{\allb}
\doublechitimages[Markers]{{game turn}}
%    \end{macrocode}
%
% Again, the macros we made for the counters comes in handy.  Note
% that we have used it twice so far: For the OOBs and here for the
% VASSAL module.  We will, in fact, use them one more time to create
% the counter sheet.
%
% Right, so that made our counter images and the associated meta
% data.  Next thing is to add our board.  For that, we use the
% environment \texttt{boardimage}.  Inside that environment we must
% draw the board.  The environment takes one optional argument which
% classifies the board.  Meaningful classifications are \texttt{board}
% (default) and \texttt{oob} for OOBs.  The first mandatory argument
% is the name of the board (more or less free form text, except any of 
% ``\texttt{./\textbackslash '"}'' should not be used.  The second
% mandatory argument is a sub-category, and is mainly reserved for
% future use.
%
%    \begin{macrocode}
\begin{boardimage}{Board}{}
  \begin{board}
  \end{board}
\end{boardimage}
%    \end{macrocode}
%
% We will make another board image for our OOB, since that component
% should hold counters in VASSAL. We pass the optional argument
% \texttt{oob} in this case. 
%
%    \begin{macrocode}
\begin{boardimage}[oob]{OOB}{}%
  \fulloob
\end{boardimage}
%    \end{macrocode}
%    
% We have two charts that we would also like to be put in: The CRT and
% the TE.  These \emph{must} be put into \Tikz{} pictures, and we
% precede those with the macro \verb+\info+. This macro takes three
% arguments: The name of the next image, the category, and
% sub-category.   Again, the name is more or less free form, and the
% category in some sense dictates how it will present in the VASSAL
% module.  For charts we should use the category \texttt{chart}.  The
% sub-category isn't really used at this point.  
%
%    \begin{macrocode}
\info{CRT}{chart}{}
\begin{tikzpicture}
  \node{\crt};
\end{tikzpicture}
% 
\info{TEC}{chart}{}
\begin{tikzpicture}
   \node{\tec};
\end{tikzpicture}
%    \end{macrocode}
%
% We also want background images for our pools of eliminated units in
% VASSAL.  This will be enlarged version of main headquarter unit of
% each faction, overlayed with a white semi-transparent background.
% 
%    \begin{macrocode}
\info{A}{pool}{}
\begin{tikzpicture}[scale=7]
  \chit[a hq];
  \fill[white,opacity=.5](-.6,-.6)rectangle++(1.2,1.2);
\end{tikzpicture}
\info{B}{pool}{}
\begin{tikzpicture}[scale=7]
  \chit[b hq];
  \fill[white,opacity=.5](-.6,-.6)rectangle++(1.2,1.2);
\end{tikzpicture}
%    \end{macrocode}
%    
% We can a splash page image.  We have not defined such an image in
% the \texttt{game} package, but we could have, so we will make it
% here. Again, it should be a \Tikz{} picture. For this, we need to
% use the category \texttt{front}.
%
%    \begin{macrocode}
\info{Splash}{front}{}
\begin{tikzpicture}
  \node[board frame,title,
  minimum width=5cm,minimum height=5cm]
  {A Game};
\end{tikzpicture}
%    \end{macrocode}
%
% We could continue to  add more if we wanted to.  Basically anything
% can be added.  For example, one might want custom button icons or
% the like.   We will add a few such icons here, mainly to show how
% the \texttt{patch.py} script works.
%
% First, a button icon for the pool window.
%
%    \begin{macrocode}
\info{pool-icon}{icon}{}
\begin{tikzpicture}[scale=.15]
  \draw[scale line widths,line width=4mm]
  (0,1)--(0,-1) (-.7,.2)--(.7,.2);
\end{tikzpicture}
%    \end{macrocode}
%
% The category \texttt{icon} has no special meaning.  The icon will
% look like \tikz[scale=.3]{\draw[scale line widths,line width=4mm]
% (0,1)--(0,-1) (-.7,.2)--(.7,.2);}
%
% We also want to add a custom icon for the OOB button.  VASSAL has a
% button icon for the piece inventory which is really quite
% appropriate, but alas it is already in use, so we will make our own
% (albeit similar).
%
%    \begin{macrocode}
\info{oob-icon}{icon}{}
\begin{tikzpicture}[scale=.6]
  \draw[fill=friendly] (.1,0)    rectangle(.5,-.1);
  \draw[fill=friendly] (.1,-.15) rectangle(.3,-.25);
  \draw[fill=friendly] (.1,-.3)  rectangle(.2,-.4);
  \draw[fill=hostile]  (-.1,0)   rectangle(-.3,-.25);
\end{tikzpicture}
%    \end{macrocode}
%
% This looks like
% \tikz{\draw[fill=friendly] (.1,0)    rectangle(.5,-.1);
%       \draw[fill=friendly] (.1,-.15) rectangle(.3,-.25);
%       \draw[fill=friendly] (.1,-.3)  rectangle(.2,-.4);
%       \draw[fill=hostile]  (-.1,0)   rectangle(-.3,-.25);}
%
% Normally the \texttt{export.py} script used the \emph{undo} image
% for the flip button.  However, that may be a bit confusing, so we
% will use a large ``F'' instead. \tikz{\node[color=blue!75!black,font=\sffamily\bfseries\LARGE]{F}}
%
% And similarly for the ``Eliminate''\tikz{\node[color=red!75!black,font=\sffamily\bfseries\LARGE]{E}}
% 
% and ``Restore'' buttons. \tikz{\node[color=green!75!black,font=\sffamily\bfseries\LARGE]{R}}
%
%    \begin{macrocode}
\info{flip-icon}{icon}{}
\begin{tikzpicture}
  \node[color=blue!75!black,inner sep=0pt,
  font=\sffamily\bfseries\large]{F};
\end{tikzpicture}
%
\info{eliminate-icon}{icon}{}
\begin{tikzpicture}
  \node[color=red!75!black,inner sep=0pt,
  font=\sffamily\bfseries\large]{E};
\end{tikzpicture}
%
\info{restore-icon}{icon}{}
\begin{tikzpicture}
  \node[color=green!75!black,inner sep=0pt,
  font=\sffamily\bfseries\large]{R};
\end{tikzpicture}
%    \end{macrocode}
%
%    \begin{macrocode}
\end{imagelist}
\end{document}
%    \end{macrocode}
%
% \subsection{Make the draft module}
%
% We run \LaTeX{} on the above \texttt{export.tex} file (the source of
% this section) to generate \texttt{export.pdf} and
% \texttt{export.json}.  We then process these with the
% \texttt{export.py} Python script to get the draft VASSAL module
% \texttt{Draft.vmod}.
%
% \begin{verbatim}
% `kpsewhich export.py` export.pdf export.json 
% \end{verbatim}
%
% The utility \texttt{kpsewhich}\footnotemark{\TeX{}Live and similar
% \TeX{} distributions.} will report the location of a file in the
% \TeX{} installation tree(s).  Note that the \texttt{`} above are
% what is typically called `back-ticks' (i.e., what you typically put
% as the leading character of scare-crows in \LaTeX{}).  This is of
% course Un*x-like syntax.  For other OSs, consult your \TeX{}
% distribution's documentation for how to find files in the \TeX{}
% installation.

% You can open the module in the VASSAL editor and see what was
% generated.  On the board, all areas marked with the \texttt{zone
% scope} (or \texttt{zone path}) should be defined as zones.  In the
% OOB, we should have two zones, one for the A faction and one for the
% B faction.   We should also have three groups of counters --- one
% for each faction and one for ``Markers''. Finally, we should have a
% window with tabs, one for each defined chart. 
%
% We can add the rules to the module.  So suppose the rules are in
% \texttt{game.pdf}, then we can do 
%
% \begin{verbatim}
% `kpsewhich export.py` export.pdf export.json \
%    -r game.pdf -o Game.vmod
% \end{verbatim}
%
% to add the rules to the ``Help'' menu.  Other information is added
% to that menu too, such as key-bindings and a short note on how the
% module was generated.  Of course, you should also see the splash
% image that we defined.  The option \texttt{-o}~\meta{filename}
% writes the module to \meta{filename} rather than the default
% \texttt{Draft.vmod}. 
%
% We define the version of the module by passing the option
% \texttt{-v}~\meta{version} to the Python script.  By default, the
% version is set to \texttt{draft}, and a note on the draft is added
% to the module and the grids are drawn.   Any other version string
% will suppress these.
%
% Also, the default module name is \texttt{Draft} and a similar
% description is likewise the default.  We can change this by passing
% the options \texttt{-t}~\meta{title} and
% \texttt{-d}~\meta{description}.  Note, you may want to quote the
% arguments if they contain spaces or the like.  Thus, to make a more
% complete module, we would do something like
%
% \begin{verbatim}
% `kpsewhich export.py` export.pdf export.json \
%   -r game.pdf -o Game.vmod \
%   -t "LaTeX Wargame tutorial" \
%   -d "Example of using wargame to make a module" \
%   -v 0.1
% \end{verbatim}
%
% Note that you typically need to quote (\texttt{"}) longer strings
% that contain spaces and other special characters. 
%
% \subsection{Going the extra mile}
% \label{sec:vassal:patch}
%
% We will take one more step on the VASSAL module, and then we will
% get back to the Print'n'Play version of the game.  We can provide
% the \texttt{export.py} script with an additional Python script that
% can tweak the VASSAL module any way we like.  We can for example
% move counters into their starting positions, to the OOB, adjust
% grids, add more materials, and so on.  It is only your imagination,
% and Python programming skills, that sets the limits on what you can
% do.
%
% Here we will make a simple \texttt{patch.py} Python script which
% does very little.  The \textsf{wargame} package,
% \textsf{wgexport} class, and \texttt{export.py} script  has already
% done the heavy work for us. Not least be because we have taken care
% to add in \texttt{zone} styles where needed. 
%
% We will 
% put all the counters on the OOB chart, and adjust some grids - most
% notably the OOB and turn track grids.  Other than that, we will not
% do much.  
% 
% \begin{verbatim}
% `kpsewhich export.py` export.pdf export.json \
%   -r game.pdf -o Game.vmod
%   -t "LaTeX Wargame tutorial" \
%   -d "Example of using wargame to make a module" \
%   -v 0.1 -p patch.py
% \end{verbatim}
%
% Now for the script:
%
% \begin{verbatim}
% def patch(build,data,vmod,verbose=False):
%     # We need to import the export module :-)
%     import export
% 
%     # Get the game and last free GPID
%     game = export.get_game(build)
%     gpid = int(game.getAttribute('nextPieceSlotId'))
% 
%     # Get all boards 
%     maps = export.get_maps(build)
%     board = maps['Board']
% 
%     mkeys = export.get_masskey(board,'name')
%     export.set_node_attr(mkeys['Eliminate'],
%                          icon='eliminate-icon.png')
%     export.set_node_attr(mkeys['Flip'],
%                          icon='flip-icon.png')
%     
%     # Get main map
%     pool = maps['DeadMap']
%     export.set_node_attr(pool,icon='pool-icon.png')
% 
%     mkeys = export.get_masskey(pool,'name')
%     export.set_node_attr(mkeys['Restore'],
%                          icon='restore-icon.png')
%     
%     # Get the OOB map
%     oob = export.get_chartwindows(game)['OOBs']
%     export.set_node_attr(oob,icon='oob-icon.png')
% \end{verbatim}
%
% In the \texttt{patch.py} script we can use all the functionality
% provided by \texttt{export.py}.  Elements are XML elements that we
% apply \texttt{xml.dom.minidom} operations on. 
% 
% \iffalse
% Local Variables:
%   mode: docTeX
%   TeX-master: "game.tex"
% End:
% \fi
