Your game state machine: states.inc.php

This file describes the game states 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, the best is to read this presentation first:

Focus on BGA game state machine

Overall structure

The machine states is 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 states ID (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 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 the string can be translate 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 (ie: if this state immediately jump 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 remains few seconds on a "game" type game state, and in this case this may be useful to display a description in the status bar during this state.

descriptionmyturn

(mandatory for "activeplayer" and "multipleactiveplayer" game states type)

"descriptionmyturn" has exactly the same role and properties than "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 description my turn in order the description can display "You" instead of the name of the player.

action

(mandatory for "game" game state type)

"action" specify a PHP method to call when entering into 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 "game" game state type, the action method is used to do some automatic stuff specified by the rules (ex: check victory conditions, deal cards for a new round, go to the next player...) and then jump to another game state.

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

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

transitions

(mandatory)

With "transition" you specify in which game state you can jump 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 game state with ID 27, or 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. Several transitions can lead to the same game state.

Note: if you have 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 for "activeplayer" and "multipleactiveplayer" game states)

"possibleactions" defines the actions possible by the players at this game state.

By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.

Example:

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

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

            ....

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

            ....

args

(optional)

From time to time, it happens that you need some information on the client side (ie : for your game interface) only for a specific game state.

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

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

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 some « 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 « 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" (ex: 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 infos 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.

This is although possible to specify that some data should be sent to some specific players only:

Example 1: send an 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 send 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 an 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(       // you select one specific player with its id
                    'somePrivateData' => self::getSomePrivateData()   // will be send only to <specific_player_id>
                )
            ),

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

IMPORTANT: in certain situation (ex: multipleactiveplayer game state) these "private data" features can have a big performance impact. 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 state (any of them) must specify updateGameProgression=>true.

Implementation Notes

Using Named Constants for States

Using numeric constant is prone to errors, if you want you can declare state constants as PHP named constants, this way you can use them in states file and game.php as well

states.inc.php:

// define contants for state ids
if (!defined('STATE_END_GAME')) { // guard since this 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 example of 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 player multiactive just before entering the state
   function st_MultiPlayerInit() {
       $this->gamestate->setAllPlayersMultiactive();
   }

When ending the player action instead of 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 non left transition to 'next' state
   }