diff options
Diffstat (limited to 'macros/latex/contrib/wargame/doc/tutorial/export.tex')
-rw-r--r-- | macros/latex/contrib/wargame/doc/tutorial/export.tex | 385 |
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 |