Main game logic: yourgamename.game.php

This file is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify changes to the client interface.

File Structure

The details on how the file is structured is described directly with comments on the code skeleton provided to you.

Basically, here's this structure:

• EmptyGame (constructor): where you define global variables.
• setupNewGame: initial setup of the game.
• getAllDatas: where you retrieve all game data during a complete reload of the game.
• getGameProgression: where you compute the game progression indicator.
• Utility functions: your utility functions.
• Player actions: the entry points for players actions.
• Game state arguments: methods to return additional data on specific game states.
• Game state actions: the logic to run when entering a new game state.
• zombieTurn: what to do it's the turn of a zombie player.

Accessing player informations

getPlayersNumber()

Returns the number of players playing at the table

Note: doesn't work in setupNewGame so use count($players) instead

getActivePlayerId()

Get the "active_player", whatever what is the current state type.

Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"

Note: avoid using this method in a "multiplayer" state because it does not mean anything.

getActivePlayerName()

Get the "active_player" name

Note: avoid using this method in a "multiplayer" state because it does not mean anything.

loadPlayersBasicInfos()

Get an associative array with generic data about players (ie: not game specific data).

The key of the associative array is the player id.

The content of each value is:

* player_name

* player_color (ex: ff0000)

getCurrentPlayerId()

Get the "current_player". The current player is the one from which the action originated (the one who send the request).

Be careful: It is not always the active player.

In general, you shouldn't use this method, unless you are in "multiplayer" state.

getCurrentPlayerName()

Get the "current_player" name

Be careful using this method (see above).

getCurrentPlayerColor()

Get the "current_player" color

Be careful using this method (see above).

isCurrentPlayerZombie()

Check the "current_player" zombie status. If true, player leave the game.

Accessing database

The main game logic should be the only point from where you should access to the game database. You access your database using SQL queries with the following methods:

DbQuery( $sql )

This is the generic method to access the database.

It can execute any type of SELECT/UPDATE/DELETE/REPLACE query on the database.

You should use it for UPDATE/DELETE/REPLACE query. For SELECT queries, the specialized methods above are much better.

getUniqueValueFromDB( $sql )

Returns a unique value from DB or null if no value is found.

$sql must be a SELECT query.

Raise an exception if more than 1 row is returned.

getCollectionFromDB( $sql, $bSingleValue=false )

Returns an associative array of rows for a sql SELECT query.

The key of the resulting associative array is the first field specified in the SELECT query.

The value of the resulting associative array if an associative array with all the field specified in the SELECT query and associated values.

First column must be a primary or alternate key.

The resulting collection can be empty.

If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"

Example 1:

self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
 1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
 1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)

Example 2:

self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
array(
 1234 => 'myuser0',
 1235 => 'myuser1'
)

getNonEmptyCollectionFromDB( $sql )

Idem than previous one, but raise an exception if the collection is empty

function getObjectFromDB( $sql )

Returns one row for the sql SELECT query as an associative array or null if there is no result

Raise an exception if the query return more than one row

Example:

self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );

Result:
array(
  'id'=>1234, 'name'=>'myuser0', 'score'=>1 
)

getNonEmptyObjectFromDB( $sql )

Idem than previous one, but raise an exception if no row is found

getObjectListFromDB( $sql, $bUniqueValue=false )

Return an array of rows for a sql SELECT query.

the result if the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).

The result can be empty.

If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:

self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
 array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
 array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)

Example 2:

self::getObjectListFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
array(
 'myuser0',
 'myuser1'
)

getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )

Return an associative array of associative array, from a SQL SELECT query.

First array level correspond to first column specified in SQL query.

Second array level correspond to second column specified in SQL query.

If bSingleValue = true, keep only third column on result

DbGetLastId()

Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

DbAffectedRow()

Return the number of row affected by the last operation

escapeStringForDB( $string )

You must use this function on every string type data in your database that contains unsafe data.

(unsafe = can be modified by a player).

This method makes sure that no SQL injection will be done through the string used.

self::getObjectFromDB( "SELECT player_id id, player_name name, player_color color FROM player WHERE player_id='1234'" );

Result:
array(
 'id' => 1234,
 'name' => 'myuser1',
 'color' => 'ff0000'
)

function getNonEmptyObjectFromDB( $sql )

Idem, but raise an exception if the query doesn't return exactly one row

Note: see Editing Game database model: dbmodel.sql to know how to define your database model.

Game states and active players

checkAction( $actionName, $bThrowException=true )

Check if action is valid regarding current game state (exception if fails)

The action is valid if it is listed as a "possibleactions" in the current game state (see game state description).

This method should be called in the first place in ALL your PHP methods that handle players action, in order to make sure a player can't do an action when the rules disallow it at this moment of the game.

if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception. This is useful when several actions are possible in order to test each of them without throwing exceptions.

function activeNextPlayer()

Make the next player active in the natural player order.

Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

function activePrevPlayer()

Make the previous player active (in the natural player order).

Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

Game statistics

function initStat( $table_or_player, $name, $value, $player_id=null )

Create a statistic entry for the specified statistics with a default value

In case of a "player" entry, if player_id is not specified, all players are set to the same value

function setStat( $value, $name, $player_id = null )

Set statistic value

function incStat( $delta, $name, $player_id = null )

Increment (or decrement) specified value

Translations

function _( $text )

Transparent function, used to mark strings to be translated on the server side (ex: error message)

function clienttranslate( $string )

Transparent function: used to mark string to be translated on client side (ex: notification message)

Reflexion time

function giveExtraTime( $player_id, $specific_time=null )

Give standard extra time to this player (standard extra time is a game option)

Managing errors and exceptions

throw new BgaUserException ( $error_message)

Base class to notify a user error

throw new BgaSystemException ( $error_message)

Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.

throw new BgaSystemVisibleException ( $error_message)

Same as previous, except that the message is visible by the user. You can use this if the message is understandable by the user.