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

Your game state machine: states.inc.php: Difference between revisions

From Board Game Arena
Jump to navigation Jump to search
(10 intermediate revisions by the same user not shown)
Line 138: Line 138:
=== descriptionmyturn ===
=== descriptionmyturn ===


('''Mandatory''' for "activeplayer" and "multipleactiveplayer" game states type)
('''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.
"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.
Line 180: Line 180:
=== transitions ===
=== transitions ===


(mandatory)
('''Mandatory''')


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


Example:
Example:
Line 193: Line 193:
</pre>
</pre>


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.
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:
Example to jump to ID 27:
Line 201: Line 201:
</pre>
</pre>


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.
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 you have only 1 transition, you may give it an empty name.
Note: If there is only 1 transition, you may give it an empty name.


Example:
Example:
Line 213: Line 213:
     $this->gamestate->nextState(  );    // We don't need to specify a transition as there is only one here
     $this->gamestate->nextState(  );    // We don't need to specify a transition as there is only one here
</pre>
</pre>


=== possibleactions ===
=== possibleactions ===


(mandatory for "activeplayer" and "multipleactiveplayer" game states)
('''Mandatory''' when the game state is "activeplayer" or "multipleactiveplayer")


"possibleactions" defines the actions possible by the players at this game state.
"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.
 
By defining "possibleactions", you make sure players can't do actions that they are not allowed to do at this game states.


Example:
Example:
Line 232: Line 229:
         function playCard( ...)
         function playCard( ...)
         {
         {
             self::checkAction( "playCard" );    // Will failed if "playCard" is not specified in "possibleactions" in current game state.
             self::checkAction( "playCard" );    // Will fail if "playCard" is not specified in "possibleactions" in the current game state.


             ....
             ....
Line 239: Line 236:
         playCard: function( ... )
         playCard: function( ... )
         {
         {
             if( this.checkAction( "playCard" ) ) // Will failed if "playCard" is not specified in "possibleactions" in current game state.
             if( this.checkAction( "playCard" ) ) // Will fail if "playCard" is not specified in "possibleactions" in the current game state.
             {  return ;  }
             {  return ;  }


Line 250: Line 247:
(optional)
(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.
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 : for Reversi, the list of possible moves during playerTurn state.
Example 1 : in ''Reversi'', the list of possible moves during the 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 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 combination to be displayed to the active player in order he can choose among them.
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 get some piece of information about the game (ex : for Reversi, the possible moves) and return 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.
Thus, this data can be transmitted to the clients and used by the clients to display it. It should always be an associative array.
Line 262: Line 259:
Let's see a complete example using args with « Reversi » game :
Let's see a complete example using args with « Reversi » game :


In states.inc.php, we specify some « args » argument for gamestate « playerTurn » :
In states.inc.php, we specify an « args » argument for gamestate « playerTurn » :
<pre>
<pre>
     10 => array(
     10 => array(
Line 284: Line 281:
</pre>
</pre>


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 :
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 :


<pre>
<pre>
Line 300: Line 297:
Note: you can also use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn" (see above).
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).
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!
'''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 ====
==== 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.
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:
However, it is possible to specify that some data should be sent to specific players only.


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


<pre>
<pre>
Line 322: Line 319:
             ),
             ),


             'possibleMoves' => self::getPossibleMoves()          // will be send to all players
             'possibleMoves' => self::getPossibleMoves()          // will be sent to all players
         );
         );
     }
     }
Line 329: Line 326:
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`)
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:
Example 2: send information to a specific player (<specific_player_id>) only:


<pre>
<pre>
Line 336: Line 333:
             '_private' => array(          // Using "_private" keyword, all data inside this array will be made private
             '_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
                 <specific_player_id> => array(      // select one specific player by id
                     'somePrivateData' => self::getSomePrivateData()  // will be send only to <specific_player_id>
                     'somePrivateData' => self::getSomePrivateData()  // will be sent only to <specific_player_id>
                 )
                 )
             ),
             ),


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


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.
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 ===
=== updateGameProgression ===
Line 352: Line 349:
(optional)
(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.
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.
''At least one'' of your game states (any one) must specify "updateGameProgression=>true".


== Implementation Notes ==
== Implementation Notes ==
Line 361: Line 358:
=== Using Named Constants for States ===
=== 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
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 states file and game.php as well
use them in the states file and in game.php as well
 
EXAMPLE:


states.inc.php:
states.inc.php:
Line 368: Line 367:
<pre>
<pre>
// define contants for state ids
// define contants for state ids
if (!defined('STATE_END_GAME')) { // guard since this included multiple times
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_PLAYER_TURN", 2);
   define("STATE_GAME_TURN", 3);
   define("STATE_GAME_TURN", 3);
Line 395: Line 394:
=== Example of multipleactiveplayer state ===
=== Example of multipleactiveplayer state ===


This is example of multipleactiveplayer state
This is an example of a multipleactiveplayer state:


   2 =>  array (
   2 =>  array (
Line 409: Line 408:


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


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


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

Revision as of 18:33, 15 September 2018

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
   }