Jools User Manual

Paul J. Pelzl

August 25, 2003

``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, and jools, by what I've heard.''
                       -- J.R.R. Tolkien, The Lord of the Rings

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 Bejeweled1, 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.

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 ``tar xvzf jools-x.xx.tar.gz''). Enter the root of the jools installation directory, e.g. ``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:
  1. Direct installation from source. You can copy all the necessary files to logical locations with the command ``python setup.py install''.

    If you wish to choose a different installation prefix, you can use ``python setup.py install --prefix=PREFIX'', where PREFIX is your desired installation root, for example ``/usr/local''. (If you choose this option, your Python search path must include the corresponding directories.)
  2. 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 ``python setup.py bdist_rpm''. The package should be created within the ``dist'' subdirectory, and you can install it using
    ``rpm -Uvh jools-x.xx-x.noarch.rpm''.

    If you have a Debian-based system, then you could use alien to create a .deb from this rpm. (Note that Jools is likely to enter Debian unstable in the near future.)
After installing, you should be able to play by executing ``jools''. If you choose not to perform the installation, you should still be able to execute ``./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 ``__init__.py'' in the ``jools'' subdirectory.

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:

Configuration

Music directories

Jools has support for background music. Inside the directory /usr/share/jools/music2 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 ~/.jools/music, which are created the first time Jools runs. Music placed in these directories will override the system-wide music in
/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. <http://www.futurecrew.org/skaven/>

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.

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.

Credits

I would like to express my thanks to:

Contact info

Jools author: Paul Pelzl <pelzlpj@eecs.umich.edu>
Jools website: http://www.eecs.umich.edu/~pelzlpj/jools
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 RCS3. Interested developers are advised to track Jools development via my public repository:
      pelzlpj@eecs.umich.edu--2003 \
            ftp://pelzlpj.dyndns.org/pub/paul/tla/2003 .

Also: 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 poor, starving graduate student, I will gratefully accept donations. Please see
http://www.eecs.umich.edu/~pelzlpj/jools/donate.html for more information.
1
Bejeweled is likely a trademark of Pop Cap Games/Astraware.
2
If you used a different installation prefix for Jools, then this directory must be changed accordingly.
3
Information on Arch may be found at http://regexps.srparish.net/www/ .
This document was translated from LATEX by HEVEA.