Introduction

This manual is aimed at helping people to bug fix or develop new gbrainy's games functionality. It covers the following areas:

• Guidelines and recommendations for new game development
• Different options for creating new games
• How to port gbrainy to other platforms

gbrainy uses Mono project coding guidelines. Please read before doing any new development.

There is a gbrainy public group where people can share its experiences, ideas and get involved in gbrainy development.

If you extend gbrainy, please considering contributing your work to be included in gbrainy.

Recommendations for developing new games

If you are creating a new gbrainy game, please take into account the following criteria:

• It should be as dynamic as possible. Every time that the user plays should be a challenge. Even if the logic is always the same, make all the elements that you can random.
• Make very clear and concise questions. The graphics shown should help to understand the puzzle. Ask other people if the puzzle makes sense to them.
• gbrainy is localized in several languages. Games based on play on words or specific to a language are not good games because they cannot be localised. It should be always possible to translate a game to any language.
• Puzzles should represent a challenge for an average person. Do not make puzzles that are trivial or only for gifted people. You can define the game's difficulty to indicate for which difficulties the game is indicated.
• Try to provide a tip if it is possible (Game.Tip property).
• Make sure that, if you give a list of possible answers to the users, the options are not repeated (e.g: random generated).
• When giving the answer, make sure that you give as good explanation to understand the rationale of the answer.

Using external game definition files

External game definition files allow game authors to define new gbrainy games without the need to do any coding.

You can define new verbal analogies and logic/calculation games using two different xml files. See games.xml and verbal_analogies.xml for real examples of how to use them.

Verbal analogies

Verbal analogies help to prove your abilities linking concepts and using the language.

gbrainy reads the file verbal_analogies.xml that contain the verbal analogies definitions for gbrainy. This file is located in the shared gbrainy directory (usually /usr/share/gbrainy/verbal_analogies.xml). You can edit, modify and extend this file as you wish.

Description of verbal_analogies.xml format

Brief description of the tags and attributes used:

<_question>. Specifies the question for the analogy

The type attribute allows to specify the type of question:

• Regular. No special processing. The question and the answer are shown.

• PairOfWordsOptions. A pair of words with multiple answers as options for answering

• PairOfWordsCompare. A pair of words with an additional sample with a single word as answer. You must use the "|" character to separate the part of words from the additional sample

<_tip>. Optional tag that allow to give a tip to the user on how to resolve the analogy

<_answer>. Allows to specify one or more answers

The attribute correct with value "yes" indicates that this is right answer.

You can use the "|" character to separate possible answers.

You can also look at AnalogiesFactory.cs in gbrainy source code as additional reference.

New logic and calculation games

The games.xml file allows you you to define new gbrainy games without the need to do any coding.

gbrainy reads the file games.xml that contain games definitions for gbrainy. This file is located in the shared gbrainy directory (usually /usr/share/gbrainy/games.xml). You can edit, modify and extend this file as you wish.

Description of games.xml format

Brief description of the tags and attributes used:

<_name>. Specifies the name of the game.

<type>. Specifies the type of the game. Logic and Calculation games are currently supported.

<question>. Specifies the question for the game.

<answer>. Specifies the correct answer for the game.

<difficulty>. Indicates the difficulty for which the game is available.

<variables>. Defines a set of variables that are evaluated as C# and then can be referenced in question, answer and rationale strings using brackets.

<_rationale>. Defines the rationale behind the answer considered correct.

<svg>. Defines a SVG file that will be shown as part of the puzzle.

You can also look at GameXmlFactory.cs in gbrainy source code as additional reference.

Using extensions

Introduction

You can extend gbrainy easily with new games that you develop as extensions. This provide more flexibility that using external files since you can use a programming language to express more complex games. Extensions are external assembly files that gbrainy recognizes at runtime. The extensibility capabilities are provided by Mono.Addins framework. You do not need to recompile gbrainy to develop or deploy extensions.

gbrainy supports three types of extensions Logic, Memory and Calculation that correspond to the types of games that gbrainy supports.

Anatomy of an extension

An extension should be a self-contained game. It should provide at least two files:

• The source code of the extension
• A manifest file that describes the extension

It also may contain graphics or additional resources required by the game.

At gbrainy source code repository there is a directory called sample_extensions that contain three types of games supported.

Building extensions

You do not need gbrainy source code to build extensions, you only need to have gbrainy properly installed. For a simple extension containing a single code file and a manifest, you should be able to compile it like this:

gmcs -t:library CalculationSample.cs -resource:CalculationSample.addin.xml -pkg:gbrainy

Installing an extension

The assembly containing your extension (and the manifest file if not bundled as resource in the assembly) have to be copied either in $PREFIX/lib/gbrainy/ (e.g. /usr/lib/gbrainy/) to make it available system-wide, or in ~/.gnome2/gbrainy/addins if you don't have enough rights to install it system-wide.

Porting gbrainy

gbrainy has been designed to be portable to different operating systems and devices. It is written in C#.

It requires the following software stack:

• A compatible Microsoft .Net runtime. Mono and Microsoft .Net can have been tested successfully. Mono is available for a wide range of operating systems and architectures.

• Cairo 1.2 or higher
• librsvg 2.2 or higher
• Mono.Addins 0.3 or higher
• GNU Get Text

Optionally:

• Mono.Addins

gbrainy source code is structured in three assemblies:

• Core. Contains the game engine and the components to support the application features like a game engine, player's score, personal records, views, etc.
• Games. Contains all the games includes in the applications.
• Clients. Clients that expose the game functionality under different UI systems.

gbrainy functionality has been made available as porting to the different systems:

• Native GTK application (gbrainy classical client). Runs under all Linux platforms, Unix and Windows.

• Winforms (using Cairo). Runs on Windows only.

• OLPC (see OLPC web and see as porting example).