Studio function reference

This page references useful server side and client side functions, so that nobody needs to reinvent the wheel (unless he wants to).

Server side (PHP functions)

APP_GameAction class (<gamename>.action.php)

function isArg( $argName )

Is this argument filled ?

function getArg( $argName, $argType, $mandatory=false, $default=NULL, $argTypeDetails=array(), $bCanFail=false )

Get script argument with the correct type

bCanFail means than a validation failure is possible (user input)

The main argType values are as follows.

define( 'AT_int', 0 );        //  an integer
define( 'AT_posint', 1 );     //  a positive integer 
define( 'AT_float', 2 );      //  a float
define( 'AT_email', 3 );      //  an email  
define( 'AT_url', 4 );        //  a URL
define( 'AT_bool', 5 );       //  1/0/true/false
define( 'AT_enum', 6 );       //  argTypeDetails list the possible values
define( 'AT_alphanum', 7 );   //  only 0-9a-zA-Z_ and space

Table class (<gamename>.game.php)

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)

function getPlayersNumber()

Returns the number of players playing at the table

function checkAction( $actionName, $bThrowException=true )

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

if "bThrowException" is set to "false", the function return false in case of failure instead of throwing and exception

function 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"

function getActivePlayerName()

Get the "active_player" name

function getCurrentPlayerId()

Get the "current_player". The current player is the one from which the action originated. It is not always the active player.

function getCurrentPlayerName()

Get the "current_player" name

function getCurrentPlayerColor()

Get the "current_player" color

function isCurrentPlayerZombie()

Check the "current_player" zombie status

function activeNextPlayer()

Make the next player active

function activePrevPlayer()

Make the previous player active

function giveExtraTime( $player_id, $specific_time=null )

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

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

function DbQuery( $sql )

Executes sql query on the database

function getCollectionFromDB( $sql, $bSingleValue=false )

Returns an associative array of rows for the sql query. First column must be a primary or alternate key. The resulting collection can be empty.

protected function getNonEmptyCollectionFromDB( $sql )

Idem, but raise an exception if the collection is empty

function getUniqueValueFromDB( $sql )

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

Raise an exception if more than 1 row is returned

function getObjectFromDB( $sql )

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

Raise an exception if the query return more than one row

function getNonEmptyObjectFromDB( $sql )

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

Exceptions you can throw

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.

Client side (Javascript functions)

this.slideToObjectPos( $('token_'+token.token_id), $('cp_background'), x_pix, y_pix, 10 ).play();

this.isSpectator

this.player_id

this.updateCounters(gamedatas.counters)

this.addTooltipToClass( 'cp_token_icon_color1', _('Green'), );

this.addEventToClass( "cp_token", "onclick", "onClickToken");

this.isCurrentPlayerActive()

this.checkAction( 'selectTokens' )

this.showMessage( _('You must select at least two tokens'), 'error' );

this.scoreCtrl[ notif.args.player_id ].incValue( notif.args.score_delta );

this.updateCounters(notif.args.counters);

this.ajaxcall( "/colorpop/colorpop/endgame.html", { }, this, function( result ) {} );