Gtkboard developer documentation

This is the developer documentation for gtkboard version 0.10.0. The end-user documentation is here.

• Gtkboard philosophy
• Writing a new game
• How you can help
• Coding style
• Gtkboard features
• Roadmap
• Doxygen documentation for source code

Gtkboard philosophy

No duplication. The raison d'etre of gtkboard is to reduce the duplication of effort involved in writing hundreds of board games. Therefore, anything that is common between two or more board games must be implemented by gtkboard and available to all games.

Allow games to be created incrementally. Just because a feature exists, a game shouldn't be forced to do something about it. Thus, when writing a new game you can concentrate on exactly what you need and ignore the rest. For instance, you can make a new game compile and display the board without writing any code, just specifying the dimensions, colors and images for the pieces. (Several common pixmaps are available for reuse.) Further, the user can already replay a game from a file -- the game doesn't need to implement anything.

Homogenize. If two games require a thing to be done in slightly different ways, see if both can be expressed as special cases of a more generic way, and the differences expressed in data rather than code. That way, if a new game required the thing to be done in a third way, it is more likely that it can be accomodated without modifying the existing code. This principle is related to the next one.

Generality is more important than efficiency. This is an application of the maxim that premature optimization is the root of all evil. For example, the AI of some games would probably become somwhat more efficient if the search strategy incorporated game specific information, and the evaluation function and the move generation function were tightly coupled. However, the extra complexity is judged to be not worth the gain in efficiency.

TIMTOWTDI. There is more than one way to do it. As far as possible, nothing will be forced on the games. Everything is a hook. The game can choose from among the defaults or provide its own. For example, three defaults are provided for ordering the highscores: decreasing order of score, increasing order of score and decreasing order of time. The game can use one of these or write its own.

Client-server model. This is the most important part. Gtkboard is currently implemented as a pair of processes, one for the ui and one for the number crunching, which communicate through a pair of pipes. This has several benefits:

• Ui won't feel slow when the machine is thinking
• Keeps the code clean
• It is relatively easy to change the code to communicate through sockets and thus have network functionality.

TODO: complete this

Writing a new game

• Get the latest source from cvs using the command:
  $ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/gtkboard co gtkboard
  Getting the latest source release from the file releases page is usually OK.
• Think about what game you want to implement and decide basic things like will it be a single or a two player game, the dimensions and colors of the board, etc.
• Read the game.h documentation. This is very important. All the details might need to know are in that file. You need to create a Game struct for your game before you can compile your game.
• • In the "src/" directory of the source, create a new file "yourgame.c".
  • In "yourgame.c" you should #include game.h and define a Game yourgame.
  • Edit the file "ui.c" and add your game to the list of games (the Game *games[] array).
  • In the file "Makefile.in" add "yourgame.c".
• You are now ready to compile your game! In the root directory of the source invoke automake and then make.
• Now run gtkboard. Your game should appear in the "Game->Select game" menu. When you choose it you will see the initial board position that you specified. However, you can not do anything yet. If you try to make a move a dialog will pop up saying "Not yet implemented."
• Your next job is to write a function that will take user input and return a move. Moves are represented in a standard format for all games. See the move.h documentation for a description of this format. You should also see the source of some other game to get a feel for the code. The function you will need to implement is game_getmove(). After writing the function remember to add a function pointer to this function in your game_init() function.
• If your game is a single player game you are nearly done. The user will be able to play your game, the only thing missing is that there is no notification of when the game is over. Skip the next step. In two player games, at this stage two humans can play the game against each other but not human vs. machine. Read the next step.
• (Only for two player games.) You need to implement two functions, game_movegen() and game_eval(). The first function generates a list of legal moves in a given position and the second associates a "goodness" value to a given position. This is used by the AI in deciding which move to make, in conjuction with the alpha-beta search strategy and transposition tables. Writing these functions (movegen and eval) is probably the most time consuming part.
• Next you have to write a function to determine whether the game is over. This function has the dual role of showing the "score", for most single player games and some two player games too. This function is game_who_won(). Again see the game.h documentation for details.
• Congrats! Now you've got a fully working game, with features like highscores (for single player games), ability to go back and forward, saving and loading the game etc. There are several frills that you could add to your game, such as animations.
• When you feel your game is complete mail me a copy of "yourgame.c".

Creating a plugin

How you can help

• Write code for gtkboard. Good at AI, search trees and the like? You could work on the back end. Like doing UI stuff? There's a lot of front end work left to do, too.
• Write a new game. You've always wanted to write a game, didn't you? You don't get a better opportunity than this! The mundane part is already taken care of, you just have to worry about the rules and strategy of the game you want to implement.
• Write documentation. End-user documentation, that is. The rules haven't been documented for several games yet. If you are good at some game, please consider writing a strategy document for the game.
• Create artwork. We badly need a logo, a splash screen, some icons etc. Apart from that, many games currently have simple colored balls as their pieces. While this helps rapid development, it doesn't hurt to have some eye candy!
• Be a tester. The hard part of fixing a bug is finding it. We could use your help!
• Contribute builds: Even though gtkboard should build without problems on any Unix with gtk+-1.2 or greater, not all users would be willing to compile from source. So if there's no build available for your platform, and you have compiled gtkboard, please contribute a build. Thanks.

Coding style

• Spaces and tabs. This being the subject of eternal flamewars, the project maintainer is usually allowed to make their decision binding on everybody, so I will take that liberty :) Your code should use only tabs for indenting, not spaces. Further, your code should look right whatever be the tabstop setting (I use 4; 3 and 8 are also common.) Therefore, no end-of-line comments. (See the section on comments.) Also

  int foo;
  float bar;
       ^
  // NO tab here
  

• Don't make your lines too long. 80 chars is not a rigid limit, because after all not many people are going to be looking at the code on 80 character terminals, I mean, its gtkboard, so a little over 80 chars is probably OK, but still don't make your lines too long.
• Minimize comments. Another subject of heated controversy. Comments are good, because they let other people understand your code. Comments are bad, because they are a maintenance nightmare. Over time, comment rot happens: your code was updated but the comment wasn't, so it serves to confuse rather than to enlighten. In my experience, the best way out is to write self-documenting code augmented by sparse comments. Therefore the rules are:
  • Use clear variable (esp. global) and function names that describes what it is. A function name should typically be module_verb_noun().
  • Describe what a function does rather than how it does it.
  • Documenting module interfaces is more important than documenting modules.
  • Use doxygen for documentation. (No learning curve here; `//!' for single line comments, and `/** ... */' for multi-line comments is all you need to know.)
  • Comments inside a function should be limited, as far as possible, to: FIXMEs, TODOs, indication of ugly hacks and misc gotchas.

Gtkboard features

Features currently provided by gtkboard

• Common user interface
• AI using alpha beta search and transposition tables
• Common representation of board position and moves of all board games
• Highscores
• Human vs. human, human vs. machine, machine vs. machine modes
• Animations
• Move back and forward
• Pause and unpause games
• Common interface to game documentation
• Tournament mode: create a computer game tournament among several evaluation functions!
• Games available as dynamically loadable plugins (currently limited to loading from command line argument)

Features coming real soon now

• Full implementation of runtime game loading
• Common board game format (cbgf): this format is still being decided. Once this is finalized all games will be able to save and load their games in a common format.
• Drag and drop support
• Genetic algorithm for evolving an evaluation function
• pgn2cbgf: convert a chess game (Portable Game Notation) into a cbgf game.
• Network support: this one's a killer :) Hopefully we'll be able to do something like FICS (Free Internet Chess Server).

Roadmap

The main things that have to be done before this are:

• Support for the Zillions language
• Plugin support (i.e, implement games as plugins)
• Standardize and implement the cbgf format
• Implement several more games, so that this will reveal missing features of the game.h API.

The last is very important, because at 1.0 we will freeze the game API. Until then it will be fluid. We hope that a huge number of games will be written for the 1.0 release, and also that some major distros will include gtkboard 1.0 :) Therefore the API should be complete enough that almost anything that can be called a board game should be implementable in gtkboard.

Post 1.0, our focus will shift to two things:

• Network support.
• Alternate implementations -- Possibilities are a java client, and a stripped down javascript client so that users can view a database of games through their browser.

Of course all this is kinda the best case scenario since gtkboard is entirely a spare time/hobby project.