Board Game Arena - Кориснички доприноси [sr]

Game options and preferences: gameoptions.inc.php

2018-09-24T08:41:22Z

Een:

In this file, you can define your game options (= game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

'''IMPORTANT:''' after you edited this file in your SFTP folder you have to go to the control panel and press "Reload game options configuration" for your changes to take effect.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ( array (
...
"my_first_game_variant" => 100,
) );

That is how you access them during runtime:

$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandartory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandartory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandartory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''tmdisplay''' - String representation of the option visible in the table description, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing when Off.
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''premium''' - Option can be only used by premium members
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''otheroption'' condition ensures another option is set to this given value. Framework options - 201 - ELO OFF.
* '''startcondition''' - checks the conditions before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given value. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down

<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
)
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
'disable' => true
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
'disable' => true
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
)
)
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the body tag. So you can use different css styling for the preference.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

Game options and preferences: gameoptions.inc.php

2018-09-24T08:39:49Z

Een:

In this file, you can define your game options (= game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

IMPORTANT: After you edited and deployed this file you have to go to control panel and press "Reload game options configuration"

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ( array (
...
"my_first_game_variant" => 100,
) );

That is how you access them during runtime:

$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandartory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandartory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandartory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''tmdisplay''' - String representation of the option visible in the table description, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing when Off.
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''premium''' - Option can be only used by premium members
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''otheroption'' condition ensures another option is set to this given value. Framework options - 201 - ELO OFF.
* '''startcondition''' - checks the conditions before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given value. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down

<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
)
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
'disable' => true
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
'disable' => true
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
)
)
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the body tag. So you can use different css styling for the preference.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

Game options and preferences: gameoptions.inc.php

2018-09-24T08:39:33Z

Een: /* Game Options */

In this file, you can define your game options (= game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ( array (
...
"my_first_game_variant" => 100,
) );

That is how you access them during runtime:

$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandartory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandartory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandartory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''tmdisplay''' - String representation of the option visible in the table description, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing when Off.
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''premium''' - Option can be only used by premium members
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''otheroption'' condition ensures another option is set to this given value. Framework options - 201 - ELO OFF.
* '''startcondition''' - checks the conditions before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given value. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down

<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
)
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
'disable' => true
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
'disable' => true
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
)
)
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the body tag. So you can use different css styling for the preference.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

Game options and preferences: gameoptions.inc.php

2018-09-24T08:37:36Z

Een: /* User Preferences */

In this file, you can define your game options (= game variants) and user preferences.

Note: If your game has no variants or preferences, you don't have to modify this file.

== Game Options ==

Game options is something selected by table creator and usually correspond to game variant, for example if game includes expansion or certain special rule.

These variants defined in gameoptions.inc.php as variable
$game_options = array(...); // exactly named that

Each option is pair number => 'option description array'.

All options defined in this file should have a corresponding "game state label" with the same ID (see "initGameStateLabels" in yourgame.game.php)

self::initGameStateLabels ( array (
...
"my_first_game_variant" => 100,
) );

That is how you access them during runtime:

$this->gamestate->table_globals[100]

The following are the parameters of option description array:
* '''name''' - '''mandartory'''. The name of the option visible for table creator. Value must be wrapped in totranslate function.
* '''values''' - '''mandartory'''. The array (map) of values with additional parameters per value.
** '''name''' - '''mandartory'''. String representation of the numeric value visible to table creator. Value must be wrapped in totranslate function.
** '''tmdisplay''' - String representation of the option visible in the table description, usually if variant "names" are On and Off, but the description would be same as option name when On, and nothing when Off.
** '''nobeginner''' - Set to true if not recommended for begginers
** '''beta''' - Option in beta stage on development
** '''premium''' - Option can be only used by premium members
* '''displaycondition''' - checks the conditions before displaying the option for selection. All conditions must be true for the option to display. Supported condition types:
** ''otheroption'' condition ensures another option is set to this given value. Framework options - 201 - ELO OFF.
* '''startcondition''' - checks the conditions before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game. Supported condition types:
** ''minplayers'' condition ensures at least this many players
** ''maxplayers'' conditions ensure at most this many players
** ''otheroption'' conditions ensure another option is set to this given value. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down

<pre>
$game_options = array(
100 => array(
'name' => totranslate('my game option'),
'values' => array(
// A simple value for this option:
1 => array(
'name' => totranslate('option 1')
),

// A simple value for this option.
// If this value is chosen, the value of "tmdisplay" is displayed in the game lobby
2 => array(
'name' => totranslate('option 2'),
'tmdisplay' => totranslate('option 2')
),

// Another value, with other options:
// beta=true => this option is in beta version right now.
// nobeginner=true => this option is not recommended for beginners
3 => array(
'name' => totranslate('option 3'),
'beta' => true,
'nobeginner' => true
),
)
),

101 => array(
'name' => totranslate('Draft variant'),
'values' => array(
1 => array(
'name' => totranslate('No draft')
),
2 => array(
'name' => totranslate('Draft'),
'tmdisplay' => totranslate('Draft'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100, // Game specific option defined in the same array above
'value' => array(2, 3, 4)
),
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1 // 1 if OFF
)
),

'startcondition' => array(
1 => array(),
2 => array(
array(
'type' => 'maxplayers',
'value' => 3,
'message' => totranslate('Draft option is available for 3 players maximum.')
)
),
),
'disable' => true
),

102 => array(
'name' => totranslate('Takeovers'),
'values' => array(
2 => array(
'name' => totranslate('No takeover')
),
1 => array(
'name' => totranslate('Allow takeovers'),
'tmdisplay' => totranslate('Takeovers'),
'premium' => true,
'nobeginner' => true
),
),
'displaycondition' => array( // Note: do not display this option unless these conditions are met
array(
'type' => 'otheroption',
'id' => 100,
'value' => array(3, 4)
)
),
'startcondition' => array(
2 => array(),
1 => array(
array(
'type' => 'maxplayers',
'value' => 2,
'message' => totranslate('Rebel vs Imperium Takeover Scenario is available for 2 players only.')
)
),
),
'disable' => true
)
);
</pre>

Example of option that condition on ELO off

<pre>
$game_options = array(

100 => array(
'name' => totranslate('Learning Game (No Research)'),
'values' => array(

1 => array( 'name' => totranslate('Off'), 'tmdisplay' => totranslate('') ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Learning Game') ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroption',
'id' => 201, // ELO OFF hardcoded framework option
'value' => 1, // 1 if OFF

)
),
'notdisplayedmessage' => totranslate('Learning variant available only with ELO off')
),

);
</pre>

Example of using condition on your own option
<pre>
102 => array(
'name' => totranslate('Scenarios'),
'values' => array(
1 => array( 'name' => totranslate('Off'),
'nobeginner' => false ),
2 => array( 'name' => totranslate('On'), 'tmdisplay' => totranslate('Scenarios'),
'nobeginner' => true ),

),
'displaycondition' => array(
// Note: do not display this option unless these conditions are met
array( 'type' => 'otheroptionisnot',
'id' => 100, // learning variant
'value' => 2, // 1 if OFF,2 is ON

)
),
'notdisplayedmessage' => totranslate('Scenarios variant is not available if Learning variant is chosen')
),
</pre>

IMPORTANT: After you edited and deployed this file you have to go to control panel and press "Reload game options configuration"

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.

<pre>
$game_preferences = array(
100 => array(
'name' => totranslate('Notation style'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Classic' ), 'cssPref' => 'notation_classic' ),
2 => array( 'name' => totranslate( 'Tournament' ), 'cssPref' => 'notation_tournament' )
)
)
);
</pre>

There is two ways to check/apply this. In java Script

if (this.prefs[100].value == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref specified it will be applied to the body tag. So you can use different css styling for the preference.

As user you have to select them from the Gear menu when game is started. On studio only user0 will have it actually working (bug?).

Practical debugging

2018-08-02T15:28:05Z

Een: /* Get the database matching a bug report */

This page gives you practical tips to debug your game during the development. Don't hesitate to share with us your difficulties in order we can improve this section.

== Tools ==

To work on BGA Studio, we recommend you to use [http://www.google.com/chrome Google Chrome] as it's the current fastest browser for BGA platform, and it's available in all OS.

Another reason to use Chrome is that it embed all tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").

A good practice is to use a second browser to develop the game, in order to check that your game is working fine on this browser too.

To debug with Firefox browser, we advise you to use these 2 extensions:
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developper]

To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...

== General tip for debugging ==

In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

You can save up to 3 different states.

== Debugging my game when it cannot start ==

If your game don't start because of an error, you are probably in one of these situations:
* There is a SQL error in your dbmodel.sql file.
* You have a syntax error in your PHP file.
* Your PHP "setup" - or any method used during the game initial states - generates an exception.

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
More cases of why game can't start described in [[Troubleshooting]] page.

== Debugging my PHP game logic (or my view) ==

Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:

* At first, I make sure that I can reproduce the needed game situation in one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be commited to the database, anyway.
* Then, I use '''var_dump''' function to dump PHP variables and check what's wrong, until it works.

Example:
<pre>

// (...my code to debug)

var_dump( $my_variable );
die('ok');

// (...my code to debug)

</pre>

=== Add traces to your code ===

You can use the following functions in your game to add server side logging:

'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

Check [[Studio logs]] for more details on how to access your logs.

This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.

Only the error log level will appear in production. This level should be used only for critical problems.
Other levels will show only in the development environment and can be used as you see fit.

== Debugging my HTML/CSS layout ==

Situation examples:
* why my game element doesn't show up in the interface?
* why my CSS property hasn't been applied to this element?
* why this game element is displayed at this position?

A first useful tip when an element does not show up in the interface is to give it a red background:
<pre>
#my_element {
... some CSS definitions ...
background-color: red;
}
</pre>

This way, you know if the element is not visible because of some of its CSS property or because of anything else.

Another tip: sometimes, you change a CSS property with no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.

Using Chrome "Elements" tab (thre first one), you can:
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.
* Using the "magnifying glass", you can click on any part of your game interface and check it's HTML code and associated CSS styles.
* You can even modify directly some CSS property and see if how it looks immediately on the game interface.

== Debugging my Javascript game interface logic ==

Compare to PHP debugging, Javascript debugging can sometimes be painful.

Here's are some tips to make your life easier while developing and debugging Javascript:

=== Do complex things on PHP side ===

The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Then, do it on PHP, and transfer the result to your client interface using the "args" game state property.

Note: check Reversi example for this.

=== Add traces in your code ===

You can use the following:

'''console.log( variable_to_inspect )'''

It will give you the object structure of the variable in the Javascript console, without blocking the execution.

It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.

'''alert( variable_to_inspect )'''

It will popup what you wish and pause the execution until you click ok.

This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

=== Use Debugger ===

Modern browsers also allow to put breakpoints in your js code.

That will stop code execution on that line and will launch the JavaScript debugger

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table on the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
* Click on the "Go to game database" button
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.
* Then you should be able to play with the same state of the game as when the report was created in production.

Practical debugging

2018-08-02T15:21:43Z

Een: /* Get the database matching a bug report */

This page gives you practical tips to debug your game during the development. Don't hesitate to share with us your difficulties in order we can improve this section.

== Tools ==

To work on BGA Studio, we recommend you to use [http://www.google.com/chrome Google Chrome] as it's the current fastest browser for BGA platform, and it's available in all OS.

Another reason to use Chrome is that it embed all tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").

A good practice is to use a second browser to develop the game, in order to check that your game is working fine on this browser too.

To debug with Firefox browser, we advise you to use these 2 extensions:
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developper]

To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...

== General tip for debugging ==

In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

You can save up to 3 different states.

== Debugging my game when it cannot start ==

If your game don't start because of an error, you are probably in one of these situations:
* There is a SQL error in your dbmodel.sql file.
* You have a syntax error in your PHP file.
* Your PHP "setup" - or any method used during the game initial states - generates an exception.

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
More cases of why game can't start described in [[Troubleshooting]] page.

== Debugging my PHP game logic (or my view) ==

Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:

* At first, I make sure that I can reproduce the needed game situation in one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be commited to the database, anyway.
* Then, I use '''var_dump''' function to dump PHP variables and check what's wrong, until it works.

Example:
<pre>

// (...my code to debug)

var_dump( $my_variable );
die('ok');

// (...my code to debug)

</pre>

=== Add traces to your code ===

You can use the following functions in your game to add server side logging:

'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

Check [[Studio logs]] for more details on how to access your logs.

This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.

Only the error log level will appear in production. This level should be used only for critical problems.
Other levels will show only in the development environment and can be used as you see fit.

== Debugging my HTML/CSS layout ==

Situation examples:
* why my game element doesn't show up in the interface?
* why my CSS property hasn't been applied to this element?
* why this game element is displayed at this position?

A first useful tip when an element does not show up in the interface is to give it a red background:
<pre>
#my_element {
... some CSS definitions ...
background-color: red;
}
</pre>

This way, you know if the element is not visible because of some of its CSS property or because of anything else.

Another tip: sometimes, you change a CSS property with no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.

Using Chrome "Elements" tab (thre first one), you can:
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.
* Using the "magnifying glass", you can click on any part of your game interface and check it's HTML code and associated CSS styles.
* You can even modify directly some CSS property and see if how it looks immediately on the game interface.

== Debugging my Javascript game interface logic ==

Compare to PHP debugging, Javascript debugging can sometimes be painful.

Here's are some tips to make your life easier while developing and debugging Javascript:

=== Do complex things on PHP side ===

The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Then, do it on PHP, and transfer the result to your client interface using the "args" game state property.

Note: check Reversi example for this.

=== Add traces in your code ===

You can use the following:

'''console.log( variable_to_inspect )'''

It will give you the object structure of the variable in the Javascript console, without blocking the execution.

It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.

'''alert( variable_to_inspect )'''

It will popup what you wish and pause the execution until you click ok.

This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

=== Use Debugger ===

Modern browsers also allow to put breakpoints in your js code.

That will stop code execution on that line and will launch the JavaScript debugger

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table on the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage your project" page for this game (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
* Click on the "Go to game database button"
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* Then you should be able to play with the same state of the game as when the report was created in production.

Practical debugging

2018-08-02T15:10:27Z

Een: Retrieve database state

This page gives you practical tips to debug your game during the development. Don't hesitate to share with us your difficulties in order we can improve this section.

== Tools ==

To work on BGA Studio, we recommend you to use [http://www.google.com/chrome Google Chrome] as it's the current fastest browser for BGA platform, and it's available in all OS.

Another reason to use Chrome is that it embed all tools you need to work on BGA Studio. You can see them by pressing "F12" or from the menu ("Tools > Development tools").

A good practice is to use a second browser to develop the game, in order to check that your game is working fine on this browser too.

To debug with Firefox browser, we advise you to use these 2 extensions:
* [https://addons.mozilla.org/firefox/addon/firebug/ Firebug]
* [https://addons.mozilla.org/firefox/addon/web-developer/ Web developper]

To debug with other browsers (IE, Edge, Opera), we advise you to use one of the most recent versions. Latest versions of the browser will likely have better development tools than the previous ones...

== General tip for debugging ==

In general for debugging, think of using the '[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]] state' functionality. It enables you to save the state of your game just before the issue you are investigating, then come back to that point with one click as many times as needed to understand what is going wrong.

You can save up to 3 different states.

== Debugging my game when it cannot start ==

If your game don't start because of an error, you are probably in one of these situations:
* There is a SQL error in your dbmodel.sql file.
* You have a syntax error in your PHP file.
* Your PHP "setup" - or any method used during the game initial states - generates an exception.

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
More cases of why game can't start described in [[Troubleshooting]] page.

== Debugging my PHP game logic (or my view) ==

Most of the time, debugging PHP is quite easy. Here's what I do when I want to develop/debug some game logic that is triggered by some game action:

* At first, I make sure that I can reproduce the needed game situation in one click. To do this, I use the "[[Tools_and_tips_of_BGA_Studio#Save_.26_restore_state|save & restore]]" function.
* Another possibility for this is to place a '''die('ok');''' PHP statement right after the PHP I am developing/debugging. This way, I make sure that every request will fail and then nothing will be commited to the database, anyway.
* Then, I use '''var_dump''' function to dump PHP variables and check what's wrong, until it works.

Example:
<pre>

// (...my code to debug)

var_dump( $my_variable );
die('ok');

// (...my code to debug)

</pre>

=== Add traces to your code ===

You can use the following functions in your game to add server side logging:

'''self::dump( 'name_of_variable', $variable );''' // dump variable, like var_dump but in the log debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::debug( $message );''' // debug level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::trace( $message );''' // info level logging, goes to [[Studio_logs|BGA request&SQL logs]]

'''self::warn( $message );''' // warning level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

'''self::error( $message );''' // error level logging, goes to [[Studio_logs#BGA_unexpected_exceptions_logs|BGA unexpected exceptions log]]

Check [[Studio logs]] for more details on how to access your logs.

This can be useful when you need to follow the flow of your code and not just stop it to see how it goes at some point.

Only the error log level will appear in production. This level should be used only for critical problems.
Other levels will show only in the development environment and can be used as you see fit.

== Debugging my HTML/CSS layout ==

Situation examples:
* why my game element doesn't show up in the interface?
* why my CSS property hasn't been applied to this element?
* why this game element is displayed at this position?

A first useful tip when an element does not show up in the interface is to give it a red background:
<pre>
#my_element {
... some CSS definitions ...
background-color: red;
}
</pre>

This way, you know if the element is not visible because of some of its CSS property or because of anything else.

Another tip: sometimes, you change a CSS property with no visible effect on your interface. In that case, add a "display:none" property. If your element does not disappear, the bug probably comes from your CSS selector and not from your CSS property.

Using Chrome "Elements" tab (thre first one), you can:
* See the CURRENT HTML of your page. Remember that the classical "show page source" is inefficient with BGA as you are modifying the page source with your Javascript code.
* Using the "magnifying glass", you can click on any part of your game interface and check it's HTML code and associated CSS styles.
* You can even modify directly some CSS property and see if how it looks immediately on the game interface.

== Debugging my Javascript game interface logic ==

Compare to PHP debugging, Javascript debugging can sometimes be painful.

Here's are some tips to make your life easier while developing and debugging Javascript:

=== Do complex things on PHP side ===

The most frequent case is the following: you want to compute possible moves in a game situation. Doing it in Javascript is a nightmare. Then, do it on PHP, and transfer the result to your client interface using the "args" game state property.

Note: check Reversi example for this.

=== Add traces in your code ===

You can use the following:

'''console.log( variable_to_inspect )'''

It will give you the object structure of the variable in the Javascript console, without blocking the execution.

It's often a good idea to precede this call with a console.log( '### HERE ###' ); to find more easily the appropriate line in the console log.

'''alert( variable_to_inspect )'''

It will popup what you wish and pause the execution until you click ok.

This won't be useful for complex structures, only native types will get plainly displayed. But this is sometimes useful just with messages to make sure which way the execution goes.

=== Use Debugger ===

Modern browsers also allow to put breakpoints in your js code.

That will stop code execution on that line and will launch the JavaScript debugger

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table on the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage your project" page for this game (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
* Click on the "Go to game database button"
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the studio by hovering over the red arrow in the player panels.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* Then you should be able to play with the same state of the game as when the report was created in production.

Game interface logic: yourgamename.js

2018-05-26T09:12:48Z

Een: /* Dojo framework */

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== 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:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: this is not a function, its a variable.
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

== Shrinksafe minification ==

For performance reasons, when deploying a game the js code is minified using Shrinksafe (based on ECMASCRIPT version 3). Some advanced syntax may not be compatible with this process. In particular:
* you should not use reserved keywords from the javascript language as variables
* you should not declare default argument values in function declaration, the following syntax is invalid for Shriksafe: function myFunc(requiredArg, optionalArg = 'defaultValue') {}

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node, duration, delay )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

<pre>
onUpdateActionButtons: function( stateName, args ) {

if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

'''confirmationDialog( message, yesHandler, noHandler )'''

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score );
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble( anchor_id, text, delay, duration, custom_class )
</pre>

delay in milliseconds is optional (default 0)

duration in milliseconds is optional (default 3000)

custom_class is optional, if you need to override the default bubble style

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Game interface logic: yourgamename.js

2018-05-26T09:11:59Z

Een: /* Dojo framework */ Version ecmascript

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== 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:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: this is not a function, its a variable.
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

For performance reasons, when deploying a game the js code is minified using Shrinksafe (based on ECMASCRIPT version 3). Some advanced syntax may not be compatible with this process. In particular:
* you should not use reserved keywords from the javascript language as variables
* you should not declare default argument values in function declaration, the following syntax is invalid for Shriksafe: function myFunc(requiredArg, optionalArg = 'defaultValue') {}

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node, duration, delay )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

<pre>
onUpdateActionButtons: function( stateName, args ) {

if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

'''confirmationDialog( message, yesHandler, noHandler )'''

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score );
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble( anchor_id, text, delay, duration, custom_class )
</pre>

delay in milliseconds is optional (default 0)

duration in milliseconds is optional (default 3000)

custom_class is optional, if you need to override the default bubble style

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

SandboxScripts

2018-05-25T09:03:30Z

Een: /* Trigger most common game actions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

== Examples/Tutorials ==

In addition to the projects you will create, you have readonly access in the sandbox to two example projects: "linesofaction" is an abstract and "apocalypseazcc" is a card game.

These two projects are fully scripted, so you can check out the scripts and use them as examples/tutorials.

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== removeElement( id ) ===

Deletes all properties from this element and remove it from play. Warning: it won't be recoverable! If you may need it later, you should move it inside a zone with visibility set to "Everyone, but hide what's inside" instead of removing it.

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside the target element (or array of elements).

=== roll( element_ids ) ===

Roll the target element (or array of elements). Target elements must have the property "Can be rolled" set.

=== setDie( element_ids, value ) ===

Set the target element (or array of elements) with this value. Target elements must have the property "Can set value" set.

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== stopEvent() ===

Must be used to stop the event propagation if you have two clickable elements on top of one another and you want only the onclick function matching the one on top to be triggered.

function onClickCard( card_id, selection_ids ) {
// Cancel event propagation
bga.stopEvent();
[... manage the event ...]
}

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-22T09:18:56Z

Een: /* Examples/Tutorials */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

== Examples/Tutorials ==

In addition to the projects you will create, you have readonly access in the sandbox to two example projects: "linesofaction" is an abstract and "apocalypseazcc" is a card game.

These two projects are fully scripted, so you can check out the scripts and use them as examples/tutorials.

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== removeElement( id ) ===

Deletes all properties from this element and remove it from play. Warning: it won't be recoverable! If you may need it later, you should move it inside a zone with visibility set to "Everyone, but hide what's inside" instead of removing it.

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== stopEvent() ===

Must be used to stop the event propagation if you have two clickable elements on top of one another and you want only the onclick function matching the one on top to be triggered.

function onClickCard( card_id, selection_ids ) {
// Cancel event propagation
bga.stopEvent();
[... manage the event ...]
}

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

BGA Code Sharing

2018-05-21T16:41:47Z

Een: /* Projects hosted not in studio */

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Hearts (Tutorial)
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|}

== Projects on studio ==

Links to studio project which owner wish share as read only.
Project owner please add you project here, dev nickname and short description if you would like to share it.
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| http://en.studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| http://en.studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

* Archive of tutorial projects https://www.dropbox.com/s/rsd5r4v49xudpp0/Studio.zip?dl=0
** Note: Hearts project is corrupted there, use Hearts tutorial project above
* Website with bunch of textures and sounds http://www.grsites.com/archive/textures/
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ (recommended by Gregory Isabelli)
* CSS shapes https://css-tricks.com/examples/ShapesOfCSS/
* PDF Scraper - extract images - http://www.extractpdf.com/
* BoardGameArena Workbench - set of tools to help test and deploy BGA projects - https://github.com/danielholmes/bga-workbench

SandboxScripts

2018-05-18T16:00:55Z

Een: /* Quick start */ Examples

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

== Examples/Tutorials ==

In addition to the projects you will create, you have readonly access in the sandbox to two example projects (one is an abstract, the other one is a card game).

These two projects are fully scripted, so you can check out the scripts and use them as examples/tutorials.

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== removeElement( id ) ===

Deletes all properties from this element and remove it from play. Warning: it won't be recoverable! If you may need it later, you should move it inside a zone with visibility set to "Everyone, but hide what's inside" instead of removing it.

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== stopEvent() ===

Must be used to stop the event propagation if you have two clickable elements on top of one another and you want only the onclick function matching the one on top to be triggered.

function onClickCard( card_id, selection_ids ) {
// Cancel event propagation
bga.stopEvent();
[... manage the event ...]
}

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:58:17Z

Een: /* Trigger most common game actions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== removeElement( id ) ===

Deletes all properties from this element and remove it from play. Warning: it won't be recoverable! If you may need it later, you should move it inside a zone with visibility set to "Everyone, but hide what's inside" instead of removing it.

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== stopEvent() ===

Must be used to stop the event propagation if you have two clickable elements on top of one another and you want only the onclick function matching the one on top to be triggered.

function onClickCard( card_id, selection_ids ) {
// Cancel event propagation
bga.stopEvent();
[... manage the event ...]
}

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:54:38Z

Een: /* stopEvent() */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== stopEvent() ===

Must be used to stop the event propagation if you have two clickable elements on top of one another and you want only the onclick function matching the one on top to be triggered.

function onClickCard( card_id, selection_ids ) {
// Cancel event propagation
bga.stopEvent();
[... manage the event ...]
}

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:54:29Z

Een: /* Other functions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== stopEvent() ===

Must be used to stop the event propagation if you have two clickable elements on top of one another and you want only the onclick function matching the one on top to be triggered.

function onClickCard( card_id, selection_ids ) {
// Cancel event propagation
bga.stopEvent();

[... manage the event ...]
}

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:52:12Z

Een: /* Gamestate functions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== setGameProgression( progression ) ===

Updates the game progression percentage (progression must be an integer between 0 and 100)

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:50:40Z

Een: /* Trigger most common game actions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== deal( deck_id, target_tag, nbr_per_target ) ===

Deal nbr_per_target cards from deck_id element to all elements having target_tag.

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:48:52Z

Een: /* Gamestate functions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== gotoState( state_id ) ===

Jumps to specified state.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:47:35Z

Een: /* = shuffle( element_ids ) */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ===

Shuffle elements contained inside this element (or array of elements).

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:47:25Z

Een: /* = flip( element_ids ) */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ===

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ==

Shuffle elements contained inside this element (or array of elements).

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:47:05Z

Een: /* Trigger most common game actions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== flip( element_ids ) ==

Flip target element (or array of elements) if the elements are flippable (ex: cards).

=== shuffle( element_ids ) ==

Shuffle elements contained inside this element (or array of elements).

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

=== setScore( color, value ) ===

Sets the score for the player with the specified color.

=== getScore( color ) ===

Gets the score of the player with the specified color.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-18T08:39:37Z

Een: /* Gamestate functions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== getActivePlayerName() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== activeAllPlayers() ===

Activates all players (multiactive state).

=== endTurn( transition ) ===

Make the current player inactive and go to the next state matching the provided transition if all players are inactive (multiactive state)

=== getActivePlayerColors() ===

Returns the colors code of the currently active players

=== getCurrentPlayerColor() ===

Returns the color code of the current player (the player who made the interface action being handled; may not be the active player).

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-17T16:26:38Z

Een: /* Gamestate functions */

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {
// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},
200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},
};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-17T16:26:03Z

Een: /* Gamestate functions */ gamestates functions

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {

// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},

200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},

};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

Check if action is valid regarding current game state and raise an error if it's not the case.

=== isActionPossible( action ) ===

Check if action is valid regarding current game state and returns a boolean with the appropriate value.

=== getActivePlayerColor() ===

Returns the color code of the currently active player

=== nextPlayer() ===

Activates the next player in play order.

=== nextState( transition ) ===

Moves to the next state matching the provided transition.

=== getPlayers() ===

Returns an array of players with the players information.

=== endGame() ===

When the end game condition is met, you can use this function to end the game (after setting the appropriate scores!)

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-17T16:08:08Z

Een: /* Other functions */ tag & styles

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {

// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},

200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},

};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

=== isActionPossible( action ) ===

=== getActivePlayerColor() ===

=== nextState() ===

=== nextPlayer() ===

=== getPlayers() ===

=== endGame() ===

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== hasTag( id, tag ) ===

Returns true if the element with this id has this tag.

=== addTag( id, tag ) ===

Adds this tag to the element with this id.

=== removeTag( id, tag ) ===

Removes this tag from the element with this id.

=== addStyle( id, style ) ===

Adds this style to the element with this id.

Predefined styles are: SELECTED / LIGHT / LIGHTBACKGROUND / REDSELECTED / CLICKABLE / ROUNDED / CLICKABLE_ROUNDED

=== removeStyle( id, style ) ===

Removes this style from the element with this id.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-17T15:16:20Z

Een: gamestate

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

== Gamestate functions ==

You can define your game flow with a list of states by adding a "states" function to your script.

function states()
{
return {

// Init game
100: {
onState: 'postSetup',
transitions: { done:200 }
},

200: {
description: _('${actplayer} must move a piece'),
descriptionmyturn: _('${you} must move a piece'),
possibleactions: ['movePiece'],
transitions: { nextPlayer: 200 }
},

};
}

Then, you will be able to use the following functions to manage the game flow.

=== checkAction( action ) ===

=== isActionPossible( action ) ===

=== getActivePlayerColor() ===

=== nextState() ===

=== nextPlayer() ===

=== getPlayers() ===

=== endGame() ===

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-17T14:30:23Z

Een: /* Other functions */ setProperties

This is the reference of functions you can call from your Sandbox scripts.

= Javascript =

BGA Sandbox scripts are written in Javascript.

Using Javascript, you can write scripts to automate moves for your Sandbox games & provide rules reinforcement.

Important : in the opposite of the most common usage of Javascript, Sandbox scripts are executed '''on server side'''.

= BGA API =

To interact with your BGA Sandbox game, we provide you an API.

With this API, you can get properties values of game elements from the current game situation, modify them and/or trigger the game actions (ex : move this element here, flip this card, and so on).

= Quick start =

== Hello World Script ==

From Sandbox editor "interface view" tab, select an element, and access to its property (top right icon).

Go to "Scripts (advanced)" section.

In front of "When this element is clicked", enter "onMyClick".

Close the window. Go to "script view" tab.

Enter the following :

function onMyClick( element_id )
{
bga.log("Hello world! You just clicked on element " + element_id + ". Congrats!");
}

Save & publish your project, starts a test session, click on the previous element : your message appears in the log on the right!

== Top useful tips ==

* You don't have to save&publish from the Sandbox editor for each modification of your script : each time you save your script (control+S), the script used for all test sessions is updated. Note that the production version on BGA is of course NOT updated until you explicitly save&publish again your project.

* To inspect the content of a variable, you can use bga.log() in combination with JSON.stringify(). For example :

bga.log( JSON.stringify( bga.getPlayers()) );

* Alternatively to bga.log(), you can use bga.exit( "my message" ) to debug your script. With bga.exit, the script execution immediately stops and all previous game changes are cancelled, so this is very practical to try and retry an action until your script is fine.

* We advise you to develop first a full playable version of the game without the scripts, and THEN to script it.

* On Board Game Arena, players have come to expect fully implemented games with all rules enforced. So even if it's technically possible not to script the full game and to implement the game only partially, in most cases we'll publish only fully scripted games :)

= Functions you can use in your Sandbox scripts=

== Debugging functions ==

=== bga.trace( txt / obj ) ===

Write something immediately in the BGA log (on the right of the screen).

This is the most practical way to debug your script :)

Important : bga.trace is for debugging purpose only and won't be displayed on production.

Note : you can also pass an object in parameter. This will dump the content of this object in the log.

Note : in the opposite of bga.log, bga.trace is NOT cancelled if the game action failed (after a call to bga.cancel or bga.error). This makes bga.trace very practical to debug a game action that failed, and for this reason you should probably NEVER use bga.log for debugging purpose.

// Example : write "Hello world" in the log
bga.trace( "Hello world" );

// Example : dump an associative array in the log
bga.trace( { mykey: 'myvalue', another_key: 'another_value' } );

=== bga.exit( txt / obj ) ===

Stop the script immediately, display the "txt" messages and cancel (ie : rollback) on every previous API call except bga.trace :

ALL previous BGA api call are canceled and there will be no visible changes on the interface (ex : no moves, no visible property changes, ...). Only "bga.trace" API commands are kept so you can debug.

bga.exit is very practical when you want to repeat a game action again and again to debug it : with a call to bga.exit at the end of your script, you make sure that your game situation will be kept unchanged after each test.

// Example :
bga.exit( "My script is stopped by this call" );

// Example with dumping a javascript variable
bga.exit( my_variable_to_dump );

== Cancelling a game action ==

=== bga.cancel( txt ) ===

This is the function to use when a player is doing something against game rules.

The text message in parameter will be displayed to this player as a "red message", so he/she can understand the rule.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
bga.cancel( _("You cannot move this piece here") );

Note : most of the time, you should wrap your text inside a _() translation marker to make this string translatable.

=== bga.error( text ) ===

This is the function to use when some unexpected error happens in your script.

The text message will be displayed to user, with mention "Unexpected error". The player will be incited to fill a bug report. The purpose of the message is to help you to identify the bug.

All previous BGA api call are cancelled, and there will be no visible changes on the interface.

// Example :
if( card_picked === null )
{
bga.error( "Cannot find a card to pick !" );
}

Note : you should NEVER wrap text inside bga.error with _() translation marker, because unexpected error should not be translate (so you can eventually recognize them when reported by players in bug report).

== Game log (history) ==

=== bga.log( txt, (optional) args ) ===

Write something in the BGA log on the right.

// Example : simple log
bga.log( _("A new round starts") );

You may add arguments to your log, like this :

// Example: log with argument to display a card name.
// In this example, variable "event_name" is specified afterwards.
// Note that using this, game translators only have to translate one "Event XXX is triggered" string for all possible events.
bga.log( _("Event ${event_name} is triggered"), { event_name: _( "Armageddon" ) } ) );

Note that argument "player_name" is ALWAYS pre-set with the name of the current player, so you can use it immediately.

// Example :
bga.log( _("${player_name} draw a card from the deck") );

=== bga.speechBubble( target, text, (optional) args, (optional) delay, (optional) duration, (optional) size ) ===

Display a "speech bubble", attached to the specified target, containing the specified text.

You can use "args" to customize text exactly like with bga.log.

delay : milliseconds to wait before displaying the speech bubble (default : 0).
duration : how long to show the speech bubble in milliseconds (default : 3000).
size : size of the text in percent (default: 100)

// Example :
bga.speechBubble( _("I play ${nbr} cards"), { nbr : 4 }, 0 );
bga.speechBubble( _("Good for you!"), { }, 2000 );

=== bga.displayScoring( target, color, score ) ===

Display an animated temporary "score number", attached to the specified target.

"color" should be the color of the player who is scoring for that target.

== Get / search game elements and their properties ==

=== bga.getElement( selector, (optional) fields ) ===

Allow you to retrieve informations about one game element specified using "selector" argument.

Return null if no element is found.

Note : getElement throw an error if several elements matches the selector. If you want to retrieve several elements, you should use "getElements" instead of "getElement".

The following examples are showing all the possible use of bga.getElement :

// Basic example :

// Retrieve the ID of a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" } );
// Return : 1234

// Examples using "field" parameter :

// Retrieve a specific property from a game element using its name ("Deck")
var deck_id = bga.getElement( { name: "Deck" }, 'x' );
// Return : 20

// Retrieve several properties from the previous element
var deck_properties = bga.getElement( { name: "Deck" }, ['name','id','parent', 'x','y','canShuffle'] );
// Return : { name:'Deck', id:1234, parent:4321, x: 20, y:50, canShuffle: true }

// Note : as you can see, getElement returns:
// _ the element ID by default, or
// _ a single value if you request a single field, or
// _ an object if you request several fields

// Examples using different "selector" paramter

// Retrieve an element name from its id
var deck_name = bga.getElement( { id: 1234 }, ['name'] );
// Return : "Deck"

// Retrieve the last child element of another element
// Here, we are requesting for elements who has element with ID=1234 (Deck) as their parent
// Note the use of "limit:1" which allows us to retrieve only 1 element.
var first_card_on_deck_id = bga.getElement( { parent: 1234, limit:1 } );

// You can also get nested properties such as the ids of the child elements of one element, or a custom property placed on the parent element
var totem_places = bga.getElements( {tag:'TOTEMZONE'}, ['id','childs:id','childs:tags','parent:id','parent:c_value'] );

=== bga.getElements( selector, (optional) fields ) ===

Returns an object holding the properties of the elements matching the selector.

// Basic example: unselect all selected elements
bga.removeStyle( bga.getElements( {tag: 'sbstyle_selected'}), 'selected' );

=== bga.getElementsArray( selector, (optional) fields ) ===

Returns an array of all elements matching the selector, holding the required properties.

// Basic example: get id of selected element
var selected_tokens = bga.getElementsArray( {tag: 'sbstyle_selected' } );
var token_id = null;
if (selected_tokens.length > 0) {
token_id = selected_tokens[0];
}
return token_id;

// Classic example: get array of elements and iterate over it
var all_cells = bga.getElementsArray( {tag: 'CELL'}, ['id','name','tags'] );
for (var i=0; i<all_cells.length; i++) {
// ... process each cell ...
}

== Utility methods ==

=== bga.isOn( element_id, parent_id ) ===

Return true if "element_id" is a descendant of "parent_id" (ie : if element_id game element has been placed on parent_id game element).

// Example :
if( bga.isOn( bga.getElementIfByName( 'Turn counter' ), bga.getElementIfByName( 'Turn 6' ) )
{
// Trigger game end
}

== Trigger most common game actions ==

=== moveTo( id, target, path ) ===

Move element to specified target id (eventually following path defined by an array of element ids to pass over on the way)

The exact destination of element depends on target's "howToArrange" property ("How elements are arranged on it?" : spreaded/deck/...).

// Example :
bga.moveTo( bga.getElementIdByName( 'Turn counter' ), bga.getElementIdByName( 'Turn 3' ) );

=== incScore( color, value ) ===

Increases the score for the player with the specified color, of the specified increment value.

== Other functions ==

=== pause( milliseconds ) ===

Pause the client interface during a specified number of milliseconds.

If you do not use bga.pause, all Sandbox game actions are executed immediately and synchronously.

// Example :
bga.log( "1" ); // Will be displayed immediately on the log
bga.pause( 3000 ); // pause during 3 seconds
bga.log( "2" ); // Will be displayed after the 3 second on the log
bga.log( "3" ); // Will be displayed right after the previous one, without delay.

Tips : if you want to execute several consecutive "moveTo", you should "bga.pause" between them, otherwise your element will move directly to the final destination.

=== setProperties( props ) ===

This function allows to directly update properties of an object, and to manage custom properties if needed (custom properties must start with prefix "c_").

Example:

// Update player labels for player zones from "<color> player" to actual player name
var players = bga.getPlayers();
for (var color in players) {
player = players[color];

var labelId = null;
if (color == 'ff0000') labelId = bga.getElement( {name: 'Red player'} );
if (color == '008000') labelId = bga.getElement( {name: 'Green player'} );
if (color == '0000ff') labelId = bga.getElement( {name: 'Blue player'} );
if (color == 'ffa500') labelId = bga.getElement( {name: 'Yellow player'} );

var props = [];
props[labelId] = {name: player.name};
bga.setProperties( props );
}

SandboxScripts

2018-05-17T14:26:14Z

Een: /* incScore( playerColor, incValue ) */

SandboxScripts

2018-05-17T14:25:25Z

Een: /* moveTo( id, target, path ) */

SandboxScripts

2018-05-17T14:25:12Z

Een: /* Trigger most common game actions */ incScore

SandboxScripts

2018-05-17T14:21:21Z

Een: /* Top useful tips */

SandboxScripts

2018-05-17T14:11:11Z

Een: /* bga.getElement( selector, (optional) fields ) */

SandboxScripts

2018-05-17T13:55:16Z

Een: /* Trigger most common game actions */

SandboxScripts

2018-05-17T13:54:57Z

Een: /* moveElement( element_id, target_id ) */

SandboxScripts

2018-05-17T13:45:35Z

Een: /* bga.displayScoring( target, color, score ) */

SandboxScripts

2018-05-17T13:45:25Z

Een: /* Game log (history) */ displayScoring

Game interface logic: yourgamename.js

2018-05-15T10:01:54Z

Een: /* Dialogs, warning messages, confirmation dialogs, ... */

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== 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:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: this is not a function, its a variable.
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

For performance reason, when deploying a game the js code is minified using Shrinksafe. Some advanced syntax may not be compatible with this process. In particular:
* you should not use reserved keywords from the javascript language as variables
* you should not declare default argument values in function declaration, the following syntax is invalid for Shriksafe: function myFunc(requiredArg, optionalArg = 'defaultValue') {}

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node, duration, delay )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

<pre>
onUpdateActionButtons: function( stateName, args ) {

if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

'''confirmationDialog( message, yesHandler, noHandler )'''

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score );
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble( anchor_id, text, delay, duration, custom_class )
</pre>

delay in milliseconds is optional (default 0)

duration in milliseconds is optional (default 3000)

custom_class is optional, if you need to override the default bubble style

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Game interface logic: yourgamename.js

2018-05-15T10:00:42Z

Een: /* Speech bubble */

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== 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:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: this is not a function, its a variable.
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

For performance reason, when deploying a game the js code is minified using Shrinksafe. Some advanced syntax may not be compatible with this process. In particular:
* you should not use reserved keywords from the javascript language as variables
* you should not declare default argument values in function declaration, the following syntax is invalid for Shriksafe: function myFunc(requiredArg, optionalArg = 'defaultValue') {}

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node, duration, delay )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

<pre>
onUpdateActionButtons: function( stateName, args ) {

if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

'''confirmationDialog( message, yesHandler, noHandler )'''

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score );
</pre>

=== Speech bubble ===

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble( anchor_id, text, delay, duration, custom_class )
</pre>

delay in milliseconds is optional (default 0)
duration in milliseconds is optional (default 3000)
custom_class is optional, if you need to override the default bubble style

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Game interface logic: yourgamename.js

2018-05-15T10:00:21Z

Een: /* Dialogs, warning messages, confirmation dialogs, ... */

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== 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:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: this is not a function, its a variable.
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

For performance reason, when deploying a game the js code is minified using Shrinksafe. Some advanced syntax may not be compatible with this process. In particular:
* you should not use reserved keywords from the javascript language as variables
* you should not declare default argument values in function declaration, the following syntax is invalid for Shriksafe: function myFunc(requiredArg, optionalArg = 'defaultValue') {}

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node, duration, delay )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

<pre>
onUpdateActionButtons: function( stateName, args ) {

if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

'''confirmationDialog( message, yesHandler, noHandler )'''

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

=== Scoring animated display ===

Sometimes (Terra Mystica final scoring for example), you may want to display a score value over an element to make the scoring easier to follow for the players.
You can do it with:

<pre>
this.displayScoring( anchor_id, color, score );
</pre>

== Speech bubble ==

For better interactivity in some games (Love Letter for example), you may use comic book style speech bubbles to express the players voices.
This is done with:

<pre>
this.showBubble( anchor_id, text, delay, duration, custom_class )
</pre>

delay in milliseconds is optional (default 0)
duration in milliseconds is optional (default 3000)
custom_class is optional, if you need to override the default bubble style

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Gamehelptablut

2018-04-27T10:21:50Z

Een: /* Captures */

= Description =
Tablut is an abstract tactical game for 2 players.

It is played on a 9 per 9 tiled board. There are 16 black pawns, called Muscovites, 8 white pawns, the Swedes, and a special white pawn, the Swedish king.

Players take turns, moving a single pawn of their color each time.

The initial setup looks like this:

[[File:Tablut_board_screenshot.png]]

= Objective of the game =
For the player with the black pawns, the Muscovites, the goal is to make encircle the king in order to capture him.

For the player with the white pawns, the Swedes, the goal his to bring the king in one of the four corners of the board.

= Moves =
All pawns move like the tower in chess: horizontally or vertically of any number of tiles.
Only the king can stop inside the four corners of the board and the center tile.

= Captures =
A pawn is captured, and hence removed from the board, when surrounded by 2 enemy pawns on opposite neighbour tiles :

[[File:Tablut_soldier_capture.png]]

However, a pawn willingly moving between 2 enemy pawns does not get captured.

The king is special in regard to capture: 2 Muscovites are not enough to eliminate him,
he must be encircled on all his 4 neighbour tiles.

The 4 corner tiles, the edge of the board (and for capturing the King, the center of the board) act like encircling pieces in regards to capture.

Gamehelptablut

2018-04-27T10:19:08Z

Een: Update rules to match scripted version

= Description =
Tablut is an abstract tactical game for 2 players.

It is played on a 9 per 9 tiled board. There are 16 black pawns, called Muscovites, 8 white pawns, the Swedes, and a special white pawn, the Swedish king.

Players take turns, moving a single pawn of their color each time.

The initial setup looks like this:

[[File:Tablut_board_screenshot.png]]

= Objective of the game =
For the player with the black pawns, the Muscovites, the goal is to make encircle the king in order to capture him.

For the player with the white pawns, the Swedes, the goal his to bring the king in one of the four corners of the board.

= Moves =
All pawns move like the tower in chess: horizontally or vertically of any number of tiles.
Only the king can stop inside the four corners of the board and the center tile.

= Captures =
A pawn is captured, and hence removed from the board, when surrounded by 2 enemy pawns on opposite neighbour tiles :

[[File:Tablut_soldier_capture.png]]

However, a pawn willingly moving between 2 enemy pawns does not get captured.

The king is special in regard to capture: 2 Muscovites are not enough to eliminate him,
he must be encircled on all his 4 neighbour tiles.

For capture, the 4 corner tiles, the edge of the board (and for capturing the King, the center of the board) act like enemy pieces.

SandboxScripts

2018-04-24T10:44:20Z

Een: /* bga.getElementsArray( selector, (optional) fields ) */

SandboxScripts

2018-04-23T14:57:39Z

Een: /* bga.getElementsArray( selector, (optional) fields ) */

SandboxScripts

2018-04-23T14:53:41Z

Een: /* Get / search game elements and their properties */

SandboxScripts

2018-04-23T14:39:23Z

Een: /* bga.getElement( selector, (optionnal) fields ) */

Game interface logic: yourgamename.js

2018-01-31T14:40:16Z

Een: /* Image loading */

This is the main file for your game interface. Here you will define:

* which actions on the page will generate calls to the server
* what happens when you get a notification for change from the server and how it will show in the browser.

== 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:
* constructor: here you can define variable global to your whole interface.
* setup: this method is called when the page is refreshed, in order you can setup the game interface.
* onEnteringState: the method is called when entering in a new game state. This way you can customize the view for this game state.
* onLeavingState: the method is called when leaving a game state.
* onUpdateActionButtons: called when entering in a new state, in order you can add action buttons in status bar.
* (utility methods): at this place you can define your utility methods
* (player's actions): at this place you can write your handlers for player's action on the interface (ex: click on an item).
* setupNotifications: in this method you associate notifications with notification handlers. This way, for each game notification, you trigger a javascript method to handle it and update the game interface.
* (notification handlers): at this place you can define your notifications handlers.

== General tips ==

; this.player_id
: Id of the player on whose browser the code is running.

; this.isSpectator
: Flag set to true if the user at the table is a spectator (not a player).
: Note: this is not a function, its a variable.
: Note: if you want to hide some element for spectators, you'd better use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains your initial set of datas to init the game, created at game start or game refresh (F5)
: You can update it as needed to keep an up to date reference of the game on the client side if you need it (most of the time you don't).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play)

; this.getActivePlayerId()
: Return the ID of active player, or null if we are not in a "activeplayer" type state.

; this.getActivePlayers()
: Return an array with the IDs of players that are currently active (or an empty array if there is not).

== Dojo framework ==

BGA is using the [http://dojotoolkit.org/ Dojo Javascript framework].

The Dojo framework allows us to do complex things easier, and the BGA framework is using Dojo framework a lot.

To realize game although, you only need to use a few part of the Dojo framework. All the Dojo methods you need to use are describe on this page.

For performance reason, when deploying a game the js code is minified using Shrinksafe. Some advanced syntax may not be compatible with this process. In particular:
* you should not use reserved keywords from the javascript language as variables
* you should not declare default argument values in function declaration, the following syntax is invalid for Shriksafe: function myFunc(requiredArg, optionalArg = 'defaultValue') {}

== Access and manipulate the DOM ==

'''$('some_html_element_id')'''

The $() function is used to get some HTML element using its "id" attribute.

Example 1: modify the content of a "span" element:
<pre>
In your HTML code:
<span id="a_value_in_the_game_interface">1234</span>

In your Javascript code:
$('a_value_in_the_game_interface').innerHTML = "9999";
</pre>

Note: $() is the standard method to access some HTML element with BGA Framework. You must not use "getElementById" function.

'''dojo.style'''

With dojo.style you can modify a CSS property of any HTML element of your interface.

Examples:
<pre>
// Make an element disappear
dojo.style( 'my_element', 'display', 'none' );

// Give an element a 2px border
dojo.style( 'my_element', 'borderWidth', '2px' );

// Change the background position of an element
// (very practical when you are using CSS sprite to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

Note: you must always use dojo.style to modify CSS properties of HTML elements.

Note²: if you have to modify several CSS properties of an element, or if you have some complex CSS transformation to do, you should consider using dojo.addClass/dojo.removeClass (see below).

'''dojo CSS classes manipulation'''

In many situation, a bunch of many small CSS property update can be replaced by a CSS class change (ie: you add a CSS class to your element instead of applying all modification manually).

Advantages are:
* All your CSS stuff remains in your CSS file.
* You can add/remove a list of CSS modifications with a simple function and whithout error.
* You can test if you applied the stuff to an element with "dojo.hasClass" method.

Example from "Reversi":
<pre>
// We add "possibleMove" to an element
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );

// In our CSS file, the class is defined as:
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}

// So we've applied 4 CSS property change in one line of code.

// ... and when we need to check if a square is a possible move on client side:
if( dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{ ... }

// ... and if we want to remove all possible moves in one line of code (see "dojo.query" method):
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );
</pre>

Conclusion: we encourage you to use dojo.addClass, dojo.removeClass and dojo.hasClass to make your life easier :)

'''dojo.query'''

With dojo.query, you can query a bunch of HTML elements with a single function, with a "CSS selector" style.

Example:
<pre>
// All elements with class "possibleMove":
var elements = dojo.query( '.possibleMove' );

// Count number of tokens (ie: elements with class "token") on the board (ie: element with id "board"):
dojo.query( '#board .token' ).length;
</pre>

But what is really cool with dojo.query is that you can combine it with almost all methods above.

Examples:
<pre>
// Trigger a method when the mouse enter in any element with class "meeple":
dojo.query( '.meeple' ).connect( 'onmouseenter', this, 'myMethodToTrigger' );

// Hide all meeples who are on the board
dojo.query( '#board .meeple' ).style( 'display', 'none' );
</pre>

'''dojo.place'''

dojo.place is the best function to insert some HTML code somewhere in your game interface without breaking something. It is much better to use that "innerHTML=''" method as soon as you must insert HTML tags and not only values.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<your html code>", "your_container_element_id" );

// Replace the container element with your new html
dojo.place( "<your html code>", "your_container_element_id", "replace" );

</pre>

The third parameter of dojo.place can take various interesting value.

values possibles :

"replace" : (see description above).

"first" : Places the node as a child of the reference node. The node is placed as the first child.

"last" : Places the node as a child of the reference node. The node is placed as the last child.

"before" : places the node right before the reference node.

"last (value by default) " : places the node right after the reference node.

"only" : replaces all children of the reference node with the node.

positif integer : This parameter can be a positif integer. In this case, the node will be placed as a child of the reference node with this number (counting from 0). If the number is more than number of children, the node will be appended to the reference node making it the last child.

See also full doc on dojo.place : [http://dojotoolkit.org/reference-guide/1.7/dojo/place.]

Usually, when you want to insert some piece of HTML in your game interface, you should use "[[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]".

'''addStyleToClass: function( cssClassName, cssProperty, propertyValue )'''

Same as dojo.style(), but for all the nodes set with the specified cssClassName

=== Animations ===

'''Dojo Animations'''

BGA animations is based on Dojo Animation ([http://dojotoolkit.org/documentation/tutorials/1.8/animation/ see tutorial here]).

However, most of the time, you can just use methods below, which are built on top of Dojo Animation.

Note: one interesting method from Dojo that could be useful from time to time is "Dojo.Animation". It allows you to make any CSS property "slide" from one value to another.

'''this.slideToObject( mobile_obj, target_obj, duration, delay )'''

You can use slideToObject to "slide" an element to a target position.

Sliding element on the game area is the recommended and the most used way to animate your game interface. Using slides allow players to figure out what is happening on the game, as if they were playing with the real boardgame.

The parameters are:
* mobile_obj: the ID of the object to move. This object must be "relative" or "absolute" positioned.
* target_obj: the ID of the target object. This object must be "relative" or "absolute" positioned. Note that it is not mandatory that mobile_obj and target_obj have the same size. If their size are different, the system slides the center of mobile_obj to the center of target_obj.
* duration: (optional) defines the duration in millisecond of the slide. The default is 500 milliseconds.
* delay: (optional). If you defines a delay, the slide will start only after this delay. This is particularly useful when you want to slide several object from the same position to the same position: you can give a 0ms delay to the first object, a 100ms delay to the second one, a 200ms delay to the third one, ... this way they won't be superposed during the slide.

BE CAREFUL: The method returns an dojo.fx animation, so you can combine it with other animation if you want to. It means that you have to call the "play()" method, otherwise the animation WON'T START.

Example:
<pre>
this.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.slideToObjectPos( mobile_obj, target_obj, target_x, target_y, duration, delay )'''

This method does exactly the same as "slideToObject", except than you can specify some (x,y) coordinates. This way, "mobile_obj" will slide to the specified x,y position relatively to "target_obj".

Example: slide a token to some place on the board, 10 pixels to the bottom:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.slideTemporaryObject( mobile_obj_html, mobile_obj_parent, from, to, duration, delay )'''

This method is useful when you want to slide a temporary HTML object from one place to another. As this object does not exists before the animation and won't remain after, it could be complex to create this object (with dojo.place), to place it at its origin (with placeOnObject) to slide it (with slideToObject) and to make it disappear at the end.

slideTemporaryObject does all of this for you:
* mobile_obj_html is a piece of HTML code that represent the object to slide.
* mobile_obj_parent is the ID of an HTML element of your interface that will be the parent of this temporary HTML object.
* from is the ID of the origin of the slide.
* to is the ID of the target of the slide.
* duration/delay works exactly like in "slideToObject"

Example:
<pre>
this.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

'''this.slideToObjectAndDestroy: function( node, to, time, delay )'''

This method is a handy shortcut to slide an existing HTML object to some place then destroy it upon arrival. It can be used for example to move a victory token or a card from the board to the player panel to show that the player earns it, then destroy it when we don't need to keep it visible on the player panel.

It works the same as this.slideToObject and takes the same arguments.

Example:
<pre>
this.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

'''this.fadeOutAndDestroy( node, duration, delay )'''

This function fade out the target HTML node, then destroy it.

Example:
<pre>
this.fadeOutAndDestroy( "a_card_that_must_disappear" );
</pre>

CAREFUL: the HTML node still exists until during few milliseconds, until the fadeOut has been completed.

'''Rotating elements'''

You can check here [http://jimfulton.info/demos/dojo-animated-rotate.html an example of use] of Dojo to make an element rotate.

This example combines "Dojo.Animation" method and a CSS3 property that allow you to rotate the element.

IMPORTANT: to asses browser compatibility, you must select the CSS property to use just like in the example (see sourcecode below):

<pre>
var transform;
dojo.forEach(
['transform', 'WebkitTransform', 'msTransform',
'MozTransform', 'OTransform'],
function (name) {
if (typeof dojo.body().style[name] != 'undefined') {
transform = name;
}
});
// ... and then use "transform" as the name of your CSS property for rotation
</pre>

=== Moving elements ===

'''this.placeOnObject( mobile_obj, target_obj )'''

placeOnObject works exactly like "slideToObject", except that the effect is immediate.

This is not really an animation, but placeOnObject is frequently used before starting an animation.

Example:
<pre>
// (We just created an object "my_new_token")

// Place the new token on current player board
this.placeOnObject( "my_new_token", "overall_player_board_"+this.player_id );

// Then slide it to its position on the board
this.slideToObject( "my_new_token", "a_place_on_board" ).play();
</pre>

'''this.placeOnObjectPos( mobile_obj, target_obj, target_x, target_y )'''

This method works exactly like placeOnObject, except than you can specify some (x,y) coordinates. This way, "mobile_obj" will be placed to the specified x,y position relatively to "target_obj".

'''this.attachToNewParent( mobile_obj, target_obj )'''

With this method, you change the HTML parent of "mobile_obj" element. "target_obj" is the new parent of this element. The beauty of
attachToNewParent is that the mobile_obj element DOES NOT MOVE during this process.

Note: what happens is that the method calculate a relative position of mobile_obj to make sure it does not move after the HTML parent changes.

Why using this method?

Changing the HTML parent of an element can be useful for the following reasons:
* When the HTML parent moves, all its child are moving with them. If some game elements is no more linked with a parent HTML object, you may want to attach it to another place.
* The z_order (vertical order of display) depends on the position in the DOM, so you may need to change the parent of some game elements when they are moving in your game area.

CAREFUL: this function destroys original object and places a clone onto a new parent, this will break all references to this HTML element (ex: dojo.connect).

== Players input ==

'''dojo.connect'''

Used to associate a player event with one of your notification method.

Example: associate a click on an element ("my_element") with one of our method ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>

Note: this is the only possible correct way to associate a player input event to your code, and you must not use anything else.

'''this.checkAction( "my_action_name" )'''

Usage: checkAction: function( action, nomessage )

Check if player can do the specified action by taking into account:
* current game state
* interface locking (a player can't do any action if an action is already in progress)

return true if action is authorized (ie: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not (display no message if nomessage parameter is true). The displayed error message could be either "This move is not allowed at this moment" or "An action is already in progress".

Example:
<pre>
function onClickOnGameElement( evt )
{
if( this.checkAction( "my_action" ) )
{
// Do the action
}
}
</pre>

'''this.ajaxcall( url, parameters, obj_callback, callback, callback_error )'''

This method must be used to send a player input to the game server.

* url: the url of the action to perform. For a game, it must be: "/<mygame>/<mygame>/myAction.html"
* parameters: an array of parameter to send to the game server. Note that "lock:true" must always be specified in this list of parameter in order the interface can be locked during the server call.
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine.
* callback_error: (optional and rarely used) a function to trigger when the server returns an error.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
} );
</pre>

Restricted arguments names (please don't use them):
* "action"
* "module"
* "class"

'''this.confirmationDialog()'''

Display a confirmation dialog with a yes/no choice.

We advice you to NOT use this function unless the player action is really critical and could ruins the game, because it slows down the game and upset players.

Usage: this.confirmationDialog( "Question to displayed", callback_function_if_click_on_yes );

Example:
<pre>
this.confirmationDialog( _('Are you sure to use this bonus (points penalty at the end of the game) ?'),
dojo.hitch( this, function() {
this.ajaxcall( '/seasons/seasons/useBonus.html',
{ id:bonus_id, lock:true }, this, function( result ) {} );
} ) );
</pre>

; addEventToClass: function( cssClassName, eventName, functionName )
: Same as dojo.connect(), but for all the nodes set with the specified cssClassName

'''this.addActionButton( id, label, method, (opt)destination, (opt)blinking, (opt)color )'''

You can use this method to add an action button in the main action status bar.

Arguments:
* id: an element ID that should be unique in your HTML DOM document.
* label: the text of the button. Should be translatable (use _() function).
* method: the name of your method that must be triggered when the player clicks on this button.
* destination (optional): deprecated, do not use this. Use '''null''' as value if you need to specify other arguments.
* blinking (optional): if set to '''true''', the button is going blink to catch player's attention. Please don't abuse of blinking button.
* color: could be '''blue''' (default), '''red''' or '''gray'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this (from Hears example):

<pre>
onUpdateActionButtons: function( stateName, args ) {

if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
break;
}
}
},
</pre>

In the example above, we are adding a "Give selected cards" button in the case we are on game state "giveCards". When player clicks on this button, it triggers our "onGiveCards" method.

Example using blinking red button:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
</pre>

Note: at least in studio example above will make button huge, because it sets it display of blinking things to '''block''',
if you don't like it you have to change css display value
of the button to inline-block (the id of the button is the first argument, i.e 'commit_button' in example above)

== Translations ==

See [[Translations]]

== Notifications ==

When something happens on the server side, your game interface Javascript logic received a notification.

Here's how you can handle these notifications on the client side.

=== Subscribe to notifications ===

Your Javascript "setupNotifications" method is the place where you can subscribe to notifications from your PHP code.

Here's how you associate one of your Javascript method to a notification "playDisc" (from Reversi example):

<pre>
// In setupNotifications method:
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
</pre>

Note: the "playDisc" corresponds to the name of the notification you define it in your PHP code, in your "notifyAllPlayers" or "notifyPlayer" method.

Then, you have to define your "notif_playDisc" method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addDiscOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

In a notification handler like our "notif_playDisc" method, you can access to all notifications arguments with "notif.args".

Example:
<pre>
// If you did this on PHP side:
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );

// On Javascript side, you can access the "myArgument" like this:
notif_myNotification: function( notif )
{
alert( "myArgument = " + notif.args.myArgument );
}
</pre>

=== Synchronous notifications ===

When several notifications are received by your game interface, these notifications are processed immediately, one after the other, in the same exact order they have been generated in your PHP game logic.

However, sometimes, you need to give some time to the players to figure out what happened on the game before jumping to the next notification. Indeed, in many games, they are a lot of automatic actions, and the computer is going to resolve all these actions very fast if you don't tell it not to do so.

As an example, for Reversi, when someone is playing a disc, we want to wait 500 milliseconds before doing anything else in order the opponent player can figure out what move has been played.

Here's how we do this, right after our subscription:
<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 ); // Wait 500 milliseconds after executing the playDisc handler
</pre>

=== Pre-defined notification types ===

'''tableWindow''' - This defines notification to display [[Game_interface_logic:_yourgamename.js#Scoring_dialogs|Scoring Dialogs]], see below.

'''message''' - This defines notification that shows on players log and have no other effect

// You can call this on php side without doing anything on client side
self::notifyAllPlayers( 'message', 'hello', array( ) );

== Tooltips ==

'''this.addTooltip( nodeId, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to the DOM node.

Specify 'helpString' to display some information about "what is this game element?".
Specify 'actionString' to display some information about "what happens when I click on this element?".

You must specify both helpString and actionString. Most of the time, you use only one and specify a void string ("") for the other one.

Usually, _() must be used for the text to be marked for translation.

"Delay" is an optional parameter. Usually, it is primarily used to specify a zero delay for some game element when the tooltip gives really important information for the game - but remember: no essential information must be placed in tooltips as they won't be displayed in some browser (see Guidelines).

Example:
<pre>
this.addTooltip( 'cardcount', _('Number of cards in hand'), '' );
</pre>

'''this.addTooltipHtml( nodeId, html, delay )'''

Add an HTML tooltip to the DOM node (for more elaborate content such as presenting a bigger version of a card).

'''this.addTooltipToClass( cssClass, _( helpString ), _( actionString ), delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass.

IMPORTANT: all concerned nodes must have IDs to get tooltips.

'''this.addTooltipHtmlToClass( cssClass, html, delay )'''

Add an HTML tooltip to to all the DOM nodes set with this cssClass (for more elaborate content such as presenting a bigger version of a card).

IMPORTANT: all concerned nodes must have IDs to get tooltips

'''this.removeTooltip( nodeId )'''

Remove a tooltip from the DOM node.

== Dialogs, warning messages, confirmation dialogs, ... ==

=== Warning messages ===

Sometimes, there is something important that is happening on the game and you have to make sure all players get the message. Most of the time, the evolution of the game situation or the game log is enough, but sometimes you need something more visible.

Ex: someone fulfill one of the end of the game condition, so this is the last turn.

'''this.showMessage( msg, type )'''

showMessage shows a message in a big rectangular area on the top of the screen of current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info" or "error". If set to "info", the message will be an informative message on a white background. If set to "error", the message will be an error message on a red background.

Important: the normal way to inform players about the progression of the game is the game log. "showMessage" is intrusive and should not be used often.

=== Confirmation dialog ===

'''confirmationDialog( message, yesHandler, noHandler )'''

When an important action with a lot of consequences is triggered by the player, you may want to propose a confirmation dialog.

CAREFUL: the general guidelines of BGA is to AVOID the use of confirmation dialog. Confirmation dialogs slow down the game and bother players. The players knows that they have to pay attention about each move when they are playing online.

The situation where you should use a confirmation dialog are the following:
* It must not happen very often during a game.
* It must be linked to an action that can really "kill a game" if the player do not pay attention.
* It must be something that can be done by mistake (ex: a link on the action status bar).

How to display a confirmation dialog:
<pre>
this.confirmationDialog( _('Are you sure you want to bake the pie?'), dojo.hitch( this, function() {
this.bakeThePie();
} ) );
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

=== Multiple choice dialog ===
You can use this dialog to give user a choice with small amount of options:
<pre>
var keys = [1,5,10];
this.multipleChoiceDialog(
_('How many bugs to fix?"), keys,
dojo.hitch(this, function(choice) {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} ); }));
</pre>

=== Dialogs ===

At first, you shouldn't use dialogs windows.

BGA guidelines specify that all game elements should be displayed on the main screen. Players can eventually scroll down to see game elements they don't need to see anytime, and you may eventually create anchors to move between game area section. Of course dialogs windows are very practical, but the thing is: all players know how to scroll down, and not all players know how to show up your dialog window. In addition, when the dialog shows up, players can't access the other game components.

Sometimes although, you need to display a dialog window. Here is how you do this:

// Create the new dialog. You should store the handler in a member variable to access it later
this.myDlg = new dijit.Dialog({ title: _("my dialog title to translate") });

// Create the HTML of my dialog.
// The best practice here is to use [[Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl#Javascript_templates|Javascript templates]]
var html = this.format_block( 'jstpl_myDialogTemplate', {
arg1: myArg1,
arg2: myArg2,
...
} );

// Show the dialog
this.myDlg.attr("content", html );
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, a "close" button:
dojo.connect( $('closeDlg'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.hide();
} );

Tip: be careful with "hide()" method to close your dialog: the dialog and its content is not completely removed from the DOM. It can cause you problems if you try to display the same dialog several times. A good practice is to wrap all the content of your dialog in a <nowiki><div id='myDlgContent'></nowiki> div element, and to call "dojo.destroy('myDlgContent')" before displaying your dialog.

=== Scoring dialogs ===

Sometimes at the end of a round you want to display a big table that details the points wins in each section of the game.

Example: in Hearts game, we display at the end of each round the number of "heart" cards collected by each player, the player who collected the Queen of Spades, and the total number of points loose by each player.

Scoring dialogs are managed entirely on '''PHP side''', but they are described here as their effects are visible only on client side.

Displaying a scoring dialog is quite simple and is using a special notification type: "tableWindow":
<pre>
// on PHP side:
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table
) );
</pre>

The "table" argument is a 2 dimensional PHP array that describe the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = array(
array( "one", "two", "three" ), // This is my first line
array( "four", "five", "six" ), // This is my second line
array( "seven", "height", "nine" ) // This is my third line
);
</pre>

As you can see above, in each "cell" of your array you can display a simple string value. But you can also display a complex value with a template and associated arguments like this:
<pre>
$table = array(
array( "one", "two", array( "str" => "a string with an ${argument}", "args" => array( 'argument' => 'argument_value' ) ) ),
array( "four", "five", "six" ),
array( "seven", "height", "nine" )
);
</pre>

This is especially useful when you want to display player names with colors. Example from "Hearts":
<pre>
$firstRow = array( '' );
foreach( $players as $player_id => $player )
{
$firstRow[] = array( 'str' => '${player_name}',
'args' => array( 'player_name' => $player['player_name'] ),
'type' => 'header'
);
}
$table[] = $firstRow;
</pre>

You can also use three extra attributes in the parameter array for the notification:

<pre>
$this->notifyAllPlayers( "tableWindow", '', array(
"id" => 'finalScoring',
"title" => clienttranslate("Title of the scoring dialog"),
"table" => $table,
"header" => array('str' => clienttranslate('Table header with parameter ${number}'),
'args' => array( 'number' => 3 ),
),
"footer" => '<div>Some footer</div>',
"closing" => clienttranslate( "Closing button label" )
) );
</pre>

*'''header''': the content for this parameter will display before the table (also, the html will be parsed and player names will be colored according to the current game colors).
*'''footer''': the content for this parameter will display after the table (no parsing for coloring the player names)
*'''closing''': if this parameter is used, a button will be displayed with this label at the bottom of the popup and will allow players to close it (more easily than by clicking the top right 'cross' icon).

== Update players score ==

Increase a player score (with a positive or negative number):

<pre>
this.scoreCtrl[ player_id ].incValue( score_delta );
</pre>

Set a player score to a specific value:

<pre>
this.scoreCtrl[ player_id ].setValue( new_score );
</pre>

== Players panels ==

=== Adding stuff to player's panel ===

At first, create a new "JS template" string in your template (tpl) file:

(from Gomoku example)
<pre>
var jstpl_player_board = '\<div class="cp_board">\
<div id="stoneicon_p${id}" class="gmk_stoneicon gmk_stoneicon_${color}"></div><span id="stonecount_p${id}">0</span>\
</div>';
</pre>

Then, you add this piece of code in your JS file to add this template to each player panel:

<pre>
// Setting up player boards
for( var player_id in gamedatas.players )
{
var player = gamedatas.players[player_id];

// Setting up players boards if needed
var player_board_div = $('player_board_'+player_id);
dojo.place( this.format_block('jstpl_player_board', player ), player_board_div );
}
</pre>

(Note: the code above is of course from your "setup" function in your Javascript).

Very often, you have to distinguish current player and others players. In this case, you just have to create another JS template (ex: jstpl_otherplayer_board) and use it when "player_id" is different than "this.player_id".

=== Player's panel disabling/enabling ===

'''this.disablePlayerPanel( player_id )'''

Disable given player panel (the panel background become gray).

Usually, this is used to signal that this played passes, or will be inactive during a while.

Note that the only effect of this is visual. There are no consequences on the behaviour of the panel itself.

'''this.enablePlayerPanel( player_id )'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels()'''

Enable all player panels that has been disabled before.

== Image loading ==

See also [[Game_art:_img_directory]].

'''Be careful''': by default, ALL images of your img directory are loaded on a player's browser when he loads the game. For this reason, don't let in your img directory images that are not useful, otherwise it's going to slowdown the game load.

'''dontPreloadImage( image_file_name )'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory.

Example of use:
<pre>
this.dontPreloadImage( 'cards.png' );
</pre>

This is particularly useful if for example you have 2 different themes for a game. To accelerate the loading of the game, you can specify to not preload images corresponding to the other theme.

Another example of use: in "Gosu" game with Kamakor extension, you play with 5 sets of cards among 10 available. Cards images are organized by sets, and we only preload the images corresponding to the 5 current sets with '''ensureSpecificGameImageLoading( image_file_names_array )'''.
<pre>
// By default, do not preload anything
this.dontPreloadImage( 'cards.png' );
this.dontPreloadImage( 'clan1.png' );
this.dontPreloadImage( 'clan2.png' );
this.dontPreloadImage( 'clan3.png' );
this.dontPreloadImage( 'clan4.png' );
this.dontPreloadImage( 'clan5.png' );
this.dontPreloadImage( 'clan6.png' );
this.dontPreloadImage( 'clan7.png' );
this.dontPreloadImage( 'clan8.png' );
this.dontPreloadImage( 'clan9.png' );
this.dontPreloadImage( 'clan10.png' );
var to_preload = [];
for( i in this.gamedatas.clans )
{
var clan_id = this.gamedatas.clans[i];
to_preload.push( 'clan'+clan_id+'.png' );
}
if( to_preload.length == 5 )
{
this.ensureSpecificGameImageLoading( to_preload );
}
</pre>

'''Note:''' You don't need to specify to not preload game box images (game_box.png, game_box75.png...) since they are not preloaded by default.

== Other useful stuff ==

'''dojo.hitch'''

With dojo.hitch, you can create a callback function that will run with your game object context whatever happen.

Typical example: display a BGA confirmation dialog with a callback function created with dojo.hitch:

<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), dojo.hitch( this, function() {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, function( result ) {} );
} ) );
</pre>

In the example above, using dojo.hitch, we are sure that the "this" object will be set when the callback is called.

; updateCounters(counters)
: Useful for updating game counters in the player panel (such as resources).
: 'counters' arg is an associative array [counter_name_value => [ 'counter_name' => counter_name_value, 'counter_value' => counter_value_value], ... ]
: All counters must be referenced in this.gamedatas.counters and will be updated.
: DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

== BGA GUI components ==

BGA framework provides some useful ready-to-use components for the game interface:

[[Studio#BGA_Studio_game_components_reference]]

Note that each time you are using an additional component, you must declare it at the top of your Javascript file in the list of modules used.

Example if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl

2018-01-14T09:29:07Z

Een: /* Javascript templates */

These 2 files work together to provide the HTML layout of your game.

Using these 2 files, you specify what HTML is rendered in your game client interface.

In <yourgame.tpl>, you can directly write raw HTML that will be displayed by the browser.

Example: extract of "hearts_hearts.tpl":

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

== WARNING ==

Your view and your template are supposed to generate only the BASE layout of the game

You shouldn't try to setup the current game situation in the view: this is the role of your Javascript code. Why? Because you'll have to write Javascript code to put game elements in place anyway, and you don't want to write it twice :)

Example of things to generate in your view:
* The overall layout of your game interface (what is displayed where).
* The board and fixed elements on the board (ex: places for cards, squares, ...).

Example of things that shouldn't be generate by your view:
* Game elements that come and go from the game area.
* Game elements that normally hidden from players (other players cards, cards in the deck).

== phplib template system ==

BGA is using the phplib template system, used for example in PHPbb forums.

More details about how to use phplib template system here:
http://www.phpbuilder.com/columns/david20000512.php3

== Variables ==

In your template ("tpl") file, you can use variables. Then in your view (".view.php") file, you fill these variables with value.

In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters border by "{" and "}".

To give a value to this variable in your view.php:

Examples:
<pre>

// Display a translated version of "My hand" at the place of the variable in the template
$this->tpl['MY_HAND'] = self::_("My hand");

// Display some raw HTML material at the place of the variable
$this->tpl['MY_HAND'] = self::raw( "<div class='myhand_icon'></div>" );

</pre>

WARNING: do not use a variable called {id} as it will interfere with action buttons.

== Blocks ==

Using "blocks", you can repeat a piece of HTML from your template several time.

You should use "blocks" everytime you have a block of HTML that you have to repeat a big number of time. For example, for Reversi, we have to generate 64 (8x8) squares:

<pre>

(in reversi_reversi.tpl)

<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>


<div id="discs">
</div>
</div>

(in reversi.view.php)

$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}

</pre>

Explanations:
* You specify a block in your template file, using "BEGIN" and "END" keywords. In the example above, we are creating a block named "square".
* In your view, you declare your block using "begin_block" method.
* Then, you can insert as many block as you want to, using "insert_block" method.

The insert_block method takes 2 parameters:
* the name of the block to insert.
* an associative array you can use to assign values to template variables of this block. In the example above, there are 4 parameters in the block (X, Y, LEFT and TOP).

== Nested blocks ==

You can use nested blocks. In the example below, we are going to add a mini-board for each player of the game, with 4 card places on each of it:

<pre>

(In template file)


<div class="miniboard" id="miniboard_{PLAYER_ID}">

<div class="card_places">

<div id="card_place_{PLAYER_ID}_{PLACE_ID}">
</div>

</div>

</div>


(In view file)

$this->page->begin_block( "mygame_mygame.tpl", "card_place" ); // Nested block must be declared first
$this->page->begin_block( "mygame_mygame.tpl", "player" );

foreach( $players as $player_id => $player )
{
// Important: nested block must be reset here, otherwise the second player miniboard will
// have 8 card_place, the third will have 12 card_place, and so one...
$this->page->reset_subblocks( 'card_place' );

for( $i=1; $i<=4; $i++ )
{
$this->page->insert_block( "card_place", array(
'PLAYER_ID' => $player_id,
'PLACE_ID' => $i
);
}

$this->page->insert_block( 'player', array( 'PLAYER_ID' => $player_id );
}

</pre>

== Javascript templates ==

For game elements that come and go from the game area, we suggest you to define a Javascript template.

A Javascript template is defined in your template file like this:

(Reversi Token from Reversi example):
<pre>
<script type="text/javascript">

// Templates

var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';

</script>
</pre>

Note: a section for javascript templates is already available at the end of your template skeleton file.

Then, you can use this javascript template to insert this piece of HTML in your game interface, like this:

<pre>
dojo.place( this.format_block( 'jstpl_disc', {
xy: x+''+y,
color: color
} ) , 'discs' );
</pre>

WARNING: always use lowercase for substitution variables in your Javascript templates, in order to avoid collision with phplib template variables (in particular, do not use ${ID}).

== How to access game information from .view.php? ==

From your .view.php, you can access the following:

=== Access current player id===

<pre>
global $g_user;
$current_player_id = $g_user->get_id();
</pre>

=== Access game object ===

In your view file, "$this->game" contains an instance of your main game class.

Example:
<pre>

// Access to some game elements description described in your "material.inc.php":
$my_cards_types = $this->game->card_types;

// Access to any (public) method defined in my .game.php file:
$result = $this->game->myMethod();
</pre>

== Tips: displaying a nice button ==

From time to time, you need to display a standard button in your interface. BGA framework provides you a standard button that you can use directly in your interface:

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

Note: To see it in action, check for example a Coloretto game

Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl

2018-01-14T09:28:45Z

Een: /* Javascript templates */

These 2 files work together to provide the HTML layout of your game.

Using these 2 files, you specify what HTML is rendered in your game client interface.

In <yourgame.tpl>, you can directly write raw HTML that will be displayed by the browser.

Example: extract of "hearts_hearts.tpl":

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

== WARNING ==

Your view and your template are supposed to generate only the BASE layout of the game

You shouldn't try to setup the current game situation in the view: this is the role of your Javascript code. Why? Because you'll have to write Javascript code to put game elements in place anyway, and you don't want to write it twice :)

Example of things to generate in your view:
* The overall layout of your game interface (what is displayed where).
* The board and fixed elements on the board (ex: places for cards, squares, ...).

Example of things that shouldn't be generate by your view:
* Game elements that come and go from the game area.
* Game elements that normally hidden from players (other players cards, cards in the deck).

== phplib template system ==

BGA is using the phplib template system, used for example in PHPbb forums.

More details about how to use phplib template system here:
http://www.phpbuilder.com/columns/david20000512.php3

== Variables ==

In your template ("tpl") file, you can use variables. Then in your view (".view.php") file, you fill these variables with value.

In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters border by "{" and "}".

To give a value to this variable in your view.php:

Examples:
<pre>

// Display a translated version of "My hand" at the place of the variable in the template
$this->tpl['MY_HAND'] = self::_("My hand");

// Display some raw HTML material at the place of the variable
$this->tpl['MY_HAND'] = self::raw( "<div class='myhand_icon'></div>" );

</pre>

WARNING: do not use a variable called {id} as it will interfere with action buttons.

== Blocks ==

Using "blocks", you can repeat a piece of HTML from your template several time.

You should use "blocks" everytime you have a block of HTML that you have to repeat a big number of time. For example, for Reversi, we have to generate 64 (8x8) squares:

<pre>

(in reversi_reversi.tpl)

<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>


<div id="discs">
</div>
</div>

(in reversi.view.php)

$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}

</pre>

Explanations:
* You specify a block in your template file, using "BEGIN" and "END" keywords. In the example above, we are creating a block named "square".
* In your view, you declare your block using "begin_block" method.
* Then, you can insert as many block as you want to, using "insert_block" method.

The insert_block method takes 2 parameters:
* the name of the block to insert.
* an associative array you can use to assign values to template variables of this block. In the example above, there are 4 parameters in the block (X, Y, LEFT and TOP).

== Nested blocks ==

You can use nested blocks. In the example below, we are going to add a mini-board for each player of the game, with 4 card places on each of it:

<pre>

(In template file)


<div class="miniboard" id="miniboard_{PLAYER_ID}">

<div class="card_places">

<div id="card_place_{PLAYER_ID}_{PLACE_ID}">
</div>

</div>

</div>


(In view file)

$this->page->begin_block( "mygame_mygame.tpl", "card_place" ); // Nested block must be declared first
$this->page->begin_block( "mygame_mygame.tpl", "player" );

foreach( $players as $player_id => $player )
{
// Important: nested block must be reset here, otherwise the second player miniboard will
// have 8 card_place, the third will have 12 card_place, and so one...
$this->page->reset_subblocks( 'card_place' );

for( $i=1; $i<=4; $i++ )
{
$this->page->insert_block( "card_place", array(
'PLAYER_ID' => $player_id,
'PLACE_ID' => $i
);
}

$this->page->insert_block( 'player', array( 'PLAYER_ID' => $player_id );
}

</pre>

== Javascript templates ==

For game elements that come and go from the game area, we suggest you to define a Javascript template.

A Javascript template is defined in your template file like this:

(Reversi Token from Reversi example):
<pre>
<script type="text/javascript">

// Templates

var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';

</script>
</pre>

Note: a section for javascript templates is already available at the end of your template skeleton file.

Then, you can use this javascript template to insert this piece of HTML in your game interface, like this:

<pre>
dojo.place( this.format_block( 'jstpl_disc', {
xy: x+''+y,
color: color
} ) , 'discs' );
</pre>

WARNING: always use lowercase for substitution variables in your Javascript templates, in order to avoid collision with PhpLib template variables (in particular, do not use ${ID}).

== How to access game information from .view.php? ==

From your .view.php, you can access the following:

=== Access current player id===

<pre>
global $g_user;
$current_player_id = $g_user->get_id();
</pre>

=== Access game object ===

In your view file, "$this->game" contains an instance of your main game class.

Example:
<pre>

// Access to some game elements description described in your "material.inc.php":
$my_cards_types = $this->game->card_types;

// Access to any (public) method defined in my .game.php file:
$result = $this->game->myMethod();
</pre>

== Tips: displaying a nice button ==

From time to time, you need to display a standard button in your interface. BGA framework provides you a standard button that you can use directly in your interface:

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

Note: To see it in action, check for example a Coloretto game

Game layout: view and template: yourgamename.view.php and yourgamename yourgamename.tpl

2018-01-14T09:27:42Z

Een: /* Javascript templates */

These 2 files work together to provide the HTML layout of your game.

Using these 2 files, you specify what HTML is rendered in your game client interface.

In <yourgame.tpl>, you can directly write raw HTML that will be displayed by the browser.

Example: extract of "hearts_hearts.tpl":

<pre>
<div id="myhand_wrap" class="whiteblock">
<h3>{MY_HAND}</h3>
<div id="myhand">
</div>
</div>
</pre>

== WARNING ==

Your view and your template are supposed to generate only the BASE layout of the game

You shouldn't try to setup the current game situation in the view: this is the role of your Javascript code. Why? Because you'll have to write Javascript code to put game elements in place anyway, and you don't want to write it twice :)

Example of things to generate in your view:
* The overall layout of your game interface (what is displayed where).
* The board and fixed elements on the board (ex: places for cards, squares, ...).

Example of things that shouldn't be generate by your view:
* Game elements that come and go from the game area.
* Game elements that normally hidden from players (other players cards, cards in the deck).

== phplib template system ==

BGA is using the phplib template system, used for example in PHPbb forums.

More details about how to use phplib template system here:
http://www.phpbuilder.com/columns/david20000512.php3

== Variables ==

In your template ("tpl") file, you can use variables. Then in your view (".view.php") file, you fill these variables with value.

In the example above, "{MY_HAND}" is a variable. As you can see, a variable is uppercase characters border by "{" and "}".

To give a value to this variable in your view.php:

Examples:
<pre>

// Display a translated version of "My hand" at the place of the variable in the template
$this->tpl['MY_HAND'] = self::_("My hand");

// Display some raw HTML material at the place of the variable
$this->tpl['MY_HAND'] = self::raw( "<div class='myhand_icon'></div>" );

</pre>

WARNING: do not use a variable called {id} as it will interfere with action buttons.

== Blocks ==

Using "blocks", you can repeat a piece of HTML from your template several time.

You should use "blocks" everytime you have a block of HTML that you have to repeat a big number of time. For example, for Reversi, we have to generate 64 (8x8) squares:

<pre>

(in reversi_reversi.tpl)

<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>


<div id="discs">
</div>
</div>

(in reversi.view.php)

$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}

</pre>

Explanations:
* You specify a block in your template file, using "BEGIN" and "END" keywords. In the example above, we are creating a block named "square".
* In your view, you declare your block using "begin_block" method.
* Then, you can insert as many block as you want to, using "insert_block" method.

The insert_block method takes 2 parameters:
* the name of the block to insert.
* an associative array you can use to assign values to template variables of this block. In the example above, there are 4 parameters in the block (X, Y, LEFT and TOP).

== Nested blocks ==

You can use nested blocks. In the example below, we are going to add a mini-board for each player of the game, with 4 card places on each of it:

<pre>

(In template file)


<div class="miniboard" id="miniboard_{PLAYER_ID}">

<div class="card_places">

<div id="card_place_{PLAYER_ID}_{PLACE_ID}">
</div>

</div>

</div>


(In view file)

$this->page->begin_block( "mygame_mygame.tpl", "card_place" ); // Nested block must be declared first
$this->page->begin_block( "mygame_mygame.tpl", "player" );

foreach( $players as $player_id => $player )
{
// Important: nested block must be reset here, otherwise the second player miniboard will
// have 8 card_place, the third will have 12 card_place, and so one...
$this->page->reset_subblocks( 'card_place' );

for( $i=1; $i<=4; $i++ )
{
$this->page->insert_block( "card_place", array(
'PLAYER_ID' => $player_id,
'PLACE_ID' => $i
);
}

$this->page->insert_block( 'player', array( 'PLAYER_ID' => $player_id );
}

</pre>

== Javascript templates ==

For game elements that come and go from the game area, we suggest you to define a Javascript template.

A Javascript template is defined in your template file like this:

(Reversi Token from Reversi example):
<pre>
<script type="text/javascript">

// Templates

var jstpl_disc='<div class="disc disccolor_${color}" id="disc_${xy}"></div>';

</script>
</pre>

Note: a section for javascript templates is already available at the end of your template skeleton file.

Then, you can use this javascript template to insert this piece of HTML in your game interface, like this:

<pre>
dojo.place( this.format_block( 'jstpl_disc', {
xy: x+''+y,
color: color
} ) , 'discs' );
</pre>

WARNING: always use lowercase for substitution variables, in order to avoid collision with PhpLib template variables.

== How to access game information from .view.php? ==

From your .view.php, you can access the following:

=== Access current player id===

<pre>
global $g_user;
$current_player_id = $g_user->get_id();
</pre>

=== Access game object ===

In your view file, "$this->game" contains an instance of your main game class.

Example:
<pre>

// Access to some game elements description described in your "material.inc.php":
$my_cards_types = $this->game->card_types;

// Access to any (public) method defined in my .game.php file:
$result = $this->game->myMethod();
</pre>

== Tips: displaying a nice button ==

From time to time, you need to display a standard button in your interface. BGA framework provides you a standard button that you can use directly in your interface:

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_gray"><span>My gray button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red"><span>My red button</span></a>
</pre>
<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_red bgabutton_big"><span>My big red button</span></a>
</pre>

Note: To see it in action, check for example a Coloretto game