Introducing libagchess

As CBase Chess goes through some updates, I wanted to provide the community with something that might be of use – the code for the C++ backend which powers CBase Chess!  It is on Sourceforge available here.  I’ve put the project in alpha stage simply because the documentation is lacking.  However, if you’re interested in seeing what I’ve come up with, the code is free for you to browse around and is available for your own use under the GNU General Public License v3.  There are numerous comments in the code, but I will try and give a good overview of what libagchess is all about.

The low-level stuff

libagchess is a C++ bitboard-based library meant for use with chess databases (as opposed to chess engines).  There are 5 “primitive” types used extensively in the library:

  • Color – for indicating the side to move and color of a piece.
  • Piece – King, Queen, Rook, Bishop, Knight, Pawn, or none – used when you don’t care what color the piece is
  • ColoredPiece – has information for both piece and color.
  • Square – one always wants to know what pieces are on what square, and what squares are valid targets to move to, etc.
  • Bitboard – a typedef for an unsigned 64-bit integral value.  The merits of using a bitboard as the basis for chess programming can be read here.

The other classes in libagchess use these “primitives” quite extensively.  A bitboard in itself has no meaning without context – is it a bitboard of squares attacked by black pieces?  Maybe it’s an occupancy bitboard for white pawns?  There are numerous uses for bitboards, though the one that really stands out is to indicate occupancy.  Occupancy bitboards indicate which squares are occupied by which pieces.  The BasicBoard class wraps occupancy bitboards for each piece of each color, and also provides a means of accessing which ColoredPiece is at a given Square.  A BasicBoard provides no state-dependent context, simply the arrangement of the pieces on the board (think about the information you would get if you walked up to a chess game and just looked at the board – you wouldn’t necessarily know whose move it was, or who had castling rights, or if there was an en-passant square).

Chess Position – because you have to represent game state somehow!

The state-aware object is a Position object.  The Position object encapsulates the data about side to move, castling rights, en passant square, piece locations on the board, and even half-move clock (for 50-move rule).  Position itself is an abstract base class that provides the basic accessors to the general information it holds.  There are two concrete subclasses of Position: SimplePosition and EditablePosition.  EditablePositions allow one to directly manipulate the position state, while SimplePosition (and its subclasses) only allow manipulation using Move objects via make (to make a move) and unmake (to undo a move).

The SimplePosition was meant to be a base class which provided the make and unmake interface, but did not enforce any chess rules, thus one could move any piece to any square and not worry about the legality of such a move.  The SimplePosition class is not actually finished because it’s usefulness in a chess database program is quite limited.  The class which actually knows and enforces the standard chess rules is StandardPosition.  The StandardPosition can only be manipulated with make and unmake and throws an exception if the Move is illegal.  The StandardPosition is meant to always stay in a consistent, legal chess state.

The EditablePosition provides the methods necessary to set up a position.  It doesn’t know any rules, but like it’s base class, keeps track of state information such as en-passant square, castling, etc.  When the EditablePosition is ready to be used, the StandardPosition can set its state to that of the EditablePosition using the member function StandardPosition.copy(EditablePosition).  This will throw an exception if the EditablePosition is not a legal chess position.

Chess Game – a collection of Positions

Wow, that was a mouthful.  Ok, so that’s the fundamental material for representing a single chess position.  What about playing through a whole game?  In libagchess, a chess game is viewed as two parts – the header information about the game, and the moves it makes, and so the classes are GameHeader and GameTree.  A StandardChessGame inherits from both of these objects and provides an interface for constructing and reviewing a chess game.

The GameHeader is fairly simple, and merely provides access to information on who the players are, when the game was played, the name of the tournament, etc.

The GameTree can be abstractly thought of as a tree of StandardPosition objects (Really should be Position objects, but I was only interested in the concrete case of having StandardPosition).  It has a root position, and child positions.  Instead of containing a StandardPosition at every node, which would be prohibitively expensive, it contains the information to reach a child position compressed in a Move.  A GameTree is most easily thought of as a container object for positions – thus an iterator class is provided.

The iterator allows for insertion of a Move into the tree, and dereferences to a StandardPosition.  I thought it was most logical to use iterators to access the moves and positions from a GameTree, so hopefully anybody reading this will find it easy to use.  I think I will make it a priority to document this class more carefully and uploaded it to Sourceforge soon, since it’s the key method of playing through and creating chess games.

Database – because sometimes you need a collection of collections of Positions, aka a collection of Games

And finally we get to the database.  libagchess was designed as a database for reading PGN files.  The PGNDatabase is actually rather simple – tell it to load a PGN database and it does a quick parse of the file to locate where each game starts and ends.  It knows how many games are in a database, and will return a StandardChessGame object using database.getGame(int index), assuming that index is less than the number of games in the database.  When a game is loaded, it is parsed and placed entirely into memory ready to review.  A StandardChessGame loaded from a PGNDatabase is guaranteed to have no illegal moves, as an exception is thrown if the database encounters any illegal moves when loading the game.  To access only the header information without loading the rest of the game, use database.headers(int index).

Final words

This post contains a lot more information than I thought it would when I first started writing it.  Hopefully it provides a small overview as to how the classes in libagchess were meant to be used (or at least how they’re used by me).  There is also a class for filtering games from a database, DatabaseFilter, which uses subclasses of SearchMask to locate games in a database that match the SearchMask.  I’m not 100% sure that the DatabaseFilter is how I want to go about searching databases, but I included it with the library since somebody might find it useful.

This entry was posted in C++, Chess, PGN. Bookmark the permalink.

3 Responses to Introducing libagchess

  1. Mike Boone says:

    Thanks for sharing your code and design ideas. Do you have any opinion on the use of your library for iOS apps in light of the GPL dispute of VLC which resulted in the removal of the app?

    • iphonechess says:

      I would encourage the library to be used for iOS apps. I am deeply saddened by the GPL dispute over VLC, which was an excellent application that was developed with the best intentions. As far as libagchess is concerned, I am mostly interested in keeping works which utilize my code open source, since I believe that it is most beneficial for the chess community. As the sole copyright holder of libagchess, I assure you that I am not interested in using any “licensing incompatibilities” between the App Store and GPL to remove applications which utilize my code.

      The license is mostly in place because I want to keep works using this code open source, and I would not object to finding a license which requires distribution of source code that is also compatible with the App Store – if you happen to know of anything like that, please post a link!

      • Mike Boone says:

        I did some Googling and did not find any license that really fits the bill. Some people seemed to think LGPL was OK but I found enough other posts that disagreed. This article was interesting. Given the recent VLC stuff, I imagine someone will come up with something soon.

        Perhaps you could dual-license it…one GPL3 and the other “OK for the iOS App Store” as long as the full source code necessary to build the app in XCode is published, with the ability to assimilate that code back to the GPL original? I have no idea how a lawyer would phrase that. 🙂

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s