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

Contents
--------

- Overview
- The Games
- Website
- License
- Mailing List
- Maintainers
- Bug Reports
- Requirements
- Building Gnome-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)

Ataxx           A disk-flipping game where players try and control the
                most disks. This is similar to Iagno, another game in
                this suite. (gataxx)

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)

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://www.gnome.org/projects/gnome-games/contributing.html

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

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:

 Richard Hoelscher <rah@rahga.com>
 Jason Clinton <me@jasonclinton.com>
 Andreas Røsdal <andrearo@pvv.ntnu.no>

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://www.gnome.org/projects/gnome-games/contributing.html

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

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

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.

A Zeroconf library is optional, but it is highly recommended to use
for example the Avahi library. http://www.avahi.org/

The games that require additional packages are:
 guile scheme:  	AisleRiot
 C++:         		Blackjack, Gnometris            


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.

If you want Zeroconf support you have some options. Avahi is one 
library which is supported. The use of Avahi is optional and 
mutually exclusive with Howl and Bonjour.

On most Unix and Linux systems Howl is another library to use, and 
it is automatically detected. Howl is no longer actively developed 
by Porchdog Software or anyone else. Therefore it is likely to be
removed from gnome-games in the future. You may also use Apple's 
Bonjour library, but you have to enable it explicitly. 

The configure options for zeroconf support are:

 --disable-howl                   Disable Howl support 
 --enable-bonjour                 Enable Bonjour support
 --enable_avahi                   Enable Avahi 
 --with-bonjour-includes=PREFIX   Specify where to find the Bonjour 
                                  header files
 --with-bonjour-libs=PREFIX       Specify where to find the Bonjour 
                                  libraries

Setting the library and include file directories explicitly should not
normally be necessary. Note that if you select Bonjour support on a
system with Howl installed and do not explicitly disable Howl then
Howl support will be disabled and a warning printed.

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

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.
 - Accessibility improvements.
 - Better graphics rendering quality and speed.
 - Making it easy for individual players to introduce their own themes.
 - Networking. Iagno and Nibbles already does it, there are several
   other games with two-player options that are just begging to be 
   networked.
