Introduction

Introduction -- Basic usage of Games_Chess

What is Games_Chess?

Games_Chess provides a basic interface for validating and playing chess. Games_Chess has facilities for calculating all of the important chess rules including check, checkmate, stalemate, basic draws such as bishop+king versus king, 50 move draw, en passant pawn captures, castling, double space first pawn move and basic piece movement. In addition, Games_Chess can set up a board to a position using the Forsyth-Edwards Notation (FEN) and can output a list of moves in Standard Algebraic Notation (SAN) as well as parse any valid SAN move, no matter how obscure (Qa3xf3, for instance), as well as simple "move the piece on a3 to h3" commands.

How do I use Games_Chess?

The Games_Chess package comes with a demonstration file, which has highlighted source at This location.

The Games_Chess package provides three different drivers, one for playing a standard chess game, and two for playing interesting variant games that are popular on the Internet Chess Club (ICC).

Crazyhouse. basic rules in Crazyhouse chess allow you to place pieces you have captured from your opponent on the board as new pieces for your own army. This is a wild and highly tactical game.
Loser's Chess. Loser's chess is similar to checkers in that if a capture is possible, it must be executed. For this reason, most of the moves are forcing moves in this game, and it results in very fast games.

To use Games_Chess on the most basic level is simple. Here is a sample script showing the initialization of the three drivers:

       
<?php
require_once 'Games/Chess/Standard.php';
require_once 'Games/Chess/Crazyhouse.php';
require_once 'Games/Chess/Losers.php';
$standard = new Games_Chess_Standard;
$crazyhouse = new Games_Chess_Crazyhouse;
$losers = new Games_Chess_Losers;
?>

By default, a Games_Chess driver is created with a blank board. To set up a new starting position, use this code:

       
<?php
require_once 'Games/Chess/Standard.php';
$standard = new Games_Chess_Standard;
$standard->resetGame();
?>

If you wish to load a particular starting position in FEN notation, pass the FEN string to resetGame() like so:

       
<?php
require_once 'Games/Chess/Standard.php';
$standard = new Games_Chess_Standard;
$standard->resetGame('rnbqkbnr/pp1ppppp/8/2p5/4P3/8/PPPP1PPP/RNBQKBNR w KQkq c6 0 2');
?>

How to move pieces with Games_Chess

There are two basic methods for performing moves with Games_Chess, moveSAN and moveSquare. Both of these methods either return TRUE or a PEAR_Error class upon error, so the proper way to handle for a return value is:

        
<?php
require_once 'Games/Chess/Standard.php';
$standard = new Games_Chess_Standard;
$err = $standard->moveSAN('Nf9');
if ($standard->isError($err)) {
    echo $err->getMessage();
    die;
}
?>

Note that Games_Chess->isError() should be used as the PEAR_Error class is only loaded when needed, to help with efficiency. If this is not a concern (and it will only be for sites serving thousands of pages per second), it is simpler to set a PEAR_Error callback, which is demonstrated in the next example.

The example below demonstrates the two ways that Games_Chess should be called to make moves on the chess board, including the way to represent a placement move in the Crazyhouse variant:

        
<?php
require_once 'PEAR.php'; // for the PEAR_Error class
function showerror($err)
{
    echo $err->getMessage();
    exit;
}
require_once 'Games/Chess/Standard.php';
require_once 'Games/Chess/Crazyhouse.php';
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'showerror');
$standard = new Games_Chess_Standard;
$crazyhouse = new Games_Chess_Crazyhouse;
$standard->resetGame();
$crazyhouse->resetGame();

$standard->moveSAN('e4'); // 'e2' to 'e4' if using moveSquare
$standard->moveSquare('d7', 'd5'); // 'd5' if using moveSAN
$standard->moveSAN('exd5');

$crazyhouse->moveSquare('e2', 'e4'); // same as moveSAN() above
$crazyhouse->moveSAN('d5'); // save as moveSquare above
$crazyhouse->moveSAN('exd5');
$crazyhouse->moveSAN('Qxd5');
$crazyhouse->moveSAN('P@d7'); // dumb move, but demonstrates piece placement
?>

Note that if promoting a pawn, moveSquare() requires that the newly promoted piece type be passed in. Options are Q for queen, R for rook, B for bishop and N for knight.

        
<?php
require_once 'PEAR.php'; // for the PEAR_Error class
function showerror($err)
{
    echo $err->getMessage();
    exit;
}
require_once 'Games/Chess/Crazyhouse.php';
PEAR::setErrorHandling(PEAR_ERROR_CALLBACK, 'showerror');
$crazyhouse = new Games_Chess_Crazyhouse;
$crazyhouse->resetGame();
$crazyhouse->moveSAN('e4');
$crazyhouse->moveSAN('d5');
$crazyhouse->moveSAN('exd5');
$crazyhouse->moveSAN('Qxd5');
$crazyhouse->moveSAN('d3');
$crazyhouse->moveSAN('Kd7');
$crazyhouse->moveSAN('d4');
$crazyhouse->moveSAN('Ke6');
$crazyhouse->moveSAN('P@d7');
$crazyhouse->moveSAN('Qd6');
// $crazyhouse->moveSAN('d8=Q'); // normal way to do this
$crazyhouse->moveSquare('d7', 'd8', 'Q'); // using moveSquare to do this
// dumb moves, but demonstrates pawn promotion to queen
?>

Retrieving information on the game in progress

To retrieve necessary information such as the current move list, current FEN, list of captured pieces (Crazyhouse only), determine whether the game is over and so on, you'll want to use one of the following methods:

gameOver(). This method can be used to determine if the game has concluded, and simply returns an abbreviation of W if the white pieces have won (checkmate), B if the black pieces have won (checkmate), D if there is a draw, or false if the game is still in progress.
renderFen().

This method returns a Forsyth-Edwards Notation (FEN) representation of the current game state. Note that the FEN standard does not contain a way to represent captured pieces, and so cannot be used to exactly replicate a Crazyhouse game in progress, although it can be close.

toArray().

For the Standard and Loser's chess drivers, this returns an associative array of algebraic square name (a1 to h8) mapped to its contents. If the square is unoccupied, it will contain its algebraic square name (a1 will map to a1), otherwise it will contain the piece name, one of P, R, N, B, Q or K. If the piece is a white piece, it will be in upper case, like P, and if the piece is a black piece, it will be in lower case like p.

For the Crazyhouse driver, this returns an associative array with two indices, board and captured. The board element is identical to the return for Standard/Loser's chess drivers described in the previous paragraph. The captured sub-array contains an array of this format:

           
<?php
$captured =
    array(
        'W' =>
            array(
                'P' => 6, // 6 black pawns captured by white
                'R' => 0,
                'N' => 0,
                'B' => 0,
                'Q' => 0,
            ),
        'B' =>
            array(
                'P' => 4, // 4 white pawns captured by black
                'R' => 0,
                'N' => 0,
                'B' => 0,
                'Q' => 0,
            ),
    );
?>

Each segment represents white's or black's pieces (W and B), and each sub-element represents the number of captured pieces of that type. In the example above, white can choose to place a pawn for up to the next 6 moves in a row, whereas black can choose to place a pawn for up to the next 4 moves in a row.

toMove().

This methods simply returns the color of the pieces that have the next move. W is returned for white, B is returned for black.