diff options
author | Karl Berry <karl@freefriends.org> | 2022-09-26 21:48:39 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2022-09-26 21:48:39 +0000 |
commit | de76806c5523a50cc8d4b5ca94b6039e9145f878 (patch) | |
tree | 1944f33b2cc6a0952554365e07ed7786b79f5515 /Master/texmf-dist/doc | |
parent | af1f3d06504be6a1c533161f07f584fc59705d24 (diff) |
wargame (26sep22)
git-svn-id: svn://tug.org/texlive/trunk@64522 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc')
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/README.md | 304 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/compat.pdf | bin | 0 -> 432806 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/symbols.pdf | bin | 0 -> 184493 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/Makefile | 51 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/README.md | 41 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/export.tex | 384 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/game.pdf | bin | 0 -> 583838 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/game.sty | 2042 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/game.tex | 200 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/tutorial/patch.py | 31 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/wargame/wargame.pdf | bin | 0 -> 1310006 bytes |
11 files changed, 3053 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/wargame/README.md b/Master/texmf-dist/doc/latex/wargame/README.md new file mode 100644 index 00000000000..000f3cd68bf --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/README.md @@ -0,0 +1,304 @@ +A package to make Hex'n'Counter wargames in LaTeX +================================================= + +Version 0.3.2 +------------- + +This package can help make classic [Hex'n'Counter +wargames](https://en.wikipedia.org/wiki/Wargame) using LaTeX. The +package provide tools for generating + +- Hex maps and boards +- Counters (called *chits* since TeX have already taken *counters*) + for units, markers, and so on +- Counter sheets +- Order of Battle charts +- Illustrations in the rules using the defined maps and counters + +The result will often be a PDF (or set of PDFs) that contain everything +one will need for a game (rules, charts, boards, counter sheets). + +- The package uses [NATO App6](#nato-app6 "Section below") symbology + for units. +- The package uses [TikZ](https://github.com/pgf-tikz/pgf) for most + things. +- The package support exporting the game to a + [VASSAL](#vassal-support%20'Section%20below') module + +Sources +------- + +The sources of the package are kept at +[GitLab](https://gitlab.com/wargames_tex/wargame_tex) + +Download from GitLab +-------------------- + +- [Zip file of package and support + files](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/download?job=dist) +- [Browse content of + package](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/browse?job=dist) +- [Documentation](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/wargame.pdf?job=dist) +- [Tutorial](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/tutorial.pdf?job=dist) + (and associated VASSAL + [module](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/Game.vmod?job=dist)) +- [Table of + symbols](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/symbols.pdf?job=dist) +- [Compatibility](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/compat.pdf?job=dist) + +To install, get the ([zip +file](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/download?job=dist)) +and unzip into your TeX tree, for example + + mkdir -p ~/texmf + (cd ~/texmf && unzip ../artifacts.zip) + +on Un\*x like systems. + +If you clone from GitLab +(`git clone https://gitlab.com/wargames_tex/wargame_tex.git`) to get the +sources, then you can do + + cd wargame + make install + +to install in `~/texmf`. If you prefer another destination, say +`/usr/local/share/texmf`, do + + make install DESTDIR=/usr/local/share/texmf + +Download from CTAN +------------------ + +The package is available from +[CTAN](https://ctan.org/tex-archive/macros/latex/contrib/wargame) in the +directory `/macros/latex/contrib/wargame`. As of this writing, the +package has not hit any of the major distributions (e.g., +[TeXLive](https://tug.org/texlive/index.html)). + +### From TDS zip archive + +You can get the *TDS* [zip +file](https://mirrors.ctan.org/install/macros/latex/contrib/wargame.tds.zip) +and unpack that into your desired destination, e.g., `~/texmf` + + unzip wargame.tds.zip -d ~/texmf + +### From sources + +If you get the source (`wargame.ins`, all `.dtx`,`.py`, and `Makefile`) +files, then do + + make install + +to install into `~/texmf`. If you prefer to install somewhere else, say +`/usr/local/share/texmf`, then do + + make install DESTDIR=/usr/local/share/texmf + +If you do not have `make` (or `gmake` on MacOSX), or because you are on +some system which does not have that tool (e.g., Windows), then do (the +equivalent of) + + latex wargame.ins + pdflatex wargame.beach + pdflatex wargame.city + pdflatex wargame.light_woods + pdflatex wargame.mountains + pdflatex wargame.rough + pdflatex wargame.swamp + pdflatex wargame.town + pdflatex wargame.village + pdflatex wargame.woods + +(You need to use `pdflatex`, `xelatex`, or `lualatex` - plain `latex` +with DVI output will not work) + +Then copy the relevant files to your TeX tree (e.g., `~/texmf/`) as + + mkdir ~/texmf/tex/latex/wargame + cp tikzlibrary*.tex ~/texmf/tex/latex/wargame/ + cp wargame.sty ~/texmf/tex/latex/wargame/ + cp wgexport.cls ~/texmf/tex/latex/wargame/ + cp wargame.*.pdf ~/texmf/tex/latex/wargame/ + cp wgexport.py ~/texmf/tex/latex/wargame/ + cp wgsvg2tikz.py ~/texmf/tex/latex/wargame/ + +To generate the documentation, after having done the above, do + + pdflatex wargame.dtx + makeindex -s gind -o wargame.ind wargame.idx + pdflatex wargame.dtx + pdflatex wargame.dtx + pdflatex symbols.tex + pdflatex compat.tex + pdflatex compat.tex + +(You need to use `pdflatex`, `xelatex`, or `lualatex` - plain `latex` +with DVI output will not work) + +You can install these into your TeX tree with (e.g., `~/texmf/`) + + mkdir -p ~/texmf/doc/latex/wargame/ + cp wargame.pdf ~/texmf/doc/latex/wargame/ + cp symbols.py ~/texmf/doc/latex/wargame/ + cp compat.py ~/texmf/doc/latex/wargame/ + +If you want to generate the tutorial document, do + + cd tutorial + make + +or + + cd tutorial + pdflatex game + pdflatex game + +If you also want to make the tutorial VASSAL module, do (also in +`tutorial`), do + + pdflatex export.tex + ../wgexport.py export.pdf export.json -o Game.vmod \ + -d "Example module from LaTeX PnP game" \ + -t "LaTeX wargame tutorial" -v 0.1 \ + -p patch.py + + +Note, you need `pdfinfo` and `pdftocairo` from Poppler, and Python with +the module `PIL` for this. On Debian based systems, do + + sudo apt install poppler-utils python3-pil + +Tutorial +-------- + +See the [tutorial](tutorial/README.md "Link works on GitLab only") page +for more +([here](https://ctan.org/tex-archive/macros/latex/contrib/wargame/doc/tutorial/) +if you browse from CTAN). + +Examples +-------- + +Below are some print'n'play board wargames made with this package. These +are not original games but rather revamps of existing games. All credits +goes to the original authors of these games. + +- WWII + - Eastern Front + - [Battle for Moscow](https://gitlab.com/wargames_tex/bfm_tex) + (classic introductory game) + - Western Front + - [D-Day](https://gitlab.com/wargames_tex/dday_tex) (Avalon + Hill classic) + - [Paul Koenig's Market + Garden](https://gitlab.com/wargames_tex/pkmg_tex) + - [Paul Koenig's + D-Day](https://gitlab.com/wargames_tex/pkdday_tex) + - Pacific theatre + - [First + Blood](https://gitlab.com/wargames_tex/firstblood_tex) + (Avalon Hill International Kriegspiel Association classic) + - Africa + - [Afrika + Korps](https://gitlab.com/wargames_tex/afrikakorps_tex) + (Avalon Hill classic) +- Modern/Speculative + - [Strike Force One](https://gitlab.com/wargames_tex/sfo_tex) + - [Kriegspiel](https://gitlab.com/wargames_tex/kriegspiel_tex) + (Avalon Hill classic) + +VASSAL support +-------------- + +The packages has the script [`wgexport.py`](utils/wgexport.py) to +generate a draft [VASSAL](https://vassalengine.org) module from the +defined charts, boards, counters, OOBs, and so on. More about this is +given in the documentation. + +The script will generate a first draft of a module, which then can be +edited in the VASSAL editor for the final thing. + +Alternatively, one can provide a Python script to do more on the +generated module, such as defining starting positions, fixing grid +layouts, and so on. Using such a patch script, one can get an (almost) +final module. This means, that even if one makes changes to the original +content, it is easy to remake the module without much need for the +VASSAL editor. + +An example of this is given in the [Battle for +Moscow](https://gitlab.com/wargames_tex/bfm_tex) project, and of course +in the [tutorial](tutorial/ "Link works on GitLab only") + +NATO App6 +--------- + +The package supports + +- All air, equipment, installation, land, sea surface, sub surface, + and space command symbols, including amplifiers and modifiers +- All friendly, hostile, neutral, and unknown faction frame. Undecided + faction frames can be made by specifying `dashed` line styles. +- Some, but very few, other kinds of symbology. + +Here are some references for more information on the NATO App6 symbology +standard. + +- The [Wikipedia + page](https://en.wikipedia.org/wiki/NATO_Joint_Military_Symbology) + on NATO Joint Military Symbology +- The [NATO + page](https://nso.nato.int/nso/nsdd/main/standards/ap-details/1912/EN). + If this does not work for you, then try to go to the [standards + page](https://nso.nato.int/nso/nsdd/main/standards) and put in and + write in `SYMBOLOGY` in the *Document Title Contains Words* field + and press *Start*. +- Other LaTeX package for making NATO symbology + [XMilSymb](https://github.com/ralphieraccoon/MilSymb) + +Copyright and license +--------------------- + +(c) 2022 Christian Holm Christensen + +This work is licensed under the Creative Commons Attribution-ShareAlike +4.0 International License (CC-BY-SA-4.0). To view a copy of this +license, visit [CC](http://creativecommons.org/licenses/by-sa/4.0/) or +send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, +USA. + +### Some comments on copyright + +*Caveat*: I am not a lawyer. + +Note that this license applies to the `wargame` package as such. What +you generate using the package is *not* required to be licensed +according to the *ShareAlike* clause of CC-BY-SA-4.0. That is, you can +license your materials *any way you want*. + +However, that copyright rights on games is not as prohibitive as you may +think (see [this thread on +BGG](https://boardgamegeek.com/thread/493249/)). What you *can* +copyright is original, artistic expression. That is, the copyrighted +work must not be a copy of something else (originality) and must be some +form of expression. One *cannot* copyright ideas, only their expression +in so far as it is *artistic* (i.e., not a trivial expression that +anyone knowledgeable within the field can do with rudimentary effort). + +So you *can not* copyright your game mechanics, for example, only how +you described them. You *can not* copyright a title (but you may be able +to claim trademark on it). You *can* copyright the wording of the rules, +the graphics that you use, and so on. + +This also means, that you are essentially free to make your own version +of previously published game, *as long as* + +- you do not copy existing text +- you do not copy existing graphics +- you respect any kind of trademark claims + +However, it is advisable to contact the copyright holders of the +previously published game to avoid +[SNAFU](https://en.wikipedia.org/wiki/SNAFU). If in doubt, seek +professional help. diff --git a/Master/texmf-dist/doc/latex/wargame/compat.pdf b/Master/texmf-dist/doc/latex/wargame/compat.pdf Binary files differnew file mode 100644 index 00000000000..70583eca2fb --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/compat.pdf diff --git a/Master/texmf-dist/doc/latex/wargame/symbols.pdf b/Master/texmf-dist/doc/latex/wargame/symbols.pdf Binary files differnew file mode 100644 index 00000000000..b7f8a0a6c07 --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/symbols.pdf diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/Makefile b/Master/texmf-dist/doc/latex/wargame/tutorial/Makefile new file mode 100644 index 00000000000..4947d84ee08 --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/Makefile @@ -0,0 +1,51 @@ +# +# +# +LATEX := pdflatex +LATEX_FLAGS := -interaction=nonstopmode \ + -file-line-error \ + --synctex=15 \ + -shell-escape +EXPORT := ../utils/wgexport.py +EXPORT_FLAGS := + +ifdef VERBOSE +MUTE := +REDIR := +LATEX_FLAGS := +EXPORT_FLAGS := -V +else +MUTE := @ +REDIR := > /dev/null 2>&1 +endif + + +%.aux:%.tex + @echo "LATEX $< -> $@" + $(MUTE)TEXINPUTS=:..: $(LATEX) $(LATEX_FLAGS) $< $(REDIR) + +%.pdf:%.aux + @echo "LATEX $*.tex -> $@ (via $*.aux)" + $(MUTE)TEXINPUTS=:..: $(LATEX) $(LATEX_FLAGS) $*.tex $(REDIR) + +%.pdf:%.tex + @echo "LATEX $< -> $@" + $(MUTE)TEXINPUTS=:..: $(LATEX) $(LATEX_FLAGS) $< $(REDIR) + +%.json:%.pdf + +all: game.pdf Game.vmod + +game.aux:game.tex game.sty export.tex +export.pdf:export.tex game.sty + +Game.vmod:export.pdf export.json patch.py game.pdf + @echo "$(EXPORT) $< -> $@" + $(MUTE)$(EXPORT) export.pdf export.json -p patch.py -r game.pdf \ + -d "Example module from LaTeX PnP game" \ + -t "LaTeX wargame tutorial" -v 0.1 -o $@ + +clean: + rm -f *~ *.log *.out *.aux *.pdf *.vmod *.json + rm -f *.synctex* *.hd + rm -rf __pycache__ diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/README.md b/Master/texmf-dist/doc/latex/wargame/tutorial/README.md new file mode 100644 index 00000000000..38fd222142a --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/README.md @@ -0,0 +1,41 @@ +# Tutorial on how to use the `wargame` package + +This directory contains a tutorial on how to use the `wargame` package +to make a hex'n'counter (Print'n'Play) wargame. + +It also contains information on how to make a VASSAL module from a +game. + +## The PDF and VASSAL module +- + [PDF](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/tutorial.pdf?job=dist) +- [VASSAL + module](https://gitlab.com/wargames_tex/wargame_tex/-/jobs/artifacts/master/file/public/doc/latex/wargame/Game.vmod?job=dist) + +## Content + +- [`game.tex`](game.tex) The tutorial and game +- [`game.sty`](game.sty) Package defining most stuff for the game +- [`export.tex`](export.tex) Export graphics to VASSAL +- [`patch.py`](patch.py) Patch VASSAL module + +## How to build + +To build the tutorial, simple do + + pdflatex game + pdflatex game + +Alternatively, if you use some sort of LaTeX Integrated Development +Environment (IDE), load [`game.tex`](game.tex) into your IDE and run +LaTeX from there. + +To build the VASSAL module, simply do + + pdflatex export.tex + `kpsewhich wgexport.py` export.pdf export.json -o Game.vmod \ + -d "Example module from LaTeX PnP game" \ + -t "LaTeX wargame tutorial" -v 0.1 \ + -p patch.py + + diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/export.tex b/Master/texmf-dist/doc/latex/wargame/tutorial/export.tex new file mode 100644 index 00000000000..d51ecf0e5c6 --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/export.tex @@ -0,0 +1,384 @@ +% \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{wgexport.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{wgexport.py} script used the \emph{undo} mage +% 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{wgexport.py} Python script to get the draft VASSAL module +% \texttt{Draft.vmod}. +% +% \begin{verbatim} +% `kpsewhich wgexport.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 wgexport.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 wgexport.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{wgexport.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{wgexport.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 wgexport.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 wgexport as wg +% +% # Get the game and last free GPID +% game = wg.get_game(build) +% gpid = int(game.getAttribute('nextPieceSlotId')) +% +% # Get all boards +% maps = wg.get_maps(build) +% board = maps['Board'] +% +% mkeys = wg.get_masskey(board,'name') +% wg.set_node_attr(mkeys['Eliminate'],icon='eliminate-icon.png') +% wg.set_node_attr(mkeys['Flip'],icon='flip-icon.png') +% +% # Get main map +% pool = maps['DeadMap'] +% wg.set_node_attr(pool,icon='pool-icon.png') +% +% mkeys = wg.get_masskey(pool,'name') +% wg.set_node_attr(mkeys['Restore'],icon='restore-icon.png') +% +% # Get the OOB map +% oob = wg.get_chartwindows(game)['OOBs'] +% wg.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{wgexport.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 diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/game.pdf b/Master/texmf-dist/doc/latex/wargame/tutorial/game.pdf Binary files differnew file mode 100644 index 00000000000..14bcde8f98f --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/game.pdf diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/game.sty b/Master/texmf-dist/doc/latex/wargame/tutorial/game.sty new file mode 100644 index 00000000000..0c8fcc0165a --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/game.sty @@ -0,0 +1,2042 @@ +% \section{The \texttt{game} package} +% \label{sec:package} +% +% To make our game components re-usable (in particular when we want to +% make a VASSAL module), we will put our definitions of counters, +% board, and charts into a package file called +% \texttt{game.sty}\footnote{In fact, most of this document is in that +% file, because it allows us to document the code using \LaTeX{}'s +% \texttt{ltxdoc} class.} +% +% Code shown below is in the package. +% +% The first thing we do in the package is to identify the package and +% load the \textsf{wargame} package. +% +% \begin{macrocode} +\ProvidesPackage{game} +\RequirePackage{wargame} +\RequirePackage{colortbl} +% \end{macrocode} +% \section{The units} +% \label{sec:units} +% +% We will set-up our units for the game. As noted above, we will make +% two factions which we will call \emph{A} and \emph{B}. +% +% \begin{quote} +% The NATO +% App6(d)\footnote{\url{https://nso.nato.int/nso/nsdd/main/standards/ap-details/1912/EN}} +% symbology defines that friendly and hostile units should have +% different symbol frames, but as we will make a game for two +% players, and it seems unfair to label one as \emph{hostile} and +% the other \emph{friendly}, we will stick with the +% \texttt{friendly} base frames. +% +% Of course, if we were to make a solitaire or cooperative game, we +% might want to use the \texttt{hostile} base frame for the opponent +% units. +% \end{quote} +% +% \subsection{Faction styles} +% \label{sec:package:factions} +% +% We will start by defining two \Tikz{}\footnote{The \textsf{wargame} +% package relies heavily on \Tikz{}. It is highly recommended that you +% acquaint yourself with \Tikz{}. The manual, including tutorials, is +% available from \url{https://ctan.org/pkg/pgf}.} styles for our two +% factions. We will call these \texttt{a} and \texttt{b} (obviously). +% These will define the colours of all counters of those sides. +% +% \begin{macrocode} +\colorlet{a-bg}{hostile} +\colorlet{b-bg}{friendly} +\tikzset{% + a/.style={fill=a-bg,draw=black}, + b/.style={fill=b-bg,draw=black}} +% \end{macrocode} +% Note that we made the colours \texttt{a-bg} and \texttt{b-bg}. +% Since we will use these colours a few times, it makes sense to make +% a single definition which we can then freely change at any point and +% then automatically have that change propagate everywhere. +% +% These styles are shown in \figurename~\ref{fig:faction-colors}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \draw[a] (0,0) rectangle ++(1,1) node[above]{\texttt{a}};% +% \draw[b] (3,0) rectangle ++(1,1) node[above]{\texttt{b}};% +% \end{tikzpicture} +% \caption{Faction colours} +% \label{fig:faction-colors} +% \end{figure} +% +% Here we have used the colours \texttt{friendly} and \texttt{hostile} +% defined by the \textsf{wargame} package, even though we said we +% would not use the corresponding \texttt{hostile} base frame. +% However, we can use any colours we can define in \LaTeX{} with the +% \textsf{xcolor}\footnote{\url{https://ctan.org/pkg/xcolor}} package, +% for example, +% +% \begin{verbatim} +% \definecolor{a-bg}{HTML}{3333ff} +% \end{verbatim} +% +% which will make a light blue colour. +% +% Since we intent to make \emph{double-sided} counters, so that units +% will have two steps (front and back), we also define styles for the +% back side. These will have lighter backgrounds than the front +% side. +% +% \begin{macrocode} +\tikzset{% + a flipped/.style={a,fill=pgffillcolor!50!white}, + b flipped/.style={b,fill=pgffillcolor!50!white}} +% \end{macrocode} +% Note that we use the styles \texttt{a} and \texttt{b} as bases for +% these styles. Thus, if we make changes to the base styles, they +% automatically propagate to our flipped styles. +% +% \begin{quote} +% By convention, it is best to name your back-sides of counters and +% so on the same as the front side, but with `\texttt{ flipped}' +% appended. It is therefore also a good idea to use that convention +% for styles and such. +% \end{quote} +% +% The colour \texttt{pgffillcolor} is what ever the current fill +% colour is (i.e., set by the \texttt{a} and \texttt{b} styles). +% +% These styles are shown in +% \figurename~\ref{fig:faction-colors-flipped}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \draw[a flipped] (0,0) rectangle ++(1,1) node[above]{\texttt{a flippped}};% +% \draw[b flipped] (3,0) rectangle ++(1,1) node[above]{\texttt{b flipped}};% +% \end{tikzpicture} +% \caption{Faction flipped colours} +% \label{fig:faction-colors-flipped} +% \end{figure} +% +% \subsection{Unit templates} +% \label{sec:units:templates} +% +% In our game we will have two kinds of units: land, and air. +% +% Land units represent ground types of different kinds (infantry, +% armoured, etc.) and have two \emph{factors}: A combat factor (CF) +% and a movement factor (MF). In addition, for artillery units, we +% will also specify a range. Each unit will also have a unique +% identifier, and possibly parent organisational identifier, starting +% hex, and turn of appearance. +% +% Air units provide different kinds of support for the ground units. +% Since we will make a game on an \emph{operational} level (armies, +% divisions, brigades), we will give air units a single factor --- the +% odds column shift (see the combat resolution table later on). +% +% Let us first define a template for the ground units. We will call +% this \texttt{gu} (for ground unit), and it will take 8\footnote{Yes, +% that's a lot, but we may leave some of them blank. Don't worry, +% we'll make more short-hands.} arguments: +% \begin{enumerate}\tightlist +% \item The unit type +% \item The lower unit type (e.g., airborne) +% \item The unit size (echelon) +% \item The unit identifier +% \item The parent unit identifier +% \item The factors (more on this later) +% \item The starting hex +% \item The turn of appearance +% \end{enumerate} +% +% \begin{macrocode} +\tikzset{ + gu/.style args={#1,#2,#3,#4,#5,#6,#7,#8}{% + chit={% + symbol={% Defines the NATO symbol + faction=friendly, % See note + command=land, % Ground units + main={#1},% Unit type(s) (e.g., infantry) + lower=#2,% Lower type + echelon=#3,% Size (e.g., division) + scale line widths, + line width=1pt, + }, + unique={chit/small identifier=#4}, % Unit ID + parent={chit/small identifier=#5}, % Parent ID + factors={#6}, % The unit factors + upper left={chit/small identifier=#7}, % Hex + upper right={gu turn=#8} % Turn + } % end of chit + } % end of gu +} +% \end{macrocode} +% +% Note the \texttt{unique}, \texttt{parent}, and \texttt{upper left} +% keys of \texttt{chit} are set to contain a \texttt{chit/identifier} +% (or \texttt{chit/small identifier}) picture. In general, all the +% keys of a \texttt{chit} and (and \texttt{natoapp6c}) \Tikz{} node +% need to be \texttt{pic}\footnote{A small re-usable picture. See the +% \Tikz{} manual, Chapter~18.} objects. The \texttt{chit/identifier} +% picture outputs the text (the argument after the \texttt{=}). +% +% Note that for \texttt{upper left}, we used the \texttt{pic} +% \texttt{gu~turn}, which we have not defined yet. Let us define that +% now. This will be a picture that puts in the turn number when a +% unit appears. Turn number ``0'' is the ``At-start'' turn, and so we +% will deal with that specifically. Other turns should just be done +% normally --- that is, we use another \texttt{chit/small identifier} picture +% +% \begin{macrocode} +\tikzset{ + gu turn/.pic={% + \ifx#1\empty\else + \ifnum0=#1\else% + \pic{chit/small identifier={#1}};\fi\fi}, + pics/gu turn/.default=0 +} +% \end{macrocode} +% Note that we set the default value in case we get no turn number. +% +% We have put the keys \texttt{scale~line~widths} and +% \texttt{line~width=1pt} into the \texttt{symbol} (the NATO symbol) +% part. The latter sets the line width to be a little thicker than +% usual. This is to make the counters more easily read. The former +% ensures that if we scale our counters up or done, then the line +% width will likewise scale\footnote{Other elements scale +% automatically because of \Tikz{}'s \texttt{transform shape} key}. +% +% For the factors, we will use two different \texttt{pic}: +% \texttt{chit/2 factors} for regular ground units, and \texttt{chit/2 +% factors artillery} for artillery units. +% +% The template is shown in \figurename~\ref{fig:ground-unit}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \chit[gu={infantry,,division,23,2, +% {chit/2 factors={2,4}},D3,2}];% +% \end{tikzpicture} +% \caption{Ground unit template} +% \label{fig:ground-unit} +% \end{figure} +% +% The image above was made with +% +% \begin{verbatim} +% \begin{tikzpicture} +% \chit[gu={infantry,,division,23,2, +% {chit/2 factors={2,4}},D3,2}]; +% \end{tikzpicture} +% \end{verbatim} +% +% As said above, we will have artillery ground units and other kinds +% of ground units. Let us make two templates --- one for +% field-artillery ground units (\texttt{fu}), which has a range, and +% regular combat units (\texttt{cu}). +% +% First the artillery unit type: \texttt{fu}. This takes 8 arguments +% +% \begin{enumerate}\tightlist +% \item The echelon +% \item The identifier +% \item The parent identifier +% \item The combat factor (CF) +% \item The movement factor (MF) +% \item The range +% \item The starting hex +% \item The turn of appearance +% +% \end{enumerate} +% \begin{macrocode} +\tikzset{ + fu/.style args={#1,#2,#3,#4,#5,#6,#7,#8}{ + gu={% + {{[fill=pgfstrokecolor]artillery}}, % Type + ,%lower + #1, % echelon + #2, % ID + #3, % Parent ID + {chit/2 factors artillery={#4,#5,#6}}, + #7, % Hex + #8 % Turn + } + } +} +% \end{macrocode} +% +% Note that we pass the options \texttt{[fill=pgfstrokecolor]} to the +% \texttt{pic} \texttt{artillery}\footnote{To be explicit +% \texttt{natoapp6c/s/artillery}.} to fill in the artillery symbol. +% Note that we need to protect this by putting in curly brackets (2 in +% this case). Similarly, we protect the +% \texttt{chit/2~factors~artillery} call. +% +% \begin{quote} +% In general, we may pass options (or keys) to a \texttt{pic} by +% preceeding its name with \oarg{keys}. However, we then +% \emph{must} protect the it as in +% \texttt{\{\oarg{keys}\meta{pic}\}}. Further, if \oarg{keys} +% contains a list of keys, separated by commas, then we need to +% protect \meta{keys} too, as in +% \texttt{\{[\{\oarg{keys}\}]\meta{pic}\}}. A little clunky, but +% that's how \TeX{} works sometimes. +% \end{quote} +% +% And now the combat unit template: \texttt{cu}. This takes 9 +% arguments. +% +% \begin{enumerate}\tightlist +% \item The type +% \item The lower type +% \item The echelon +% \item The identifier +% \item The parent identifier +% \item The combat factor (CF) +% \item The movement factor (MF) +% \item The starting hex +% \item The turn of appearance +% \end{enumerate} +% \begin{macrocode} +\tikzset{ + cu/.style args={#1,#2,#3,#4,#5,#6,#7,#8,#9}{ + gu={% + {#1}, % Type + #2, % lower + #3, % echelon + #4, % ID + #5, % Parent + {chit/2 factors={#6,#7}}, + #8, % Hex + #9 % Turn + } + } +} +% \end{macrocode} +% +% Again, let us see what that looks like (\figurename~\ref{fig:fu-cu}). + +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \chit[cu={infantry,airborne,regiment, +% 21,2,6,4,E2,}](0,0);% +% \chit[fu={battalion,23,21,1,3,4,E2,}](2,0);% +% \end{tikzpicture} +% \caption{Combat and field artillery templates} +% \label{fig:fu-cu} +% \end{figure} +% +% The above was made with +% +% \begin{verbatim} +% \begin{tikzpicture} +% \chit[fu={battalion,23,21,1,3,4,E2,}](0,0); +% \chit[cu={infantry,airborne,regiment,21,2,6,4,E2,}] +% (2,0); +% \end{tikzpicture} +% \end{verbatim} +% +% Finally, we make a template for air units. We will have +% Close-combat Air Support (CAS \texttt{cas}) and strategic bombers +% (\texttt{sb}). To make things a little easier for us, we first +% define a template for all air units. This takes 7 arguments: +% \begin{enumerate}\tightlist +% \item The unit type (e.g., \texttt{fixed wing}, \texttt{rotary +% wing}). +% \item The upper modifier (e.g., \texttt{F} for fighter) +% \item The lower modifier (e.g., \texttt{H} for `heavy') +% \item The unit identifier +% \item The parent unit identifier +% \item The factor (column shift) +% \item The turn of appearance +% \end{enumerate} +% \begin{macrocode} +\tikzset{ + au/.style args={#1,#2,#3,#4,#5,#6,#7}{% + chit={% + symbol={% Defines the NATO symbol + faction=friendly, % See note + command=air, % Air units + main=#1,% Unit type + upper={text=#2}, + lower={text=#3}, + scale line widths, + line width=1pt, + }, + unique={chit/identifier=#4}, % Unit ID + parent={chit/identifier=#5}, % Parent ID + factors={#6}, % The unit factors + upper right={gu turn=#7} % Turn + } % end of chit + } % end of gu +} +% \end{macrocode} +% Here, \texttt{text}\footnote{really \texttt{/natoapp6c/s/text}.} for +% \texttt{lower} and \texttt{upper} is a picture that puts the text +% given as the argument after the \texttt{=}. The template is shown in +% \figurename~\ref{fig:au}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \chit[au={fixed wing,B,,A,1,% +% {chit/1 factor=+2},3}](0,0);% +% \end{tikzpicture} +% \caption{Air unit template} +% \label{fig:au} +% \end{figure} +% % +% The above was made with +% +% \begin{verbatim} +% \begin{tikzpicture} +% \chit[au={fixed wing,B,,A,1, +% {chit/1 factor=+2},3}](0,0); +% \end{tikzpicture} +% \end{verbatim} +% +% As we said, we will have CAS and strategic bomber wings in this +% game, so we make templates for these. Our CAS will be helicopters +% (\texttt{rotery wing}) while the strategic bombers are planes. CAS +% gives a 1 CF, while strategic bombers gives 1 column shift. +% Arguments are +% +% \begin{enumerate}\tightlist +% \item The identifier +% \item The parent identifier +% \item The turn of appearance +% \end{enumerate} +% \begin{macrocode} +\tikzset{ + cas/.style args={#1,#2,#3}{ % Close air support + au={% Air unit + rotary wing, % Helicopter + ,, % No lower, upper + #1, % ID + #2, % Parent ID + {chit/2 factors={1,0}}, + #3 %Turn + } + }, + sb/.style args={#1,#2,#3}{% strategic bomber + au={% Air unit + fixed wing, %Planes + B, % Bomber + M, % Medium + #1, % ID + #2, % Parent + {chit/1 factor={+1}}, + #3 % Turn + } + } +} +% \end{macrocode} +% +% The templates are shown in \figurename~\ref{fig:cas-sb}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \chit[cas={1,2,10}](0,0);% +% \chit[sb={3,4,}](2,0);% +% \end{tikzpicture} +% \caption{CAS and SB templates} +% \label{fig:cas-sb} +% \end{figure} +% +% The above was made with +% +% \begin{verbatim} +% \begin{tikzpicture} +% \chit[cas={1,2,10}(0,0); +% \chit[sb={3,4,}(2,0); +% \end{tikzpicture} +% \end{verbatim} +% +% \subsection{Specialisations} +% \label{sec:units:specialisations} +% +% We will now make some specialisations of the \texttt{gu} style. +% These represent headquarters \texttt{hq}, mechanised infantry +% \texttt{mi}, infantry \texttt{in}, and so +% on. We do this because we want units of the same kind to have +% similar factors and so on. Since almost all of our units are +% battalions, we also code that in. +% +% +% All of these, except \texttt{ff} for field artillery units, take 4 +% arguments +% \begin{enumerate}\tightlist +% \item The identifier +% \item The parent identifier +% \item The starting hex +% \item The turn of appearance +% \end{enumerate} +% +% The style \texttt{ff} precedes these arguments with a single +% argument for the unit size (echelon). +% +% \begin{macrocode} +\tikzset{ + in/.style args={#1,#2,#3,#4}{% + cu={infantry,,battalion,#1,#2,2,3,#3,#4}}, + mi/.style args={#1,#2,#3,#4}{% + cu={{armoured,infantry},,battalion,#1,#2,4,4,#3,#4}}, + ab/.style args={#1,#2,#3,#4}{% + cu={infantry,airborne,battalion,#1,#2,1,3,#3,#4}}, + ca/.style args={#1,#2,#3,#4}{% + cu={combined arms,,battalion,#1,#2,3,3,#3,#4}}, + ar/.style args={#1,#2,#3,#4}{% + cu={armoured,,battalion,#1,#2,6,4,#3,#4}}, + re/.style args={#1,#2,#3,#4}{% + cu={reconnaissance,,battalion,#1,#2,6,5,#3,#4}}, + ff/.style args={#1,#2,#3,#4,#5}{% + fu={#1,#2,#3,2,5,3,#4,#5}}, + hq/.style args={#1,#2,#3,#4,#5}{ + cu={headquarters,,#1,#2,#3,0,1,#4,#5}},% + hqbg/.style args={#1,#2,#3,#4}{ + hq={brigade,#1,#2,#3,#4}}, + hqregt/.style args={#1,#2,#3,#4}{ + hq={regiment,#1,#2,#3,#4}}, +} + +% \end{macrocode} +% \subsection{The actual units} +% \label{sec:units:actual} +% +% Above we defined templates for the various units. These templates +% saves us a lot of trouble when defining the \emph{actual} units. +% Below we will make the units for each faction in the game. We will +% define them as \Tikz{} styles, just like we did for the templates. +% +% \begin{quote} +% Above we said we want to make double sided counters. We will get +% back to the back-side (flipped) versions of the counters in a +% moment. +% \end{quote} +% +% \subsubsection{Side A} +% +% Below we will define the units without much commentary. Note that +% we use the style \texttt{a} for all our units so that they get the +% right style. Note that we pass the single argument \texttt{\#1} as +% the turn of appearance to all units. This will be used when +% generating an \emph{Order of Battle} later on. +% +% \begin{macrocode} +\tikzset{ + a hq/.style ={a,hq={corps,,,A2,#1}}, + a 1 hqbg/.style ={a,hqbg={1,,A2,#1}}, + a 1 1lg ibn/.style={a,mi={I-LG,1,D3,#1}}, + a 1 1gh ibn/.style={a,mi={I-GH,1,C2,#1}}, + a 1 2jd ibn/.style={a,mi={II-JD,1,A2,#1}}, + a 1 1 abn/.style ={a,ff={battalion,1,1,A1,#1}}, + a 2 hqbg/.style ={a,hqbg={2,,C2,#1}},% + a 2 1jd abn/.style={a,ar={I-JD,2,A2,#1}},% + a 2 3gh rbn/.style={a,re={I-JD,2,D2,#1}},% + a aregt/.style={a,ff={regiment,,,A1,#1}},% + a f/.style={a,cas={,,#1}},%VR + a b/.style={a,sb={,,#1}}%SK +} +% \end{macrocode} +% \iffalse +% KA: A2 Karup +% HO: A2 Holsterbro +% HV: D3 Høvelte +% SL: C2 Slagelse +% OK: A1 Oksbøl +% RO: D2 Rønne +% VR: D3 Værløse +% SK: B2 Skydstrup +% \fi +% Let us draw these units in what looks like an organisational +% diagram (\figurename~\ref{fig:a-org}). +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \node[a hq] (a hq) {}; +% \node[a aregt, below right=10mm and 10mm of a hq] (a aregt) {}; +% \node[a 1 hqbg, below left=10mm and 10mm of a hq] (a 1 hqbg) {}; +% \node[a 1 1lg ibn,below right=5mm and -8mm of a 1 hqbg] (a 1 1lg ibn){}; +% \node[a 1 1gh ibn,below=5mm of a 1 1lg ibn] (a 1 1gh ibn){}; +% \node[a 1 2jd ibn,below=5mm of a 1 1gh ibn] (a 1 2jd ibn){}; +% \node[a 1 1 abn, below=5mm of a 1 2jd ibn] (a 1 1 abn) {}; +% \node[a 2 hqbg, below=10mm of a hq] (a 2 hqbg) {}; +% \node[a 2 1jd abn,below right=5mm and -8mm of a 2 hqbg] (a 2 1jd abn){}; +% \node[a 2 3gh rbn,below=5mm of a 2 1jd abn] (a 2 3gh rbn){}; +% \node[a f, right=10mm of a aregt] (a f) {}; +% \node[a b, below=5mm of a f] (a b) {}; +% \draw(a 1 hqbg.south west) |- (a 1 1lg ibn.west); +% \draw(a 1 hqbg.south west) |- (a 1 1gh ibn.west); +% \draw(a 1 hqbg.south west) |- (a 1 2jd ibn.west); +% \draw(a 1 hqbg.south west) |- (a 1 1 abn.west); +% \draw(a 2 hqbg.south west) |- (a 2 1jd abn.west); +% \draw(a 2 hqbg.south west) |- (a 2 3gh rbn.west); +% \coordinate (mid) at ($(a hq.south)+(0,-.5)$) {}; +% \coordinate (off) at ($(mid)+(1.5,0)$) {}; +% \draw(a hq.south) -- (mid); +% \draw(mid) -| (a 1 hqbg.north); +% \draw(mid) -- (a 2 hqbg.north); +% \draw(mid) -| (a aregt.north); +% \end{tikzpicture} +% \caption{Faction A organisational chart} +% \label{fig:a-org} +% \end{figure} +% +% Before we go on to side B, we will make a macro that contains a list +% of all our A side counters. +% +% \begin{macrocode} +\def\alla{{% + a hq, + a 1 hqbg, + a 1 1lg ibn, + a 1 1gh ibn, + a 1 2jd ibn, + a 1 1 abn, + a 2 hqbg, + a 2 1jd abn, + a 2 3gh rbn, + a aregt, + a f, + a b}} +% \end{macrocode} +% +% \subsubsection{Side B} +% +% Below we will define the units without much commentary. Note that +% we use the style \texttt{b} for all our units so that they get the +% right style. Note that we pass the single argument \texttt{\#1} as +% the turn of appearance to all units. This will be used when +% generating an \emph{Order of Battle} later on. +%` +% \begin{macrocode} +\tikzset{ + b hq/.style= {b,hq= {corps,,,F6,#1}}, + b lg hqregt/.style= {b,hqregt={LG,,F6,#1}}, + b lg ibn/.style= {b,in= {LG,,F6,#1}}, + b k3 hqregt/.style= {b,hqregt={K3,,E7,#1}}, + b k3 31 abibn/.style= {b,ab= {31,K3,E7,#1}}, + b k4 hqregt/.style= {b,hqregt={K4,,F10,#1}}, + b k4 abibn/.style= {b,ab= {NL,K4,F10,#1}}, + b p4 hqregt/.style= {b,hqregt={P4,,D7,#1}}, + b p4 41 cabn/.style= {b,ca= {41,P4,D7,#1}}, + b p4 42 cabn/.style= {b,ca= {42,P4,D7,#1}}, + b p7 hqregt/.style= {b,hqregt={P7,,D4,#1}}, + b p7 71 ibn/.style= {b,mi= {71,P7,D4,#1}}, + b p7 72 cabn/.style= {b,ca= {72,P7,D4,#1}}, + b i13 hqregt/.style= {b,hqregt={I13,,D8,#1}}, + b i13 131 ibn/.style= {b,in= {131,I13,D8,#1}}, + b i13 132 ibn/.style= {b,in= {132,I13,D8,#1}}, + b p18 hqregt/.style= {b,hqregt={P18,,F5,#1}}, + b p18 181 cabn/.style={b,ca= {181,P18,F5,#1}}, + b i19 hqregt/.style= {b,hqregt={I19,,F10,#1}}, + b i19 191 cabn/.style={b,ca= {191,I19,F10,#1}}, + b i19 192 cabn/.style={b,ca= {192,I19,F10,#1}}, + b i21 hqregt/.style= {b,hqregt={I21,,D10,#1}}, + b i21 211 ibn/.style= {b,in= {211,I21,D10,#1}}, + b i21 212 ibn/.style= {b,in= {212,I21,D10,#1}}, + b f/.style= {b,cas= {F17,BL,#1}}, + b b/.style= {b,sb= {F7,SA,#1}} +} +% \end{macrocode} +% \iffalse +% SH: F6 Stockholm +% KU: F6 Kungsängen near stockholm F6 +% KA: E7 Karlsborg +% AR: Off Arvisjaur (top of baltic) +% SK: D7 Skövde +% RE: D3 Revingehed +% FA: D8 Falun +% VI: F5 Visby (delay from island) +% BO: Off Boden (top of baltic) +% SO: Off (D10) Sollefteå +% \fi +% Let us draw these units in what looks like an organisational +% diagram (\figurename~\ref{fig:b-org}). +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \node[b hq] (b hq) {}; +% \node[b lg hqregt, below left=10mm and 20mm of b hq] (b lg hqregt){}; +% \node[b lg ibn, below right=5mm and -8mm of b lg hqregt] (b lg ibn){}; +% \node[b k3 hqregt, below left=10mm and -1mm of b hq] (b k3 hqregt){}; +% \node[b k3 31 abibn, below right=5mm and -8mm of b k3 hqregt] (b k3 31 abibn){}; +% \node[b k4 hqregt, below right=10mm and -1mm of b hq] (b k4 hqregt){}; +% \node[b k4 abibn, below right=5mm and -8mm of b k4 hqregt] (b k4 abibn){}; +% \node[b p4 hqregt, below right=10mm and 20mm of b hq] (b p4 hqregt){}; +% \node[b p4 41 cabn, below right=5mm and -8mm of b p4 hqregt] (b p4 41 cabn){}; +% \node[b p4 42 cabn, below=5mm of b p4 41 cabn] (b p4 42 cabn){}; +% \node[b p7 hqregt, below left=65mm and 20mm of b hq] (b p7 hqregt){}; +% \node[b p7 71 ibn, below right=5mm and -8mm of b p7 hqregt] (b p7 71 ibn){}; +% \node[b p7 72 cabn, below=5mm of b p7 71 ibn] (b p7 72 cabn){}; +% \node[b i13 hqregt, below left=65mm and -1mm of b hq] (b i13 hqregt){}; +% \node[b i13 131 ibn, below right=5mm and -8mm of b i13 hqregt](b i13 131 ibn){}; +% \node[b i13 132 ibn, below=5mm of b i13 131 ibn] (b i13 132 ibn){}; +% \node[b p18 hqregt, below right=65mm and -1mm of b hq] (b p18 hqregt){}; +% \node[b p18 181 cabn,below right=5mm and -8mm of b p18 hqregt](b p18 181 cabn){}; +% \node[b i19 hqregt, below right=65mm and -1mm of b hq] (b i19 hqregt){}; +% \node[b i19 191 cabn,below right=5mm and -8mm of b i19 hqregt](b i19 191 cabn){}; +% \node[b i19 192 cabn,below=5mm of b i19 191 cabn] (b i19 192 cabn){}; +% \node[b i21 hqregt, below right=65mm and 20mm of b hq] (b i21 hqregt){}; +% \node[b i21 211 ibn, below right=5mm and -8mm of b i21 hqregt] (b i21 211 ibn){}; +% \node[b i21 212 ibn, below=5mm of b i21 211 ibn] (b i21 212 ibn){}; +% \node[b f, right=15mm of b hq] (b f){}; +% \node[b b, right=5mm of b f] (b b){}; +% +% \draw(b lg hqregt.south west) |- (b lg ibn.west); +% \draw(b k3 hqregt.south west) |- (b k3 31 abibn.west); +% \draw(b k4 hqregt.south west) |- (b k4 abibn.west); +% \draw(b p4 hqregt.south west) |- (b p4 41 cabn.west); +% \draw(b p4 hqregt.south west) |- (b p4 42 cabn.west); +% \draw(b p7 hqregt.south west) |- (b p7 71 ibn.west); +% \draw(b p7 hqregt.south west) |- (b p7 72 cabn.west); +% \draw(b p18 hqregt.south west) |- (b p18 181 cabn.west); +% \draw(b i19 hqregt.south west) |- (b i19 191 cabn.west); +% \draw(b i19 hqregt.south west) |- (b i19 192 cabn.west); +% \draw(b i13 hqregt.south west) |- (b i13 131 ibn.west); +% \draw(b i13 hqregt.south west) |- (b i13 132 ibn.west); +% \draw(b i21 hqregt.south west) |- (b i21 211 ibn.west); +% \draw(b i21 hqregt.south west) |- (b i21 212 ibn.west); +% +% \coordinate (mid) at ($(b hq.south)+(0,.-.5)$); +% +% \draw(b hq.south) -- (mid); +% \draw(mid) -| (b lg hqregt.north); +% \draw(mid) -| (b k3 hqregt.north); +% \draw(mid) -| (b k4 hqregt.north); +% \draw(mid) -| (b p4 hqregt.north); +% +% \coordinate (mid2) at ($(b hq.south)+(0,.-6)$); +% \draw(mid) -- (mid2); +% \draw(mid2) -| (b p7 hqregt.north); +% \draw(mid2) -| (b i13 hqregt.north); +% \draw(mid2) -| (b i19 hqregt.north); +% \draw(mid2) -| (b i21 hqregt.north); +% +% \end{tikzpicture} +% \caption{Faction B organisational chart} +% \label{fig:b-org} +% \end{figure} +% +% As before, we will make a macro that contains all B counters. +% +% \begin{macrocode} +\def\allb{{ + b hq, b lg hqregt, b lg ibn, + b k3 hqregt, b k3 31 abibn, + b p4 hqregt, b p4 41 cabn, b p4 42 cabn, + b p7 hqregt, b p7 71 ibn, b p7 72 cabn, + b i13 hqregt, b i13 131 ibn,b i13 132 ibn,% + b f, b b% + },{},{},{% Empty turns + b p18 hqregt, b p18 181 cabn% + },{ + b i21 hqregt, b i21 211 ibn, b i21 212 ibn% + },{},{ + b k4 hqregt, b k4 abibn% + },{ + b i19 hqregt, b i19 191 cabn, b i19 192 cabn% + }} +% \end{macrocode} +% +% Note that this is defined as a list of lists, and some of the lists +% are a little special. This is because we will reuse this list over +% and over again, and in particular for the Order of Battle charts. +% The point is that each element of the outer most list correspond to +% a turn, starting with turn ``0'', or ``At start''. Empty elements +% are thus turns where there will be no reinforcements for the faction. +% +% \subsection{The \texttt{flipped} side of things} +% \label{sec:units:flipped} +% +% Well, really the \texttt{flipped} definitions of the units. The +% flipped side of our unit counters will represent a ``spent'' state, +% i.e., a state where the unit cannot attack and only do limited +% manoeuvres. In this state, all units will have a combat factor or +% zero and movement factor of 1. Thus, we define a simple style that +% sets the factors +% +% \begin{macrocode} +\tikzset{ + flipped/.style={% + /chit/factors={chit/2 factors={0,1}}, + /chit/upper left={}, + /chit/upper right={} + } +} +% \end{macrocode} +% Note that we give the \emph{explicit full} path to the chits factors +% key. This is because we want to \emph{monkey patch} our units to +% have these new factors. We also clear the upper left and right +% corners on the flip side. +% +% Now, we'll do a little hack. Previously, we defined the +% \texttt{a~flipped} and \texttt{b~flipped} styles, but if you look +% closely, we can see how we can automatically define the flipped fill +% colours. Thus we make another style that does this. +% +% \begin{macrocode} +\tikzset{% + f/.style={% + flipped,fill=pgffillcolor!50!white}} +% \end{macrocode} +% +% With this, we can define the \texttt{flipped} state of all A +% counters. +% +% \begin{macrocode} +\tikzset{% + a hq flipped/.style= {a hq ,f}, + a 1 hqbg flipped/.style= {a 1 hqbg ,f}, + a 1 1lg ibn flipped/.style= {a 1 1lg ibn,f}, + a 1 1gh ibn flipped/.style= {a 1 1gh ibn,f}, + a 1 2jd ibn flipped/.style= {a 1 2jd ibn,f}, + a 1 1 abn flipped/.style= {a 1 1 abn ,f}, + a 2 hqbg flipped/.style= {a 2 hqbg ,f}, + a 2 1jd abn flipped/.style= {a 2 1jd abn,f}, + a 2 3gh rbn flipped/.style= {a 2 3gh rbn,f}, + a aregt flipped/.style= {a aregt ,f}, + a f flipped/.style= {a,f}, + a b flipped/.style= {a,f}, +} +% \end{macrocode} +% +% Let us draw the A side counters, front and back, using the macro +% \verb+doublechits+ (\figurename~\ref{fig:a-all}). +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \doublechits{\alla}{3}{1.24} +% \end{tikzpicture} +% \caption{All faction A counters, front and back} +% \label{fig:a-all} +% \end{figure} +% +% The above was produced by +% +% \begin{verbatim} +% \begin{tikzpicture} +% \doublechits{\alla}{3}{1.24} +% \end{tikzpicture} +% \end{verbatim} +% +% We will use the macro \verb+\doublechits+ later on to make our chit +% sheets. This works \emph{only} because we define the back sides of +% our chits to have the style `\meta{front} \texttt{flipped}', which +% is why it is \emph{highly} recommended to follow this convention. +% +% We do the same thing for the faction B counters. +% +% +% \begin{macrocode} +\tikzset{% + b hq flipped/.style= {b hq, f}, + b lg hqregt flipped/.style= {b lg hqregt, f}, + b lg ibn flipped/.style= {b lg ibn, f}, + b k3 hqregt flipped/.style= {b k3 hqregt, f}, + b k3 31 abibn flipped/.style= {b k3 31 abibn, f}, + b k4 hqregt flipped/.style= {b k4 hqregt, f}, + b k4 abibn flipped/.style= {b k4 abibn, f}, + b p4 hqregt flipped/.style= {b p4 hqregt, f}, + b p4 41 cabn flipped/.style= {b p4 41 cabn, f}, + b p4 42 cabn flipped/.style= {b p4 42 cabn, f}, + b p7 hqregt flipped/.style= {b p7 hqregt, f}, + b p7 71 ibn flipped/.style= {b p7 71 ibn, f}, + b p7 72 cabn flipped/.style= {b p7 72 cabn, f}, + b i13 hqregt flipped/.style= {b i13 hqregt, f}, + b i13 131 ibn flipped/.style= {b i13 131 ibn, f}, + b i13 132 ibn flipped/.style= {b i13 132 ibn, f}, + b p18 hqregt flipped/.style= {b p18 hqregt, f}, + b p18 181 cabn flipped/.style={b p18 181 cabn,f}, + b i19 hqregt flipped/.style= {b i19 hqregt, f}, + b i19 191 cabn flipped/.style={b i19 191 cabn,f}, + b i19 192 cabn flipped/.style={b i19 192 cabn,f}, + b i21 hqregt flipped/.style= {b i21 hqregt, f}, + b i21 211 ibn flipped/.style= {b i21 211 ibn, f}, + b i21 212 ibn flipped/.style= {b i21 212 ibn, f}, + b f flipped/.style= {b,f}, + b b flipped/.style= {b,f}} +% \end{macrocode} +% +% Let us draw the faction B counters, front and back, using the macro +% \verb+doublechits+ (\figurename~\ref{fig:b-all}). +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \doublechits{\allb}{3}{1.24} +% \end{tikzpicture} +% \caption{All faction B counters, front and back} +% \label{fig:b-all} +% \end{figure} +% +% The above was produced by +% +% \begin{verbatim} +% \begin{tikzpicture} +% \doublechits{\allb}{3}{1.24} +% \end{tikzpicture} +% \end{verbatim} +% +% \subsection{Other counters} +% \label{sec:units:other} +% +% In principle one can make as many and different counters and markers +% as needed. Here, we will keep things simple and only define a game +% turn marker. The package \textsf{wargame} already defines one as +% shown in \figurename~\ref{fig:plain-game-turn}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \chit[game turn] +% \end{tikzpicture} +% \caption{The \textsf{wargame} game turn counter} +% \label{fig:plain-game-turn} +% \end{figure} +% +% However, this has no flip side and we would like the side to reflect +% the faction currently in turn +% +% \begin{macrocode} +\tikzset{ + game turn/.append style={a}, + game turn flipped/.style={game turn,b} +} +% \end{macrocode} +% +% This modified game turn is shown in \figurename~\ref{fig:game-turn}. +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \doublechits{{game turn}}{1}{1.24} +% \end{tikzpicture} +% \caption{Modified game turn, front and back} +% \label{fig:game-turn} +% \end{figure} +% +% \section{The board} +% \label{sec:board} +% +% Designing the board is probably where one will spend the most time. +% The \textsf{wargame} package is not omnipotent, but tries to make it +% as simple as possible. However, some artistic streak is a good +% thing, and familiarity with \Tikz{} is highly recommended. +% +% The simplest thing one can do is to import an image and superimpose +% hexes on top of that image. While often a good solution, it does +% not always give the most pleasing board. +% +% The \textsf{wargame} package does not, in and of it self, provide +% fancy ``modern'' graphics (though it can be done). Rather, off the +% shelf, it mimics classic wargames of yore (Afrika Korps, D-Day, +% Russian Campaign, and so on). That is, it uses rather simplified +% graphics. +% +% For our game, we will have three kinds of terrain: Clear, woods, and +% mountains. The map will have a lot of coastline, but the scale of +% the game is such that naval units are not really called for. +% Indeed, the game focuses on land combat with abstracted aerial +% support. +% +% The first thing we do, is to decide a few things about the map. We +% want to have the hexes automatically label with alphabetic columns +% and numerical rows. We want to start our rows and columns at 1 (the +% default is starting at 0). By default, we want the hexes to be white +% (for clear terrain). To set this up, we define some more +% keys. +% +% \begin{macrocode} +\tikzset{% + hex/short bottom columns=even, + hex/short top columns=odd, + hex/label is name, + hex/first row and column are=1, + every hex/.style={ + /hex/label={auto=alpha column}, + fill=white}, +}% +% \end{macrocode} +% +% Note how we used the \emph{full} path for the \texttt{/hex/label} +% key. This will be important when we generate a VASSAL module later +% on. +% +% The key \texttt{hex/label is name} makes it so that every hex on the +% board will be a named \texttt{node}. This means we can refer to a +% hex in \Tikz{} simply by its label. In fact, we can use various +% anchors of the hex if we want to --- it is a \texttt{node} like any +% other node in \Tikz{}. +% +% The keys \texttt{hex/short bottom column=even} and +% \texttt{hex/short~top~column=odd} is mainly used by the +% \verb+\boardframe+ macro to generate a proper frame. +% +% Having defined the settings, we can move on to the board itself. We +% will do this in parts. This makes it easier to get an overview of, +% and helps us in this tutorial to explain what is going on. +% +% The first thing we do, is define a macro that defines the coast line +% of our map. We use the hexagonal coordinate system provided by the +% \textsf{wargame} package, but we could also have used general +% Cartesian coordinates. +% +% \begin{quote} +% Defining the coastline of a map can be quite tedious. You may +% want to use some vector graphics editor, say Inkscape, to do +% this. In the \textsf{wargame} package you will find a Python +% script to convert an SVG to \Tikz{} paths. +% \end{quote} +% +% Alright, let's make our macro to define the coastline. +% +% \begin{macrocode} +\newcommand\coastline{% + (hex cs:c=1,r=1,v=SE) + --(hex cs:c=1,r=1,e=SE) + --(hex cs:c=1,r=1,e=NE,o=.5) + --(hex cs:c=1,r=1,v=NW,o=.7) + --(hex cs:c=1,r=2,v=W,o=.6) + --(hex cs:c=1,r=2,v=NW,o=.7) + --(hex cs:c=1,r=3,v=SE,o=.9) + --(hex cs:c=1,r=3,e=SE,o=.9) + --(hex cs:c=2,r=4,e=S,o=.7) + --(hex cs:c=2,r=3,v=NE,o=.4) + --(hex cs:c=2,r=3,e=S,o=.1) + --(hex cs:c=2,r=3,v=E,o=.8) + --(hex cs:c=2,r=3,e=SE,o=.8) + --(hex cs:c=2,r=3,v=SE,o=.6) + --(hex cs:c=2,r=2,v=NW,o=.2) + --(hex cs:c=2,r=2,e=SE) + --(hex cs:c=3,r=1,e=NE) + --(hex cs:c=4,r=2,e=N,o=.3) + --(hex cs:c=5,r=2,e=S,o=.6) + --(hex cs:c=5,r=2,v=SE,o=.9) + --(hex cs:c=7,r=3,v=E) + --(hex cs:c=7,r=1,v=E) + --(hex cs:c=6,r=1,v=E,o=2.5) + --cycle + (hex cs:c=3,r=2,v=W,o=.5) + --(hex cs:c=4,r=3,e=NW,o=.75) + --(hex cs:c=4,r=3,e=SW,o=.3) + --(hex cs:c=4,r=2,e=NW,o=.7) + --(hex cs:c=3,r=2,v=SW,o=.4) + --cycle + (hex cs:c=2,r=4,e=N,o=.8) + --(hex cs:c=2,r=4,v=E,o=.7) + --(hex cs:c=3,r=3,v=E,o=.8) + --(hex cs:c=4,r=3,v=NW,o=.6) + --(hex cs:c=4,r=3,e=NW,o=.1) + --(hex cs:c=4,r=3,v=SE,o=.4) + --(hex cs:c=5,r=3,v=SW,o=.6) + --(hex cs:c=5,r=3,v=NE,o=.2) + --(hex cs:c=5,r=3,e=NE) + --(hex cs:c=6,r=4,v=SW,o=.3) + --(hex cs:c=5,r=4,v=E,o=1.7) + --(hex cs:c=6,r=5,e=N) + --(hex cs:c=6,r=6,v=E) + --(hex cs:c=7,r=6,v=NW,o=.4) + --(hex cs:c=6,r=7,e=S,o=.2) + --(hex cs:c=6,r=7,e=NW) + --(hex cs:c=6,r=8,e=NW,o=.7) + --(hex cs:c=7,r=9,e=NE) + --(hex cs:c=6,r=10,v=E,o=2.5) + --(hex cs:c=7,r=10,v=E) + --(hex cs:c=1,r=10,v=W) + --(hex cs:c=2,r=4,v=W,o=2.5) + --(hex cs:c=2,r=5,v=SW) + --cycle + ; +} +% \end{macrocode} +% +% The coast line is shown in \figurename~\ref{fig:coast}\footnote{Any +% resemblance to any actual location is, erhm, accidental?} +% +% \begin{figure} +% \centering +% \begin{tikzpicture}[scale=.7] +% \draw[fill=gray] \coastline; +% \end{tikzpicture} +% \caption{The coast line} +% \label{fig:coast} +% \end{figure} +% +% As you can see, it is pretty simple. Not too many details about the +% nooks and crannies. Now we want to define some colours that we will +% use on the map. As mentioned above, we will have some sea, and we +% will have some surrounding neutral countries. Let us define some +% colours for these things. +% +% \begin{macrocode} +\definecolor{sea}{HTML}{18b5db} +\colorlet{neutral}{gray!25!white} +\colorlet{coast}{black} +% \end{macrocode} +% +% OK, with that out of the way, we start on the hexes in earnest. We +% define the macro \verb+\hexes+ to produce our hexes within our map. +% +% \begin{macrocode} +\newcommand\hexes[1][]{ +% \end{macrocode} +% +% We have defined this macro to take a single optional argument. We +% wont use that here, but it might come in handy at some later point. +% +% The first thing we do, is to fill the entire map with \texttt{sea}. +% +% \begin{macrocode} + \fill[sea](-1.000,-0.866) rectangle(10.,15.580); +% \end{macrocode} +% +% Then we use the macro \verb+\coastline+ to define a path that we may +% use over and over again. +% +% \begin{macrocode} + \path[save path=\coast]\coastline; +% \end{macrocode} +% +% Next up, we want to draw hexes that are on the coast line but also +% has land parts in it. This is so that the hexes are complete and +% get a proper label on it. We define the fill to be the sea +% colour, and the lines labels to be white +% +% \begin{macrocode} + \begin{scope}[ + every hex/.append style={white,fill=sea}, + hex/label/.append style={color=white}] + \hex(c=1,r=1); \hex(c=1,r=2); + \hex(c=1,r=3); + \hex(c=2,r=2); \hex(c=2,r=3); + \hex(c=2,r=4); + \hex(c=3,r=2); \hex(c=3,r=3); + \hex(c=4,r=2); \hex(c=4,r=3); + \hex(c=5,r=3); \hex(c=5,r=7); + \hex(c=6,r=4); \hex(c=6,r=5); + \hex(c=6,r=6); \hex(c=6,r=7); + \hex(c=6,r=8); \hex(c=6,r=9); + \hex(c=7,r=6); \hex(c=7,r=9); + \end{scope} +% \end{macrocode} +% Note that we use the \texttt{.append style} handler so that we get +% the setting from above here too (labels, among other things). These +% amended styles only have effect inside the \texttt{scope}. Once we +% leave the scope, then the old settings are restored. +% +% We draw a compass needle. +% +% \begin{macrocode} + \draw[white,-{Stealth[]}, + scale line widths, + line width=1mm] + (hex cs:c=7,r=4,v=SE) -- ++(110:2) + node[midway, + font=\sffamily\bfseries\LARGE, + transform shape, + rotate=-90,sloped]{N}; +% \end{macrocode} +% +% Since the areas where we do not add hexes are considered neutral +% countries in this game, we fill the whole coast line with the +% previously defined \texttt{neutral} colour. +% +% \begin{macrocode} + \settosave{\coast} + \fill[neutral]; +% \end{macrocode} +% +% Here we have the first use of the saved path \verb+\coast+. We make +% that the current path by calling \verb+\setosave+ --- a small +% utility in the \textsf{wargame} package. +% +% We can now add the actual hexes. Some of the hexes will represent +% different terrain, and that will be clear from the definitions. We +% will put our definitions inside a scope, and the first thing we do +% in that scope is to clip everything to our coast line. This will be +% the second use of \verb+\coast+. +% +% \begin{macrocode} + \begin{scope} + \settosave{\coast} + \clip; + + \hex(c=1,r=1);\hex(c=1,r=2);\hex(c=1,r=3); +% \end{macrocode} +% +% Note that we use the \texttt{hex cs} coordinate system. We specify +% the column (\texttt{c}) and the row (\texttt{r}) of each hex. We can +% use longer forms, of the keys if we want. +% +% The southern border of A factions country needs a little special +% attention. We clip the drawn hex, and draw the border. In fact, we +% draw the hex twice, first time with a white outline and the neutral +% fill colour. This is so that the full hex will be drawn, even it is +% only partially within the map area. +% +% \begin{macrocode} + \hex[white,fill=neutral,label=](c=2,r=2); + \begin{scope} + \clip(hex cs:c=2,r=2,v=SW) + --(hex cs:c=2,r=2,v=E) + --(hex cs:c=2,r=2,v=NE) + --(hex cs:c=2,r=2,v=NW) + --(hex cs:c=2,r=2,v=W) + --cycle; + \hex(c=2,r=2); + \end{scope} + \draw[coast] (hex cs:c=2,r=2,v=SW) + --(hex cs:c=2,r=2,v=E); +% \end{macrocode} +% Note that our clipping path is defined in the \texttt{hex cs} +% coordinate system, and how we have retrieved vertex coordinates via +% the key \texttt{v}. +% +% Now we come to some other terrain: woods and mountains. +% +% \begin{macrocode} + \hex(c=2,r=3);\hex(c=2,r=4);\hex(c=2,r=5); + \hex[terrain=mountains](c=2,r=6); + \hex[terrain=mountains](c=2,r=7); + \hex[terrain=mountains](c=2,r=8); +% \end{macrocode} +% +% Again, we do not want to draw the hex in the neutral country to +% the south, so we clip this hex too. +% +% +% +% +% \begin{macrocode} + \hex[white,fill=neutral,label=](c=4,r=2); + \begin{scope} + \clip(hex cs:c=4,r=2,v=W) + --(hex cs:c=4,r=2,v=NE) + --(hex cs:c=4,r=2,v=NW) + --cycle; + \hex(c=4,r=2); + \end{scope} +% \end{macrocode} +% +% \begin{macrocode} + \hex(c=3,r=2); \hex(c=3,r=3); + \hex[terrain=woods](c=3,r=4); + \hex(c=3,r=5); + \hex[terrain=woods](c=3,r=6); + \hex[terrain=woods](c=3,r=7); + \hex[terrain=mountains](c=3,r=8); + \hex[terrain=mountains](c=3,r=9); +% \end{macrocode} +% +% In the next step, we will add a town to the map. +% +% \begin{macrocode} + \hex[town={ + place={(hex cs:c=1,r=1,e=SW,o=.5)}}] + (c=4,r=3); + \hex[terrain=woods](c=4,r=4); + \hex(c=4,r=5); + \hex[terrain=woods](c=4,r=6); + \hex[terrain=woods](c=4,r=7); + \hex[terrain=woods](c=4,r=8); + \hex[terrain=woods](c=4,r=9); + \hex(c=4,r=10); +% \end{macrocode} +% The \texttt{place} key specifies the placement of the town relative +% to the hex centre. +% +% For the rest of the map, there isn't much new. +% +% \begin{macrocode} + \hex(c=5,r=3); + \hex[terrain=woods](c=5,r=4); + \hex[](c=5,r=5); + \hex[terrain=woods](c=5,r=6); + \hex[terrain=woods](c=5,r=7); + \hex[terrain=woods](c=5,r=8); + \hex[terrain=woods](c=5,r=9); + + \hex[terrain=woods](c=6,r=4); + \hex[terrain=woods](c=6,r=5); + \hex[town={ + place={(hex cs:c=1,r=1,v=E,o=.3)}}] + (c=6,r=6); + \hex(c=6,r=7); \hex(c=6,r=8); + \hex[terrain=woods](c=6,r=9); + \hex[terrain=woods](c=6,r=10); + + \hex(c=7,r=4); \hex(c=7,r=5); + \hex(c=7,r=6); \hex(c=7,r=7); + \hex(c=7,r=8); \hex(c=7,r=9); + \end{scope} +} +% \end{macrocode} +% +% That concludes our hexes. Let us draw it (\figurename~\ref{fig:hexes}). +% +% \begin{figure} +% \centering +% \begin{tikzpicture}[scale=.7] +% \hexes +% \end{tikzpicture} +% \caption{Our hexes} +% \label{fig:hexes} +% \end{figure} +% +% This only defines the map. Now we would like to make the full +% board. Typically one want to add a turn track and some other stuff. +% Here, we will keep it fairly simple and just add a turn track. +% +% \begin{quote} +% This is where we need to start to consider VASSAL. Essentially, +% VASSAL can split a board into \emph{zones}. These zones can be +% different game specific places, e.g., a place to keep eliminated +% units, a place for the turn track, and so on. We will take +% advantage of this in our board definition by applying some +% specific styles. +% \end{quote} +% +% Below we customise the board frame, and some other things on the +% board. +% +% \begin{macrocode} +\colorlet{framebg}{gray!50!white} +\colorlet{titlefg}{gray!50!black} +\tikzset{ + hex/board frame/.style={ + scale line widths, + line width=.5pt, + draw=black}, + board frame/.style={% + anchor=south west, + transform shape, + scale line widths, + line width=1pt, + draw=black, + fill=framebg, + minimum width=14cm,% + minimum height=19cm + }, + turn/.style={ + scale line widths, + line width=.5pt, + fill=white, + draw=black, + text=gray, + minimum width=1.4cm, + minimum height=1.4cm, + text width=1.2cm, + align=center, + font=\sffamily\bfseries\huge, + transform shape, + anchor=north east + }, + title/.style={ + text=titlefg, + font=\sffamily\bfseries\Huge, + scale=1.5, + transform shape, + }, + sub title/.style={ + text=titlefg!75!white, + font=\sffamily\bfseries\normalsize, + scale=1.5, + transform shape, + text width=5cm, + align=right + } +} +% \end{macrocode} +% +% Let us start the board. The \textsf{wargame} package has a tool +% \verb+\boardrame+ which will put a frame around the map as defined +% by hex coordinates. It also output the map bounding box to the +% standard log file. So running \LaTeX{} once with this macro in +% effect will give us some useful information. +% +% We will define the board in two steps. First we define an +% \emph{environment} which holds the map, turn track, and title of the +% game, and after that we will add an environment that wraps it in a +% \Tikz{} picture. +% +% We define the board as an environment, so that we may put +% things on the board in our explanations of the rules. +% +% \begin{macrocode} +\newenvironment{innerboard}[1][]{% + \node[board frame] (frame) {}; +% \end{macrocode} +% +% This adds in our frame of the whole map as defined by the style +% above. +% +% Also note that we made our outer frame a \texttt{node}. This is so +% that we can refer to its anchors without too much knowledge of its +% size. +% +% We have made our frame a little bigger than the hex, so that we may +% add a turn track. We will at it at the top, and we will add 10 +% turns. Here, we make use of \Tikz{} loops, and they do the trick for +% us. +% +% We will make use the style \texttt{zone scope} with the name +% \texttt{Turns}. This will be made into a VASSAL zone that has a +% coordinate system that identifies it (at least by convention) as +% turn track. We will in fact deploy a little trick here to make the +% module even more complete. This is because we add the style +% \texttt{zone~point} to the turn number nodes below, and the first +% one will have the name of the game turn marker. This means that the +% game turn marker will \emph{automatically} be placed there. If the +% below is a little complicated for you, take a look at the +% alternative below the code +% +% \begin{macrocode} + \begin{scope}[ + shift={($(frame.south east)+(-0.5,.5)$)}] + \begin{scope}[zone scope=Turns] + \foreach \i in {1,...,10}{% + \pgfmathparse{\i*1.65-.225-.7} + \edef\y{\pgfmathresult} + \ifnum1=\i + \def\tname{game turn} + \else + \def\tname{T\i} + \fi + \node[turn,zone point={\tname}{-.7}{\y}] + at (0,\y+.7) {\i}; + } + \end{scope} + \end{scope} +% \end{macrocode} +% +% A simpler alternative would be +% +% \begin{verbatim} +% \begin{scope}[ +% shift={($(frame.south east)+(-0.5,.5)$)}] +% \begin{scope}[zone scope=Turns] +% \foreach \i in {1,...,10}{% +% \node[turn] at (0,\i*1.65-.225) {\i}; +% } +% \end{scope} +% \end{scope} +% \end{verbatim} +% We also add a title using the styles we defined above. Note, +% consistent use of \Tikz{} styles makes it very easy to change things +% consistently throughout the game. +% +% \begin{macrocode} + \node[below right=5mm and 5mm of + frame.north west,title]{A Game}; + \node[below left=5mm and 5mm of + frame.north east,sub title]{A tutorial in the\\ + {\color{white}wargame} package}; +% \end{macrocode} +% +% With this, we are left with adding in the map. +% +% \begin{macrocode} + \scope[shift={(.5,.5)}] + \scope[shift={(1,0.86603)}, + zone scope=Hex] + \hexes + \boardframe(c=1,r=1)(c=7,r=10) + % Reported by the above + % Board Frame: + % BBox: (-1.0,-0.86603)x(10.0,15.5885) + % WxH: (11.0x16.45453) + % NCxNR (1,1)x(7,10) +% \end{macrocode} +% +% Above, we see the output from \verb+\boardframe+. This in turn +% informs us how to set the offset of the inner most scope. We also +% see that the map is $11\times 16.45453\,\textrm{cm}$ big, which means +% our board will easily fit on standard paper (A4 or, less standard, +% Letter). +% +% \begin{quote} +% The offset of $(-1,0.86603)$ is not surprising when you know that +% the radius $r$ of the circumscribed circle of the hexes is 1\,cm, +% and that the first hex centre is placed in $(0,0)$. The horizontal +% offset of -1 is just that radius $r$, and the vertical offset is +% $r\sin60^{\circ}=\sqrt{3}/2=0.86603$. +% \end{quote} +% +% The outer most scope translates the hex 5mm in from both edges so +% that we may draw a nice frame around the map. +% +% The style \texttt{zone scope=Hex} will make this area a zone in +% VASSAL and it will have a hex grid (because its argument contains +% the sub string \texttt{hex}) attached to it. +% +% This end the start of the environment. Next, we define the end of +% it. This simply closes the scopes and the \Tikz{} picture. +% +% \begin{macrocode} +}{ + \endscope% + \endscope% +} +% \end{macrocode} +% +% This ends the environment that defines the board proper. Now we +% wrap it in another environment that will put the map inside a +% \Tikz{} picture. +% +% \begin{macrocode} +\newenvironment{board}[1][]{% + \tikzpicture[#1,zoned] + \innerboard}{% + \endinnerboard% + \endtikzpicture} +% \end{macrocode} +% +% The style \texttt{zoned} on the \Tikz{} picture ensures that we will +% get a zoned map when generating the VASSAL module. Note that we +% used the \TeX{}-like form of the environment \verb+\tikzpicture+, +% rather than \verb+\begin{tikzpicture}+, so that the various +% \verb+\end+s does not mess up things. +% +% +% We can draw the final board (\figurename~\ref{fig:board}). +% \begin{figure} +% \centering +% \begin{board}[scale=.5] +% \end{board} +% \caption{The final board} +% \label{fig:board} +% \end{figure} +% +% \subsection{Adding units to the board} +% \label{sec:board:units} +% +% We have defined our board as a environment so we can add units to it +% without much hassle. Let us add the starting units at the starting +% positions. Since we will be \emph{stacking} chits, we will use the +% \verb+\chitstack+ macro for this. Note that this macro expects code +% to produce the chits (rather than the unit styles). Therefore we +% must add in some \verb+\noexpand+ in front of the \verb+\chit+ +% command. +% +% \begin{figure} +% \centering +% \begin{board}[scale=.5]% +% \stackchits(A2)(.2,.2){%% +% \noexpand\chit[a hq],% +% \noexpand\chit[a 1 hqbg],% +% \noexpand\chit[a 1 2jd ibn],% +% \noexpand\chit[a 2 1jd abn]}% +% \chit[a 1 1lg ibn](D3);% +% \stackchits(C2)(.2,.2){%% +% \noexpand\chit[a 2 hqbg],% +% \noexpand\chit[a 1 1gh ibn]}% +% \stackchits(A1)(.2,.2){%% +% \noexpand\chit[a aregt],% +% \noexpand\chit[a 1 1 abn]}% +% \chit[a 2 3gh rbn](D2);% +% +% \stackchits(F6)(.2,.2){%% +% \noexpand\chit[b hq],% +% \noexpand\chit[b lg hqregt],% +% \noexpand\chit[b lg ibn]}% +% \stackchits(E7)(.2,.2){%% +% \noexpand\chit[b k3 hqregt],% +% \noexpand\chit[b k3 31 abibn]}% +% \stackchits(D7)(.2,.2){%% +% \noexpand\chit[b p4 hqregt],% +% \noexpand\chit[b p4 41 cabn],% +% \noexpand\chit[b p4 42 cabn]}% +% \stackchits(E3)(.2,.2){%% +% \noexpand\chit[b p7 hqregt],% +% \noexpand\chit[b p7 71 ibn],% +% \noexpand\chit[b p7 72 cabn]}% +% \stackchits(D4)(.2,.2){%% +% \noexpand\chit[b i13 hqregt],% +% \noexpand\chit[b i13 131 ibn],% +% \noexpand\chit[b i13 132 ibn]}% +% \end{board} +% \caption{The board with units at their starting positions} +% \label{fig:board-start} +% \end{figure} +% +% The board with the ``At-start'' units in place are shown in +% \figurename~\ref{fig:board-start}. The first part of this was made +% with +% +% \begin{verbatim} +% \begin{board} +% \stackchits(A2)(.2,.2){% +% \noexpand\chit[a hq], +% \noexpand\chit[a 1 hqbg], +% \noexpand\chit[a 1 2jd ibn], +% \noexpand\chit[a 2 1jd abn]} +% \chit[a 1 1lg ibn](D3); +% \end{verbatim} +% +% The first argument to \verb+\stackchits+ is where to put the +% stack. The second is the offset applied to each stack unit in +% succession (obviously the first offset is $(0,0)$). The third +% argument is the list of chits to add to the stack. +% +% Note that we use the hex labels, rather than the hex coordinates, to +% place the units and stacks of units, thanks to \texttt{hex/label is +% name}. +% +% We have made the counters and board for the game. What remains is +% the various tables (and or of course the rules). +% +% \subsection{Clipped boards} +% \label{sec:board:clipped} +% +% We are not quite done with the board just yet. We want to make +% \emph{another} environment which will clip to a specified area of +% the map. We will reuse our \texttt{innerboard} environment so that +% everything is consistent. Let us go ahead and define the +% environment, and then see later how it is used. We define our +% environment as two macros \verb+\clipped+ and \verb+\endclipped+ so +% that we can use parenthesis for our arguments. +% +% \begin{macrocode} +\tikzset{ + clip board/.style={gray,line width=.5pt}} +\newcommand\clipped[1][]{\doclipped[#1]} +\def\doclipped[#1](#2)(#3){ + \def\tmp@clip@a{#2} + \def\tmp@clip@b{#3} + \tikzpicture[#1] + \scope + \clip (#2) rectangle (#3); + \scope[shift={(-.5-1,-.5-0.86603)}] + \innerboard} +\def\endclipped{% + \endinnerboard + \endscope + \endscope + \draw[clip board](\tmp@clip@a) + rectangle (\tmp@clip@b); + \endtikzpicture} +% \end{macrocode} +% +% Our environment \texttt{clipped} takes 3 arguments. One is optional +% and is keys to pass to the \Tikz{} picture environment. The two +% others are the coordinates (relative to the hexes) of our clipping +% rectangle. Let us illustrate this with an example --- see +% \figurename~\ref{fig:clipped}. +% +% \begin{figure} +% \centering +% \begin{clipped}(hex cs:c=2,r=2)(hex cs:c=5,r=5) +% \end{clipped} +% \caption{Example of using \texttt{clipped}.} +% \label{fig:clipped} +% \end{figure} +% +% The figure was produced by the code +% +% \begin{verbatim} +% \begin{clipped}(hex cs:c=2,r=2)(hex cs:c=5,r=5) +% \end{clipped} +% \end{verbatim} +% +% Note that we \emph{must} use the hex coordinate system. When we +% make the clipping path, the nodes of the hex map has not yet been +% defined. We can use this to illustrate things on the map. For +% example, \figurename~\ref{fig:clipped-attack} show that B P7/72 CABN +% attacks A 2/1JD ABN with the code +% +% \begin{verbatim} +% \begin{clipped}(hex cs:c=2,r=3)(hex cs:c=5,r=5) +% \chit[b p7 72 cabn](D5); +% \chit[a 2 1jd abn](C4); +% \draw[hex/attack] (D5)--(C4); +% \end{clipped} +% \end{verbatim} +% +% \begin{figure} +% \centering +% \begin{clipped}(hex cs:c=2,r=3)(hex cs:c=5,r=5) +% \chit[b p7 72 cabn](D5); +% \chit[a 2 1jd abn](C4); +% \draw[hex/attack] (D5)--(C4); +% \end{clipped} +% \caption{Example of using \texttt{clipped}.} +% \label{fig:clipped-attack} +% \end{figure} +% +% Note that \emph{inside} the environment we \emph{can} use hex +% labels as coordinates. +% +% \section{The charts} +% \label{sec:charts} +% +% We will not go into details about how to make tables in +% \LaTeX{}. There are plenty of excellent resources out there for that +% purpose. Here we will make three tables: The combat resolution +% table (CRT), the terrain effects chart (TEC), and the Order of Battle +% (OOB) chart\footnote{In some games this is called the Order of +% Appearance (OOA) chart.} --- all of which in some respect uses +% elements of the +% \textsf{wargame} package. +% +% For all the tables, we would like to use the \textsf{colortbl} +% package to colour the rows. Here, we make some short hands for +% doing just that. +% +% \begin{macrocode} +\colorlet{headbg}{gray!50!white} +\colorlet{altbg}{gray!15!white} +\newcommand\headrow{\rowcolor{headbg}} +\newcommand\defrow{\rowcolor{white}} +\newcommand\altrow{\rowcolor{altbg}} +% \end{macrocode} +% +% \subsection{The CRT} +% \label{sec:charts:crt} +% +% The combat resolution table is in some sense a straight forward +% \LaTeX{} table. Here's the definition +% +% \begin{macrocode} +\newcommand\crt{% + \begin{tabular}{|c|cccccc|} + \hline + \headrow + \textbf{Die} + & \multicolumn{6}{c|}{\textbf{Odds}} + \\ + \headrow + \textbf{roll} + & \textbf{1:3} + & \textbf{1:2} + & \textbf{1:1} + & \textbf{2:1} + & \textbf{3:1} + & \textbf{4:1} + \\ + \hline + \defrow + 1 & AE & AR & AR & EX & DR & DR \\ + \altrow + 2 & AE & AR & EX & EX & DR & DR \\ + \defrow + 3 & AR & EX & EX & DR & DR & DE \\ + \altrow + 4 & AR & EX & EX & DR & DR & DE \\ + \defrow + 5 & EX & EX & DR & DR & DE & DE \\ + \altrow + 5 & EX & DR & DR & DE & DE & DE \\ + \hline + \end{tabular}} +% \end{macrocode} +% +% And what it looks like is shown in \tablename~\ref{tab:crt} +% +% \begin{table} +% \centering +% \crt{} +% \caption{The combat resolution table} +% \label{tab:crt} +% \end{table} +% +% \subsection{The TEC} +% \label{sec:charts:te} +% +% In this table we will use small version of hexes to make a nice +% table. The definition is as follows. +% +% \begin{macrocode} +\newcommand\tec{% + \begin{tabular}{|cl|cc|} + \hline + \headrow + \multicolumn{2}{|c|}{\textbf{Terrain}} + & MF + & CF\textsuperscript{\dag} + \\ + \hline + \defrow + \tikz[scale=.5]{\hex[label=]} + & Clear + & 1 + & --- + \\ + \altrow + \tikz[scale=.5]{\hex[label=,terrain=woods]} + & Woods + & 2 + & \texttimes 2\textsuperscript{*} + \\ + \defrow + \tikz[scale=.5]{\hex[label=,terrain=mountains]} + & Mountains + & Stop + & \texttimes 2\textsuperscript{*} + \\ + \altrow + \tikz[scale=.5]{ + \hex[label=,fill=sea](c=1,r=1); + \begin{scope} + \clip + (hex cs:c=1,r=1,v=NW) + --(hex cs:c=1,r=1,v=W) + --(hex cs:c=1,r=1,v=SW) + --(hex cs:c=1,r=1,e=S) + --(hex cs:c=1,r=1,v=W,o=.5) + --cycle + (hex cs:c=1,r=1,e=N) + --(hex cs:c=1,r=1,v=NE) + --(hex cs:c=1,r=1,v=E) + --(hex cs:c=1,r=1,e=SE) + --(hex cs:c=1,r=1,v=E,o=.4) + --cycle + ; + \hex[label=](c=1,r=1); + \end{scope} + } + & Coastal + & 2 + & \texttimes2\phantom{\textsuperscript{*}} + \\ + \hline + \multicolumn{4}{l}{\textsuperscript{\dag} + \emph{Defender} modifier}\\ + \multicolumn{4}{l}{\textsuperscript{*} + \infantrymark{}\,\pgmark{} \emph{only}, + unless \artillerymark} + \\ + \end{tabular} +} +% \end{macrocode} +% +% The result is in \tablename~\ref{tab:te}. Note the use of +% \verb+\infantrymark+ to put in \infantrymark{} in the table. The +% \textsf{wargame} package defines a number of macros like this. +% +% \begin{table} +% \centering +% \tec +% \caption{The terrain effects table} +% \label{tab:te} +% \end{table} +% +% \subsection{The OOB} +% \label{sec:charts:oob} +% +% We like to make an OOB chart that we can place our unit counter on +% so we can keep track of which units are available when. In our +% game, all A faction units start already on the board. The B faction, +% however, has most of its reinforcement troops way up north, and will +% therefore bring them on the map piecemeal. +% +% We will use the \textsf{wargame} macro \verb+\oob+ to make our +% OOBs. This macro uses the \texttt{pic} \texttt{chits/oob~turn} to +% make the turns. The default setting is not what we want, so we +% redefine that picture. In particular, we want turn ``0'' to say +% ``At start''. +% +% We also want to reuse the style \texttt{turn} we used +% to make the turn track on the board, but modify it a bit to fit our +% purposes here. We therefore define the style \texttt{oob~turn} +% which derives from \texttt{turn}, but scale it down 70\%, change the +% anchor, and add some extra space outside of it +% (\texttt{outer~sep}). +% +% \begin{macrocode} +\tikzset{ + oob turn/.style={ + turn, + transform shape, + anchor=east, + outer sep=5mm, + scale=.7}, +} +% \end{macrocode} +% +% Our modified \texttt{chit/oob~turn} picture will check if we get an +% empty turn number, or the special ``0'' turn, and then put in a node +% with the appropriate contents. Note that we define two pictures, +% one which actually puts in the turn, and one that puts in nothing, +% so when we make the combined OOB we only output the turns once. We +% then default \texttt{chit/oob~turn} to the first picture +% +% \begin{macrocode} +\tikzset{ + oob turn real/.pic={% + \def\tmp{{\Large At start}} + \ifx|#1|\else% + \ifnum0=#1\else% + \def\tmp{#1}% + \fi% + \fi% + \node[oob turn,transform shape]{\tmp}; + }, + oob turn empty/.pic={}, +} +\newcommand\oobrealturn{% + \tikzset{ + pics/chit/oob turn/.style=% + {oob turn real=##1}}} +\newcommand\oobemptyturn{% + \tikzset{ + pics/chit/oob turn/.style=% + {oob turn empty=##1}}} +\oobrealturn +% \end{macrocode} +% +% Let us see how this looks for both factions. Factions A and B are +% shown in \figurename~\ref{fig:a-oob} and \ref{fig:b-oob}, +% respectively. +% +% \begin{figure} +% \centering +% \begin{tikzpicture}[oob turn/.append style={anchor=west}] +% \oob*{\alla}{4}{1.24}{0} +% \end{tikzpicture} +% \caption{Faction A OOB} +% \label{fig:a-oob} +% \end{figure} +% +% \begin{figure} +% \centering +% \begin{tikzpicture} +% \oob{\allb}{4}{1.24}{0} +% \end{tikzpicture} +% \caption{Faction B OOB} +% \label{fig:b-oob} +% \end{figure} +% +% These were done with +% +% \begin{verbatim} +% \begin{tikzpicture}[oob turn/.append style={anchor=west}] +% \oob{\alla}{4}{1.24}{0} +% \end{tikzpicture} +% \begin{tikzpicture} +% \oob{\allb}{4}{1.24}{0} +% \end{tikzpicture} +% \end{verbatim} +% +% Note that the stared version \verb+\oob*+ puts out the counters +% right aligned. This is also why we append the style +% \texttt{oob~turn} to be anchored to the west. +% +% The first argument to \verb+\oob+ is the list of lists of counters. +% This is why we defined \verb+\alla+ and \verb+\allb+ in the way we +% did. The second argument is the distance between each counter. +% Since the counters are 1.2\,cm wide, we gave them a little extra +% space between them by setting the second argument to 1.24\,(cm). +% The third argument is the spacing between turn rows. Above we have +% set that to 0\,(cm), but that we will change in the real OOB chart. +% +% And that's what we will do next. This will be rather wide, so we +% when we show it in a minute, we will do so in a wide table (leaving +% the two-column layout for a minute). +% +% \begin{macrocode} +\newcommand\inneroob[1][]{% + \node[board frame,anchor=north] (oob frame) + at (0,2.5) {};% + % Game title + \node[% + below right=5mm and 5mm of oob frame.north west, + title,scale=.8]{A Game}; + % Chart title + \node[% + below left=5mm and 5mm of oob frame.north east, + sub title,scale=1.2,transform shape]{% + Order of Battle}; + % Turn title + \node[font=\sffamily\bfseries\Large, + white,transform shape] + at (0,1) {Turn}; + % + \begin{scope}[% + transform shape, + oob turn/.append style={anchor=west},% + shift={(-1.35,0)}, + zone scope=A OOB]% + \oobemptyturn% + \oob*{\alla}{4}{1.4}{.2}% + \end{scope}% + % + \begin{scope}[% + transform shape, + shift={(1.35,0)}, + zone scope=B OOB]% + \oobrealturn% + \oob{\allb}{4}{1.4}{.2}% + \end{scope}% + % +} +\newcommand\fulloob[1][]{% + \begin{tikzpicture}[#1,zoned]% + \inneroob + \end{tikzpicture}} +% \end{macrocode} +% A couple of things to note. +% +% We put everything inside a \Tikz{} picture with the option +% \texttt{zoned} so that we will get a zoned +% map in VASSAL. We also add the zones \texttt{A OOB} and \texttt{B +% OOB} via the key \texttt{zone scope}. We will need to adjust the +% grids of the zones later on. Another side effect of using +% \verb+\oob+ is that each turn will be marked as a ``region'' of a +% ``region grid'' in in VASSAL, so that the each counter will be +% automatically placed in its place on the OOB in the VASSAL module. +% +% Secondly, we reuse our \texttt{board frame}, \texttt{title}, and +% \texttt{sub~title} styles to make the OOB come out in similar manner +% as the board. We do adjust the font sizes a bit though. We have +% also made the OOB the same size as the board so that they stack +% nicely. +% +% Finally, when we make the faction A oob, we turn off generation of +% the turn numbers. This is so we do note produce those twice. +% +% +% The final OOB is shown in \figurename~\ref{fig:oob}. This was +% produced with +% +% \begin{verbatim} +% \fulloob +% \end{verbatim} +% +% \begin{figure} +% \centering +% \fulloob[scale=.5] +% \caption{The OOB} +% \label{fig:oob} +% \end{figure} +% +% \section{Ending the package} +% \label{sec:end:package} +% +% At the end of the package we should end with the marker +% \verb+\endinput+. +% +% \begin{macrocode} +\endinput +% \end{macrocode} +% +% This is the end of the package. We will do a little more in the +% main document. +% +% +% \iffalse +% Local Variables: +% mode: docTeX +% TeX-master: "game.tex" +% End: +% \fi
\ No newline at end of file diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/game.tex b/Master/texmf-dist/doc/latex/wargame/tutorial/game.tex new file mode 100644 index 00000000000..6db72bff27b --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/game.tex @@ -0,0 +1,200 @@ +\documentclass[11pt,twoside]{ltxdoc} + +\usepackage{game} +\usepackage[margin=1cm,bottom=2cm,top=2cm,a4paper]{geometry} +\newcommand\Tikz{Ti{\itshape k}Z/PGF} +\setlength{\parskip}{.5ex} +\setlength{\parindent}{0em} +\newcommand\tightlist{\setlength{\itemsep}{3pt} + \setlength{\parskip}{0pt}} +\newcommand\copyleftnotice{{% + \footnotesize \copyright{} 2022, Christian Holm Christensen, + licensed under the CC-BY-SA 4.0}} +\makeatletter +\def\ps@game{% + \def\@oddfoot{\hfill\copyleftnotice\hfill}% + \def\@evenfoot{\hfill\copyleftnotice\hfill}% + \def\@oddhead{The \textsf{wargame} tutorial\hfill\thepage}% + \def\@evenhead{\thepage\hfill\rightmark} + \def\sectionmark##1{% + \markright{\ifnum\c@secnumdepth>\z@% + \thesection. \ \fi##1}}} +\makeatother +\pagestyle{game} + +\title{The \LaTeX{} \textsf{wargame} package\\ + {\large A tutorial}} +\author{Christian Holm Christensen} +\date{\today} + +\def\MacroFont{% + \fontencoding{\encodingdefault}% + \fontfamily{\ttdefault}% + \fontseries{\mddefault}% + \fontshape{\shapedefault}% + \footnotesize} +\let\theCodelineNo\empty +\begin{document} +\thispagestyle{plain} +\twocolumn +\maketitle + +\section{Introduction} + +This is a short tutorial on how to use the \LaTeX{} \textsf{wargame} +package. We will walk through the definition materials for a game. +We will \emph{not} give actual rules for the game. That is a whole +different topic and I refer you to the literature, for example + +\begin{description}\tightlist +\item[\href{https://www.bloomsbury.com/uk/simulating-war-9781472533913/}{\textit{Simulating war}}] by P.Sabin +\item[\href{https://www.professionalwargaming.co.uk/Complete-Wargames-Handbook-Dunnigan.pdf}{\textit{The + Complete Wargames Handbook}}] by J.F.Dunnigan +\item[\href{https://www.scribd.com/book/220336866/Designing-Wargames-Introduction}{Designing + Wargames: Introduction}] by G.Phillies (and associated + \href{https://www.youtube.com/playlist?list=PLjnA1DE9KX645eBC2gDWHkSlCPvpb4JAQ}{Youtube + lecture series}) + +\end{description} + +\section{The game} + +The game we will create is a small game with two factions (sides, or +players). The game is \emph{not} supposed to be play-able, and we'll +leave out a lot of details which we would need in a full game. + +\DocInput{game.sty} + +\section{Rules} + +We will not write any rules for this demonstration game. The focus of +this tutorial is how to use the \textsf{wargame} package, not how to +design a game. + +The \textsf{wargame} package does however have a number of tools that +helps the developer write the rules. We've already seen some of them +in action. For example, we saw how to add stacks of units to a board +in Section~\ref{sec:board:units} or how to make board clippings to +show a zoom of the map (Section~\ref{sec:board:clipped}). + +Figure~\ref{fig:clipped-attack} showed how we can illustrate an attack, +for example. The package also provides means to indicate eliminated +units, movement, retreats, advances, and much more. The manual gives +a lot more information about this. + +\DocInput{export.tex} + +\section{The materials} + +Next, we will make some materials for printing. The next few pages +will contain only the materials and no text, so we will summarise what +we do here. + +The first thing we put out is the map. That is pretty simple. We do + +\begin{verbatim} + \begin{board} + \end{board} +\end{verbatim} + +Then comes the OOB. We simply use the \verb+\fulloob+ macro. + +After that are the two tables put into one page. + +\begin{verbatim} + \crt \tec +\end{verbatim} + +And the final part are the counter sheets. We will take advantage of +the macros \verb+\alla+ and \verb+\allb+ yet again. + +\begin{verbatim} + \doublechits{\allb}{4}{1.24} +\end{verbatim} + +As a final bonus, we also make a board that includes our three charts: +The OOB, CRT, and TE. We will not demonstrate the code here, but take +a look in the sources if you are curious. + +\newcommand\fullboard[1][]{% + \begin{tikzpicture}[#1,rotate=90]% + \begin{scope} + \begin{innerboard} + \end{innerboard} + \end{scope} + \begin{scope}[shift={($(frame.north east)+(7,-2.5)$)}] + \inneroob + \end{scope} + % + \node[anchor=south west,minimum width=6.2cm,minimum height=10cm, + line width=1pt,sub title,scale=.66,draw,align=center, + text depth=9.7cm,fill=neutral,transform shape] + at (oob frame.south west) + {{\LARGE Charts}}; + % + \node[above right=5mm and 4mm of oob frame.south west, + inner sep=0pt, + transform shape,scale=.75,anchor=south west] (crt) {\crt}; + % + \node[above=5mm of crt.north west,anchor=south west,inner sep=0pt, + transform shape,scale=.9] (tec) {\tec}; + % + % \end{scope} + \node[below=1mm of frame.south west,anchor=north west, + transform shape]{% + \copyleftnotice}; + \end{tikzpicture}} + +We put in \verb+\cleardoublepage+ between all this so that we can +print directly on a duplex printer. + +\section{Epilogue} + +I hope that this short tutorial has helped you. Suggestions, +corrections, and so on are very welcomed. + +\begin{flushright} + \textit{Christian} +\end{flushright} +\onecolumn +\cleardoublepage + +\begin{center} + \begin{board} + \end{board} +\end{center} +\cleardoublepage + +\begin{center} + \fulloob +\end{center} +\cleardoublepage + +\begin{center} + \crt\space\space\tec +\end{center} +\cleardoublepage + +\begin{center} + \begin{tikzpicture} + \doublechits{\allb}{7}{1.24} + \end{tikzpicture} + + \begin{tikzpicture} + \doublechits{\alla}{6}{1.24} + \end{tikzpicture} + + \begin{tikzpicture} + \doublechits{{game turn}}{1}{1.24} + \end{tikzpicture} +\end{center} + +\cleardoublepage +\newgeometry{margin=7mm} +\pagestyle{empty} +\fullboard + +\end{document} +%% Local Variables: +%% mode: LaTeX +%% End: diff --git a/Master/texmf-dist/doc/latex/wargame/tutorial/patch.py b/Master/texmf-dist/doc/latex/wargame/tutorial/patch.py new file mode 100644 index 00000000000..0fcdd49645f --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/tutorial/patch.py @@ -0,0 +1,31 @@ +def patch(build,data,vmod,verbose=False): + # We need to import the export module :-) + import wgexport as wg + + # Get the game and last free GPID + game = wg.get_game(build) + gpid = int(game.getAttribute('nextPieceSlotId')) + + # Get all boards + maps = wg.get_maps(build) + board = maps['Board'] + + mkeys = wg.get_masskey(board,'name') + wg.set_node_attr(mkeys['Eliminate'],icon='eliminate-icon.png') + wg.set_node_attr(mkeys['Flip'],icon='flip-icon.png') + + # Get main map + pool = maps['DeadMap'] + wg.set_node_attr(pool,icon='pool-icon.png') + + mkeys = wg.get_masskey(pool,'name') + wg.set_node_attr(mkeys['Restore'],icon='restore-icon.png') + + # Get the OOB map + oob = wg.get_chartwindows(game)['OOBs'] + wg.set_node_attr(oob,icon='oob-icon.png') + + + + + diff --git a/Master/texmf-dist/doc/latex/wargame/wargame.pdf b/Master/texmf-dist/doc/latex/wargame/wargame.pdf Binary files differnew file mode 100644 index 00000000000..c25e83c175f --- /dev/null +++ b/Master/texmf-dist/doc/latex/wargame/wargame.pdf |