Gtkboard developer documentation
This is the developer documentation
for gtkboard version 0.10.0. The end-user documentation is here.
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
This is a simple step-by-step guide to get you started writing a new
- Get the latest source from cvs using the command:
$ cvs -z3
-d:pserver:email@example.com:/cvsroot/gtkboard co gtkboard
Getting the latest source release from the file releases page is
- 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
- 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
- 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
Creating a plugin
To make a plugin follow the same steps as above, but also add a line
Game * plugin_game = &Yourgame; to yourgame.c, and compile
yourgame.c with the -static flag to create a .so file. The -G option
for gtkboard allows you to specify the plugin file to load.
How you can help
Here's a list of ways you can help gtkboard:
- 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
You are requested to follow these guidelines if you intend to
contribute to gtkboard.
Well that's it I guess. And also keep in mind the general words of C
wisdom, like remember to free() everything, use snprintf
rather than sprintf, use lots of assert()s and that
sort of thing. So far the code's been rather clean, I've never had a
gdb session longer than a couple of minutes, let's keep it that way :)
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
- Human vs. human, human vs. machine, machine vs. machine modes
- Move back and forward
- Pause and unpause games
- Common interface to game documentation
- Tournament mode: create a computer game tournament among several
- 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
- Network support: this one's a killer :) Hopefully we'll be able
to do something like FICS (Free
Internet Chess Server).
The current priority is to get a stable 1.0 release out.
The main things that have to be done before this are:
- Support for the Zillions
- 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
games through their browser.
Of course all this is kinda the best case scenario since gtkboard is
entirely a spare time/hobby project.