# &appname; Manual V&manrevision;

2001-2002 Timothy Musson
&legal;
Timothy Musson

    trmusson@ihug.co.nz

&appname; Manual V&manrevision;
&date;

Timothy Musson trmusson@ihug.co.nz

This manual describes version &appversion; of &appname;.

Feedback

To report a bug or make a suggestion regarding the &appname; application or this manual, follow the directions in the GNOME Feedback Page.

## Introduction

&app; is a four-in-a-row game for the GNOME Project. The object of the game is to build a line of four of your marbles while trying to stop your opponent (human or computer) building a line of his or her own. A line can be horizontal, vertical or diagonal.

To run &app;, select &appname; from the Games submenu of the Main Menu, or type `gnect` on the command line.

&app; is included in the `GNOME-games` package, which is part of the GNOME desktop environment. This document describes version &version; of &app;.

## Basic Usage

### Playing &appname;

Once you've started &app;, select New game from the Game menu to begin playing.

The game board consists of seven columns and six rows. Above it, a special row indicates the current player. To make a move, select a column using your pointing device or keyboard. Your marble will drop into the topmost empty row of that column.

&appname;'s Main Window

&appname;'s Main Window

The game's won when one of the two players manages to line up four of his or her marbles horizontally, vertically or diagonally. If the board fills up without a win, the game ends in a draw.

### Menus

The menu bar, located above the game board, contains the following menus:

Game

  This menu contains five items:

  - Ctrl-N New game — This resets the board and starts a new game.

  - Ctrl-Z Undo move — If you're playing against a friend, this will undo one move. If you're playing against the computer, this will undo the computer's last move and then yours. Repeating this will return the board to its initial state.

  - Hint — This'll give you the computer's best suggestion for your move.

  - Scores… — This opens a small window containing a tally of wins and draws for the current playing session. The scores will be reset to zero if Player Selection is changed in Preferences.

  - Ctrl-Q Exit — This quits the game.

Settings

  This menu contains four items:

  - Toolbar — This toggle switches the tool bar on and off.

  - Enable sound — This toggle switches the game's sound effects on and off.

  - Draw grid — This toggles the display of grid lines over the game board. Themes that specifically disable grids will not be affected.

  - Preferences… — This opens the Preferences Dialog, allowing you to configure the game.

Help

  This menu contains:

  - F1 Contents— Opens your help browser and shows this manual.

  - About — Opens the About Dialog, showing basic information about &app; such as its version number and the names of its authors.

### Preferences

To change the game's settings, select Preferences… from the Settings menu. This opens the Preferences Dialog.

Configuration options in the Player Selection tab are:

Player 1 and Player 2

  These two columns tell &app; who's playing. Velena is the name of the algorithm used to make the computer player challenging. To play against a friend, select Human for both Player 1 and Player 2.

Who starts?

  This column lets you choose who moves first when a new game begins. By default, players take turns to start.

Options in the Appearance and Behaviour tab are:

Theme

  The theme menu lists available themes and lets you choose your favourite.

Animation

  Here you can toggle the game's animation on or off.

Sound type

  &app; can make sounds when certain events occur. If you choose the Speaker beep option, &app; will beep when a game ends or if you make an illegal move. If you choose the GNOME sound option, &app; will play the audio files you specify using the GNOME Control Center. To disable &app;'s sound completely, use the sound toggle in the Settings menu.

Finally there is a Controls tab to change the keyboard controls. To change a control, click the appropriate button and then type the new key.

## Creating New Themes

This section's included in case you'd like to make your own themes for &app;. It assumes you're familiar with basic text editing, graphics software and the command line.

### Images

&app;'s tile sets contain six tiles of equal size, lined up horizontally. From left to right:

1. Player One's marble as it appears on the game board

2. Player Two's marble as it appears on the game board

3. The game board's background

4. The top row's background

5. Player One's marble as it appears on the top row

6. Player Two's marble as it appears on the top row

An example tile set

This image shows the six tiles in a tile set

Tiles three and four will be repeated over the game board and top row unless a full window background image is specified in the theme file.

TIP

PNG format is recommended for tile sets. The first, second, fifth and sixth tiles should contain some transparency if you want the background to show through. The third and fourth tiles should be solid, with no transparency, even if you'll be using a full window background image with your theme.

TIP

Tiles can be square or rectangular, and any size you like. Most of the tile sets that come with &app; use square tiles measuring either 40 by 40 pixels ("small") or 50 by 50 ("large").

For a full window background image, there's a bit more work to do. Let's say your tiles measure 50 by 50 pixels each. The game's display measures 7 by 7 tiles, including the top row, so the ideal background image for your tile set measures 350 by 350 pixels.

TIP

&app; will automatically scale the background image if it doesn't match the tile set. This means you can make "large" and "small" versions of your theme, both using the same background image, just by having a large and a small version of your tile set.

So, you now have a tile set and perhaps a background image to go with it. The next step is to write a theme file.

### Theme Files

Here's an example theme file, showing all the keywords &app; understands. Lines starting with a hash (#) are comments; they'll be ignored. Note that values containing spaces must be quoted.

    #
    # buttons_50x50.gnect (an example theme file)
    #

    # This theme's title (required)
    Title = "Button Shop (large)"

    # Tileset filename (required)
    Tileset = tileset_50x50_buttonshop.png

    # Full-window background image (optional)
    Background = bg_buttonshop.jpg

    # Description of Player One's marble (required)
    Player1 = Green

    # Description of Player Two's marble (required)
    Player2 = Yellow

    # Grid colour (optional, defaults to "#525F6C")
    GridRGB = "#FFFFFF"

    # Disable the grid for this theme (optional)
    # Useful if your artwork has rows/cols drawn in
    NoGrid

    # Details (optional)
    Tooltip = "Artwork credits or whatever you like"

Legal values for the `Player1` and `Player2` keywords are as follows:

`Light`, `Dark`, `Black`, `White`, `Grey`, `Yellow`, `Red`, `Blue`, `Green`, `Orange`, `Purple`, `Pink`, `Violet`, `Brown`.

### Putting It Together

The last step is to put your image(s) and theme file where &app; can find them. You could put them in Gnect's install directory (which will depend on your particular system), but your home directory's probably a better idea.

Make a `~/.gnect` directory, a `~/.gnect/pixmaps` directory and a `~/.gnect/themes` directory. Those names are important, as &app; won't look anywhere else.

Copy your image(s) into the pixmaps directory and your theme file into the themes directory. Make sure the theme file has `.gnect` as the suffix.

If you start &app; from the command line, it'll give you clues about about any problems it has with your new theme. If it has none, you'll find your new theme listed the Preferences Dialog.

Have fun!

## Known Bugs and Limitations

Occasionally a marble-dropping animation doesn't look as smooth as it should.

## Authors

&app; was written by Timothy Musson (trmusson@ihug.co.nz) and David Neary (bolsh@gimp.org). Various others have taken the time to help in many ways since work on &app; began.

The Velena Engine, &app;'s main computer player, was written by Giuliano Bertoletti. We're grateful to him for allowing us to include his work, without which &app; wouldn't be nearly as worthwhile.

Please send all comments, suggestions, and bug reports to the GNOME bug tracking database. You can also use Bug Report Tool (`bug-buddy`), available in the Utilities submenu of Main Menu, for submitting bug reports.

This manual was written by Timothy Musson. Please send all comments and suggestions regarding this manual to the GNOME Documentation Project by sending an email to docs@gnome.org. You can also add your comments online by using the GNOME Documentation Status Table.

## License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

A copy of the GNU General Public License is included as an appendix to the GNOME Users Guide. You may also obtain a copy of the GNU General Public License from the Free Software Foundation by visiting their Web site or by writing to

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