summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/wargame/doc/tutorial/export.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/wargame/doc/tutorial/export.tex')
-rw-r--r--macros/latex/contrib/wargame/doc/tutorial/export.tex385
1 files changed, 385 insertions, 0 deletions
diff --git a/macros/latex/contrib/wargame/doc/tutorial/export.tex b/macros/latex/contrib/wargame/doc/tutorial/export.tex
new file mode 100644
index 0000000000..adbb65ba6e
--- /dev/null
+++ b/macros/latex/contrib/wargame/doc/tutorial/export.tex
@@ -0,0 +1,385 @@
+% \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