Your game state machine: states.inc.php

This file describes the state machine of your game (all the game states properties, and the transitions to get from one state to another).

Important: to understand the game state machine, it's recommended that you read this presentation first:

Focus on BGA game state machine

Overall structure

The machine states are described by a PHP associative array.

Example:

$machinestates = array(

    // The initial state. Please do not modify.
    1 => array(
        "name" => "gameSetup",
        "description" => clienttranslate("Game setup"),
        "type" => "manager",
        "action" => "stGameSetup",
        "transitions" => array( "" => 2 )
    ),
    
    // Note: ID=2 => your first state

    2 => array(
    		"name" => "playerTurn",
    		"description" => clienttranslate('${actplayer} must play a card or pass'),
    		"descriptionmyturn" => clienttranslate('${you} must play a card or pass'),
    		"type" => "activeplayer",
    		"possibleactions" => array( "playCard", "pass" ),
    		"transitions" => array( "playCard" => 2, "pass" => 2 )
    ),

Syntax

id

The keys determine game state IDs (in the example above: 1 and 2).

IDs must be positive integers.

ID=1 is reserved for the first game state and should not be used (and you must not modify it).

ID=99 is reserved for the last game state (end of the game) (and you must not modify it).

Note: you may use any ID, even an ID greater than 100. But you cannot use 1 or 99.

Note²: You must not use the same ID twice.

Note³: When a game is in prod and you change the ID of a state, all active games (including many turn based) will behave unpredictably.

name

(Mandatory)

The name of a game state is used to identify it in your game logic.

Several game states can share the same name; however, this is not recommended.

Warning! Do not put spaces in the name. This could cause unexpected problems in some cases.

PHP example:

// Get current game state
$state = $this->gamestate->state();
if( $state['name'] == 'myGameState' )
{
...
}

JS example:

        onEnteringState: function( stateName, args )
        {
            console.log( 'Entering state: '+stateName );
            
            switch( stateName )
            case 'myGameState':
            
                // Do some stuff at the beginning at this game state
                ....
                
                break;

type

(Mandatory)

You can use 3 types of game states:

• activeplayer (1 player is active and must play.)
• multipleactiveplayer (1..N players can be active and must play.)
• game (No player is active. This is a transitional state to do something automatic specified by the game rules.)

description

(Mandatory)

The description is the string that is displayed in the main action bar (top of the screen) when the state is active.

When a string is specified as a description, you must use "clienttranslate" in order for the string to be translated on the client side:

 		"description" => clienttranslate('${actplayer} must play a card or pass'),

In the description string, you can use ${actplayer} to refer to the active player.

You can also use custom arguments in your description. These custom arguments correspond to values returned by your "args" PHP method (see below "args" field).

Example of custom field:

In states.inc.php:
        "description" => clienttranslate('${actplayer} must choose ${nbr} identical energies'),
        "args" => "argMyArgumentMethod"

In mygame.game.php:
    function argMyArgumentMethod()
    {
        return array(
            'nbr' => 2  // In this case ${nbr} in the description will be replaced by "2"
        );    
    }

Note: You may specify an empty string ("") here if it never happens that the game remains in this state (i.e., if this state immediately jumps to another state when activated).

Note²: Usually, you specify a string for "activeplayer" and "multipleactiveplayer" game states, and you specify an empty string for "game" game states. BUT, if you are using synchronous notifications, the client can remain on a "game" type game state for a few seconds, and in this case it may be useful to display a description in the status bar while in this state.

descriptionmyturn

(Mandatory when the state type is "activeplayer" or "multipleactiveplayer")

"descriptionmyturn" has exactly the same role and properties as "description", except that this value is displayed to the current active player - or to all active players in case of a multipleactiveplayer game state.

In general, we have this situation:

        "description" => clienttranslate('${actplayer} can take some actions'),
        "descriptionmyturn" => clienttranslate('${you} can take some actions'),

Note: you can use ${you} in descriptionmyturn so the description will display "You" instead of the name of the player.

action

(Mandatory when the state type is "game.")

"action" specifies a PHP method to call when entering this game state.

Example:

In states.inc.php:
    28 => array(
        "name" => "startPlayerTurn",
        "description" => '',
        "type" => "game",
        "action" => "stStartPlayerTurn",

In mygame.game.php:
    function stStartPlayerTurn()
    {   
        // ... do something at the beginning of this game state

Usually, for a "game" state type, the action method is used to perform automatic functions specified by the rules (for example: check victory conditions, deal cards for a new round, go to the next player, etc.) and then jump to another game state.

Note: a BGA convention specifies that PHP methods called with "action" are prefixed by "st".

Note: this field CAN be used for player states to set something up; e.g., for multiplayer states, it can make all players active.

transitions

(Mandatory)

With "transitions" you specify which game state(s) you can jump to from a given game state.

Example:

    25 => array(
        "name" => "myGameState",
        "transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
        ....
    }

In the example above, if "myGameState" is the current active game state, I can jump to the game state with ID 27 or the game state with ID 39.

Example to jump to ID 27:

In mygame.game.php:
    $this->gamestate->nextState( "nextPlayer" );

Important: "nextPlayer" is the name of the transition, and NOT the name of the target game state. Multiple transitions can lead to the same game state.

Note: If there is only 1 transition, you may give it an empty name.

Example:

In states.inc.php:
    "transitions" => array( "" => 27 ),

In mygame.game.php:
    $this->gamestate->nextState(  );     // We don't need to specify a transition as there is only one here

possibleactions

(Mandatory when the game state is "activeplayer" or "multipleactiveplayer")

"possibleactions" defines the actions possible by the players in this game state, and ensures they cannot cannot perform actions that are not allowed in this state.

Example:

In states.game.php:
       	"possibleactions" => array( "playCard", "pass" ),

In mygame.game.php:
        function playCard( ...)
        {
             self::checkAction( "playCard" );    // Will fail if "playCard" is not specified in "possibleactions" in the current game state.

            ....

In mygame.js:
        playCard: function( ... )
        {
            if( this.checkAction( "playCard" ) ) // Will fail if "playCard" is not specified in "possibleactions" in the current game state.
            {  return ;   }

            ....

args

(optional)

Sometimes it happens that you need some information on the client side (i.e., for your game interface) only for a specific game state.

Example 1 : in Reversi, the list of possible moves during the playerTurn state. Example 2 : in Caylus, the number of remaining king's favors to choose in the state where the player is choosing a favor. Example 3 : in Can't Stop, the list of possible die combinations to be displayed to the active player so that he can choose from among them.

In such a situation, you can specify a method name as the « args » argument for your game state. This method must retrieve some piece of information about the game (example: for Reversi, the list of possible moves) and return it.

Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.

Let's see a complete example using args with « Reversi » game :

In states.inc.php, we specify an « args » argument for gamestate « playerTurn » :

    10 => array(
        "name" => "playerTurn",
		"description" => clienttranslate('${actplayer} must play a disc'),
		"descriptionmyturn" => clienttranslate('${you} must play a disc'),
        "type" => "activeplayer",
        "args" => "argPlayerTurn",    <================================== HERE
        "possibleactions" => array( 'playDisc' ),
        "transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
    ),

It corresponds to a « argPlayerTurn » method in our PHP code (reversi.game.php):

    function argPlayerTurn()   {
        return array(
            'possibleMoves' => self::getPossibleMoves()
        );
    }

Then, when we enter into the « playerTurn » game state on the client side, we can highlight the possible moves on the board using information returned by argPlayerTurn :

        onEnteringState: function( stateName, args )  {
           console.log( 'Entering state: '+stateName );
            
            switch( stateName )  {
            case 'playerTurn':
                this.updatePossibleMoves( args.args.possibleMoves );
                break;
            }
        },

Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).

Note: as a BGA convention, PHP methods called with "args" are prefixed by "arg" (example: argPlayerTurn).

Warning: the "args" method can be called before the "action" method so don't expect data modifications by the "action" method to be available in the "args" method!

Private info in args

By default, all data provided through this method are PUBLIC TO ALL PLAYERS. Please do not send any private data with this method, as a cheater could see it even it is not used explicitly by the game interface logic.

However, it is possible to specify that some data should be sent to specific players only.

Example 1: send information to active player(s) only:

    function argPlayerTurn()  {
        return array(
            '_private' => array(          // Using "_private" keyword, all data inside this array will be made private

                'active' => array(       // Using "active" keyword inside "_private", you select active player(s)
                    'somePrivateData' => self::getSomePrivateData()   // will be send only to active player(s)
                )
            ),

            'possibleMoves' => self::getPossibleMoves()          // will be sent to all players
        );
    }

Inside the js file, these variables will be available through `args._private`. (e.g. `args._private.somePrivateData` -- it is not `args._private.active.somePrivateData` nor is it `args.somePrivateData`)

Example 2: send information to a specific player (<specific_player_id>) only:

    function argPlayerTurn()  {
        return array(
            '_private' => array(          // Using "_private" keyword, all data inside this array will be made private

                <specific_player_id> => array(       // select one specific player by id
                    'somePrivateData' => self::getSomePrivateData()   // will be sent only to <specific_player_id>
                )
            ),

            'possibleMoves' => self::getPossibleMoves()          // will be sent to all players
        );
    }

IMPORTANT: in certain situations (example: "multipleactiveplayer" game state) these "private data" features can have a significant impact on performance. Please do not use if not needed.

updateGameProgression

(optional)

If you specify "updateGameProgression => true" in a game state, your "getGameProgression" PHP method will be called at the beginning of this game state - and thus the game progression of the game will be updated.

At least one of your game states (any one) must specify "updateGameProgression=>true".

Implementation Notes

Using Named Constants for States

Using numeric constants is prone to errors. If you want you can declare state constants as PHP named constants. This way you can use them in the states file and in game.php as well

EXAMPLE:

states.inc.php:

// define contants for state ids
if (!defined('STATE_END_GAME')) { // ensure this block is only invoked once, since it is included multiple times
   define("STATE_PLAYER_TURN", 2);
   define("STATE_GAME_TURN", 3);
   define("STATE_PLAYER_TURN_CUBES", 4);
   define("STATE_END_GAME", 99);
}
 
$machinestates = array(

   ...

    STATE_PLAYER_TURN => array(
    		"name" => "playerTurn",
    		"description" => clienttranslate('${actplayer} must select an Action Space or Pass'),
    		"descriptionmyturn" => clienttranslate('${you} must select an Action Space or Pass'),
    		"type" => "activeplayer",
                "args" => 'arg_playerTurn',
    		"possibleactions" => array( "selectWorkerAction", "pass" ),
    		"transitions" => array( 
    		        "loopback" => STATE_PLAYER_TURN,
    		        "playCubes" => STATE_PLAYER_TURN_CUBES,
    		        "pass" => STATE_GAME_TURN )
    ),

Example of multipleactiveplayer state

This is an example of a multipleactiveplayer state:

 2 =>  array (
   'name' => 'playerTurnSetup',
   'type' => 'multipleactiveplayer',
   'description' => clienttranslate('Other players must choose one Objective'),
   'descriptionmyturn' => clienttranslate('${you} must choose one Objective card to keep'),
   'possibleactions' =>     array ('playKeep' ),
   'transitions' =>    array (       'next' => 5, 'loopback' => 2, ),
   'action' => 'st_MultiPlayerInit',
   'args' => 'arg_playerTurnSetup',
 ),

In game.php:

   // this will make all players multiactive just before entering the state
   function st_MultiPlayerInit() {
       $this->gamestate->setAllPlayersMultiactive();
   }

When ending the player action, instead of a state transition, deactivate player.

   function action_playKeep($cardId) {
       $this->checkAction('playKeep');
       $player_id = $this->getCurrentPlayerId(); // CURRENT!!! not active
       ... // some logic here
       $this->gamestate->setPlayerNonMultiactive($player_id, 'next'); // deactivate player; if none left, transition to 'next' state
   }