# Galois Manual 0.8

2012
2013
2014
2015
2016
2017
2018
2020
2021
2022
Gerardo Ballabio

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in .

Gerardo
Ballabio
Version 0.1
November 2012
Version 0.2
January 2013
Version 0.3
March 2014
Version 0.4
July 2015
Version 0.5
November 2017
Version 0.6
June 2018
Version 0.7
August 2020
Version 0.8
November 2022
This manual describes version 0.8 of Galois.

## Introduction

Galois is a computer game of the "falling blocks" type, but with unique features. Unlike most other games of that type, it is not limited to blocks made of four two-dimensional, square bricks: you can choose among several different brick shapes, blocks composed of more or fewer bricks, and even between two- and three-dimensional games.

Galois is free software, released under the terms of the GNU General Public License, version 3 or later. This essentially means that you can use, modify and redistribute it without restrictions, except that you are required to pass along the same freedom to everybody to whom you redistribute it.

Galois is hosted at Savannah, the software forge for people committed to free software.

### Name of the Game

Évariste Galois was a French mathematician, one of the founders of "group theory", a framework that encompasses nearly all fields of modern mathematics. This game makes use internally of groups of a specific kind, namely, symmetry groups. Because the first falling blocks game (which unfortunately was a proprietary program) had a name which ended in "is", I thought calling mine Galois would be a nice homage to both. And as an added bonus, it starts with G, like Gtk+ and GNOME.

### Legal Notice

Copyright 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2020, 2021, 2022 Gerardo Ballabio

Galois 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 3 of the License, or (at your option) any later version.

Galois 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 license is included in .

## How to Install

The most recent version of Galois can be downloaded from the Galois web site: https://www.nongnu.org/galois/

The easiest way is to install a precompiled binary, if that is available for your platform (see ). Otherwise, you'll have to download the source code and compile it (see ).

If you are upgrading from an older release, you may want to read the upgrade notes (see ).

### Supported Platforms

Galois is supposed to run on every system where the software libraries it depends on are available (see ). This includes (but is not limited to) GNU/Linux, BSD, Microsoft Windows, and Mac OS X.

I have actually tested it on the following systems:

- Debian GNU/Linux stable, i386 and amd64 architectures (i.e., 32-bit and 64-bit PC). The latter is my own computer, thus it is and will remain the best supported platform in the foreseeable future.

- Microsoft Windows 10.

If you try it on another system, whether you succeed of fail, please let me know.

### Hardware Requirements

Being a game that doesn't require fast animation nor sophisticated graphics, Galois has very low requirements. It should run well even on very old and cheap computers and without hardware acceleration.

### Binary Packages

At this moment, precompiled Galois binaries are available for the following platforms:

- Debian GNU/Linux: since Debian 10 (Buster) Galois is part of the official Debian stable release. That means that you can install it via the standard Debian package management facilities, that is, `apt-get` or `aptitude` on the command line, or a graphical package manager like `synaptic`. The package name is `galois`. For example, if you are allowed to use `sudo`, you may run:

        sudo apt-get install galois

  The package is available for all release architectures. I have verified that it works on i386 and amd64; it should supposedly run on the other architectures as well, but I don't know whether anyone has actually tried. If you try, please let me know.

  If there is a more recent version of Galois than that in the current Debian stable release, you can download a binary package for that version from the Galois web site and install it with `dpkg`. That is available for the i386 and amd64 architectures.

  The Debian packages may work also on Debian-based distributions. If you try, please let me know.

- Microsoft Windows: there is a Galois binary that you can download and run, but there isn't a full installation package which will also install documentation files and make Galois appear on the programs menu. The documentation is available on the Galois web site anyway.

  The binary was built on Debian GNU/Linux using the MXE cross-compiling environment.

- This web page: https://repology.org/project/galois/packages lists other GNU/Linux distributions that include Galois binaries. I do not maintain that page, nor those binaries, and haven't tested them.

For other platforms, Galois must be compiled from source (see ). I am willing to provide binary packages if someone volunteers to build and maintain them.

### Source Installation

To install Galois from source, first you need to check that all its dependencies are installed on your system, and install any missing ones (see ). When you've done that, unpack the compressed archive file `galois-0.8.tar.gz` in a directory of your choice. Then open a command-line shell (console or terminal), change to the base directory of the unpacked source tree, `galois-0.8`, and type the following commands:

      ./configure
      make
      make install

`configure` has many command-line options by which you can specify where to install, where to find dependencies (you'll need this if they are installed in nonstandard places), which compiler flags to use, and so on. Run `./configure --help` for a complete list.

For the `make install` step, you need write permission on the installation directory. On GNU/Linux and other Unix-compatible systems, if you are installing in the standard place (i.e., under `/usr/local`), this means you must run that command as root (use `su` or `sudo`).

### Dependencies

In order to compile Galois, the following packages must be installed on your system:

- A basic Unix environment, including the `make` utility

- g++ or another C++ compiler supporting at least the C++11 standard

- gtkmm 3

- libxml++

For all major versions of GNU/Linux, precompiled versions of these packages are available. Precompiled libraries are usually split into a "base" and a "development" package (the latter has a name ending with `-dev` or `-devel`). In order to compile Galois, you must install both; while in order to run the compiled program, only the base packages are required. If you also want to be able to rebuild the HTML and PDF versions of the documentation, you'll need these too:

- xmlto

- dblatex (for the PDF version)

Package names for Debian 11 (Bullseye):

- base packages: `libgtkmm-3.0-1v5`, `libxml++2.6-2v5`.

- compiler and development packages: `make`, `g++`, `libgtkmm-3.0-dev`, `libxml++2.6-dev`.

- documentation building tools: `xmlto`, `dblatex`, `texlive-lang-italian` (for the Italian version).

Packages for other GNU/Linux distributions should have similar names, particularly for Debian-based distributions.

If you are installing a precompiled binary package (see ), you normally need not worry about having the necessary dependencies installed because the package management system takes care automatically.

### Upgrade Notes

In Galois 0.3, the paths where user data files are stored were changed to be more consistent with commonly used conventions. If you are upgrading from an older release, existing files will not be moved automatically to the new paths: if you don't want to lose your settings and scores, you must move them manually before running the new version.

The new pathname for the settings file is config_dir`/galois/galois.conf`, where config_dir is the path returned by the glibmm function `get_user_config_dir()` on your computer (typically `$HOME/.config` on GNU/Linux systems). The old pathname was config_dir`/galois.conf` (without the `galois` subdirectory). You must create the subdirectory and move the file therein.

The new pathname for the scores file is data_dir`/galois/galois.res`, where data_dir is the path returned by the glibmm function `get_user_data_dir()` on your computer (typically `$HOME/.local/share` on GNU/Linux systems). The old pathname was data_dir`/galois.res` (without the `galois` subdirectory). You must create the subdirectory and move the file therein.

## How to Play

Galois games are played on a board made of square, hexagonal, triangular or cubic cells, where blocks made of "bricks" packed together, each brick filling a cell, fall at a regular pace, one at a time, until they land on the bottom of the board or over other blocks.

While they are falling, you can move them horizontally, rotate and (if that option is enabled) reflect them, so that when they land, they fit together with other blocks, leaving as few empty cells as you can. When a horizontal line (or, in 3D games, a plane) is filled completely with bricks, it is removed from the board, and all bricks that were above it fall down by one cell. (You can also remove multiple lines at once if you fill them with the same block.)

The goal is to remove lines (or planes) fast enough to prevent bricks from piling up to the top of the board: when there is no more space to accommodate a new falling block, the game is over. This becomes more and more difficult as the game proceeds, because, depending on the selected game mode, either the speed at which the blocks fall down, or the number of bricks composing the blocks, increase as more lines are filled.

### Running Galois

If you are running a graphical environment that supports the XDG menu specification (e.g., GNOME or KDE), you'll see an entry for Galois in the system menus (under Applications Games in Gnome 2) or in the equivalent function provided by your environment (Applications overview in Gnome 3 or later), and can start it by clicking on that. Otherwise, you may create a shortcut to the `galois` executable file on your desktop (if your environment allows desktop shortcuts), or open a file manager and browse to the directory where it was installed (typically `/usr/games` or `/usr/local/games` on GNU/Linux systems), or run it from the command line.

To start a new game, choose Game New from the menu bar, or press Ctrl N . This command is disabled while a game is already active (running or paused).

To pause a running game, or resume a paused game, press the key assigned to the Pause action: by default it's Esc.

To stop permanently a running or paused game, choose Game Stop from the menu bar. If no game is currently active, this command is disabled.

To open the preferences dialog, choose Game Preferences from the menu bar. This command is disabled while a game is active.

To open the scores dialog, choose Game Scores from the menu bar. This command is disabled while a game is active. The scores dialog will also pop up at the end of the game whenever you set a score that ranges within the top 10 for the current settings, and will let you enter your name in that entry.

To get help on Galois, choose Help Contents from the menu bar, or press F1. The Galois Manual (i.e., this document) will be displayed. If you aren't running GNOME, this might not work; in any case an HTML version of the manual is shipped with the source tarball, and HTML and PDF versions can be downloaded from the Galois web site.

To get basic information on Galois, choose Help About from the menu bar.

To quit Galois, choose Game Quit from the menu bar, or press Ctrl Q .

### Game Interface

The Galois window contains the following elements:

Menu bar (1)

  At the top of the window. It contains menu entries to start a new game; stop the current game; open the preferences and scores dialogs; get help and information about Galois; and quit the program.

Next block preview (2)

  At the upper-right corner of the window.

Game board (3)

  At the left of the window. This is the main element of the game interface: that's where blocks fall.

Score display (4)

  At the right of the window. Shows the current score, level, and number of filled lines.

### Game Controls

While blocks fall, you can perform the following actions on them:

- Move left or right, and in 3D games up or down.

- Rotate: in 2D games there is a single rotation mode (counterclockwise), in 3D games there are three (along axis X, Y, and Z).

- Reflect: this action can be turned on or off in the preferences dialog. By default it's off.

- Drop: the block falls down very fast.

You can perform each of those actions by pressing the corresponding key on the keyboard. The mapping between actions and keys is shown in the preferences dialog (Controls tab) and can be changed by the user. The default mapping is as follows:

- For 2D games: ← and → to move the block, ↑ to rotate, ↓ to reflect (if allowed) and space to drop the block.

- For 3D games: ←, →, ↑ and ↓ to move in the four directions, 1, 2 and 3 to rotate, 4 to reflect (if allowed) and space to drop the block.

I set up separate sets of controls for 2D and 3D games because in 2D, ↑ for rotate is the norm in falling blocks games and lets you play comfortably with a single hand; but in 3D it is natural to use the four arrow keys to move in the four directions.

### Preferences

The preferences dialog has two tabs:

Game

  Settings about the game geometry and playing modes:

  - Choose the game geometry among: square, hexagonal, triangular (all these 2D), and cubic (3D), with or without block reflection.

  - Choose the board width and (for 3D games) depth.

  - Choose what to do on level changes (every 10 filled lines): increase game speed, maximum block size, or superblock size. If you choose maximum block size, you can also choose whether to increase, keep fixed or decrease the minimum block size. Superblocks are blocks larger than the maximum: they are enabled only if you choose superblock size.

  - Choose the initial speed level and maximum and minimum block size.

  - Choose whether to remove lines also when they aren't completely filled: up to 2 missing bricks can be allowed.

  - Choose whether to preview the next block.

  - Choose whether to display where the block will land.

Controls

  Settings about the keyboard controls: to change any of them, double-click on the current key label (or select it with the keyboard and hit Enter) and when it gets highlighted, press the key that you want to replace it with.

Settings are saved into the file config_dir`/galois/galois.conf`, where config_dir is the path returned by the glibmm function `get_user_config_dir()` on your computer (typically `$HOME/.config` on GNU/Linux systems). You may restore the pristine settings by deleting that file.

### Scores

Galois records the scores of the best games together with their respective settings. The scores dialog shows the top 10 scores for the current settings.

Scores can be filtered by various criteria, for example you can choose whether to see only games played with a specified initial range of block sizes, or all games played with square bricks, or even with any brick shape. The filters can be changed using the buttons and boxes at the top of the scores dialog.

I tried to calibrate the scores proportionally to the difficulty of the game, so that games played with different settings can be compared; but it is very hard to give an objective evaluation of how difficult a given game mode is.

Scores are saved into the file data_dir`/galois/galois.res`, where data_dir is the path returned by the glibmm function `get_user_data_dir()` on your computer (typically `$HOME/.local/share` on GNU/Linux systems).

## How to Contribute

> "Freely you have received, freely give." (Matthew 10:8)

If you would like to help making Galois better, you're welcome to contact me (see ). You must agree to license your contributions as free software under the license Galois is released with (the GNU General Public License, version 3 or later).

## Contact Information

The Galois web site is at https://www.nongnu.org/galois/

The project's page on Savannah is at https://savannah.nongnu.org/projects/galois

For any requests about Galois, send email to galois-list@nongnu.org

To subscribe to the mailing list, or browse its archives, go to https://lists.nongnu.org/mailman/listinfo/galois-list