This is a documentation for Board Game Arena: play board games online !

„Main game logic: yourgamename.game.php” változatai közötti eltérés

Innen: Board Game Arena
Ugrás a navigációhoz Ugrás a kereséshez
Nincs szerkesztési összefoglaló
 
(20 közbenső módosítás, amit 2 másik szerkesztő végzett, nincs mutatva)
1. sor: 1. sor:
=== Table class (<gamename>.game.php) ===


; function _( $text )
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.
: Transparent function, used to mark strings to be translated on the server side (ex: error message)
 
; function clienttranslate( $string )
== File Structure ==
: Transparent function: used to mark string to be translated on client side (ex: notification message)
 
; function getPlayersNumber()
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
: Returns the number of players playing at the table
; function checkAction( $actionName, $bThrowException=true )
: Note: doesn't work in setupNewGame so use count($players) instead
: 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
; getActivePlayerId()
; function getActivePlayerId()
: Get the "active_player", whatever what is the current state type.
: 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: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
; function getActivePlayerName()
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.
 
; getActivePlayerName()
: Get the "active_player" name
: Get the "active_player" name
; function getCurrentPlayerId()
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.
: Get the "current_player". The current player is the one from which the action originated. It is not always the active player.
 
; function getCurrentPlayerName()
; 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
: Get the "current_player" name
; function getCurrentPlayerColor()
: Be careful using this method (see above).
 
; getCurrentPlayerColor()
: Get the "current_player" color
: Get the "current_player" color
; function isCurrentPlayerZombie()
: Be careful using this method (see above).
: Check the "current_player" zombie status
 
; 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:
<pre>
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 )
)
</pre>
Example 2:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );
 
Result:
array(
1234 => 'myuser0',
1235 => 'myuser1'
)
 
</pre>
 
; 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:
<pre>
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
)
</pre>
 
; 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:
<pre>
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 )
)
</pre>
Example 2:
<pre>
self::getObjectListFromDB( "SELECT player_id id, player_name name FROM player", true );
 
Result:
array(
'myuser0',
'myuser1'
)
 
</pre>
 
; 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.
 
<pre>
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'
)
 
</pre>
 
 
; 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.
 
== Use globals ==
 
Sometimes, you have to keep a single integer value that is global to your game, and you don't want to create a DB table specifically for it.
 
Using a BGA framework "global", you can do such a thing. Your value will be stored in the "global" table in database, and you can access it with simple methods.
 
'''initGameStateLabels'''
 
This method is located at the beginning of your game logic. This is the place you defines the globals used in your game logic, by assigning them IDs.
 
You can define up to 89 globals, with IDs from 10 to 89. You must NOT use globals outside this range as globals are used by other components of the framework.
 
<pre>
        self::initGameStateLabels( array(
                "my_first_global_variable" => 10,
                "my_second_global_variable" => 11
        ) );
</pre>
 
'''setGameStateInitialValue( $value_label, $value_value )'''
 
Init your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.
 
'''getGameStateValue( $value_label )'''
 
Retrieve the current value of a global.
 
'''setGameStateValue( $value_label, $value_value )'''
 
Set the current value of a global.
 
'''incGameStateValue( $value_label, $increment )'''
 
Increment the current value of a global. If increment is negative, decrement the value of the global.
 
Return the final value of the global.
 
== 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()
; function activeNextPlayer()
: Make the next player active
: 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()
; function activePrevPlayer()
: Make the previous player active
: Make the previous player active (in the natural player order).
; function giveExtraTime( $player_id, $specific_time=null )
: Note: you CANT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.
: Give standard extra time to this player (standard extra time is a game option)
 
== Players turn order ==
 
'''createNextPlayerTable( $players, $bLoop=true )'''
 
Return an associative array which associate each player with the next player around the table.
 
In addition, key 0 is associated to the first player to play.
 
Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:
<pre>
  $players = self::loadPlayersBasicInfos()
  $nextPlayers = createNextPlayerTable( $players );          // return array( 1 => 2, 2 => 3, 3 => 1, 0 => 1 );
  $nextPlayers = createNextPlayerTable( $players, false );    // return array( 1 => 2, 2 => 3, 0 => 1 );
</pre>
 
== Notify players ==
 
== Game statistics ==
 
; function initStat( $table_or_player, $name, $value, $player_id=null )
; function initStat( $table_or_player, $name, $value, $player_id=null )
: Create a statistic entry for the specified statistics with a default value
: Create a statistic entry for the specified statistics with a default value
36. sor: 264. sor:
; function incStat( $delta, $name, $player_id = null )
; function incStat( $delta, $name, $player_id = null )
: Increment (or decrement) specified value
: 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 ===
 
== Translations ==
 
See [[Translations]]
 
== 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)
; throw new BgaUserException ( $error_message)

A lap jelenlegi, 2013. január 11., 17:03-kori változata

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.

Use globals

Sometimes, you have to keep a single integer value that is global to your game, and you don't want to create a DB table specifically for it.

Using a BGA framework "global", you can do such a thing. Your value will be stored in the "global" table in database, and you can access it with simple methods.

initGameStateLabels

This method is located at the beginning of your game logic. This is the place you defines the globals used in your game logic, by assigning them IDs.

You can define up to 89 globals, with IDs from 10 to 89. You must NOT use globals outside this range as globals are used by other components of the framework.

        self::initGameStateLabels( array( 
                "my_first_global_variable" => 10,
                "my_second_global_variable" => 11
        ) );

setGameStateInitialValue( $value_label, $value_value )

Init your global value. Must be called before any use of your global, so you should call this method from your "setupNewGame" method.

getGameStateValue( $value_label )

Retrieve the current value of a global.

setGameStateValue( $value_label, $value_value )

Set the current value of a global.

incGameStateValue( $value_label, $increment )

Increment the current value of a global. If increment is negative, decrement the value of the global.

Return the final value of the global.

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.

Players turn order

createNextPlayerTable( $players, $bLoop=true )

Return an associative array which associate each player with the next player around the table.

In addition, key 0 is associated to the first player to play.

Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:

  $players = self::loadPlayersBasicInfos()
  $nextPlayers = createNextPlayerTable( $players );           // return array( 1 => 2, 2 => 3, 3 => 1, 0 => 1 );
  $nextPlayers = createNextPlayerTable( $players, false );    // return array( 1 => 2, 2 => 3, 0 => 1 );
 

Notify players

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

See Translations

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.