% Jools documentation
\documentclass[11pt,notitlepage]{article}
\usepackage{times}
\usepackage{fullpage}

% End preamble
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\begin{document}
\title{Jools User Manual}
\author{Paul J. Pelzl}
\date{August 25, 2003}
\maketitle

\noindent
{\em ``There's a tidy bit of money tucked away up there, I hear tell,'' said a
stranger, a visitor on business from Michel Delving in the Westfarthing.
``All the top of your hill is full of tunnels packed with chests of gold
and silver, {\em and} jools, by what I've heard.''} \\

\hspace{8cm}-- J.R.R. Tolkien, {\em The Lord of the Rings}

\section*{Introduction}
Jools is a graphical puzzle game in the tradition of Tetris.  Although I 
expect that it will evolve somewhat over time, it has begun as 
a clone of Bejeweled\footnote{Bejeweled is likely a trademark of Pop Cap 
Games/Astraware.}, which is currently available for Windows, Mac, and 
Palm/Pocket PC devices.  In a nutshell, the goal is to swap adjacent jools
(jewels) within a grid, in order to create rows of three or more of a kind.  
These jools will then disappear, and more will fall to fill their places.

Jools is written in Python using Pygame (Python bindings for SDL).  As a 
result, it should be quite cross-platform.  It will certainly run on GNU/Linux 
(my development platform), and ought to run on *BSD, Mac OS X, Windows, and 
others.

Although there are no specific CPU requirements, you may expect good 
performance from a 500MHz x86 machine.

\section*{Installation}
Before installing Jools, you should have Python v2.1 or greater and Pygame v1.4 
or greater.  (Your Pygame library must be built with support for SDL\_image 
and SDL\_ttf.  SDL\_mixer support is not required, but will provide audio.)

I will assume you have received this program in the form of a source tarball, 
e.g. ``jools-x.xx.tar.gz''.  You have undoubtedly extracted this archive 
already (e.g. using ``{\tt tar xvzf jools-x.xx.tar.gz}'').  Enter the root of 
the jools installation directory, e.g. ``{\tt cd jools-x.xx}'';  there should 
be a file called ``setup.py'' in this directory.  Become root before 
trying to perform the installation.  There are a couple of ways to install Jools:
\begin{enumerate}
\item {\bf Direct installation from source.}  You can copy all the necessary 
files to logical locations with the command ``{\tt python setup.py install}''.  

If you wish to choose a different installation prefix, you can use ``{\tt 
python setup.py install --prefix=PREFIX}'', where {\tt PREFIX} is your desired
installation root, for example ``/usr/local''.  (If you choose this option, 
your Python search path must include the corresponding directories.)
\item {\bf Installation via rpm.}  If you use an rpm-based distribution you 
can build an rpm package for Jools, which gives you the ability to remove the 
program easily (not that you would ever want to do that).  Create the rpm with 
the command ``{\tt python setup.py bdist\_rpm}''.  The package should be created 
within the ``dist'' subdirectory, and you can install it using \\
``{\tt rpm -Uvh jools-x.xx-x.noarch.rpm}''.

If you have a Debian-based system, then you could use {\tt alien}
to create a .deb from this rpm.  {\em (Note that Jools is likely to enter Debian 
unstable in the near future.)}
\end{enumerate}

After installing, you should be able to play by executing ``{\tt jools}''.  If 
you choose not to perform the installation, you should still be able to 
execute ``{\tt ./jools}'' within the ``jools'' subdirectory.

A Windows installer may become available soon.  For the moment, Windows 
users are advised to leave Jools uninstalled, and simply execute ``{\tt 
\_\_init\_\_.py}'' in the ``jools'' subdirectory.


\section*{Playing the game}
Upon launching a game, you are presented with a grid of jools.  You must swap 
the positions of adjacent jools in order to make rows or columns of three or 
more of a kind.  You may only make these swaps vertically and horizontally 
(not diagonally), and you will only be allowed to perform swaps that will 
result in a row of matching jools.  You can make a swap by pressing the left 
mouse button on a jool, dragging over a jool you wish to swap with, and 
releasing.  (Alternatively, click on one jool, then make a second click  
on the jool you wish to swap with.)  The keyboard can also be used to swap 
jools; use the arrow keys (or the vi-style \{h,j,k,l\} keyset) to move the selection 
box, and press the space bar to select and swap jools.

If you match a row or column of jools, they will disappear and more will fall 
to fill their places.  If you choose your matches carefully, these falling 
jools may create more matches (chain combos).  The points for a chain combo 
double at each match, so triple or quadruple combos can boost your score rapidly.
Matching four or five jools in a row will also give you more points than 
matching only three.  See ``POINTS'' for a more comprehensive breakdown of the scoring.

Jools can be played in two modes: Time Trial and Untimed.  In Time Trial mode, 
you must make as many matches as you can before the clock runs out.  You 
will receive time bonuses in proportion to the points you score, so 
combinations are good for boosting the clock.  When you pass levels and when 
you run out of available moves, a new grid of jools is provided.  The clock 
speeds up at every level change.

In Untimed mode, Jools is more of a strategy game.  The game ends when you run 
out of available moves.  Take your time to set up combinations and boost your 
score.

Some useful keys:
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}
\item {\bf p}: toggle pause
\item {\bf q}: quit to main menu
\item {\bf m}: toggle music
\item {\bf s}: toggle sound effects
\end{itemize}


\section*{Configuration}
\subsection*{Music directories}
Jools has support for background music.  Inside the directory {\tt 
/usr/share/jools/music}\footnote{If you used a different installation prefix for
Jools, then this directory must be changed accordingly.} are directories 
where you may place music for the title screen, time trial play, and untimed 
play.  If your SDL\_mixer library has been linked against all the optional 
audio libraries, then Jools should support the following set of music formats: 
\{.wav, .voc, .mp3, .ogg, .mid, .mod, .s3m, .it, .xm\}.  The tracks will be 
played in alphabetical order.

Any user may also put music in the directories under {\tt \~{}/.jools/music}, 
which are created the first time Jools runs.  Music placed in these 
directories will override the system-wide music in \\
{\tt /usr/share/jools/music}.

If you want your Jools experience to closely resemble that of Bejeweled,
then you may wish to download original Bejeweled tracks composed by Skaven.
{\tt <http://www.futurecrew.org/skaven/>}

\subsection*{Options menu}
The options menu lets you control audio settings.  The two sliders control 
music and sound effects volume.  Clicking on the icons (or pressing the ``m'' 
and ``s'' keys) will toggle music and SFX on and off.  Use the ``sound FX 
set'' arrows to choose between multiple sets of sound effects.  Click the 
``Test FX'' button to play a sample sound effect.  

\section*{Licensing}
Jools has been made available under the GNU General Public License (GPL), 
version 2.  You should have received a copy of the GPL along with this 
program, in the file ``COPYING''.

Brian Kent's ``Detonate'' font, which is included with Jools, may be
distributed under the terms described in ``detonate.txt.''  Note that the font 
should not be altered without his permission.


\section*{Credits}
I would like to express my thanks to:
\begin{itemize}\addtolength{\itemsep}{-0.5\baselineskip}
\item Greg Smethells, for feedback and beta testing
\item David Koppenhofer {\tt <djk@users.sourceforge.net>}, for music code and helpful 
design discussions
\item Niklas Vainio {\tt <niklas.vainio@uta.fi>}, for improved sound effects
\item Brian Kent {\tt <http://www.aenigmafonts.com/>}, for providing the 
``Detonate'' font under a liberal license
\item Sam Lantinga, for the outstanding SDL graphics library
\item Pete Shinners, for providing Pygame (thereby making SDL programming a 
piece of cake)
\end{itemize}


\section*{Contact info}
Jools author: Paul Pelzl {\tt <pelzlpj@eecs.umich.edu>} \\
Jools website: {\tt http://www.eecs.umich.edu/\~{}pelzlpj/jools} \\


\noindent
Feel free to contact me if you have bugs, feature requests, patches, etc.  I 
would also welcome volunteers interested in packaging Jools for various platforms.

Jools is developed with the aid of the excellent Arch RCS\footnote{Information 
on Arch may be found at {\tt http://regexps.srparish.net/www/} .}.  Interested 
developers are advised to track Jools development via my public repository: \\
\hspace*{2cm}{\tt pelzlpj@eecs.umich.edu--2003 $\backslash$ \\
\hspace*{4cm} ftp://pelzlpj.dyndns.org/pub/paul/tla/2003} .  

Also: {\bf HELP!}  I'm not much of a graphic artist, and I'm certainly no 
composer.  Now that Jools supports music playlists, I would be interested in 
putting together a default music pack; if you would like to donate some 
original music to the project, please let me know.  I think Jools could also 
benefit from a nice splash screen and some background artwork, so please 
contact me if that interests you.

Do you feel compelled to compensate me for writing Jools?  As a {\em poor, 
starving} graduate student, I will gratefully accept donations.  Please see \\
{\tt http://www.eecs.umich.edu/\~{}pelzlpj/jools/donate.html} for more information.
\end{document}