## Gnect

2001
Timothy Musson

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You may obtain a copy of the GNU Free Documentation 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.

Many of the names used by companies to distinguish their products and services are claimed as trademarks. Where those names appear in any GNOME documentation, and those trademarks are made aware to the members of the GNOME Documentation Project, the names have been printed in caps or initial caps.

This is version 1.0 of the Gnect manual.

## Introduction

Gnect is a "Four In A Row" game for GNOME. The object of the game is to build a line of four of your counters 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.

Gnect has two computer-driven players. One's very simple - it's included to provide a fun opponent for young children. The other is driven by Giuliano Bertoletti's Velena Engine. The Velena Engine takes a much more sophisticated approach; its strongest level is unbeatable if it makes the first move.

To run Gnect, select Games Gnect from the Main Menu, or type `gnect` on the command line.

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

## Using Gnect

### Basic usage

Once you've started Gnect, select Game New game to begin playing.

The game display consists of seven columns and seven rows. The top row is only used to show the current player's cursor, so the actual playing area measures seven by six cells. To make a move, just move your pointer over the column you'd like to drop a counter into and select that column (for most people, that'll be a left-click). If you'd rather play by keyboard, keys can be assigned using the Preferences Dialog.

### Toolbar

The toolbar, which can be toggled on or off from the Settings Menu, contains the following buttons:

New

  This resets the board and starts a new game.

Undo

  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 tell you the best move you can make, in the form of a column number. Columns are numbered from left to right, with 1 being the leftmost column.

Exit

  This quits the game.

### Menus

The menu bar, located at the top of the game window, contains the following menus:

Game

  This menu contains:

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

  - CtrlZ 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 tell you the best move you can make, in the form of a column number. Columns are numbered from left to right, with 1 being the leftmost column.

  - Scores… — This opens a small window containing the number of wins each player has had. The number of drawn games is also shown.

  - CtrlQ Exit — This quits the game.

Settings

  This menu contains:

  - Show toolbar — This toggle switches the toolbar on and off.

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

  - Draw grid — This toggles the display of a grid over the game board. Some themes will disable the grid themselves if they don't need it (...that is, if they already have something like a grid in their tile sets or background images). So don't be surprised if this option doesn't always have an effect.

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

Help

  This menu contains:

  - Manual — This item opens a browser and displays this manual.

  - About — This opens the About dialog which shows basic information about Gnect, such as the names of its authors, the program's version number, and the URL for the program's Web page.

## Customization

### Preferences

To change the game's settings, select Settings Preferences... . This opens the Preferences dialog.

The properties in the Player Selection tab are:

Player 1 and Player 2

  These options tell Gnect who's playing. To play against a friend, select Human for both Player 1 and Player 2. (Note that changing players will end a game in progress and reset the scores.)

Who starts?

  These options let you select which player starts when a new game begins.

The properties in the Appearance and Behaviour tab are:

Theme selection

  The theme menu lists available themes and lets you choose between them.

Keyboard control

  These options let you arrange keyboard play to your liking. Select the entry box of the action you'd like to change, then press the key you'd like to perform that action.

Animation

  Here you can toggle all animation on or off, or just enable or disable the wipe effects between games.

Sound type

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

If stopping an unfinished game: Ask me first

  If this option is selected, the program will ask you before quitting or starting a new game while there's a still game in progress.

To check your changes without closing the Preferences dialog, use the Apply button. Once you've made all the changes you want, select OK.

### Custom Themes

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

#### Images

Gnect's tilesets contain six tiles of equal size, lined up horizontally. From left to right:

1. Player One's counter as it'll appear on the main board

2. Player Two's counter as it'll appear on the main board

3. Main board background

4. Top row background

5. Player One's counter as it'll appear on the top row

6. Player Two's counter as it'll appear on the top row

##### An example tileset

This image shows the six tiles in a tileset

##### TIP

PNG format is recommended for tilesets. They should usually contain transparency in tiles 1, 2, 5 and 6. Tiles 3 and 4 should be solid, with no transparency, even if you'll be supplying a full window background image.

Gnect automatically calculates the tile dimensions:

    tile height = tileset height
    tile width  = tileset width / 6

That is, your tiles can be square or rectangular - and any size you like. Most of the tilesets that come with Gnect use square tiles measuring either 40x40 pixels ("small") or 50x50 ("large").

So, what if you want a full-window background image, rather than repeating tiles 3 and 4 over the game board? For that, you'll need to make a separate image. Say each tile in your set measures 50 by 50 pixels. The game board measures 7 by 7 tiles, including the top row, so the ideal background for your tileset measures 350 by 350 pixels. But if your background doesn't fit, Gnect will scale it for you.

Before you can try your new tileset and background image, you'll need to create a theme file.

#### Theme Files

Here's an example theme file, showing all possible keywords. Lines starting with a hash (#) are ignored. Note that values containing white space 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 counter (required)
    Player1 = Green

    # Description of player two's counter (required)
    Player2 = Yellow

    # Grid colour (optional, defaults to RGB:52/5F/6C)
    GridRGB = RGB:/FF/FF/FF

    # Disable the grid for this theme (optional)
    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 all together

So, you've made a tileset, a theme file and maybe a background image. Now what?

Make a `~/.gnect` directory, a `~/.gnect/pixmaps` directory and a `~/.gnect/themes` directory. Copy the image(s) into the pixmaps directory and the theme file into the themes directory. Make sure the theme file has `.gnect` as the suffix. Next time you start Gnect, you should find your new theme listed in the Preferences dialog. If not, try running Gnect from the command-line - if your theme is found, Gnect should display a message to let you know what the problem is.

## Known Bugs and Limitations

The latest plans and currently known bugs are listed the online TODO file.

Known bugs in gnect-1.4.2:

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

Typing certain keys (eg., TAB and the cursor keys) into the Keyboard control boxes in Preferences changes the focus.

If upgrading:

Theme file format changed slightly between Gnect versions 1.2.1 and 1.2.2, so if you have any pre-1.2.2 themes hanging about you'll have to edit them, wrapping any values containing spaces with quote (") characters. For example:

    Title = This theme's title

    # ...becomes...

    Title = "This theme's title"

## Authors

Gnect was written by Timothy Musson (trmusson@ihug.co.nz) and David Neary (dneary@eircom.net). The Velena Engine was written by Giuliano Bertoletti. Giuliano has very kindly granted permission to include his Velena Engine with Gnect and distribute the result under the GPL.

For more information about Gnect, please visit Gnect's homepage. To find out more about the Velena Engine, please visit Velena's homepage.

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