GeekGameBoard (GGB) is a small framework for building board and card games. It's based on Apple's Core Animation framework, which provides 2.5D image compositing, animation, and visual effects. GGB adds domain-specific classes like "Grid" and "Piece", an abstract "Game" class that's subclassed to define the rules of a particular game, and a controller layer that lets the user make moves via direct manipulation. Several example games are provided, including checkers and Go, most less than 150 lines of code.

Some of the generally-useful Core Animation techniques illustrated are:

  • Hit testing
  • Dragging CALayers with the mouse
  • Loading images from files and setting them as layer contents
  • 3D "card-flip" animations

GeekGameBoard runs on Mac OS X 10.5 or later, and iPhone OS 2.1 or later. (I've only done a small amount of testing on iPhone, though.)

How To Get It

      hg clone GeekGameBoard


I wrote GeekGameBoard in 2007 while at Apple, which published it as sample code. Apple's sample code license allows unrestricted use of the source code, requiring only that you keep their copyright notice in an unmodified distribution.

I am no longer employed by Apple. To encourage further development of this framework, in March 2008 I created this open source project (under a BSD license) based on a slightly-evolved version of the published sample code.

  • 1.0: Original Apple sample code release (12/19/2007)
  • 2.0: First open source release. (Major version number bumped to avoid conflict with any future Apple revisions.) No longer requires garbage collection. Fixed some memory leaks of CG objects. Fixed a bug when advancing to the 8th row in the Checkers game. (3/7/2008)

Project Description

Important Classes

  • A Bit is a moveable object in a game, either a Card or a Piece.
  • A BitHolder is a container for Bits; they can be dragged into and/or out of it. Typical BitHolders are GridCells (the squares/hexes in a board), Decks or Stacks of cards, and Dispensers (supplies of new pieces.)
  • A Grid is a regular arrangement of GridCells; rectangular and hex grids are implemented. BoardView is the NSView whose layer hosts all of the above. It also tracks mouse events so the user can drag Bits.
  • Game represents the rules of a particular game. It sets up the pieces/cards/grids that make up the game, decides which moves are legal, keeps track of whose turn it is, and decides when someone's won.
  • Player is a passive object that represents one of the players in a Game.

Class Hierarchy

(Parenthesized classes are from external frameworks; italic classes are abstract.)

  • (CALayer)

    • Bit
    • BitHolder *
      • GridCell
        • Hex
        • Square
          • GoSquare
      • Deck
      • Dispenser
      • Stack
    • Grid
      • HexGrid
      • RectGrid
    • Card
      • PlayingCard
    • DraggedStack
    • Piece
      • DiscPiece
  • (NSObject)

    • Game
      • TicTacToeGame (etc...)
    • Player
  • (NSView)

    • BoardView

*BitHolder is actually both a protocol, and a class that implements the protocol. I've combined them here, for simplicity.

New-ticket Create new ticket

Create your profile

Help contribute to this project by taking a few moments to create your personal profile. Create your profile ยป

A small framework for building board and card games, using Apple's Core Animation.

Language: Objective-C 2.0
Platform: Mac OS X, iPhone