===============================================================================
                             Gnome-Games
===============================================================================

Contents
--------

- Overview
- The Games
- Website
- License
- Mailing List
- Maintainers
- Bug Reports
- Requirements
- Building Gnome-Games
- Testing Gnome-Games
- Network Games
- Security Issues
- The Future

Overview
--------

Gnome-games is a collection of simple, but addictive, games from the
GNOME desktop project. They represent many of the popular games and
include card games, puzzle games and arcade games. They are meant to
be the sort of game that can be played in five minutes or so. They are
also meant to be fun enough that you will play them again and
again. Of course we can't be held responsible for the time and
productivity lost while playing them.

The Games
---------

Here is a list of the games in this compilation along with a brief
description. The names in brackets are the program names you use from the
command line.

AisleRiot       A compilation of seventy different solitaire card games.
                (sol)

Blackjack       The casino card game without any need to actually pay
                your gambling debts. (blackjack)

Four-in-a-row   The classic game where each player tries to make a line
                of four disks before their opponent. There is a very
                popular version of this in the real world called
                Connect Four. (gnect)

Gnometris       That Russian game of fitting falling geometric
                shapes. Need I say more ? (gnometris)

Iagno           Gnome version of the popular Othello (R) disk flipping
                game. The goal is to control all the disks on the
                board by trapping your opponents disks between two of
                yours. (iagno)

Klotski         A series of sliding block puzzles. (gnotski)

Five or More    You move balls around the grid and try and form lines
                of the same colour to make them disappear. Unfortunately 
                more balls keep dropping in ... (glines)

Chess		glChess is a chess game which supports several chess engines,
		with 2D and optionally 3D support if OpenGl and GtkGLExt
		is present. glChess is written in Python and uses GTK+
		and Cairo to render the chess board. glChess uses gnuchess
		as the default AI player. (glchess)

Sudoku		Gnome Sudoku is a logic game with a Japanese name that has
		recently exploded in popularity. (gnome-sudoku)

Mahjongg        A tile-based solitaire game with an oriental
                flavor. Remove tiles in matching pairs from a pile to
                try and dismantle it. (mahjongg)

Mines           The popular logic puzzle minesweeper. Clear mines from
                a board using hints from squares you have already
                uncovered. (gnomine)

Nibbles         The "worm" game. You pilot a worm around a maze trying
                to collect diamonds. With each diamond your worm grows
                and navigation becomes ever more difficult. (gnibbles)

Robots          The classic BSD robots game where you have to avoid a
                hoard of robots who are trying to kill you. Mac users
                might remember a similar "daleks" game. (gnobots2)

Same GNOME      You start with a grid of stones of different
                colors. You can only remove stones where two or more
                of the same colour touch each other. The goal is to
                remove as many as possible. You score more points by
                removing them in bigger groups.

Tali            Sort of poker with dice and less money. An ancient
                Roman game, this variant is similar to Yahtzee (R).
                (gtali)

Tetravex	A puzzle game where you have to match a grid of tiles 
		together. The skill level ranges from the simple two by
		two up to the seriously mind-bending six by six grid.
		(gnotravex)


Website
-------

Further information and screenshots can be found at:

http://www.gnome.org/projects/gnome-games/

Aspiring developers should see:

http://live.gnome.org/GnomeGames

License
-------

This is Free Software and there are no restrictions on your use and
enjoyment of it. In most countries copyright law would prevent you
from sharing these programs, either as is or in a modified
form. However we provide a license to allow you to modify and
redistribute this code. This is the GNU General Public License and it
can be found in the file COPYING. This allows you to do almost
anything you would like with this software, including selling
it. There are only two catches, firstly you can't restrict anyone else
from copying the code, you have to give them the same freedoms you
received (including access to the source code). Secondly, because the
code may have been modified and we have no idea what state it will be
in when it reaches you, we cannot provide a warranty. All the details
can be found in the file COPYING which should have accompanied this
software. If it didn't you can find a copy at

http://www.gnu.org/copyleft/gpl.html 

or write to the Free Software Foundation, Inc., 59 Temple Place, Suite
330, Boston, MA 02111-1307 USA

Some parts of this software, notably some of the artwork, are licensed
under different terms or have been placed in the public domain. None
of these terms are more restrictive than what has been described
above. Please check the artwork files for full details. If there is no
information embedded within the file or alongside it then it is licensed
under the GPL.

Mailing List
------------

Gnome-games has a mailing list at <games-list@gnome.org>. You can
subscribe to the list at:

 http://mail.gnome.org/mailman/listinfo/games-list

and browse the archives at:

 http://mail.gnome.org/archives/games-list/

The mailing list is for announcements and discussion about games
written for the GNOME environment. It is moderated and low volume.

Maintainers
-----------

The current maintainers for gnome-games are:

 Jason Clinton <me@jasonclinton.com>

While you can email them with suggestions and bug reports it is better
to use either the bug tracking system (see below) or the mailing
list. Even for suggestions the bug tracking system is better because
it ensures that there is an archive of the discussion and it is harder
for the maintainer to loose suggestions. For more general discussion,
policy issues and issues that many people will be interested in, the
mailing list is the best place.

Reporting Bugs
--------------

If you find any bugs in gnome-games, or even just have a suggestion
for an improvement to the games then please submit a bug report. There
are two ways to do this, either by using the web-based interface to
the GNOME bug tracking system at

http://bugs.gnome.org/simple-bug-guide.cgi

or use the bug reporting tool, which you can find under the Development
sub-menu of the GNOME menu. The bug reporting tool can also be launched
from the command line via the bug-buddy command.

If a game crashes then the bug reporting tool will be automatically
launched.

There is one problem with the standard bug reporting tools and
gnome-games. Because gnome-games uses setgid bit to give the programs
extra privileges the ordinary bug reporting tools don't do a complete
job because a stack trace cannot be made. Stack traces are very useful
in determining what went wrong. To get a proper stack trace with
gnome-games binaries then you should try and recreate your crash while
running as the root use, or, with the setgid bit temporarily removed
from the file. Both these require root privileges which you may not
have.

Contributing
------------

See the file HACKING and the webpages mentioned within for details
about contributing to gnome-games. In particular, the following
page is relevant:

http://live.gnome.org/GnomeGames/Contributing

Requirements
------------

This is the list of required software packages for gnome-games:

 - GNOME 2.16.0
 - GTK+ 2.8.0
 - GNOME Doc Utils - gnome-doc-utils 0.10.0
 - Cairo 1.0
 - RSVG 2.14.0
 - Guile 1.8.0
 - GStreamer 0.10.11
 - Python 2.4 
 - PyGTK - python-gtk2-dev 2.10.0 
 - libxml 2.4.0
 - scrollkeeper
 - expat
 - ggz-client-libs 0.0.14
 - libggz 0.0.14


These packages are optional, but highly recommended:

 - SDL_Mixer 1.2.0 or later for sound support using SDL.
 - gtkglext 1.2.0 , pygtkglext 1.1.0 and pyopengl 2.0 for 3D support in Chess.
 - ggz-server 0.0.14 for hosting GGZ servers.


To compile these packages, we recommend using the baseline GNOME 2.18.x
development packages. While gnome-games may compile with older versions,
we will not accept bug reports for games used under those conditions.

GStreamer 0.10 is required by gnome-games, and is used to play sounds.
SDL_Mixer is also supported for playing sounds.

CVS checkouts will require the latest intltool.

In addition it is useful to have a working C++ compiler (e.g. g++,
part of the gcc suite) and the guile implementation of the Scheme
programming language version 1.6 or later
(http://www.gnu.org/software/guile/guile.html). If either of these is
missing then the games that rely on them will simply not be built.

glChess can optionally take advantage of Python OpenGL and GtkGLExt 
to render the board using 3D OpenGl. glChess supports any 
CECP compatible AI, such as crafty or gnuchess. See the README file 
in the glchess directory for more information about glChess and it's
optional software dependencies.

The included gnuchess AI can be run using the 'gnome-gnuchess' binary.
To compile glChess without the bundled gnuchess binary, you can 
compile with ./configure --disable-gnuchess 

The games that require additional packages are:
 guile scheme:  	AisleRiot
 C++:         		Blackjack, Gnometris            
 Python:		glchess, gnome-sudoku

Building Gnome-Games
--------------------

Gnome-games uses the GNU automake system and installation may be as
easy as:

$ ./configure
$ make install

Generic, but detailed, instructions can be found in the file INSTALL.

There are several gnome-games specific options you can pass to
configure. These security related options are:

--disable-setgid                Do not set the setgid bit on the
                                installed binaries.
--with-scores-group=group       If you are using setgid binaries, set
                                the group for the programs. The
                                default is games.
--with-scores-user=user         If you are using setgid binaries, set
                                the user for the programs. The default
                                is games.

For a discussion of the details behind these options and why you might
want to change them see the "Security" section. In general you will
not need to change any of them.

To select which games to compile use --enable-omitgames and
--enable-games. Each option takes a comma separated list of directory
names (not the screen-names of the games). "all" is also a valid
name. For example:

./configure  --enable-omitgames=gnometris,gnome-stones

would compile all the games except gnometris and gnome-stones.

./configure --enable-omitgames=all --enable-games=gnomine

would only build the gnomine game. The choice of the awkward phrase
"enable-omitgames" is due to a limitation in the autoconf tools which
doesn't allow us to supply an argument to --disable-games.

./configure --enable-games=none,gnomine

has the same effect. The names in the lists are applied in order.

Use './configure --help' for a complete list of currently supported
options and environment variables.

If you are compiling gnome-games from CVS you should look at:

http://www.gnome.org/projects/gnome-games/contributing.html


Testing Gnome-Games
-------------------

gnome-games supports the unit testing framework Check, which provides
unit tests to verify that the code in gnome-games is correct.

To run these the unit tests, enter the command: 'make check'
which will run all the unit tests in the tests subdirectory.  

When you are submitting a change to gnome-games, make sure that
the tests still run without errors after you have done your changes.
Bugfixes could also be supplied with a new unit test which
checks for the bug, so that it will not return (regression testing).

See the README file in the tests subdirectory for more information
about unit testing in gnome-games.


Network Games
--------------------
Network games can be played with the games Gnibbles, Four-in-a-Row and
Iagno. These games requires GGZ Gaming Zone version 0.0.14 or later.

Network games can be started using the "Network Game" menu item
in the supported games. Network games can also be started using
the ggz-gtk application which is a part of GGZ.

GGZ can be downloaded from http://www.ggzgamingzone.org/
See the included file README.GGZ for an introduction to GGZ.

GGZ will be automatically detected by configure, and is a required
library requirement for gnome-games.

The following libraries are required for GGZ support:
- ggz-client-libs
- libggz

- ggzd is optional library for GGZ server hosters.

To compile the gnome-games with the optional server support, use:
/autogen.sh --with-ggz-server 

Several other games in gnome-games will get GGZ support in the future.
Further, it is planned to implement support for observers and statistics.

For an up-to-date list of GGZ servers, see: http://live.gnome.org/GnomeGames
Behave politely on the GGZ game servers, and have a lot of fun.

Security Issues
---------------

It might seem a little strange that a collection of games needs to
talk about security issues, but it all stems from an attempt to avoid
cheating. To stop people writing arbitrary scores into the score file
without actually having played the game, the games are given special
privileges and the score files are set to be only writable by programs
with these privileges. In this case the privilege is being part of the
games group.

The potential problem comes when there are bugs in the games that
allow someone to get the program to do something else (like classic
buffer overruns). This gives the (supposedly) evil user a way to do
things with the same privileges as the game, but not necessarily the
things that were intended. This is generally considered to be bad.

There are two mitigating factors here:
a) The programs open the score files and drop privileges very shortly
   after they have been started. This severely reduces the scope for an
   exploitable to occur.
b) On most systems having the privileges of the games group should
   allow you to do no more than change high score files.

The problem is that in a) the probability is small, but not zero, and
in b) "most systems" is not "all systems". If you are using a
typical Linux distribution then you should have no problems. If you
don't have a typical system and the "games" group is somewhat more
special than a way of maintaining the high scores then you may need to
change things.

If you need to change things, here are your options:

1) Do not use setgid binaries. This means that high score tracking
won't work (although you can make the files world-writable and
therefore open to use/abuse by everyone). Use the --disable-setgid at
configuration time to do this.

2) Change the group used. Creating a new, unique, group for
gnome-games (e.g. gnomegames) is the best solution. You can change the
group (and user) used via the --with-scores-group and
--with-scores-user options to configure at compile time.

The Future
----------

As time marches on, we shall strive to drag more of our games kicking and
screaming into the 21st century. The following is a short list of recent 
priorities, and many more can be found in the bug tracker and the TODO file.
 - Usability, Accessibility and Fancibility improvements.
 - Better graphics rendering quality and speed.
 - Making it easy for individual players to introduce their own themes.
 - During the 2.17.x cycle, one old game will be replaced with one new game!