alcalyn/awale

Awale game PHP implementation

Awale

This library provides a PHP implementation of the Awale (or Oware) game., _(*1)

Installation

Download

Using Composer:, _(*2)

``` js { "require": { "alcalyn/awale": "1.0.x" } }, <sub>(*3)</sub>

Update your composer.

``` bash
composer update

Not using Composer ? Install it directly., <sub>(*4)</sub>

Usage

Creating an instance

Create an instance of Awale, which is an instance of an Awale game state, with seeds., <sub>(*5)</sub>

``` php use Alcalyn\Awale\Awale;, <sub>(*6)</sub>

$awale = new Awale();, <sub>(*7)</sub>

// Players start with 4 seeds in each container. $awale->setSeedsPerContainer(4);, <sub>(*8)</sub>

// The first player starts. $awale->setCurrentPlayer(Awale::PLAYER_0);, <sub>(*9)</sub>

// Needs to explicitly init the grid (containers seeds number, and attics). $awale->initGrid();, <sub>(*10)</sub>

Or to do it shorter:

``` php
use Alcalyn\Awale\Awale;

$awale = new Awale::createWithSeedsPerContainer(4);

The grid

The Awale grid represents the containers and attics., <sub>(*11)</sub>

``` php // Retrieve the grid array from the Awale instance $grid = $awale->getGrid();, <sub>(*12)</sub>

print_r($grid);, <sub>(*13)</sub>

/* Outputs: Array ( [0] => Array // Player 0, or player top. ( [seeds] => Array ( [0] => 4 // Player 0 seeds, he has 4 seeds in each containers. [1] => 4 // The first container is the top left container. [2] => 4 [3] => 4 [4] => 4 [5] => 4 // The top right container. ), <sub>(*14)</sub>

        [attic] => 0        // Player 0 has no seeds in his attic.
    )

[1] => Array                // Player 1, or player bottom.
    (
        [seeds] => Array
            (
                [0] => 4    // The bottom left container.
                [1] => 4
                [2] => 4
                [3] => 4
                [4] => 4
                [5] => 4    // The bottom right container.
            )

        [attic] => 0        // No seeds in player 1 attic.
    )

) */, <sub>(*15)</sub>

Or to get a graphical representation:

``` php
echo $awale;

/* Outputs:

Awale game instance.
     4  4  4  4  4  4
  0                    0
     4  4  4  4  4  4
seeds per container: 4
current player: PLAYER_0
last move: null

*/

Play moves

Once you have an instance of a game, you can play move., <sub>(*16)</sub>

``` php // Top player plays his third container (from left) $awale->play(Awale::PLAYER_0, 2);, <sub>(*17)</sub>

// Bottom player plays his first container (from left) $awale->play(Awale::PLAYER_1, 0);, <sub>(*18)</sub>

The `play` method throws an `Alcalyn\Awale\Exception\AwaleException` on invalid move.


### Game usefull checks

``` php
// Last played move
// An array with keys 'players' and 'move', example: {player:1, move:5}, Player 1 played his 5th container
$awale->getLastMove();

// Player's turn to play
$awale->getCurrentPlayer(); // Awale::PLAYER_0 or Awale::PLAYER_1

// Get amount of seeds needed to exceed, depending on seedsPerContainer
$awale->getSeedsNeededToWin(); // 24 if seedsPerContainer = 4

// Check is game is over (a player has more than 24 seeds, or game is looping, or player cannot feeds his opponent)
$awale->isGameOver(); // true or false

// Get winner when game is finished
$awale->getWinner(); // Awale::PLAYER_0 or Awale::PLAYER_1 or Awale::DRAW or null

// Get seeds number in a player attic
$awale->getScore(Awale::PLAYER_1);

// Whether a loop is detected (a same state of the game will appear again and again)
$awale->isGameLooping();

There is some other methods in the Awale class., <sub>(*19)</sub>

Run unit tests

First, update your composer to get phpunit, then run:, <sub>(*20)</sub>

bash vendor/bin/phpunit -c ., <sub>(*21)</sub>

License

This library is under the MIT License., <sub>(*22)</sub>