Board Game Arena - User contributions [en]

Gamehelpproteus

2025-11-11T20:04:50Z

AmadanNaBriona: Created page with "***Background*** In ancient Greek mythology there was a sea god named Proteus. His most notable characteristic was that he could change his shape at will, from a man to a fish, a whale, a bird, or anything else. This most useful skill against opponents gave rise to the expression of being in a "Protean struggle." The Proteus game set is so named because the game can change its form — not its physical form, but rather the game rules themselves. How to play PROTEUS®..."

***Background*** In ancient Greek mythology there was a sea god named Proteus. His most notable characteristic was that he could change his shape at will, from a man to a fish, a whale, a bird, or anything else. This most useful skill against opponents gave rise to the expression of being in a "Protean struggle." The Proteus game set is so named because the game can change its form — not its physical form, but rather the game rules themselves.

How to play PROTEUS®

Players: Two.
Object: Attain the Goal in effect at the end of the turn.
Equipment: The Proteus board; 3 pieces per player; 9 engraved tiles.

The rule tiles:

The 9 tiles have markings on their face only. The backs are blank. There are 3 tiles in each of three colors. During the game, only one tile of each color may be face up (active) at a time. Here's what the inscriptions mean:

MOVE (maroon tiles)
Proteus pieces move like certain chess figures, with these exceptions: — a piece, except when moving as a king, may leap over another piece if there is an empty space on the other side of the piece being jumped over; there is no capturing. Active MOVE rules apply equally to all pieces. Only one piece allowed per space.

KING — moves like a chess king, one space in any direction.
ROOK — moves like a chess rook, any distance in the same row or column (horizontal or vertical).
BISHOP/KNIGHT — moves to any empty space not in the same row or column.

TRADE (turquoise tiles)
Two tiles may exchange places. Their relative positions don’t matter, nor whether they are face-up or face-down. Pieces, if any occupy them, stay put to await the new tile. Only one tile allowed per space. There are 27 different tile pair combinations for each of these:

POLARITY — both tiles to be traded must contain pieces, and the pieces must belong to opposing players. The symbols on the pieces don't matter.
COLOR — both tiles to be traded must be the same color. The color doesn't matter, and they need not be occupied.
SHAPE — both tiles to be traded must be the same shape. The shape doesn't matter, and they need not be occupied.

GOAL (gold tiles)
These tiles represent the three different ways a game can be won. The first method is just like Tic-Tac-Toe. The other two methods require that a player's 3 pieces occupy similar tiles, regardless of their relative positions on the board.

3-IN-LINE — The winning player's three pieces must be in a straight line, horizontally, vertically, or diagonally.
COLOR — the player's three pieces must occupy tiles of a single color; symbols on pieces need not match the tiles.
SHAPE — the player's three pieces must occupy tiles of the same shape.

Placement Phase

The board begins empty, with the 9 tiles spread around for easy selection in a common pool. Black places first.

Players take turns placing any of the tiles from the pool face-down onto any empty space of the board, or placing one of their own pieces onto any space already occupied by a vacant tile (never onto an empty space). Once placed, no piece or tile can be moved during this phase of the game.

When a piece and a tile of the same shape come together, that tile is turned face-up and becomes active. Its rule will stay in effect until another tile of the same color is activated.

During the 15 turns of the placement phase, one and only one tile of each color must be activated. They may be activated in any order and by either player. Once a tile is activated, no other tile of the same color can accept a piece of matching shape until after all tiles and pieces have been placed.

Plan ahead: it may happen that only one player can activate a tile and therefore must do so. For example, if two of the three tiles of a color are already occupied by non-matching pieces, only the third tile is still open for activation. If only one player has a piece of the requisite shape to activate that tile, that is a mandatory placement for that player.

Movement Phase

The movement phase begins when all the pieces and tiles are on the board and three tiles of different colors are active (provided the game was not already won during the placement phase).

Players take turns moving any one of their own pieces to a vacant tile (according to the active Move rule), or exchanging two tiles (according to the active Trade rule).

When, through a move or trade, a piece and tile of the same shape are brought together, that tile becomes activated. It is turned face-up, and the previously active tile of the same color is turned face-down. The new rule is now in effect for both players. If a trade of two inactive tiles of the same color produces two matches, they cancel each other and the previously active tile stays in effect.

The first player to satisfy the Goal active at the end of that turn is the winner. If both players simultaneously meet the goal, neither wins and the game continues until there is a clear winner.

Game material description: material.inc.php

2025-11-11T16:03:40Z

AmadanNaBriona: /* Testing */

{{Studio_Framework_Navigation}}

== Overview ==
'''IMPORTANT NOTE''': This file is not generated anymore by default, but you can still create it (the name is important as only a <code>material.inc.php</code> file at the root of your project will be automatically loaded) to describe the material of your game.

If you want to put all your material.inc.php in modules/php instead, please read [https://en.doc.boardgamearena.com/Game_material_description:_material.inc.php#Move_it_to_modules/php Move it to modules/php]

This file is included by the constructor of your main game logic (yourgame.game.php), and then the variables defined here are accessible everywhere in your game logic file (and also view.php file).

Using material.inc.php makes your PHP logic file smaller and clean. Normally you put ALL static information about your cards, tokens, tiles, etc in that file which do not change. Do not store static info in database.

== Definition ==
Example from "Eminent Domain":
<pre>
$this->token_types = [
'card_role_survey' => [
'type' => 'card_role',
'name' => clienttranslate("Survey"),
'tooltip' => clienttranslate("ACTION: Draw 2 Cards<br/><br/>ROLE: Look at <div class='icon survey'></div> - 1 planet cards, keep 1<br/> <span class='yellow'>Leader:</span> Look at 1 additional card"),
'b'=>0,
'p'=>'',
'i'=>'S',
'v'=>0,
'a'=>'dd',
'r'=>'S',
'l'=>'v',
],

'card_tech_1_51' => [
'type' => 'tech',
'name' => clienttranslate("Improved Trade"),
'b' => 3,
'p' => 'E',
'i' => 'TP',
'v' => 0,
'a' => 'i',
'side' => 0,
'tooltip' => clienttranslate("Collect 1 Influence from the supply."),
],

...
];
</pre>

So this defines all info about cards, including types, names, tooltips (to be show on client), rules, payment cost, etc.

You can also define PHP constants that can be used in material file and game.php file:

<pre>
if (!defined('TAPESTRY')) { // guard since this included multiple times
define("TAPESTRY", 0);
define("TRACK_EXPLORATION", 1);
define("TRACK_SCIENCE", 2);
define("TRACK_MILITARY", 3);
define("TRACK_TECHNOLOGY", 4);
}
</pre>

== Access ==

=== Data fields ===
To access this in PHP side:
$type = $this->token_types['card_tech_1_51']['type'];

To access on JS side you have to send all variables from material file via getAllDatas first:
protected function getAllDatas() {
$result = array ();
$result ['token_types'] = $this->token_types;
...
return $result;
}

Then you can access it in similar way:
var type = this.gamedatas.token_types['card_tech_1_51'].type; // not translatable
var name = _(this.gamedatas.token_types['card_tech_1_51'].name); // to be shown to user (NOI18N)

To send this in notification from PHP side:
$this->notifyAllUsers('gainCard',clienttranslate('player gains ${card_name}'), [
'i18n'=>['card_name'],
'card_id' => $card_id,
'card_name' => $this->token_types[$card_id]['name']
]);

=== PHP constants ===
If you also want to access constants in JS side, you can send them via getAllData like this

$cc = get_defined_constants(true)['user'];
$result['constants']=$cc; // this will be all constants though, you may have to filter some stuff out for security reasons

Alternately you can include a material.inc.php in local php file and call this method to print constants in JS format, then include this file in JS, you may have to synchronize this manually, but its better for auto-complete also.
// this needs to be run locally after including materal file (see example in testing below)
$cc = get_defined_constants(true)['user'];
foreach ($cc as $key => $value) {
print ("const $key = $value;\n");
}

== Testing ==
If you screw up your material file such as by missing some brackets, it is very hard to diagnose. But you can test it locally like this:

misc/material_test.php:
<pre>
<?php
class material_test {
function __construct() {
include '../material.inc.php';
var_dump($this->token_types); // whatever your var
}
}
// stub
function clienttranslate($x) { return $x; }

new material_test();
</pre>

== Adjusting material ==

In rare cases expansions of the game changes the materials of the original game. In such cases (for example, the same card was re-printed with a different text/rules),
can you keep same card and have material adjust based on selected game options? It is possible with some trickery.

You need to modify the data in that file AFTER constructor when database access is initialized, and have it available for all php entry points.
This is possible if you override function initTable() in your game.php file:
<pre>
/**
* This is called before every action, unlike constructor this method has initialized state of the table so it can
* access db
*
* @Override
*/
protected function initTable() {
// this fiddles with material file depending on the extension selected
$this->adjustMaterial();
}

function adjustMaterial($force = false) {
if ( !$force && $this->token_types_adjusted)
return;
$this->token_types_adjusted = true;
... // fiddle with data in material file
}
</pre>

To adjust material itself - you can do it in any number of ways I personally use this method: for modified values I specify key posfix that match my game option, and adjustment function re-write my keys, for example
<pre>
'card_tech_1_51' => [
'name' => clienttranslate("Improved Trade"),
'name@e3' => clienttranslate("Much Improved Trade"),
'cost' => 3,
'cost@p2' => 2
</pre>

In this example if player selects game expansion 3, the key name@e2 would override key name, and if there is 2 players, cost@p2 will override cost. If you need exact code, check adjustMaterial in Ultimate Railroads

Note: if you need to add some data to material.inc.php programmatically which does not require database, you can just do it right in that file. Keep in mind will run multiple time for each php call back, so it should be very light
<pre>
$this->decks = array (
'g' => array ('id' => 'green','name' => clienttranslate('Green'),'num' => 1 ),
'r' => array ('id' => 'red','name' => clienttranslate('Red'),'num' => 3 ),
'v' => array ('id' => 'violet','name' => clienttranslate('Violet'),'num' => 4 ),
'y' => array ('id' => 'yellow','name' => clienttranslate('Yellow'),'num' => 2 ) )
;

$this->dcolor_map = array();
// reverse map
foreach ($this->decks as $info) {
$this->dcolor_map[$info['num']]=$info['id'];
}
</pre>

== Move it to modules/php ==
You can move the file to any modules/php folder/subfolder, but it will not be included automatically, you'll need to import it.

<pre>
class Game extends Table {
private array $DECKS; // so the IDE knows you define an array called DECKS on the material file

function __construct()
{
parent::__construct();

require 'material.inc.php'; // your material.inc.php in modules/php folder contains $this->DECKS = [...]

$this->initGameStateLabels([]);
}

protected function getAllDatas(): array
{
// ...
// use it the same way
$result['DECKS'] = $this->DECKS;

return $result;
}
</pre>

Note: this way, you can use any file name and even split you material in multiple files if you want to.

[[Category:Studio]]

Testing by developer

2025-11-10T01:24:38Z

AmadanNaBriona:

When you develop a game you obviously have to test it, this page collects the info about testing in one place

== Manual Testing on BGA ==

For manual testing the most important things to know are:
* how to start/stop game in one click
* how to switch between players in one click
* how to save/restore the game state
* how to construct the game state automatically
All of these described here https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio

There is also HUGE checklist of things you need to test manually which you may not even think about, defined here https://en.doc.boardgamearena.com/Pre-release_checklist

== Manual Testing locally ==

'''HTML/CSS'''
At this era the file sync is almost instant so you do not save much by doing this locally, however if internet is a challenge - here are some tips
https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Speed_up_CSS_development_and_layout

'''PHP'''
You can run and debug php locally using tip https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

== Automated Testing ==
'''JavaScript'''

I have not tried it. If you have any success please add instructions here. Theoretically its is possible to hook something like selenium to studio games

'''PHP'''

You can hook up phpunit and write unit tests for php, for that you need stubs for framework functions and classes.

* Install php-cli (you need a verson that bga runs - consult https://en.doc.boardgamearena.com/Studio#Software_Versions)
* Install phpunit matching this specific php version (the latest does not work), if you use composer DO not install it in the game directory - install it somewhere else
* Create directory modules/tests
** If you do file sync - exclude it from the sync
* Checkout/get stubs from github (see https://en.doc.boardgamearena.com/Setting_up_BGA_Development_environment_using_VSCode), i.e
** git clone git@github.com:elaskavaia/bga-sharedcode.git
* So the main issue - php unit needs to find the parts of bga framework which is not available, in this example we will use stubs above
* Create autoload.php in modules/ directory
<pre>
<?php

define("APP_GAMEMODULE_PATH", getenv('APP_GAMEMODULE_PATH'));

spl_autoload_register(function ($class_name) {

switch ($class_name) {
case "APP_DbObject":
//var_dump($class_name);
//var_dump(APP_GAMEMODULE_PATH);
include APP_GAMEMODULE_PATH."/module/table/table.game.php";
break;
default:
include $class_name . ".php";
break;
}
});

?>
</pre>
* Set env var APP_GAMEMODULE_PATH to point to where stubs are, in this case APP_GAMEMODULE_PATH=$HOME/git/bga-sharedcode/misc/
* Create a test in tests/ folder (see phpunit examples)
<pre>
<?php declare(strict_types=1);
use PHPUnit\Framework\TestCase;

require_once "../mygame.game.php";

class GameUT extends MyGame {
function __construct() {
parent::__construct();
include "../material.inc.php";
}
// override/stub methods here that access db and stuff
}

final class GameTest extends TestCase {
public function testGameProgression() {
$m = new GameUT();
$this->assertEquals(0,$m->getGameProgression());
}
// more tests
}

</pre>
* Run this from modules/ dir (this assumes env var above already set globally)
phpunit --bootstrap autoload.php tests/

== Play testing on studio ==

To play test on studio you can use your test accounts dev0... dev9. You can give some of these account to other people just make sure you change the password.
You should not encourage other people who are not developers to create studio account, this is against bga policy.

Game interface logic: Game.js

2022-10-09T19:46:40Z

AmadanNaBriona: /* Destroy */

{{Studio_Framework_Navigation}}

__TOC__

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 a change from the server and how it will show in the browser.
* Setup user interface

== File structure ==

The details of how the file is structured are described below with comments in the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

'''setup(gamedatas: object) '''
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

* when the game starts
* when a player opens a game in the browser later
* when a player refreshes the game page (F5)
* when player does a server side Undo

"gamedatas" argument contains all data retrieved by your "getAllDatas" PHP method and some more.

'''onEnteringState(stateName: string, args: { args: any } | null): void'''

This method is called each time we enter a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling php arg* method use args?.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.
It is also called (for the current game state only) when doing a browser refresh (after the setup method is called).

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.
If you are doing initialization of some structures which do not depend on the active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

'''onLeavingState(stateName: string): void'''

This method is called each time we leave a game state.
You can use this method to perform some user interface changes at this point (i.e. cleanup).

'''onUpdateActionButtons(stateName: string, args: object | null): void'''

In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling php arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when the active or multiactive player changes. In a classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls depends on whether you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== Dojo framework ==

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

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing Players Information ==

'''player_id: number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)
if (notif.args.player_id == this.player_id) {
...
}

'''isSpectator: boolean'''
Flag set to true if the user at the table is a spectator (not a player).

Example:
<pre>
if (this.isSpectator) {
this.player_color = 'ffffff';
} else {
this.player_color = gamedatas.players[this.player_id].color;
}
</pre>

Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

You may consider making a function like this, to detect if the game is in a read-only state (i.e. non-interactive):
// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

'''gamedatas: object'''
Contains the initial set of data to init the game, created at game start or by 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, however most of the time this is unnecessary.

Note: In hotseat mode, the framework does not keep this.gamedatas of hotseat players and shares the same set as the main player to store data.

Note: be careful when you update this data structurally, many framework functions expect data to be certain way and they will break if they see something else.

Typical example of accessing player's info
<pre>
for (var player_id in this.gamedatas.players) {
var playerInfo = this.gamedatas.players [player_id];
var c = playerInfo.color;
var name = playerInfo.name;
// do something
}
</pre>

'''isCurrentPlayerActive(): boolean'''
Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.
if (this.isCurrentPlayerActive()) {

'''getActivePlayerId(): number'''
Return the ID of the active player, or null if we are not in an "activeplayer" type state.
if (this.player_id == this.getActivePlayerId()) ...

'''getActivePlayers(): number[]'''
Return an array with the IDs of players who are currently active (or an empty array if there are none).

== Accessing and manipulating the DOM ==

=== Element by Id ===

'''$(elementId: ElementOrId)'''

The $ function is used to get an HTML element using its "id" attribute.

Example: 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: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''getElementById(elementId: string)'''

Note: $() is the standard method to access some HTML element with the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.

=== Style ===

'''dojo.style(node: ElementOrId, styleName: string, styleValue: any): void'''

With dojo.style you can modify the CSS property of any HTML element in 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 sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

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

You can also use object to set multiple values
<pre>
dojo.setStyle("thinger", {
"opacity": 0.5,
"border": "3px solid black",
"height": "300px"
});
</pre>

'''addStyleToClass(cssClassName: string, styleName: string, styleValue: any):void'''

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

dojo.query(`.${aclass}`).style(styleName, styleValue)

<pre>
dojo.query("#baz > div").style({
opacity:0.75,
fontSize:"13pt"
});
</pre>

'''Vanila JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

=== Classes ===

'''dojo.addClass(node: ElementOrId, classes: string): void'''

'''dojo.removeClass(node: ElementOrId, classes: string): void'''

'''dojo.hasClass(node: ElementOrId, aclass: string): void'''

'''dojo.toggleClass(node: ElementOrId, aclass: string): void'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications 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 without error.
* You can test whether you applied the CSS to an element with the '''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 changes in one line of code.

// ... and when we need to check if a square is a possible move on the 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>

'''Vanila JS classList'''

This is the only exception where dojo versions are better
// add class
$(token_id).classList.addClass('possibleMove');
// remove class
$(token_id).classList.removeClass('possibleMove');
// add 2 classes
const myclasses = ['a','b'];
$(token_id).classList.addClass(...myclasses);
// add classes to query result
document.querySelectorAll(".hand .card").forEach((node)=>node.classList.addClass('possibleMove'));

=== Attributes ===

;dojo.attr

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanila JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

=== Queries ===

'''dojo.query(cssSelector: string): Element[]'''

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 (i.e., elements of class "token") on the board (i.e., the 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>

'''Vanila JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

=== Creating and Destroying elements ===

'''dojo.empty(node: ElementOrId)'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy(node: ElementOrId)'''

Remove the element
dojo.destroy('my_token');

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create(tag: string, attributes?: obj, parent?: ElementOrId): Element'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''this.format_block(name: string, args: object): string'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.format_string(name: string, args: object): string'''
This bga function just substitute variables in a string, i.e.
<pre>
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );
</pre>
Note: result is trimmed

Note: this can be replaced by using backquoted string now:
const player_color = '#ff0000';
const div = `<div color="${player_color}"></div>`;

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

TODO: find better place for these function docs

=== Moving elements ===

'''dojo.place(node: string | Element, refNode: ElementOrId, pos?: string | number): Element'''

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

node:

Can be a String or a DOM node. If it is a string starting with “<”, it is assumed to be an HTML fragment, which will be created. Otherwise it is assumed to be an id of a DOM node.

<pre>
// Insert your HTML code as a child of a container element
dojo.place( "<div class='foo'></div>", "your_container_element_id" );
</pre>

pos:

Optional argument. Can be a number or one of the following strings: “before”, “after”, “replace”, “only”, “first”, or “last”. If omitted, “last” is assumed.

"replace": Replace the container element with my_node element

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

"last" (default): 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.

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

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

positive integer: This parameter can be a positive 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.

<pre>
// Replace all children of container with my_node
dojo.place( $('my_node'), "your_container_element_id", "only" );
</pre>

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

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]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''placeOnObject(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

places mobile_obj on target_obj, set the absolute positions and centers the mobile_obj on target_obj,
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>

'''placeOnObjectPos( mobile_obj: ElementOrId, target_obj: ElementOrId, target_x: number, target_y: number ): void'''

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

''Note: the placement works differently from this.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.attachToNewParent(mobile_obj: ElementOrId, target_obj: ElementOrId): void'''

With this method, you change the HTML parent of "mobile_obj" element without moving it.
"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.

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).
If you need version that does not destroy the object but the same otherwise see [[BGA_Studio_Cookbook#Attach_to_new_parent_without_destroying_the_object]]

== 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.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

===Sliding===

'''slideToObject(mobile_obj: string | Element, target_obj: string | Element, duration?: number, delay?: number): Animation'''

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>

'''slideToObjectPos(mobile_obj: string | Element, target_obj: string | Element, target_x: number, target_y: number, duration?: number, delay?: number ): Animation'''

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 from the top:
<pre>
this.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''slideTemporaryObject( mobile_obj_html: string, mobile_obj_parent: string | Element, from: string | Element, to: string | Element, duration?: number, delay?: number ): Animation'''

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' ).play();
</pre>

===Destroy===
'''slideToObjectAndDestroy: function(mobile_obj: string | Element, target_obj: string | Element, duration?: number, delay?: number): void'''

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, but it starts the animation.

CAREFUL: Make sure nothing is creating the same object at the same time the animation is running, because this will cause some random disappearing effects

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

'''fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):void'''

This function fade out the target node, then destroy it. Its starts the animation.
* duration/delay works exactly like in "slideToObject"

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.
Make sure nothing is creating same object at the same time as animation is running, because you will be some random dissapearing effects

===Rotating elements===

This example combines "Dojo.Animation" method and a CSS property transform that allow you to rotate the element.
<pre>
// node is Element we rotating
var animation = new dojo.Animation({
curve: [fromDegree, toDegree],
onAnimate: (v) => {
node.style.transform = 'rotate(' + v + 'deg)';
}
});

animation.play();
</pre>

BGA has its own interface to rotate

'''rotateTo(node: string | Element, degree: number): void'''

It starts the animation, and stored the rotation degree in the class, so next time you rotate object - it is additive.
There is no animation hooks in this one, if you need to change any parameters use dojo animation above.

There is also '''rotateInstantTo''' with same signature which does not animate

===Animation Callbacks===

If you wish to run some code only after an animation has completed you can do this by linking a callback method to 'onEnd'.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, 500 );
dojo.connect(animation_id, 'onEnd', ()->{
// do something here
});
animation_id.play();
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

== Players input ==

=== Connecting ===
'''dojo.connect(element: ElementOrId, event: string, context: object, method: eventHandler): any'''

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

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

Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: if you need to disconnect the handler you have to store handler returned from this method, i.e.

<pre>
var handler = dojo.connect(...);
...
dojo.disconnect(handler);
</pre>

If you don't store the handler - you have to destroy the object to disconnect it

Typical function that implements the input handler will look like this

<pre>
onPet: function(event) {
var id = event.currentTarget.id;
console.log('onPet ' + id);
dojo.stopEvent(event);
if (this.gamedatas.gamestate.name == 'playerTurnPet') {
this.ajaxcallwrapper('playPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''connect(element: ElementOrId, event: string, method: eventHandler): void'''

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

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.

'''connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
<pre>
this.connectClass('pet', 'onclick', 'onPet');
</pre>

'''disconnect(element: ElementOrId, event: string): void'''

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

;disconnectAll()

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

this.disconnectAll();

=== Actions ===
'''this.ajaxcall(url, parameters, obj_callback, callback, callback_anycase?, ajax_method?: string)'''

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions or break replay game and tutorial features. It should be used only in reaction to a user action in the interface.

* 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 parameters in order the interface can be locked during the server call. Cannot use lock: false - to not lock it has to be undefined.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback (non-optional but rarely used): a function to trigger when the server returns result and everything went fine (not used, as all data handling is done via notifications).
* callback_anycase: (optional) a function to trigger when the server returns ok OR error. If no error this function is called with parameter value false.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = {};
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''checkAction(action: string, nomessage?: boolean): boolean '''

Check if player can do the specified action by taking into account:
* if interface is locked it will return false and show message "An action is already in progress", unless nomessage set to true
* if player is not active it will return false and show message "This is not your turn", unless nomessage set to true
* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

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

'''checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario. Unlike this.checkAction, this function does NOT take interface locking into account

* if action is not in list in possible actions (defined by "possibleaction" in current game state) it will return false and show "This move is not authorized now" error (unconditionally).
* otherwise returns true

function onChangeMyMind( evt ) {
if( this.checkPossibleActions( "my_action" ) ) {
// Do the action
}
}

'''checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors. Note: normally you only need to use this.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.checkLock() ) {
// Do the action
}
}

== 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 all notifications arguments with "notif.args".

Example:

PHP

<pre>
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );
</pre>

JavaScript

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

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* type - type of the notification (as passed by php function)
* log - the log string passed from php notification
* args - This is the arguments that you passed on your notification method on php
* bIsTableMsg - is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig - information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig - name of the game
* move_id - ID of the move associated with the notification
* table_id - ID of the table (comes as string)
* time - UNIX GMT timestamp
* uid - unique identifier of the notification
* h - unknown

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== Ignoring notifications ===
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring.

NOTE: You can think that it would be possible to send such notification to all players except active just by using notifyPlayer and it seems to work. The problem however is that table spectators would miss such notification and their user interface (and game log) wouldn't be updated. Since there is no way to send notification just to spectators, ignoring the notification (or "filtering") is the only reasonable solution.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notif_type: type of the notification
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

Before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored, if it return true - the notification will be dispatched, i.e. logged or handled.

<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should '''preserve''' it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== 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, there 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>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

'''WARNING: combining synchronous and ignored notifications'''
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== 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 (technically any unhandled notification will do the same but its recommended to use this keyword for consistency)

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

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

Note: the following types are RESERVED by framework, do not use:

gameStateChange gameStateChangePrivateArg gameStateMultipleActiveUpdate newActivePlayer playerstatus yourturnack clockalert tableInfosChanged playerEliminated tableDecision archivewaitingdelay end_archivewaitingdelay replaywaitingdelay end_replaywaitingdelay replayinitialwaitingdelay end_replayinitialwaitingdelay aiPlayerWaitingDelay replay_has_ended updateSpectatorList wouldlikethink updateReflexionTime undoRestorePoint resetInterfaceWithAllDatas zombieModeFail zombieModeFailWarning aiError skipTurnOfPlayer zombieBack allPlayersAreZombie gameResultNeutralized playerConcedeGame showTutorial showCursor showCursorClick skipTurnOfPlayerWarning banFromTable resultsAvailable switchToTurnbased newPrivateState infomsg

== Tooltips ==

'''this.addTooltip( nodeId, helpStringTranslated, actionStringTranslated, delay )'''

Add a simple text tooltip to the DOM node.

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

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. 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 browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

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

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique

'''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, helpStringTranslated, actionStringTranslated, delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and 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 exist and have IDs to get tooltips.

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

Remove a tooltip from the DOM node with given id.

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

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

=== Warning messages ===

Sometimes, there is something important that is happening in 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 fulfills one of the end of the game conditions, so this is the last turn.

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

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

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", "only_to_log" or custom string. 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 and it will be added to log. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.
If set to custom string, it will be transparent, to use other stype define "head_xxx" in css, where xxx is the type. For example if you want yellow warning, use "warning" as type and add this to css:
.head_warning {
background-color: #e6c66e;
}

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.

<pre>
notif_messageinfo: function(notif) {
if (!g_archive_mode) {
var message = this.format_string_recursive(notif.log, notif.args);
this.showMessage(_('Announcement:') + " " + message, 'info');
}
},
</pre>

Show message could be used on the client side to prevent user wrong moves before it is send to server.
Example from 'battleship':
<pre>
onGrid(event) {
if (checkIfPlayerTriesToFireOnThemselves) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

;showMoveUnauthorized()

Shows predefined user error that move is unauthorized now

=== 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 guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations 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 does 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?'), () => {
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,
(choice) => {
var bugchoice = keys[choice];
console.log('dialog callback with '+bugchoice);
this.ajaxcall( '/mygame/mygame/fixBugs.html', { bugs: bugchoice}, this, function( result ) {} );
}
);
</pre>

=== Dialogs ===

As a general rule, 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 over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// 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.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.destroy();
} );

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback( function() { ... } );

=== 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" => clienttranslate("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:

'''displayScoring( anchor_id:string, color:string, score:number|string, duration?:number, offset_x?:number, offset_y?: number ):void'''

'''anchor_id''': ID of the element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+' or '-'

'''duration''': animation duration in milliseconds (optional, default is 1000)

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation. Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.
<pre>
setupNotifications: function() {
dojo.subscribe( 'displayScoring', this, "notif_displayScoring" );
...
}
...

notif_displayScoring: function(notif) {
const duration = notif.args.duration?notif.args.duration:1000;
this.notifqueue.setSynchronous('displayScoring', duration );
this.displayScoring( notif.args.target, notif.args.color, notif.args.score, duration);
},
</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 showBubble:

'''showBubble(anchor_id: string, text: string, delay?: number, duration?: number, custom_class?: string)'''

anchor_id - where to attach the bubble

text - what to put in bubble, can be html actually not just text

delay - in milliseconds is optional (default 0)

duration - in milliseconds is optional (default 3000)

custom_class - extra class to add to bubble is optional, if you need to override the default bubble style

<pre>
this.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.format_string_recursive(notif.args.text, notif.args.args);
this.showBubble(notif.args.target, html, notif.args.delay, notif.args.duration);
},
</pre>

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Translations ==

See [[Translations]]

== Players panels ==

=== Update players score ===

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the game setup() function. However this score must be updated as the game progresses using notifications.

Note: this.scoreCtrl[player_id] is object of class [[Counter]], you can use other counter API.

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>

Set a player score to a specific value with animation:

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

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_score);
},
</pre>

=== 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: number):void'''

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:number):void'''

Enable a player panel that has been disabled before.

'''this.enableAllPlayerPanels():void'''

Enable all player panels that has been disabled before.

=== Counters ===
Note: there is bga component called "ebg/counter" this API is not using it, these methods
below declared right in core game. If you need animation for counters use ebg/counter

To use this API just create a counter dom element like this (class does not really matter)
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
The "bread" will the counter name.

The php code should send all "counters" data from getAllDatas() method like this

game.php
<pre>
protected function getAllDatas() {
// (the key must match counter_name)
$result['counters']=[
'bread' => [
'counter_name' => 'bread',
'counter_value' => 3
],
'coin' => [
'counter_name' => 'coin',
'counter_value' => 5
]
];
return $result;
}
</pre>

'''setCounter(counter_name:stirng, new_value: string | number): void
updates the global this.gamedatas.counters and value of node $(counter_name)
<pre>
notif_counter: function(notif) {
this.setCounter(notif.args.counter_name, notif.args.counter_value);
},
</pre>

'''incCounter(counter_name:string, delta: number): void
<pre>
notif_counter : function(notif) {
this.incCounter(notif.args.counter_name, notif.args.inc);
},
</pre>

'''updateCounters(counters: object): void'''

Useful for updating game counters in the player panel (such as resources).
'counters' arg is map of counters (the key must match counter_name)
{
'bread': {
'counter_name' : 'bread',
'counter_value' => 3
},
'coin': {
'counter_name' : 'coin',
'counter_value' => 5
}
}
All counters MUST be referenced in this.gamedatas.counters (means they should be send from php) and will be updated.
DOM objects referenced by 'counter_name' will have their innerHTML updated with 'counter_value'.

Usually you call this from notification

<pre>
notif_counter : function(notif) {
this.updateCounters(notif.args.counters);
},
</pre>

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

== BGA Buttons ==

=== Basic Button ===
'''addActionButton( id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?:string): void'''

You can use this method to add an action button in the main action status bar (or other places).

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). Note: this can also be any html, such as "<div class='brick'></div>", see example below on how to make image action buttons.
* method: the name of your method that must be triggered when the player clicks on this button (can be name of the method on game class or handler).
* destination (optional): id of parent on where to add button, ONLY use in rare cases if location is not action bar. 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 DO NOT abuse blinking button. If you need button to blink after some time passed add class 'blinking' to the button later.
* color: could be '''blue''' (default), '''red''','''gray''' or '''none'''.

You should only use this method in your "onUpdateActionButtons" method. Usually, you use it like this:

<pre>
onUpdateActionButtons: function( stateName, args ) {
if (this.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.addActionButton( 'giveCards_button', _('Give selected cards'), 'onGiveCards' );
this.addActionButton( 'pass_button', _('Pass'), ()=>this.ajaxcallwrapper('pass') );
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( 'button_confirm', _('Confirm?'), 'onConfirm', null, true, 'red');
</pre>

If you want to call the handled with arguments, you can use arrow functions, like this:
<pre>
this.addActionButton( 'commit_button', _('Confirm'), () => this.onConfirm(this.selectedCardId), null, false, 'red');
</pre>

=== Image Button ===

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, null, false, bcolor);
// remove boarder, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add additional styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

=== Disabling Button ===

You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>
this.addActionButton('play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton');
if (condition) {
dojo.addClass('play_button_id', 'disabled');
}
</pre>

=== Custom Buttons ===

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<pre>
<a href="#" id="my_button_id" class="bgabutton bgabutton_blue"><span>My blue button</span></a>
</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 out ''Coloretto''.

=== Button outside of action bar ===

Use addActionButton() method with destination argument set
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', 'player_board', true, 'red');
</pre>

== 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: string)'''

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' );
}

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.

'''ensureSpecificGameImageLoading(list: string[])'''

This is oppostive of dontPreloadImage - its ensure specific images is loaded. Note: only makes sense if preload list is empty, otherwise everything is loaded anyway

'''load specific images'''
All images that will be preloaded stored in g_img_preload. If you want to override it directly - there is no API, but you can do this in GAME constructor

g_img_preload = ['tokens.png', 'trains.png', 'loc_plan.png', 'eng.png', 'eng-back.png'];

You can also set it to empty array and call ensureSpecificGameImageLoading() on specific images

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file with the names <code><gamename>_<yoursoundname>[.ogg][.mp3]</code>.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>'); // do not add 'this.' - its a global function
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

== Title bar and states ==

=== Client states ===

Client states is a way to simulate the state transition but without actually going
to server. It is usefull when you need to ask user multiple questions before you
send things to server

'''setClientState(newState: string, args: object)'''

Example:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});

For more information see [[BGA_Studio_Cookbook#Multi_Step_Interactions:_Select_Worker.2FPlace_Worker_-_Using_Client_States]]

'''restoreServerGameState()'''
If you are in client state it will restore the current server state (cheap undo)

'''this.on_client_state'''
Boolean indicating that we are in client state

=== Title bar ===
If you simply want to show something in title bar you can do it directly
$('pagemaintitletext').innerHTML = text;

This however will not work with parameters and will not draw You in color,
if you want to do proper args rendering use method below

;'''removeActionButtons()'''
Removes all buttons from title bar

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function allows to update the turn description without changing state.

Note: this functional also will call onUpdateActionButtons, if you want different buttons, use method in example to replace them

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

== 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 ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains reply number in live game, it is set to undefined (i.e. not set) when it is not a reply mode, so consequentially the good check is '''typeof g_replayFrom != 'undefined'''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

; g_tutorialwritten
: Returns an object like the below if the game is in tutorial mode, or undefined otherwise. Tutorial mode is a special case of archive mode where comments have been added to a previous game to teach new players the rules.
{
author: "91577332",
id: "576",
mode: "view"
status: "alpha"
version_override: null
viewer_id: "84554161"
}

[[Category:Studio]]

BGA Code Sharing

2022-10-05T01:53:06Z

AmadanNaBriona: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode
| Code can be found in project
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Disjktra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
|}

== 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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Innovation
| https://github.com/micahstairs/bga-innovation
| Micah Stairs (micahstairs)
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
| The Lady and the Tiger (Doors)
| https://github.com/Fnordistan/ladyandthetiger
| AmadanNaBriona
|-
| For-Ex
| https://github.com/Fnordistan/forex
| AmadanNaBriona
|-
| In the Year of the Dragon (10th Anniversary Edition)
| https://github.com/Fnordistan/ityotd
| AmadanNaBriona
|-
| Perikles
| https://github.com/Fnordistan/perikles
| AmadanNaBriona
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).
The list below are no-games which do not have bgg id and not showing up there.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| https://studio.boardgamearena.com/gamepanel?game=sharedcode
| Victoria_La
|-
| Original BGA template
| https://studio.boardgamearena.com/gamepanel?game=template
| Victoria_La
|-
|}

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

BGA Code Sharing

2022-10-05T01:51:35Z

AmadanNaBriona: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode
| Code can be found in project
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Disjktra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
|}

== 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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Innovation
| https://github.com/micahstairs/bga-innovation
| Micah Stairs (micahstairs)
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
| The Lady and the Tiger (Doors)
| https://github.com/Fnordistan/ladyandthetiger
| AmadanNaBriona
|-
| For-Ex
| https://github.com/Fnordistan/forex
| AmadanNaBriona
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).
The list below are no-games which do not have bgg id and not showing up there.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| https://studio.boardgamearena.com/gamepanel?game=sharedcode
| Victoria_La
|-
| Original BGA template
| https://studio.boardgamearena.com/gamepanel?game=template
| Victoria_La
|-
|}

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

BGA Code Sharing

2022-10-05T01:50:16Z

AmadanNaBriona: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode
| Code can be found in project
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Disjktra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
|}

== 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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Innovation
| https://github.com/micahstairs/bga-innovation
| Micah Stairs (micahstairs)
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).
The list below are no-games which do not have bgg id and not showing up there.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| https://studio.boardgamearena.com/gamepanel?game=sharedcode
| Victoria_La
|-
| Original BGA template
| https://studio.boardgamearena.com/gamepanel?game=template
| Victoria_La
|-
|}

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

Game meta-information: gameinfos.jsonc

2022-10-01T18:37:07Z

AmadanNaBriona: /* Multiple tie breaker management */

{{Studio_Framework_Navigation}}

__TOC__

== Overview ==

From this file, you can edit the various meta-information of your game.

Once you modified the file, don't forget to click on "Reload game informations" from the Control Panel in order in can be taken into account.

Note: if you broke gameinfos and cannot load management page reload using direct URL https://studio.boardgamearena.com/admin/studio/reloadGameInfos.html?game= (with your game name at the end of url).

Most information provided in this file are self-explainable.

See sections below for specific cases.

== Publisher/Designer fields ==

These fields should match the publisher/designer for the game. In the case of a public domain name, they should be left empty (empty string '')

== Beta ==

You are not allowed to set the "'''is_beta'''" to 0 before the game has been released on BGA and stabilized.

== Time Profiles ==
'''fast/medium/slow_additional_time''': please set high values here: after the game has been released, we will lower these value to match the real game duration.

== Number of players ==

'''players'''
'players' => array( 3, 4, 6 ),

* during the first step of development of a game, it is recommended to have "1 player" configuration: much easy to start/stop a game this way, don't need to switch players.
* if you change the minimum number of players from for example 1 to 2, make sure the new tables you create are not restricted from 1 to 1 player otherwise when you create a new table and this account setting is used, there will be a conflict with the new minimum number of players allowed and you will be blocked from creating the game.
But you can also unblock yourself by changing player number again, launching a game with a larger number, and then getting back to the numbers you want.

'''suggest_player_number''' / '''not_recommend_player_number'''
don't specify anything here if there is no configuration that is REALLY better/worst than another one. You can check player's poll on BoardGameGeek game page if you have any doubt. '''Important exception:''' in the automatic lobby, if 'suggest_player_number' is not specified, the system will try first the lowest. So if the lowest player number is not compatible with the default options for your game (especially if there is a Solo mode that can only be played in training mode) you have to specify a suggest_player_number of your choice, so that players launching a game in the automatic lobby without checking the option don't get an error with the default configuration.

== Colors ==

'''player_colors'''
'player_colors' => array( "ff0000", "008000", "0000ff", "ffa500", "ffffff" ),

This array defines the default player colors, theoretically this can be bigger then maximum number of players but you have to support all of the in your game.
Your setupNewGame in php is responsible for attributing these values to players. See section "Player color preferences" in [[Main_game_logic:_yourgamename.game.php]] for details.

== Losers not ranked between themselves ==

By default, all player are ranked, but in some games, the rules say that there is only one winner and that all the other players are losers and not ranked between themselves. You can set this option to true so that for your game, there is only one winner and losers, without a full ranking of all players.

The score in this case should be 1 for the winner and 0 for the losers.

// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => false,

== Disable player rotation in case of rematch ==

By default, in case of a rematch players are rotated so that the first player changes. If for your game it's better to always have a random player order you can change this option.

// When doing a rematch, the player order is swapped using a "rotation" so the starting player is not the same
// If you want to disable this, set this to true (even if the comment in your game file say the opposite).
'disable_player_order_swap_on_rematch' => false,

== Custom "buy this game" button ==

By default, the "buy this game" button is a link to an Amazon search with the name of the game.

You can replace it by a different URL / game button label with :

'custom_buy_button' => array(
'url' => 'http://yoururl.com',
'label' => 'Name of the website'
),

Note : button label will be "Buy on <Name of the website>"

== Tags ==

A maximum of '''ten''' tags can be attributed to your game (not counting complexity and duration tags).

Tags are useful to place your game in the correct game list section and to give a good quick overview of what the game is about to players.

'''⚠ Note''': The ''order'' of the tags is very important too, you'll have to put the most relevant first.

'''⚠ Note''': tags are <b style="color:darkred">only read during the first deploy</b> from the file <code>gameinfos.inc.php</code> ; afterwards, setting tags for a game is done via the [[Game_metadata_manager|Game Metadata Manager]].

Game complexity (you '''must''' specify one tag '''and only one''' from this category):
* <code>2</code>: Casual games
* <code>3</code>: For regular players
* <code>4</code>: For core gamers

Duration tags (only indicative - the correct tag will be automatically set by BGA after a while):
* <code>10</code>: Short game (<10 minutes)
* <code>11</code>: Medium length game (10 minutes to 30 minutes)
* <code>12</code>: Long game (>30mn)

Other tags:
* <code>20</code>: Awarded game (Win a prestigious award) (the game must have been at the '''first''' place of one the [http://boardgamegeek.com/wiki/page/Gaming_Industry_Awards# following major awards list]).
* <code>22</code>: Prototype (This game has not been published yet)
* <code>23</code>: Classic (This game is a classic from Public Domain)
* <code>25</code>: Party game
* <code>26</code>: Family
* <code>27</code>: Miniatures (figurines)
* <code>28</code>: Recommended in Realtime
* <code>29</code>: Recommended in Turnbased
* <code>30</code>: Best for 2 (best with 2 players) (automatically added to games for 2p only)

Theme tags:
* <code>100</code>: Fantasy
* <code>101</code>: Science-Fiction
* <code>102</code>: Historical
* <code>103</code>: Adventure
* <code>104</code>: Exploration
* <code>105</code>: Conquest
* <code>106</code>: Building
* <code>107</code>: Western
* <code>108</code>: Espionage
* <code>109</code>: Trains
* <code>110</code>: Sport
* <code>111</code>: Economy
* <code>112</code>: Aviation
* <code>113</code>: Surreal/Silly/Absurd
* <code>114</code>: Animals
* <code>115</code>: Wargame
* <code>1</code>: Abstract game

Mechanism tags:
* <code>200</code>: Cards (cards plays a central role in this game)
* <code>201</code>: Dice
* <code>202</code>: Solo
* <code>203</code>: Worker placement
* <code>204</code>: Hand management
* <code>205</code>: Bluffing
* <code>206</code>: Tile placement
* <code>207</code>: Combos
* <code>208</code>: Area Majority
* <code>209</code>: Race
* <code>210</code>: Collection
* <code>211</code>: Cooperative
* <code>212</code>: Random
* <code>213</code>: Speed
* <code>214</code>: Asymmetrical
* <code>215</code>: Communication
* <code>216</code>: Conquest
* <code>217</code>: Team
* <code>218</code>: Bidding
* <code>219</code>: Objectives
* <code>220</code>: Trick-taking
* <code>221</code>: Resource management
* <code>222</code>: Roles
* <code>223</code>: Roll & Write
* <code>224</code>: Push your luck
* <code>225</code>: Voting
* <code>226</code>: Word games
* <code>227</code>: Deck Building
* <code>228</code>: Engine building
* <code>229</code>: Drafting
* <code>230</code>: Player elimination

== Game Presentation ==

Short game presentation text that will appear on the game description page, structured as an array of paragraphs.

Each paragraph must be wrapped with totranslate() for translation and should not contain html (plain text without formatting). A good length for this text is between 100 and 150 words (about 6 to 9 lines on a standard display)

Example:
'presentation' => array(
totranslate("This wonderful game is about geometric shapes!"),
totranslate("It was awarded best triangle game of the year in 2005 and nominated for the Spiel des Jahres."),
...
),

== Tie breaker description ==
Describe tie breaker score calculation (player_score_aux in player table).

Important: This is used in the javascript too, which is automatically generated. Using newlines in here will cause errors in the javascript, which will cause the game to not load.

Example:
'tie_breaker_description' => totranslate("Number of remaining cards in hand"),

== Multiple tie breaker management ==

If your game has multiple tie breakers, here is what you should do.

Let's take this example: "In case of a tie, the winner is the game with the most remaining money, then number of buildings built, then number of cards in your hand".

In this example, your "player_score_aux" field might be calculated like this:

10000 * (remaining_money ) + 100 * (buildings_built) + (number_of_cards)

In this case, you should add the following in gameinfos.inc.php:

'tie_breaker_split' => array( 10000, 100 , 1 ),

It means that the first tie breaker has been multiplied by 10000, the second by 100, and the third by 1.

Using this, the result screen will be adapted to show exactly what is needed. For example:
* When 2 players are tied, it will show their remaining money.
* If their remaining money are equal, it will show the number of building built in addition to the remaining money.
* If these two tie breaker are still the same, it will show the 3 tie breaking values.

== Language dependency ==

If you have a game that is language dependent, you can use the option described here: [[Main_game_logic:_yourgamename.game.php#Language_dependent_games_API]]

== Game page warning ==

If a specific warning is needed on the game page (to discuss and validate with admins) it can be displayed from the game infos. For example for Texas Hold'em:

'gamepanel_page_warning' => totranslate("There is no real money involved on BGA: this game has the mechanism of Poker but is using points instead of real money."),

== Coop Elo Mode ==

For cooperative games, by default players will earn as many Elo points as the score.

For games where there is no variable difficulty (such as for example Bandido) we keep that setting, but for all coop games where we have options to change the difficulty level and/or where the score reached indicates a higher level of skill and/or where the number of players has a significant impact on the difficulty, we have to set up a reference scale for Elo points (between 1300 and 2500). Players regularly winning with a specific difficulty setting will have their Elo nearing this value asymptotically over time.

For this, you have to set up the coop_elo_mode parameter.

'''Warning: While this can reflect player skills more precisely compared to flat ELO gain, players may abandon losing games or avoid new players to prevent ELO loss.'''

Related discussion - https://forum.boardgamearena.com/viewtopic.php?f=3&t=24363

Here is an example using options and win/loss (score 1/0):

'coop_elo_mode' => [
'type' => 'points_references',
'references' => [
// Difficulty 1
['players_nbr' => 2, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 2, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1350]],
['players_nbr' => 3, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 0], 'elo' => [0 => 1000, 1 => 1400]],
['players_nbr' => 4, 'options' => [100 => 1, 101 => 1], 'elo' => [0 => 1000, 1 => 1470]],
// Difficulty 2
['players_nbr' => 2, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 2, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1450]],
['players_nbr' => 3, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 4, 'options' => [100 => 2, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
// Difficulty 3
['players_nbr' => 2, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 2, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1540]],
['players_nbr' => 3, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 0], 'elo' => [0 => 1000, 1 => 1690]],
['players_nbr' => 4, 'options' => [100 => 3, 101 => 1], 'elo' => [0 => 1000, 1 => 1910]],
// Difficulty 4
['players_nbr' => 2, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 2, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1640]],
['players_nbr' => 3, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 0], 'elo' => [0 => 1000, 1 => 1830]],
['players_nbr' => 4, 'options' => [100 => 4, 101 => 1], 'elo' => [0 => 1000, 1 => 2120]],
// Difficulty 5
['players_nbr' => 2, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 2, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1740]],
['players_nbr' => 3, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 0], 'elo' => [0 => 1000, 1 => 1980]],
['players_nbr' => 4, 'options' => [100 => 5, 101 => 1], 'elo' => [0 => 1000, 1 => 2340]],
],
],

Here is an example using different scoring values to indicate the level of difficulty mastered by the players winning the game:

'coop_elo_mode' => array(
'type' => 'points_references',
'references' => array(
array(
'players_nbr' => 2,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1350,
2 => 1425,
3 => 1500,
4 => 1576,
5 => 1651,
6 => 1727,
7 => 1802,
8 => 1878,
9 => 1953,
10 => 2029,
11 => 2104,
12 => 2180
)
),
array(
'players_nbr' => 3,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1400,
2 => 1470,
3 => 1541,
4 => 1612,
5 => 1683,
6 => 1754,
7 => 1825,
8 => 1895,
9 => 1966,
10 => 2018,
11 => 2095,
12 => 2250
)
),
array(
'players_nbr' => 4,
//'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1430,
2 => 1505,
3 => 1580,
4 => 1655,
5 => 1730,
6 => 1805,
7 => 1880,
8 => 1955,
9 => 2030,
10 => 2105,
11 => 2180,
12 => 2330
)
),
array(
'players_nbr' => 5,
// 'options' => array( ),
'elo' => array(
0 => 1000,
1 => 1480,
2 => 1558,
3 => 1636,
4 => 1714,
5 => 1792,
6 => 1870,
7 => 1949,
8 => 2027,
9 => 2105,
10 => 2183,
11 => 2261,
12 => 2340
)
)
)
),

[[Category:Studio]]

Table

2022-10-01T17:08:02Z

AmadanNaBriona: /* Selected static methods in utility modules */

This is reference for public and protected method defined in Table and its ancestors, this information obtained by using php reflection.

Most of these methods documented on various other wikis, this is just refeference for completeness and in case you run into accidental overloading of undocumented functions...

<span style="color:red">
Its a long list please help with editing this wiki
</span>

If you need these method for IDE autocompletion and validation there is unofficial project that has stubs to documented methods:
* https://github.com/elaskavaia/bga-sharedcode/blob/master/misc/module/table/table.game.php (if you want more stubs pull requests are welcome to this repo)
* https://github.com/danielholmes/bga-workbench/tree/master/src/BGAWorkbench/Stubs (not sure who is supporting this one)

== Class hierarchy ==

* APP_Object
** APP_DbObject
*** APP_GameClass
**** Table - this is a class all games inherit
**** [[Deck]] - db handling component for specific schema (deck)

== Methods in the Table class ==

;Table.getGameName
:part of template, return game name, not to be modified by developer, not document on wiki
;Table._
:translation wrapper function, see [[Translations]]
;Table.setTable
:method that sets up the php side, do not call or override
;Table.initTable protected
:This method is called by framework before every action (does nothing by default), unlike constructor this method has initialized state of the table so it can access db, undocumented as it has very limited use
;Table.getAllTableDatas
:undocumented
;Table.getAllDatas
:part of template, override, see [[Main game logic: yourgamename.game.php]]
;Table.setupNewGameTable
:undocumented
;Table.setupNewGame
:part of template, override, see [[Main game logic: yourgamename.game.php]]
;Table.getTableOptionsForGame static
:undocumented
;Table.getTableOptions
:undocumented, likely return gameoptions (i.e. variants of the games)
;Table.getTablePreferencesForGame static
:undocumented
;Table.getTablePreferences
:undocumented, likely return UI preferences (i.e. display tooltips or not)
;Table.getGameInfosForGame static
:undocuments, likely return $gameinfos from gameinfos.inc.php
;Table.getGameOptionsInfos
:undocumented
;Table.start
:undocumented, likely starts the game, do not call
;Table.stMakeEveryoneActive
:this method can be used in state machine to make everybody active as "st" method of multiplayeractive state

;Table.loadPlayersBasicInfos
:very usefull function get players table, see [[Main game logic: yourgamename.game.php]]
;Table.reloadPlayersBasicInfos
:reload players info, see [[Main game logic: yourgamename.game.php]]
;Table.reattributeColorsBasedOnPreferences
:change players colors, see [[Main game logic: yourgamename.game.php]]
;Table.getBestColorFromColorPrefs
:undocumented, do not call, use to pick a color based on preference
;Table.initSetupPlayersInfos
:undocumented
;Table.getPlayersNumber
:returns number of players, see [[Main game logic: yourgamename.game.php]]
;Table.checkAction
:check action on server, see [[Main game logic: yourgamename.game.php]]
;Table.checkGameStart
;Table.color_to_color_back
:@deprecated, undocumented
;Table.initGameStateLabels
;Table.setGameStateInitialValue
:Set initial state of global, technically same as setGameStateValue see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.getGameStateValue
:get value of global see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.setGameStateValue
:set value of global see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.incGameStateValue
:increment value of global see [[Main_game_logic:_yourgamename.game.php#Use_globals]]
;Table.is_testmode
:@deprecated
;Table.testmodedatas
:@deprecated
;Table.applyTestModeDbFixture
;Table.getActivePlayerId
:get active player id, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getActivePlayerName
:get active player name, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getCurrentPlayerId
:get current player id, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getCurrentPlayerName
:get currrent player name, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getCurrentPlayerColor
:get current player color, see [[Main_game_logic:_yourgamename.game.php#Game_states_and_active_players]]
;Table.getPlayerNameById
:get the name by id, see [[Main_game_logic:_yourgamename.game.php#Accessing_player_information]]
;Table.getPlayerColorById
:get the color by id, see [[Main_game_logic:_yourgamename.game.php#Accessing_player_information]]
;Table.getPlayerNoById
:get 'player_no' (number) by id, see [[Main_game_logic:_yourgamename.game.php#Accessing_player_information]]
;Table.isCurrentPlayerZombie
;Table.getPlayerCount
:@deprecated, use getPlayersNumber,
;Table.createNextPlayerTable
:Return linked table of player order using passed parameter, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.getNextPlayerTable
:Return linked table of player order using natural players order, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.createPrevPlayerTable
:do not use
;Table.getPrevPlayerTable
:Return linked table of player order using natural players order reversed, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.getPlayerAfter
:get player after, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.getPlayerBefore
:get player before, see [[Main_game_logic:_yourgamename.game.php#Players turn order]]
;Table.activeNextPlayer
:Make the next player active in the natural player orde, see [[Main_game_logic:_yourgamename.game.php#Game states and active players]]
;Table.activePrevPlayer
:Make the prev player active in the natural player orde, see [[Main_game_logic:_yourgamename.game.php#Game states and active players]]
;Table.forceEndOfGame
:force to abandon game, normally its called when all players agree, but can be called to force people out when testing alpha or beta games and don't want to deal with update db and such ($this->forceEndOfGame( $reason ))
;Table.giveExtraTime
:give extra time to a player, usually when turn require multiple player states, see [[Main_game_logic:_yourgamename.game.php#Reflexion_time]]
;Table.checkZombieTurn
;Table.skipPlayersOutOfTime
:this is called by framework, do not use
;Table.onPlayerHasBeenZombified
:called when some player has been zombified because he quits the game (or have been "skipped"), unlikely you need to override this method, if you do you have to take into account first player quit vs any other player quit, you must call super implementation in any case if you decide to override it
;Table.forceAbandon
:it may be possible for force to abandon game in some cases, for example in alpha games when new database schema requires update and you did not code this (because for alpha its waste of time)
;Table.zombieBack
;Table.aiPlayer
;Table.aiNotPlaying
;Table.aiError
;Table.say
:this function processes chat message, do not use for game purposes, for word games use dedicated control
;Table.getGameProgression
:part of template, override to return proper data, see [[Main_game_logic:_yourgamename.game.php]] and [[Your_game_state_machine:_states.inc.php]]
;Table.getStatTypesForGame static
;Table.getStatTypes
:get the $stats_type array defined in stats.inc.php
;Table.stat_type_id_to_name
;Table.initStat
:initialize statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.getStat
:get statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.setStat
:set statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.setStatForAllPlayers
:set player statistics for all players, not document, does not check params, have some bad side effects
;Table.incStat
:inc statistic https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Game_statistics
;Table.getStatFromResult
:helper function, do not use, should have been private for table class
;Table.setStatOnResult
:helper function, do not use, should have been private for table class
;Table.setStatOnResultForPlayer
:helper function, do not use, should have been private for table class
;Table.getStandardGameResultObject
:helper function, do not use, should have been private for table class
;Table.getGameRankInfos
;Table.argGameEnd
:framework end game function, do not call or override
;Table.stGameEnd
:framework end game function, do not call or override
;Table.stTutorialStart
;Table.isSoloGame
:return true if game is 1 player game or all other players are AI
;Table.notifyAllPlayers
:notification function, see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php
;Table.notifyPlayer
:notification function, see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php
;Table.onEndAjaxAction
:can be overriden to be executed before end of ajax action, unclear why would anybody need that
;Table.checkReturnState
:framework internal check action, do not call or override
;Table.sendNotifications
:framework internal function, do not call or override
;Table.getCurrentNotificationNextNo
;Table.getNotificationHistory
;Table.debugChat
:studio only - execute php code from chat, overriding won't work as it is called statically from table class
;Table.timeout
:studio only - can call from chat console to zombify current player
;Table.eliminatePlayer
:eliminate player, https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php
;Table.isAsync
:return true if game is turn based, false if realtime, undocumented (why?)
;Table.getTimeLimits static
:internal framework function, do not call or override
;Table.getAsyncTimeLimits
:return time limits for turn based games
;Table.checkAsyncActivePlayersChange
:framework internal check action, do not call or override
;Table.upgradeTableDb
:override to perform db upgrade, see game template, also some notes in https://en.doc.boardgamearena.com/Post-release_phase
;Table.getReplayPoints
;Table.saveReplayPoint
;Table.undoAndReplayInit
;Table.removeAutoIncrementFromTable
:@deprecated
;Table.getFieldsListOfTable
:do not use or override, framework internal method to return columns of table
;Table.undoInit
;Table.undoSavepoint
:Instruction to save database state after current transaction is complete [[Main game logic: yourgamename.game.php#Undo moves]]
;Table.doUndoSavePoint
:do not call directly
;Table.undoRestorePoint
:Restore database from save point [[Main game logic: yourgamename.game.php#Undo moves]]
;Table.showTutorial
:do not call directly
;Table.seenTutorial
:do not call directly
;Table.activeTutorial
:do not call directly
;Table.forceGameTournamendEnd
:do not call directly
;Table.showCursor
;Table.showCursorClick
:undocumented, probably to share the cursor for demo/training
;Table.storeLegacyData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.storeLegacyTeamData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.retrieveLegacyData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.retrieveLegacyTeamData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.removeLegacyData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]
;Table.removeLegacyTeamData
:API for campain games see [[Main game logic: yourgamename.game.php#Legacy games API]]

== Methods in the APP_GameClass class ==

;APP_GameClass.getNewUnique
;APP_GameClass.getNew
;APP_GameClass.notifyNow

== Methods in the APP_DbObject class ==

;APP_DbObject.ConnectDb static
;APP_DbObject.DbQuery static
:main query method, see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.DbTraceTimeBefore static
;APP_DbObject.DbTraceTimeAfter static
;APP_DbObject.DbGetLastId static
;APP_DbObject.DbDumpQueryHistory static
;APP_DbObject.DbAffectedRow static
;APP_DbObject.DbStartTransaction static
;APP_DbObject.DbCommit static
;APP_DbObject.DbRollback static
;APP_DbObject.DbRestartTransaction static
;APP_DbObject.DbSelect static
;APP_DbObject.CommitAllAndRestart static
;APP_DbObject.setDeadlockMode
;APP_DbObject.isDeadlockModeRetry
;APP_DbObject.enableMultiQueries
;APP_DbObject.sendMultiQueries
;APP_DbObject.escapeStringForDB
;APP_DbObject.getCollectionFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getNonEmptyCollectionFromDB
;APP_DbObject.getDoubleKeyCollectionFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getUniqueValueFromDB
;APP_DbObject.mysql_fetch_row
;APP_DbObject.mysql_fetch_assoc
;APP_DbObject.mysql_query
;APP_DbObject.getObjectFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getNonEmptyObjectFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getObjectListFromDB
:see https://en.doc.boardgamearena.com/Main_game_logic:_yourgamename.game.php#Accessing_the_database
;APP_DbObject.getSelectedDb static
;APP_DbObject.sqlParsing
;APP_DbObject.DbUsePrefix
;APP_DbObject.applyPrefix
;APP_DbObject.cache_store static
;APP_DbObject.cache_add static
;APP_DbObject.cache_exists static
;APP_DbObject.cache_fetch static
;APP_DbObject.cache_delete static
;APP_DbObject.cache_rollback static
;APP_DbObject.cache_commit static
;APP_DbObject.ensure_enough_time_since_last_action
;APP_DbObject.getMasterNodeDomain
;APP_DbObject.getMasterNodeUrl
;APP_DbObject.masterNodeRequest
;APP_DbObject.gameserverNodeRequest
;APP_DbObject.gameserverNodeRequestNoTable
;APP_DbObject.bgaCallUrl

== Methods in the APP_Object class ==
;APP_Object.watch
:@deprecated, do not use (noop)
;APP_Object.debug
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.trace
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.warn
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.error
:see https://en.doc.boardgamearena.com/Practical_debugging
;APP_Object.dump
:see https://en.doc.boardgamearena.com/Practical_debugging

== Selected static methods in utility modules ==
;bga_rand
:recommended for randomness (dice rolls, etc), see [[Main game logic: yourgamename.game.php#About random and randomness]]
;shuffle_with_keys
:shuffle array with keys (basically shuffle keys and keep linked values), it shuffle argument, does not return anything
;totranslate
:returns its argument, used for MARKING of string for server strings https://en.doc.boardgamearena.com/Translations
;clienttranslate
:returns its argument, used for MARKING of string for client strings https://en.doc.boardgamearena.com/Translations
;_
:this is not the same as self::_, it is also translation function but only can translate mainsite strings, do not use in game code

[[Category:Studio]]

Gamehelpforex

2022-07-29T01:39:09Z

AmadanNaBriona: /* RESOLVE */

= FOR-EX GAME SUMMARY =

== SPOT TRANSACTION==

Before taking your action for your turn, you may, but are not required to, perform one Spot Transaction with another player, trading 1 buck of any currency for its equivalent in another, or vice-versa.

== MAKE A CONTRACT ==

Take the next available set of Contract cards, placing one in front of yourself, one at the back of the Contract Queue, and leaving the last in the Contract Display. To the left of this last card, place the amount (taken from the Bank) that you wish to pay. To its right, place the equivalent amount in the other currency. The amount of the Stronger Currency must be a whole number, and cannot be in excess of ten bucks.

== INVEST ==

Buy one or two certificates for 2 bucks each of the relevant currencies. You cannot buy two certificates for the same currency in a single action, nor can you have more than four certificates in a single currency at one time. Any currencies that are invested in are '''strengthened'''.

== DIVEST ==

Sell one or more certificates of a single type, removing those certificates from the game and receiving 2 bucks of that currency for each certificate divested. As part of your turn, clockwise around the table, each other player has the opportunity to divest certificates of the same type, likewise receiving 2 bucks of that currency and removing the certificate from the game. The divested currency is weakened '''once for each certificate that is divested'''.

== RESOLVE ==

Resolve the front item in the Contract Queue:

* If the front item is a Contract, the player who created it must pay the amount to the left of the Contract, and receive the amount to its right. If they cannot pay, they still receive the amount to its right, and the Contract converts to a Loan, with the amount owed increased by +1. The Loan moves to the back of the Contract Queue, with the player who created the Contract now responsible for the Loan. If the player already has a Loan in the Contract Queue, the new Loan is combined with the previous Loan; all combined Loans must be paid off at the same time.<br/><br/>

* If the front item is a Loan, the player who is responsible for the Loan must pay the amount owed. If the Loan cannot be repaid, the player is Bankrupt and the game immediately ends.<br/><br/>

* If the front item is a Dividend, players earn 0, 2, or 3 bucks of a given currency for each Certificate they hold in that currency, as shown on the Dividend card. If a Currency has any counters on the "8" space, Certificates for that Currency pay nothing. After making payouts, determine which Currency has the most Certificates currently in player hands: '''that Currency is Strengthened'''. If multiple Currencies qualify, the acting player chooses one Currency from among the tied Currencies. When the final Dividend is Resolved, there are no more player turns; instead, the remaining items in the Contract Queue are Resolved in order.

If either a Contract or a Loan is paid off, all associated Contract cards return to the contract display and can be used again.

== STRENGTHENING/WEAKENING ==

Currencies are Strengthened:
* each time it is Invested in.
* when, after Resolving a Dividend, it has the most Certificates in player hands.

Currencies are Weakened:
* each time it is Divested in.

== GAME END ==

The game ends when one of the following occurs:
* Any player goes Bankrupt.
* There are no items left in the Contract Queue.

Determine which Currency is Strongest (the stronger half of the most Currency Pairs); if there is a tie, the tied Currency with the most Certificates in player hands is the Strongest; if a tie persists, the player who last took a turn decides which of those tied Currencies is Strongest. All players convert all monies to that Currency, rounding any fractions down. The player with the most money wins.

Gamehelpforex

2022-07-29T01:36:57Z

AmadanNaBriona:

= FOR-EX GAME SUMMARY =

== SPOT TRANSACTION==

Before taking your action for your turn, you may, but are not required to, perform one Spot Transaction with another player, trading 1 buck of any currency for its equivalent in another, or vice-versa.

== MAKE A CONTRACT ==

Take the next available set of Contract cards, placing one in front of yourself, one at the back of the Contract Queue, and leaving the last in the Contract Display. To the left of this last card, place the amount (taken from the Bank) that you wish to pay. To its right, place the equivalent amount in the other currency. The amount of the Stronger Currency must be a whole number, and cannot be in excess of ten bucks.

== INVEST ==

Buy one or two certificates for 2 bucks each of the relevant currencies. You cannot buy two certificates for the same currency in a single action, nor can you have more than four certificates in a single currency at one time. Any currencies that are invested in are '''strengthened'''.

== DIVEST ==

Sell one or more certificates of a single type, removing those certificates from the game and receiving 2 bucks of that currency for each certificate divested. As part of your turn, clockwise around the table, each other player has the opportunity to divest certificates of the same type, likewise receiving 2 bucks of that currency and removing the certificate from the game. The divested currency is weakened '''once for each certificate that is divested'''.

== RESOLVE ==

Resolve the front item in the Contract Queue:

* If the front item is a Contract, the player who created it must pay the amount to the left of the Contract, and receive the amount to its right. If they cannot pay, they still receive the amount to its right, and the Contract converts to a Loan, with the amount owed increased by +1. The Loan moves to the back of the Contract Queue, with the player who created the Contract now responsible for the Loan. If the player already has a Loan in the Contract Queue, the new Loan is combined with the previous Loan, and all Loans be paid off at the same time.<br/><br/>

* If the front item is a Loan, the player who is responsible for the Loan must pay the amount owed. If the Loan cannot be repaid, the player is Bankrupt and the game immediately ends.<br/><br/>

* If the front item is a Dividend, players earn 0, 2, or 3 bucks of a given currency for each Certificate they hold in that currency, as shown on the Dividend card. If a Currency has any counters on the "8" space, Certificates for that Currency pay nothing. After making payouts, determine which Currency has the most Certificates currently in player hands: '''that Currency is Strengthened'''. If multiple Currencies qualify, the acting player chooses one Currency from among the tied Currencies. When the final Dividend is Resolved, there are no more player turns; instead, the remaining items in the Contract Queue are Resolved in order.

If either a Contract or a Loan is paid off, all associated Contract cards return to the contract display and can be used again.

== STRENGTHENING/WEAKENING ==

Currencies are Strengthened:
* each time it is Invested in.
* when, after Resolving a Dividend, it has the most Certificates in player hands.

Currencies are Weakened:
* each time it is Divested in.

== GAME END ==

The game ends when one of the following occurs:
* Any player goes Bankrupt.
* There are no items left in the Contract Queue.

Determine which Currency is Strongest (the stronger half of the most Currency Pairs); if there is a tie, the tied Currency with the most Certificates in player hands is the Strongest; if a tie persists, the player who last took a turn decides which of those tied Currencies is Strongest. All players convert all monies to that Currency, rounding any fractions down. The player with the most money wins.

Stock

2022-07-15T02:32:08Z

AmadanNaBriona: /* Customize apperance */

{{Studio_Framework_Navigation}}

== Overview ==

'''Stock''' is a javascript component that you can use in your game interface to display a set of elements of the same size that need to be arranged in single or multiple lines.

Stock is very flexible and is the most used component in BGA games.

Examples of stock use cases:

* Display a set of cards, typically hands (examples: ''Hearts'', ''Seasons'', ''The Boss'', ''Race for the Galaxy'').
* Display items in player panels (examples: ''Takenoko'', ''Amyitis'', ...)
* ... Many other situations. For example, black dice and cubes on cards in ''Troyes'' are displayed with stock components.

Using stock:

* Your items are arranged nicely and sorted by type.
* When adding or removing items to a set, all items slide smoothly to their new position in the set.
* Selecting and unselecting items are built-in functions.
* You don't have to worry about inserting/removing HTML code; the entire life cycle of the stock is managed by the component.

== Using stock: a simple example ==

Let's have a look on how the stock is used in the game ''Hearts'' to display a hand of standard cards.

First, don't forget to add "ebg/stock" as a dependency in your js file:

<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock" /// <==== HERE
],
</pre>

The stock is initialized in the Javascript "setup" method like this:

<pre>
// Player hand
this.playerHand = new ebg.stock();
this.playerHand.create( this, $('myhand'), this.cardwidth, this.cardheight );
</pre>

Explanations:
* We create a new stock object for the player hand.
* As parameters of the "create" method, we provide the width/height of an item (a card), and the div container "myhand" - which is a simple empty "div" element defined in our HTML template (.tpl).

Then, we must tell the stock what items it is going to display during its life: the 52 cards of a standard card game. Of course, we did not create 52 different images, but a "CSS sprite" image named "cards.jpg" with the cards arranged in 4 rows and 13 columns.

Here's how we tell stock what items to display:

<pre>
// Specify that there are 13 images per row in the CSS sprite image
this.playerHand.image_items_per_row = 13;

// Create card types:
for( var color=1;color<=4;color++ )
{
for( var value=2;value<=14;value++ )
{
// Build card type id
var card_type_id = this.getCardUniqueId( color, value );
this.playerHand.addItemType( card_type_id, card_type_id, g_gamethemeurl+'img/cards.jpg', card_type_id );
}
}
</pre>

Explanation:

* First, we tell the stock component that our CSS sprite contains 13 items per row. This way, it can find the correct image for each card type id.
* Then for the 4x13 cards, we call the "addItemType" method that creates the type. The arguments are the type id, the weight of the card (for sorting purpose), the URL of our CSS sprite, and the position of our card image in the CSS sprite.

Note: In this specific example we need to generate a unique ID for each type of card based on its color and value. This is the only purpose of "getCardUniqueId".

From now on, if we need to add a card - for example, the 5 of Hearts - to a player's hand, we can do this:

<pre>
this.playerHand.addToStock( this.getCardUniqueId( 2 /* 2=hearts */, 5 ) );
</pre>

In reality, cards have some IDs, which are useful to manipulate them. This is the reason we are using "addToStockWithId" instead:

<pre>
this.playerHand.addToStockWithId( this.getCardUniqueId( 2 /* 2=hearts */, 5 ), my_card_id );
</pre>

If afterwards we want to remove this card from the stock:

<pre>
this.playerHand.removeFromStockById( my_card_id );
</pre>

== Complete stock component reference ==

=== Creation ===

'''create( page, container_div, item_width, item_height ):'''

With create, you create a new stock component.

Parameters:
* page: the container page. Usually: "this".
* container_div: the container "div" element (an empty div element in your template, with an id).
* width and height (in pixels) for the stock component.

(See ''Hearts'' example above).

'''addItemType( type, weight, image, image_position ):'''

Define a new type of item and add it to the stock.

This is mandatory to define a new item type before adding it to the stock. Example: if you want to have a stock contain cubes of 3 different colors, you must add 3 item types (one for each color).

Parameters:
* {int} type: id of the type to add. You can choose any positive integer. All item types must have distinct IDs.
* {int} weight: weight of items of this type. Weight value is used to sort items of the stock during the display. Note that you can specify the same weight for all items; in this case, they are not sorted and their order might change randomly at any time.
* {string} image: URL of item image. Most of the time, you will use a CSS sprite for stock items, so you have to specify CSS sprite image here.

Be careful: you must specify the image url as this:

<pre>
g_gamethemeurl+'img/yourimage.png'
</pre>

* image_position: if "image" specify the URL of a CSS sprite, you must specify the position of the item image in this CSS sprite. For example, if you have a CSS sprite with 3 cubes with a size of 20x20 pixels each (so your CSS image has for example a size of 20x60 or 60x20), you specify "0" for the first cube image, 1 for the second, 2 for the third.

''Important'': if there is more than one line of items in your CSS sprite, you must specify how many items per line you have in your CSS sprite, see image_items_per_row below:

'''image_items_per_row'''
Class member to set number of columns in css sprite (or how many items per row). I.e. if you sprite is 4 cards horizontally and 6 vertically, you have to set it to 4.
<pre>
// Specify that there are 10 image items per row in images used in "myStockObject" control.
this.myStockObject.image_items_per_row = 4;
</pre>

=== Add/Remove items ===

'''addToStock( type, from )'''

Add an item to the stock, with the specified type, but without a unique ID.

To make your life easier, in most cases we suggest you use '''addToStockWithId''' in order to give an ID to the item added. '''addToStock''' is suitable when you are using a stock to control items that are generic game materials that don't need to be tracked individually (example: a bunch of money tokens).

Parameters:
* type: ID of the item type to use (as specified in "addItemType")
* from: OPTIONAL: if you specify an HTML item here, the item will appear on this item and will be slid to its position on the stock item.

Example:
<pre>
// Add a money token to the "player money" stock.
// The money token will appear on "player_id" player panel and will move to its position.
this.playerMoney.addToStock( MONEY_TOKEN, 'overall_player_board_'+player_id );
</pre>

Important: for a given stock control, you must use either '''addToStock''' or '''addToStockWithId''', but NEVER BOTH OF THEM.

'''addToStockWithId( type, id, from )'''

This is the same method as '''addToStock''', except that it also associates an ID with the newly created item.

This is especially useful:

* When you need to know which item(s) have been selected by the user (see '''getSelectedItems''').
* When you need to remove a specific item from the stock with '''removeFromStockById'''.

'''removeFromStock( type, to, noupdate )'''

Remove an item of the specific type from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears. Note that this method does not expose the associated animation object, however, so it's not possible to trigger other actions when it finishes, for example. If you need to do that, use Dojo's slideToObject() instead.

'noupdate' is an optional parameter. If set to "true" it will prevent the Stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. If you pass noupdate you have to call updateDisplay() after all items are removed.

'''removeFromStockById( id, to, noupdate )'''

Remove an item with a specific ID from the stock.

'to' is an optional parameter. If "to" contains the ID of an HTML element, the item removed from the Stock slides to this HTML element before it disappears. Note that this method does not expose the associated animation object, however, so it's not possible to trigger other actions when it finishes, for example. If you need to do that, use Dojo's slideToObject() instead.

'noupdate' is an optional parameter. If set to "true" it will prevent the Stock display from changing. This is useful when multiple (but not all) items are removed at the same time, to avoid ghost items appearing briefly. If you pass noupdate you have to call updateDisplay() after all items are removed.

'''removeAll()'''

Remove all items from the stock.

'''removeAllTo( to )'''

Remove all items from the stock. If "to" contains the ID of an HTML element, the item removed from the stock slides to this HTML element before it disappears.

=== Getters ===

'''getPresentTypeList()'''

Return an array with all the types of items present in the stock right now.

Example:
<pre>
this.myStockControl.removeAll();
this.myStockControl.addToStock( 65 );
this.myStockControl.addToStock( 34 );
this.myStockControl.addToStock( 89 );
this.myStockControl.addToStock( 65 );

// The following returns: { 34:1, 65:1, 89:1 }
var item_types = this.myStockControl.getPresentTypeList();
</pre>

'''count():'''

Return the total number of items in the stock right now.

'''getAllItems()'''

Get all items (same format as getSelectedItems and getUnselectedItems).

'''getItemDivId(id)'''

Get the div id using the stock item id (to manipulate element properties directly).

'''getItemById(id)'''

Get the Stock item with the id in parameter
ex : return the object { type:1, id: 1001 }

=== Selection ===

'''setSelectionMode( mode )'''

For each stock control, you can specify a selection mode:
* 0: no item can be selected by the player.
* 1: a maximum of one item can be selected by the player at a time.
* 2 (default): multiple items can be selected by the player at the same time.

'''setSelectionAppearance( type )'''

For each stock control, you can specify a selection highlighting type:
* 'border': there will be a red border around selected items (this is the default). The attribute 'apparenceBorderWidth' can be used to manage the width of the border (in pixels).
* 'disappear': the selected item will fade out and disappear. This is useful when the selection has the effect of destroying the item.
* 'class': there will be an extra '''stockitem_selected''' css class added to the element when it is selected (and removed when unselected). The name of the class can be changed by using the '''selectionClass''' attribute. You can also override the default class in the css file for your game but beware of the '''!important''' keyword.

By default this class definition is:
<pre>
.stockitem_selected {
border: 2px solid red ! important;
}
</pre>

If you want to override it (for example, to change the border color) add this in your <game>.css file:
<pre>
.stockitem_selected {
border: 2px solid orange ! important;
}
</pre>

'''isSelected( id )'''

Return a boolean indicating whether the specified item id has been selected.

'''selectItem( id )'''

Select the specified item.

'''unselectItem( id )'''

Unselect the specified item.

'''unselectAll()'''

Unselect all items of the stock.

'''onChangeSelection'''

This callback method is called when the player selects/unselects an item of the stock.

You can connect this to one of your methods like this:

<pre>
dojo.connect( this.myStockControl, 'onChangeSelection', this, 'onMyMethodToCall' );

(...)

onMyMethodToCall: function( control_name, item_id )
{
// This method is called when myStockControl selected items changed
var items = this.myStockControl.getSelectedItems();

// (do something)
},
</pre>

Nota bene:
- The "control_name" argument is the ID (the "DOM" id) of the "div" container of your stock control. Using "control_name", you can use the same callback method for different Stock control and see which one trigger the method.
- The "item_id" argument is the stock ID (index) of the stock item that has just been selected/unselected.

'''getSelectedItems()'''

Return the list of selected items, as an array with the following format:
<pre>
[
{ type:1, id: 1001 },
{ type:1, id: 1002 },
{ type:3, id: 1003 }
...
]
</pre>

'''getUnselectedItems()'''

Same as the previous one, but return unselected item instead of seleted ones.

=== Layout ===

'''resetItemsPosition()'''

If you moved an item from the stock control manually (ex: after a drag'n'drop) and want to reset their positions to their original ones, you can call this method.
Note: it is the same as updateDisplay() without arugment, not sure why there are two methods.

'''updateDisplay(from)'''
Update the display completely (if 'from' is defined: moves new items from this location).

Example code if you change the underlying stock item, or otherwise want to make the stock item refresh:
<pre>
this.myStockControl.updateDisplay();
</pre>

'''item_margin'''

By default, there is a margin of 5px between the items of a stock. You can change the member variable "item_margin" to change this.

Example:
<pre>
this.myStockControl.item_margin=5;
</pre>

'''changeItemsWeight( newWeights )'''

With this method you can change dynamically the weight of the item types in a stock control.

Items are immediately re-sorted with the new weight.

Example: with a stock control that contains classic cards, you can order them by value or by color. Using changeItemsWeight you can switch from one sort method to another when a player request this.

newWeights is an associative array: item type id => new weight.

Example:
<pre>
// Item type 1 gets a new weight of 10, 2 a new weight of 20, 3 a new weight of 30.
this.myStockControl.changeItemsWeight( { 1: 10, 2: 20, 3: 30 } );
</pre>

Example2:
<pre>
// Be careful with object initialisers with variables, use the bracket notation.
// Item type 1 gets a new weight of 10
var card_type = 1;
this.myStockControl.changeItemsWeight( { [card_type]: 10 } );
</pre>

'''centerItems'''

Center the stock items in the middle of the stock container.
e.g. this.myStock.centerItems = true;

'''setOverlap( horizontal_percent, vertical_percent )'''

Make items of the stock control "overlap" each other, to save space.

By default, horizontal_overlap and vertical_overlap are 0.

When horizontal_overlap=20, it means that a stock item will overlap to only show 20% of the width of all the previous items. horizontal_overlap can't be greater than 100.

vertical_overlap works differently: one items on two are shifted up.

See the games "Jaipur" or "Koryŏ" to see examples of use of this function.

'''autowidth'''

Stock does not play well if you attempt to inline-block it with other blocks, to fix that you have to set this flag which will calculate width properly
mystock.autowidth = true;

'''resizeItems( width, height, background_width, background_height )'''

background_width is an optional argument.

background_height is an optional argument.

<pre> stock.resizeItems(100, 120, 150, 170);</pre>

=== Customize Appearance ===

'''extraClasses'''

Can be set to a list of class names (separated by space) on stock object, so when div is created these are added, i.e.

this.playerHand.extraClasses='mycard';

Note that it is the same list for all items.

'''onItemCreate'''

Using onItemCreate, you can trigger a method each time a new item is added to the Stock, in order to customize it.

Complete example:
<pre>
// During "setup" phase, we associate our method "setupNewCard" with the creation of a new stock item:
this.myStockItem.onItemCreate = dojo.hitch( this, 'setupNewCard' );

// And here is our "setupNewCard":
setupNewCard: function( card_div, card_type_id, card_id )
{
// Add a special tooltip on the card:
this.addTooltip( card_div.id, _("Some nice tooltip for this item"), '' );

// Note that "card_type_id" contains the type of the item, so you can do special actions depending on the item type

// Add some custom HTML content INSIDE the Stock item:
dojo.place( this.format_block( 'jstpl_my_card_content', {
....
} ), card_div.id );
}

</pre>

'''onItemDelete'''

Function handler called when div is removed

this.myStock.onItemDelete = (card_div, card_type_id, card_id) => { console.log("card deleted from myStock: "+card_id); };

== Tips when adding/removing items to/from Stock components ==

Most cases will be one of the following situations:

'''Situation A''':

When you add a card to a stock item, and this card is '''not''' coming from another stock:

* Use '''addToStockWithId''' with a "from" argument set to the element of your interface where the card should come from (i.e. div id). For example if you want to "reveal" card from player hand and it is not an interface element you can set from to be 'player_board_'+activePlayerId (where activePlayerId is player who played that card).

'''Situation B''':

When you add a card to a stock item, and this card is coming from another stock:

* On the destination Stock, use '''addToStockWithId''' with a "from" argument which is the HTML id of the corresponding item in the source Stock. For example, if the source stock id is "myHand", then the HTML id of card 48 is "myHand_item_48".
* Then, remove the source item with '''removeFromStockById'''. Note: do NOT set the 'to' argument in this call, otherwise you'll get two animations.

(Note that it's important to do things in this order, because the source item must still exist when you use it as the origin of the slide.)

'''Situation C''':

When you move a card from a stock item to something that is not a stock item:

* Insert the card as a classic HTML template (dojo.place / this.format_block).
* Place it on the Stock item with '''this.placeOnObject''', using the Stock item HTML id (see above).
* Slide it to its new position with '''this.slideToObject'''.
* Remove the card from the Stock item with '''removeFromStockById'''.

Using the methods above, your cards should slide to, from, and between your Stock controls smoothly.

You can customize this (showing the default value):
<pre>

this.mystock.jstpl_stock_item= "<div id=\"${id}\" class=\"stockitem\" style=\"top:${top}px;left:${left}px;width:${width}px;height:${height}px;z-index:${position};background-image:url('${image}');\"></div>";
</pre>
To produce a different type of stock item

== Known issues ==

==== Incorrectly displayed sprites on Safari ====

As mentioned above, stock displays its images using "sprites" consisting of a portion of a larger image. To accomplish this, it uses the CSS background-position attribute in negative multiples of 100%. For example, the first element of the first row would be 0% 0%. The second element of the first row would be -100% 0%, etc.

This works fine except in Safari, which sometimes slightly modifies the width of elements at smaller screen sizes (usually when minimum width of 'game_interface_width' is not null) in game. For example, you might get a ~49.99px x ~49.99px div instead of the 50px x 50px specified by CSS width/height. Combined with using percentages in background-position, this can cause sprites to be slightly off-center.

Using pixels in background-position is probably the easiest way to fix this problem, but that would require modifying the stock code itself. As a developer, you can also work around the problem by specifying a background-size attribute based on the size in elements of your source image. For example, if you have a source image that contains 5 rows of 28 sprites, you should specify "background-size: 2800% 500%;"

You can add background-size to your stock items by using the extraClasses attribute as explained above and then specifying the values in your game.css file.

[[Category:Studio]]

Translations

2022-02-20T19:11:23Z

AmadanNaBriona: /* Method _ (underscore) */

{{Studio_Framework_Navigation}}

Using BGA Studio, the game you create is ready to be translated to each language by the BGA community. To make this possible, you only need to specify which string must be translated and how to combine them.

== Localization Overview ==

Localization for BGA games happens largely on the CLIENT. Games must be developed in English and English strings are sent to the client.

It's only at the client that your English strings will be displayed with the translation for the user's language, when such a translation exists.

For anyone who has worked on a system where translation happens at the server and localized strings are sent to the client: you must unlearn what you have learned. Just stick with English and send the untranslated English strings. The magic happens at the client.

== How will my strings be translated? ==

When developing your game, all strings must be in English. Strings must be coherent with the English version of the game.

Once your game enters Beta, the BGA player community will descend upon your game like a plague of locusts and translate it into dozens of languages before you can say "Je ne parle pas anglais".

== What do I have to do from a programming standpoint? ==

Not as much as you think. Read on for full details, but the golden rules are:

# Make sure that any string on the server side that needs to be translated on the client side is wrapped in a clienttranslate() function when defined. For example: $my_response = clienttranslate('Hey translators, please translate this string'). clienttranslate doesn't actually do anything at all (it just passes the text through) but the translation engine searches your code for strings wrapped in that function and uses them to build the list of strings that need to be translated.
# On the client side, just display your text, but wrap it in _().
## If you pass a string constant to _() - such as _('This is my string') then the parser will automatically detect and add your string to the list of strings that need to be translated, AND it will display the local translation for it when displaying.
## If you pass a variable to _() - such as _(args.my_message) then MAKE SURE that the variable is set to an English string that is either defined somewhere in your PHP code in a clienttranslate() function or somewhere else in your javascript code in a _() function. As long as it is, the translators will provide translations for it, and the _() function will display the local translation of your English string.
# A string used as the message for notifyAllPlayers or notifyPlayer will automatically have its translation displayed on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used as the "description" or "descriptionmyturn" for a state in your state machine will also be automatically translated on the client - you don't need to do anything EXCEPT make sure that it is wrapped in a clienttranslate() on the server, so that it gets translated.
# A string used in the pre-games option screen will also automatically have any translation displayed at the client - you don't need to do anything EXCEPT make sure that it is wrapped in a totranslate() on the server (nota bene: you should not use clienttranslate() here as this file is processed specifically and those strings will not be included in the game translation file but in the main site translation file - with a prefix to keep translations isolated by module - as they have to be translated on main site pages. If you need exactly the same string in your game for a client side translation, it should be declared somewhere else in your code wrapped inside a clienttranslate() to be included in the game translation file.
# A string used in the statistics screen will operate like a string in the pre-game options screen. It will automatically have any translation displayed at the client as long as you make sure that it is wrapped in a totranslate() on the server.
# If you are using parameters for a call to notifyAllPlayers or notifyPlayers, or for a state's "description" or "descriptionmyturn" and those parameters contain text that needs to be translated, you will need to tell the system to display the translated versions of them by using the 'i18n' argument. See below for full details.

== What strings should be translated? ==

Every text that can be visible by the player when the game is running normally. This includes tooltips, texts on cards, error messages.

This does NOT include error messages that are not supposed to happen (unexpected errors).

== What rules should I follow for the original English strings? ==

For a coherent and homogeneous interface, here are some rules about ending a sentence with a final period '.'

* As a general rule:
** If a sentence is displayed isolated in the interface => no final period
** If a sentence is followed or could be followed by another sentence in the same interface space => final period.

* In detail:
** No final period:
*** button labels
*** section titles
*** menu elements
*** links triggering an isolated action
*** anything that is not a full sentence
*** current actions in the status bar
** Final period:
*** complete sentences (e.g., explanations and descriptions) that can be chained with other sentences
** Either a period or no period is acceptable (but this should be consistent throughout the game) for:
*** isolated tooltips / small sentences
*** game logs (no period is usually preferable)
*** error messages (unless there is more than one sentence in the error message; final period is mandatory in this case)

Otherwise, you should try to follow as closely as possible the general style and format (including capitalization) used in the published English rulebook and game materials.

== Focus on translating notifications ==

Usually, translating a website is simple: you just call a function on every string you have to translate, and the string is translated in the player's language. On Board Game Arena, this is exactly the same with the "_( string )" function.

However, there is one difference on BGA: notifications. The server is sending notifications to players, and most of the time the notifications are the same for every players, no matter what language each player is using. This is why notifications are translated on client side in the proper language, even if the strings are defined on server side.

== How to not make translators crazy ;) ==

* Try to reuse the exact same strings (with the same case, etc.) to minimize the number of strings to translate.
** '''Example''': Consider replacing <pre>self::_("Winner")</pre> and <pre>self::_("Winners")</pre> (two strings to translate) with <pre>self::_("Winner(s)")</pre>
** '''Example 2''': <pre>clienttranslate("play a card")</pre> and <pre>clienttranslate("Play a card")</pre> means there will be two strings to translate.
* Do not mark as translatable a game element that does not have to be translated (e.g., if the name of a monster on a card is "Zzzzz", maybe there's no need to translate it).
* Words does not come in the same order in each language. Thus, when you have to translate a string with an argument, do not write something like:
<pre>self::_("First part of the string, ").$argument.' '.self::_("second part of the string")</pre>
Write instead:
<pre>sprintf( self::_("First part of the string, %s second part of the string"), $argument )</pre>
(or the equivalent "dojo.string.substitute" in Javascript)
* When translators are going to translate your game, the most difficult task for them is to get the context of the string to be translated. The shorter the string is, the more difficult the task is for them. As a rule of thumb, try to avoid short, insignificant strings that require knowledge of their surrounding context. You can also leave a comment on the context of the string in the translation program (English to English) if you are the developer of the game.
* The BGA translation policy is to be flexible on grammar. We prefer to write "player gets 1 coin(s)" rather than write two versions of the same string for plural and singular - it reduces the number of strings to translate.
* Instead of writing elaborate strings like "With the effect of ZZZ, player XXX gains a new YYY", which is very difficult to translate, write strings like "ZZZ: XXX gets YYY".
* Use present tense instead of past. E.g., "player gets wood" instead of "player got wood".
* Avoid using gender-specific wording as much as possible. If needed be aware that [[https://forum.boardgamearena.com/viewtopic.php?f=11&t=19432&start=10#p88592 a pronoun replacement system]] is in place, and cannot work if your use "their" as a singular genderless pronoun, as it removes the information that it's singular. E.g., you should write "playerX returns card to *his* hand" or "playerX returns card to *his/her* hand" and not "playerX returns card to *their* hand" as in the 2 first case the system will substitute the proper pronoun his/her/their depending on playerX declared/undeclared gender, but in the second case it will always stay "their" whatever the player preference setting.
* Where two strings are identical apart from (say) a number, use the same string with a ${parameter}, and call format_string_recursive (on the client) or use args (for notifications and state descriptions) to provide the details. But *never* do that for composing multiple sentences with words: other languages have different grammar and it would most likely create untranslatable strings.

== WARNING: Make sure your strings will be translated! ==

For each game, our translation tool does a full scan of the code, looking for translation markers like "_()" or "clienttranslate()". (See below for the full list of translation markers.)

If your original string is not completely contained inside one of these markers, it won't be translated.

<pre>
// Examples: the following strings will be translated:
var mystring_translated = _("my string"); // JS
$mystring_translated = self::_("my string"); // PHP
$mystring_translated = sprintf( self::_("my string with an %s argument"), $argument ); // PHP

// Examples: the following strings WILL NOT be translated:
$my_string = "my string";
$not_translated = self::_( $my_string ); // The original string is not contained within a translator marker => no translation
$not_translated = self::_( sprintf( "my string with a %s argument", $argument ) ); // Ditto
</pre>

== On client side (Javascript) ==

On client side, things are quite simple: you just have to use the "_()" function for all strings you want to translate.

Examples:
<pre>
// Get a string in player's language:
var translated = _("original english string");

// Get a string in player's language with parameter:
var translated = dojo.string.substitute( _("You can pick ${p} cards and discard ${d}"), {
p: 2,
d: 4
} );
</pre>

'''WARNING:''' in Javascript strings to translate, you should never use '\n', '\t' or such, as it will break the translation bundle and result in all the Javascript translation to fail. In any case, the strings will result in HTML code, and such character codes won't have any impact on the HTML rendering. You should use HTML markup instead.

'''ANOTHER WARNING:''' you cannot use this function _() in the javascript object constructor, but you can achieve the same if you use it the setup method

== On server side (PHP) ==

On PHP side, you can use 3 different functions to specify that a string must be translated.

=== Function clienttranslate ===

'''clienttranslate( 'string to translate' ):'''

This function is ''transparent'': it will return the original English string without any change. Its only purpose is to mark this string as "must be translated", and to make sure the translated version of the string will be available on client side.

In general, you use clienttranslate:
* In your '''states.inc.php''', for the fields "description" and "descriptionmyturn".

<pre>
"description" => clienttranslate('${card_name}: ${actplayer} must discard 4 identical energies'),
</pre>

* In '''material.inc.php''', when defining text for game materials that must be displayed on the client side.

<pre>
$this->card_types = array(

1 => array(
'name' => clienttranslate('Amulet of Air'), // Thus, we can use "_( card_name )" on Javascript side.
</pre>

* When sending a notification with ''notifyAllPlayers'' or ''notifyPlayer'', in the game log string and all game log arguments that need a translation.

<pre>
// A game log string with no argument:
self::notifyAllPlayers( 'pickLibraryCards', clienttranslate('Everyone draw cards from their library'), [] );
</pre>

As a consequence there is no point passing variables to this function. E.g.:

<pre>
notif="foo";
self::notifyAllPlayers( 'log', clienttranslate(notif),[]); // BAD

notif=clienttranslate("foo");
self::notifyAllPlayers( 'log', notif,[]); // GOOD

self::notifyAllPlayers( 'log', clienttranslate("player gains ${num} gems"),[num=>2]); // BAD it is dynamic string enterpreted by php
self::notifyAllPlayers( 'log', clienttranslate('player gains ${num} gems'),[num=>2]); // GOOD, difference is single quotes

self::notifyAllPlayers( 'log', clienttranslate("player gains ".${num}." gems"),[num=>2]); // BAD concatenation

</pre>

Translating arguments is a little bit more complex. This uses the '''i18n''' special argument as below:

<pre>
// In the following example, we translate the game log itself, but also the "card_name" argument:

self::notifyAllPlayers( 'winPoints', clienttranslate('${card_name}: ${player_name} gains ${points} point(s)'), array(
'i18n' => array( 'card_name' ), // <===== We specify here that "card_name" argument must be translated
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'points' => $points,
'card_name' => $this->card_types[8]['name'] // <==== Here, we provide original English string.
) );
</pre>

To ensure the translation of the i18n argument will be made, clienttranslate must have been used somewhere, for instance:

<pre>
$this->card_types = array(
...
8 => array(
'name' => clienttranslate("Amulet of Fire"),
...
</pre>

Pay attention when using the '''i18n''' argument when translating arguments for the client: do NOT use same argument for both translations AND key codes for client-side actions (like using 'card_name' to move it on the player board as described in the example). It's pretty obvious in the example, but it can be very tricky when translation is made at the end of the development (which is often the case). Use explicit argument names like 'card_name_translated' by example.

'''WARNING:''' you should NEVER use concatenation with ''clienttranslate'', as it would result in a different string to translate at runtime than the one retrieved statically in the translation system, and so translation would not be applied. If you need to compose a string, use substitution and the i18n parameter (but you also have to pay attention not to compose sentences in a way that is dependent upon the English language specific syntax, or it may be impossible to translate correctly in another language: sometimes, you need multiple full sentences rather than relying on substitution).

=== Method _ (underscore) ===

'''self::_( "my string to translate" ):'''

This function returns a string translated in the language of CURRENT user (i.e. player who send the request to the server) (be careful, this is NOT the active player).

This can be used like self::_('bla') or this->('bla'). You cannot use static underscore function _('bla') in php, it is not the same, it will not translate strings from your game.

The returned string will be surrounded by HTML tags, so you cannot use it in places where pure text is required or your string already has another html markup.

Most of the time, you don't need to translate strings on server side, except on the following situations:
* Throwing user exceptions
* Creating the labels for the game interface used in your template
* Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions
* Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user

Imporant! This function does two things:
* Mark string for translation
* Translates in runtime
As a consequence you absolutely cannot have $var in there! Or string concatenations.
I.e.
$food=self::_("Banana");// good
self::_("User gives $food to a cat"); // bad
For the translator we will have two strings "Banana" and "User gives $food to a cat", but in runtime we will be
"Banana" and "User gives Banana to a cat" and second string would not match anything. And this is as bad
self::_("User gives ".$food." to a cat");// bad

==== Throwing an exception because the player did a forbidden move ====

<pre>
// This will display a translatable red message to the player that just did some wrong action:
throw new BgaUserException( self::_('You must choose 3 cards') );

// ... notice the use of BgaUserException that signals that this exception is "expected". In theory, all exception that are expected should be translated.
</pre>

==== Creating labels ====

In "yourgame.view.php", when creating the labels for the game interface used in your template (.tpl) file.

<pre>
$this->tpl['CARDS_FOR_YEAR_2'] = self::_("Your cards for year II");
</pre>

'''Nota bene:''' it is recommended to set translated text in your interface client side rather than use template variables and server translation, so that translation works natively in replays (that don't have server side translations). For simple strings, the framework will handle moving the translation client side, but for more complex strings it may not work. In particular, you should not use server side translation for templates with substitution variables (or use the specific function "gameview_str_replace( $search, $replace, $string )" if not possible otherwise or for old code compatibility). Also, you should never use a "to_translate" class in your .tpl as it is used internally by the framework.

Example with view.php:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">{EMPIRE_LABEL}</div>
</pre>
in view.php:
$this->page->insert_block("player_board", array ("COLOR" => $color,"PLAYER_NAME" => $name,"PLAYER_NO" => $no,
"PLAYER_ID" => $player_id, "CLASSES" => $own?"own":"",
"EMPIRE_LABEL" => self::raw(gameview_str_replace('${player_name}', $name, self::_('${player_name}\'s EMPIRE')))
));
Example with client side:
in .tpl:
<pre>
<div id="empire_title_{COLOR}" class="side_title color_{COLOR}">Stub</div>
</pre>
in .js:
<pre>
for (var player_id in this.gamedatas.players) {
var player_color = this.gamedatas.players[player_id].color;
var player_name = this.gamedatas.players[player_id].name;
$('empire_title_'+player_color).innerHTML=this.format_string_recursive(_("${player_name}'s EMPIRE"), {player_name: player_name});
}
</pre>

==== Translating strings in material file ====

Rarely, in your material.inc.php, if for example you need to use some string elements in your exceptions.

<pre>
// In material.inc.php, $this->energies[n]['nametr'] has been created with the self::_() method. Now we can do this:
throw new BgaUserException( self::_("To execute this action you need more: ").' '.$this->energies[$resource_id]['nametr'] );
</pre>

Note: you could also do this, so you don't need to pollute your material file
throw new BgaUserException( self::_("To execute this action you need more: ").' '.self::_($this->energies[$resource_id]['name']) );

where $this->energies[$resource_id]['name'] were marked in material file using regular clienttranslate function
<pre>
$this->energies = [
22 => [
'name' => clienttranslate('Sun')
...
]
];
</pre>

==== Strings in getAllDatas ====

Rarely, in your "getAllDatas" PHP method, as the data return by this method is used only by current user.

Note: not sure why would you send strings from the server in this case, as same can be achieved on the client usually.

=== Function totranslate ===

'''totranslate( "my string to translate" ):'''

This function works exactly like 'clienttranslate', except it tells BGA that the string is not needed on client side.

You should not use this function, except on the following cases:
* Statistics name in stats.inc.php
* Option names and option values name in gameoptions.inc.php

== Top Secret Undocumented Features ==

If your string contains the clause '$${value}' (such as 'You gain $${value}.') then the translation system seems to move the position of the $ to a localized location (eg $5 in English but 5$ in French). This only seems to occur when using the argument 'value'.

In JavaScript, you can get the current user's language by retrieving the translation for the special string "$locale":

var lang = _('$locale'); // en, fr, etc.

== On server side - advanced (PHP) ==

If you want to use translation system in your custom static modules, you will first need to expose the _() function :
<pre>
class mygame extends Table {
// Exposing protected method translation
public static function totranslate($text) {
return self::_($text);
}
}
</pre>

Then you'll be able to use this directly in other modules by doing
<pre>
throw new BgaUserException(mygame::totranslate("Translated error from my awesome module file"));
</pre>

Notice how the "totranslate" is also used by the static analysis to detect your string. So the following will not work :
<pre>
$msg = "Translated error from my awesome module file";
throw new BgaUserException(mygame::totranslate($msg));
</pre>

== Analyze your project ==

It looks super complex but there is help!
On studio control panel you can find a button "Check project" - it runs bunch of static analysis on your project including scanning for bad translations and missing translations.
It also will extact all you translation keys as translator will see them so you can double check - and run spell checker on them.

BGA Code Sharing

2021-11-27T23:07:39Z

AmadanNaBriona: Undo revision 10374 by AmadanNaBriona (talk)

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode
| Code can be found in project
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout buy just using css
|-
|}

== 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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! 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)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Innovation
| https://github.com/micahstairs/bga-innovation
| Micah Stairs (micahstairs)
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).
The list below are no-games which do not have bgg id and not showing up there.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| https://studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| https://studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

BGA Code Sharing

2021-11-27T23:06:38Z

AmadanNaBriona: added Trick of the Rails

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode
| Code can be found in project
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout buy just using css
|-
|}

== 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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! 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)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Innovation
| https://github.com/micahstairs/bga-innovation
| Micah Stairs (micahstairs)
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).
The list below are no-games which do not have bgg id and not showing up there.

{| class="wikitable"
|-
! NAME
! CODE LINK
! DEVELOPER
|-
| Shared Code
| https://studio.boardgamearena.com/#!studiogame?game=sharedcode
| Victoria_La
|-
| Original BGA template
| https://studio.boardgamearena.com/#!studiogame?game=template
| Victoria_La
|-
|}

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

Game interface logic: Game.js

2021-11-02T01:47:08Z

AmadanNaBriona: /* File structure */

{{Studio_Framework_Navigation}}

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 a change from the server and how it will show in the browser.

== File structure ==

The details of how the file is structured are described below with comments on the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

;setup(gamedatas)
This method must set up the game user interface according to current game situation specified in parameters.
The method is called each time the game interface is displayed to a player, ie:

- when the game starts

- when a player refreshes the game page (F5)

"gamedatas" argument contains all datas retrieved by your "getAllDatas" PHP method.

;onEnteringState(stateName, args)
This method is called each time we are entering into a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling arg* method use args.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.

'''Warning''': for multipleactiveplayer states:
the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.
If you are doing initialization of some structure which do not depend on active player, you can just replace (this.isCurrentPlayerActive()) with (!this.isSpectator)
for the main switch in that method.

See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]

;onLeavingState(stateName)
This method is called each time we are leaving a game state.
You can use this method to perform some user interface changes at this moment (i.e. cleanup).

;onUpdateActionButtons(stateName, args)
In this method you can manage "action buttons" that are displayed in the action status bar and highlight active UI elements.
To access state arguments passed via calling arg* method use '''args''' parameter. Note: args can be null! For '''game''' states and when you don't supply state args function - it is null.
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of calls would depends on either you get into that state from transitions OR from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Difference_between_Single_active_and_Multi_active_states]]

== 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 a variable, not a function.
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains the initial set of data to init the game, created at game start or by 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 this is unnecessary).

; this.isCurrentPlayerActive()
: Returns true if the player on whose browser the code is running is currently active (it's his turn to play). Note: see remarks above about usage of this function inside onEnteringState method.

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

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

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; g_replayFrom
: Global contains reply number in live game, it is set to undefined (i.e. not set) when it is not a reply mode, so consequentially the good check is '''g_replayFrom !== undefined''' which returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

You may consider making a function like this, to detect if the game is in a read-only state:

// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

== Dojo framework ==

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

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing and manipulating the DOM ==

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

The $() function is used to get an 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 the BGA Framework. You can use '''getElementById''' but a longer to type and less handy as it does not do some checks.
Note²: It is safe to use if you don't know if variable is string (id of element) or element itself, i.e.
<pre>
foo: function(card) {
card = $(card); // now its node, no need to write if (typeof card === 'string') ...
// but its good idea to check for null here
...
}
</pre>

'''dojo.style'''

With dojo.style you can modify the CSS property of any HTML element in 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 sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

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

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

'''Vanila JS style'''
$('my_element').style.display='none'; // set
var display = $('my_element').style.display; // get
$('my_element').style.removeProperty('display'); // remove

'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications 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 without error.
* You can test whether you applied the CSS to an element with the '''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 changes in one line of code.

// ... and when we need to check if a square is a possible move on the 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.attr'''

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''Vanila JS attr'''

$(token).id=new_id; // set attr for "id"
var id = $(token).id; // get

'''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 (i.e., elements of class "token") on the board (i.e., the 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>

'''Vanila JS query'''

var cards=document.querySelectorAll(".hand .card");// all cards in all hands
var cards=$('hand').querySelectorAll(".card");// all cards in specific hand
var card=document.querySelector(".hand .card");// first card or null if none (super handy)

'''dojo.place'''

dojo.place is the best function to insert HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if 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 values:

"replace" : (see description above).

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

"last" (default) : 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.

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

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

positive integer: This parameter can be a positive 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: [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

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]]".

But you can also relocate elements like that. Note: it won't animate if you do that.

'''dojo.empty'''

Remove all children of the node element
dojo.empty('my_hand');

'''dojo.destroy'''

Remove the element

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

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

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

'''this.format_block'''
This bga function that takes global var from template file and substitute variables, typical use would be

var player = gamedatas.players[player_id];
var div = this.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file

'''this.format_string'''
This bga function just substitute variables in a string, i.e.
var div = this.format_string('<div color="${player_color}"></div>', {player_color: '#ff0000'} );

'''this.format_string_recursive'''
This bga function is similar to this.format_string but is capable of processing recursive argument structures and translations. It is used to format server notifications.

=== 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.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

'''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' ).play();
</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, but it starts the animation.

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. Its starts the animation.

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>

Note: This wiki was probably written 10 years ago - now all modern broser support 'transform' so just ignore this and use transform.

'''Animation Callbacks'''

If you wish to run some code only after an animation has completed you can do this by linking a callback method.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));
animation_id.play();

…

callback_function: function(params) {
// this will be called after the animation ends
},
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

=== Moving elements ===

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

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

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 methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>
Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.

'''this.connect'''
function(element, event, handler)

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

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.

'''this.connectClass'''
function( cssClassName, event, handler )

Same as connect(), but for all the nodes set with the specified cssClassName.
<pre>
this.connectClass('pet', 'onclick', 'onPet');
</pre>
'''this.disconnect'''
function( element, event )

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

'''this.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 (i.e: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not authorized (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.checkPossibleActions'''
function( action, nomessage )

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario.

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)

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

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions.

* 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 parameters in order the interface can be locked during the server call.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.
* ajax_method: (optional and rarely used) if you need to send large amounts of data (over 2048 bytes), you can set this parameter to 'post' (all lower-case) to send a POST request as opposed to the default GET. This works, but was not officially documented, so only use if you really need to.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
// NB : usually not needed as changes must be handled by notifications
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)
// You should NOT make another ajaxcall in a callback in order not to create race conditions
} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = [];
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args,//
this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''this.isInterfaceLocked()'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.

== 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 all notifications arguments with "notif.args".

Example:

PHP

<pre>
self::notifyAllPlayers( "myNotification", '', array( "myArgument" => 3 ) );
</pre>

JavaScript

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

=== The notification Object received by client ===

When sending a notification on your PHP, the client side will receive an Object with the following attributes:

* args : This is the arguments that you passed on your notification method on php
* bIsTableMsg : Boolean, is true when you use [[Main_game_logic:_yourgamename.game.php#NotifyAllPlayers|NotifyAllPlayers]] method (false otherwise)
* channelorig : information about table ID (formatted as : "/table/t[TABLE_NUMBER]")
* gamenameorig : name of the game
* log: the log information as written in PHP function
* move_id : ID of the move associated with the notification
* table_id : ID of the table
* time : UNIX GMT time
* type : name of the notification
* uid : identifier of the notification

'' Note that those information were inferred from observation on console log. If an Admin can confirm/correct (and remove this line), you're welcome :)''

=== 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, there 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>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</pre>

=== WARNING: combining synchronous and ignored notifications ===
You must be careful when combining dynamic synchronous durations (as described above) with ignored notifications. If you have a conditionally ignored notification like this (see below section):

<pre>this.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.player_id) /* or any other condition */ )</pre>

then you CANNOT do

<pre>this.notifqueue.setSynchronous('myNotif');</pre>

as, when the ignored check passes, the notification handler, in which `this.notifqueue.setSychronousDuration` is called, is never called and so the duration is never set and interface locking results.

The workaround is to set a "dummy" time:

<pre>this.notifqueue.setSynchronous('myNotif', 5000);</pre>

whose value is irrelevant but must be large enough to cover the time before the notification handler is called. The large value never actually comes into play because the notification is either ignored, or the synchronous duration is reset to a sensible value inside the handler.

=== Ignoring notifications ===
Sometimes you need to ignore some notification on client side. You don't want them to be shown in game log and you don't want them to be handled.

The most common use case is when a player gets private information. They will receive a specific notification (such as "You received Ace of Heart"), while other players would receive more generic notification ("Player received a card").

In X.game.php
<pre>
$this->notifyAllPlayers("dealCard", clienttranslate('${player_name} received a card'), [
'player_id' => $playerId,
'player_name' => $this->getActivePlayerName()
]);

$this->notifyPlayer($playerId, "dealCardPrivate", clienttranslate('You received ${cardName}'), [
"type" => $card["type"],
"cardName" => $this->getCardName($card["type"])
]);
</pre>

The problem with this approach is that the active player will receive two notifications:
* Player1 received a card
* You received Ace of Hearts

Hence, notification ignoring. Similar to setting a synchronous notification above, you can set up a check whether a notification should be ignored:
<pre>
this.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => (notif.args.player_id == this.player_id) );
</pre>

'''setIgnoreNotificationCheck(notificationId, predicate)'''
This method will set a check whether any of notifications of specific type should be ignored.

The parameters are:
* notificationId: before dispatching any notification of this type, the framework will call predicate to check whether notification should be ignored
* predicate (notif => boolean): a function that will receive notif object and will return true if this specific notification should be ignored

NOTE: You can think that it could be possible to send generic notification to all other players with notifyAllPlayers and it will seem to work. The problem is that table spectators would miss this notification and their user interface (and game log) wouldn't be updated.

IMPORTANT: Remember that this notification is ignored on the client side, but was still received by the client. Therefore it shouldn't contain any private information as cheaters can get it. In other words this is not a way to hide information.

IMPORTANT: When a game is reloaded with F5 or when opening a turn based game, old notifications are replayed as history notification. They are used just to update the game log and are stripped of all arguments except player_id, i18n and any argument present in message. If you use and other argument in your predicate you should preserve it as explained [[Main_game_logic:_yourgamename.game.php#Notify_players|here]].

=== 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', [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

== Tooltips ==

'''this.addTooltip( nodeId, helpStringTranslated, actionStringTranslated, delay )'''

Add a simple text tooltip to the DOM node.

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

You must specify both of the strings. You can only use one and specify an empty string ('') for the other one.

When you pass text directly function _() must be used for the text to be marked for translation! Except for empty string.

Parameter "delay" is optional. 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 browsers (see [[BGA_Studio_Guidelines|Guidelines]]).

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

Note: this generates static tooltip and attaches to existing dom element, if you need to generate tooltip more dynamically you have to call that method every time information about object is updated or use completely different tehnique

'''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, helpStringTranslated, actionStringTranslated, delay )'''

Add a simple text tooltip to all the DOM nodes set with this cssClass. See more details above for this.addTooltip.
this.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

IMPORTANT: all concerned nodes must exist and 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 exist and have IDs to get tooltips.

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

Remove a tooltip from the DOM node with given id.

'''force tooltip to open'''

If you want to force tooltip to open in reaction to some other action, i.e. click you can do this

this.tooltips[id].open(id)

where id is the id of the tooltip node where tooltip was installed.

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

=== Warning messages ===

Sometimes, there is something important that is happening in 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 fulfills one of the end of the game conditions, 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 the current player.

* "msg" is the string to display. It should be translated.
* "type" can be set to "info", "error", or "only_to_log". 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. If set to "only_to_log", the message will be added to the game log but will not popup at the top of the screen.

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 guideline of BGA is to AVOID the use of confirmation dialogs. Confirmation dialogs slow down the game and bother players. The players know that they have to pay attention to each move when they are playing online.

The situations 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 does 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 ===

As a general rule, 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 over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// 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.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.destroy();
} );

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback( function() { ... } );

=== 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" => clienttranslate("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, duration, offset_x, offset_y );
</pre>

'''anchor_id''': ID of the element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+'

'''duration''': animation duration in milliseconds

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation. Note that the score is centered in the anchor, so the offsets might have to be negative if you calculate the position.

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.

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

text - what to put in bubble, can be html actually not just text

delay - in milliseconds is optional (default 0)

duration - in milliseconds is optional (default 3000)

custom_class - extra class to add to bubble is optional, if you need to override the default bubble style

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Update players score ==

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).

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>

Set a player score to a specific value with animation :

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

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_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 ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

; 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'.

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

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

== BGA Buttons ==

'''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 Hearts 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)

'''buttons with images'''

You can use the same method, but add extra class to a button to disable the padding and style it, i.e.
<pre>
this.addActionButton( 'button_brick', '<div class="brick"></div>', ()=>{... on brick ...}, null, null, 'gray');
dojo.addClass('button_brick','bgaimagebutton');
</pre>

where

<pre>
.bgaimagebutton {
padding: 0px 12px;
min-height: 28px;
border: none;
}
</pre>

If you use this a lot, you can define a helper function, i.e.
<pre>
/**
* This method can be used instead of addActionButton, to add a button which is an image (i.e. resource). Can be useful when player
* need to make a choice of resources or tokens.
*/
addImageActionButton: function(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.addActionButton(id, div, handler, '', false, bcolor);
// remove boarder, for images it better without
dojo.style(id, "border", "none");
// but add shadow style (box-shadow, see css)
dojo.addClass(id, "shadow bgaimagebutton");
// you can also add addition styles, such as background
if (tooltip) {
dojo.attr(id, "title", tooltip);
}
return $(id);
},
</pre>

'''buttons outside of action bar'''

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<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 out ''Coloretto''.

Note: You can also create button using addActionButton() method, then move anywhere
<pre>
this.addActionButton( 'commit_button', _('Confirm'), 'onConfirm', null, true, 'red');
dojo.place('commit_button','player_board');
</pre>

'''Disabling:'''
You can disable the '''bgabutton''' by adding the css class '''disabled''' in you js. The disabled button is still visible but is grey and not clickable.
For example in the '''onUpdateActionButtons''' :
<pre>this.addActionButton( 'play_button_id', _('Play 1 to 3 cards'), 'playFunctionButton', null, false, 'blue' ); //Create a blue button
if (Condition == true)
{
dojo.addClass( 'play_button_id', 'disabled');//disable the button
}</pre>

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>');
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

Your game state machine: states.inc.php

2021-11-02T01:46:25Z

AmadanNaBriona: /* Difference between Single active and Multi active states */

{{Studio_Framework_Navigation}}

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

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

[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]

== Overall structure ==

The machine states are described by a PHP associative array.

Example:

<pre>
$machinestates = array(

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

// Note: ID=2 => your first state

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

== Syntax ==

=== id ===

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

IDs must be positive integers.

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

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

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

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

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

=== name ===

('''Mandatory''')

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

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

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

PHP example:
<pre>

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

</pre>

JS example:
<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
case 'myGameState':

// Do some stuff at the beginning at this game state
....

break;
</pre>

=== type ===

('''Mandatory''')

You can use 3 types of game states:
* activeplayer (1 player is active and must play.)
* multipleactiveplayer (1..N players can be active and must play.)
* game (No player is active. This is a transitional state to do something automatic specified by the game rules.)

'''Note:''' Make sure you don't mistype the value of this attribute. If you do (e.g. 'multiactiveplayer' instead of 'multipleactiveplayer'), things won't work, and you might have a hard time figuring out why.

=== description ===

('''Mandatory''')

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

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

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

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

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

Example of custom field:
<pre>

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

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

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

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

=== descriptionmyturn ===

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

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

In general, we have this situation:

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

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

Note 2: you can use ${otherplayer} to refer to some other player if you want this to be shown in player's color, but you must provide otherplayer_id as argument (along with otherplayer) to specify this player's id in this case or game won't load.

I.e.

"descriptionmyturn" => clienttranslate('${you} can follow action of ${otherplayer}'),

And this will have to be state arguments for this
<pre>
function arg_playerTurnFollow(){
return ['otherplayer'=> $this->getLeaderPlayerName(),
'otherplayer_id'=> $this->getLeaderPlayerId()
];
}
</pre>

=== action ===

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

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

Example:
In states.inc.php:
<pre>
28 => array(
"name" => "gameTurnNextPlayer",
"description" => clienttranslate('Updating some stuff...'),
"type" => "game",
"action" => "st_gameTurnNextPlayer",
</pre>
In mygame.game.php:
<pre>
function st_gameTurnNextPlayer() {
$player_id = $this->getActivePlayerId();
$next_player_id = $this->getPlayerAfter($player_id);
$this->giveExtraTime($next_player_id);
$this->incStat(1, 'turns_number', $next_player_id);
$this->incStat(1, 'turns_number');
$this->gamestate->changeActivePlayer($next_player_id);
$this->gamestate->nextState('next');
}
</pre>

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

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

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

Example for action in player state:
in states.inc.php:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'st_MultiPlayerInit',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "playPlace" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>
in mygame.game.php:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

=== transitions ===

('''Mandatory''')

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

Example:
<pre>
25 => array(
"name" => "myGameState",
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
....
}
</pre>

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

Example to jump to ID 27:
<pre>
In mygame.game.php:
$this->gamestate->nextState( "nextPlayer" );
</pre>

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

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

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

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

=== possibleactions ===

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

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

Example:

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

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

....

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

....

</pre>

=== args ===

(optional)

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

Example 1: in ''Reversi'', the list of possible moves during the playerTurn state.

Example 2: in ''Caylus'', the number of remaining king's favors to choose in the state where the player is choosing a favor.

Example 3: in ''Can't Stop'', the list of possible die combinations to be displayed to the active player so that he can choose from among them.

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

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

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

In states.inc.php, we specify an '''args''' argument for gamestate '''playerTurn''':
<pre>
10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn", // <==== HERE
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),
</pre>

It corresponds to a '''argPlayerTurn''' method in our PHP code (reversi.game.php):
<pre>
function argPlayerTurn() {
return array(
'possibleMoves' => self::getPossibleMoves()
);
}
</pre>

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

<pre>
onEnteringState: function( stateName, args ) {
console.log( 'Entering state: '+stateName );

switch( stateName ) {
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

==== Naming and API conventions ====

As a BGA convention, PHP methods called with "args" are prefixed by "arg" followed by state name (example: '''argPlayerTurn''').

All "arg*" methods are put into corresponding section of .game.php file commented as
//////////// Game state arguments

Arg method MUST return array. Return integer or string will result in some undebuggable exceptions.

Arg method MUST be defined in php if it is declared in state description, if you don't need it comment it out from the states.inc.php file (the '''args''' parameter). If you not sure if you need it or not you can keep it returning empty array until you figure it out.

function argPlayerTurn() {
return array(); // must be an array
}

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

You should NOT be calling getCurrentPlayer() in the context of this function, since state transitions are broadcasted to all player independent of who initiated it. Instead you should send information on per player basis (Note: if this is private info see section below).

If you using this function in multi-player state, you should not call getActivePlayer() either, you should send per player info:

function arg_playerTurn() {
$res = array ();
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player_info ) {
$color = $player_info ['player_color'];
$res [$player_id] = array("color"=>$color);
}
return $res;
}

Note: you never need to send player color like this, this is just an example.

Note 2: you CAN call methods that return all active players if multi-player states if its relevant.

==== Other usages ====

You can use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn", i.e. in states.inc.php:

"descriptionmyturn" => clienttranslate('${you} must play ${color} disc'),

So arg function will be something like:

function argPlayerTurn() {
return array('color'=>this->getActivePlayerColor());
}

You can use args also in '''onUpdateActionButtons''' function on js side, however two important notes:
* it is just '''args''' (not args.args like in '''onEnteringState''')
* it is args of the current state, which may not be state you think it will be! This method is called during change of active player, which happens in some weird place especially during "multipleactiveplayer" states. If you pulling your hair thinking why its "undefined" on js side - check the current state.

==== Private info in args ====

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

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

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

<pre>
function argPlayerTurn() {
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private
'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),
'possibleMoves' => self::getPossibleMoves() // will be sent to all players
);
}
</pre>

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

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

<pre>
function argPlayerTurn() {
$specific_player_id = ...; // calculate some-how
return array(
'_private' => array( // all data inside this array will be private
$specific_player_id => array( // will be sent only to that player
'somePrivateData' => self::getSomePrivateData()
)
),

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

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

It is also possible to use these private args in the "description" messages, like "${you} have to play ${_private.count} cards".

==== Translations in args ====
You can do the same as in notification by adding i18n parameter, i.e
<pre>
function argPlayerTurn() {
return [
'i18n' => ['terrainName' ],
'terrainName' => ($this->token_types[$terrain]['name']), // this should be defined in material.inc.php and with clienttranslate
'terrain' => $terrain,
];
}
</pre>

Than you can do something like this in state:
"descriptionmyturn" => clienttranslate('${you} must place a house on ${terrainName}'),

See more in [[Translations]]

=== updateGameProgression ===

(optional)

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

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

== Implementation Notes ==

=== Using Named Constants for States ===

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

EXAMPLE:

states.inc.php:

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

$machinestates = array(

...

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

=== Example of multipleactiveplayer state ===

This is an example of a multipleactiveplayer state:

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

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

Note: if you want exact this function its already defined in table class its called 'stMakeEveryoneActive'

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

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

=== Difference between Single active and Multi active states ===
In a classic "activePlayer" state:

* You cannot change the active player DURING the state. This is to ensure that during 1 activePlayer state, only ONE player is active
* As a consequence, you must set the active player BEFORE entering the activePlayer state
* In such states on JS side onUpdateActionButtons is called before onEnteringState during game play (but after during reload, i.e. F5)
* Finally, during onEnteringState, on JS side, the active player is signaled as active and the information is reliable and usable.

In a "multiplePlayer" state:

* You can (and must) change the active players DURING the state
* During such a state, players can be activated/desactivated anytime during the state, giving you the maximum of possibilities.
* You shouldn't set active player before entering the state. But you can set it in "state initializer" php function (see example above st_MultiPlayerInit)
* Finally, during onEnteringState, on JS side, the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.

=== Designing states ===

As a general rule you state machine should resemble "round/turn overview" from the game rule-book. Normally if book say its player turn and player can do multiple things during their turn it is still only
one player state (plus a game to switch player), not muliple states.

In a classic game (i.e. chess), there is only active player at any time, so it is simple playerTurn/gameTurn sequence and you only need 2 states.

[[File:Simplestates.png]]

In complex euro game there can be multiple rounds, and each round have phases which can be distinctly unique, i.e. in first phase everybody draws card and discard (multi-player), then player have one turn each (single-active), then another is resolution of actions from players and some of them may become active again, then there is round upkeep/reset. This would require one multi-player state for phase 1, pair of states for phase2 (singel-active + game), pair of states for phase3 and finally round-end/unkeep game state.

For pair of active player/game states you can make player state first, which transitions to game state, or the other way around, you start with game state which transition to active player state, its loop in any case but depends on how you want to do "phase" initiazations.

[[File:Eurogamestates.png]]

=== Complete examples ===

Example of simple game where player take turns

<pre>
if ( !defined('STATE_END_GAME')) { // guard since this included multiple times
define("STATE_PLAYER_TURN", 2);
define("STATE_GAME_TURN_NEXT_PLAYER", 3);
define("STATE_PLAYER_GAME_END", 4);
define("STATE_END_GAME", 99);
}

$machinestates = [
1 => [ // The initial state. Please do not modify.
"name" => "gameSetup",
"description" => "",
"type" => "manager",
"action" => "stGameSetup",
"transitions" => [ "" => STATE_PLAYER_TURN ] ],
// Game states
STATE_PLAYER_TURN => [ // main active player state
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must do something or pass'),
"descriptionmyturn" => clienttranslate('${you} must do something or pass'),
"type" => "activeplayer",
"args" => "arg_playerTurn",
"possibleactions" => [ "dosomething","pass" ],
"transitions" => [ "next" => STATE_GAME_TURN_NEXT_PLAYER,"last" => STATE_PLAYER_GAME_END ] //
],
STATE_GAME_TURN_NEXT_PLAYER => [ // next player state
"name" => "gameTurnNextPlayer",
"description" => clienttranslate('Upkeep...'),
"type" => "game", //
"action" => "st_gameTurnNextPlayer", //
"updateGameProgression" => true,
"transitions" => [ "next" => STATE_PLAYER_TURN,"loopback" => STATE_GAME_TURN_NEXT_PLAYER,
"last" => STATE_PLAYER_GAME_END ], // TODO replace with STATE_END_GAME, its there to use undo/restore during dev
],

STATE_PLAYER_GAME_END => [ // active player state for debugging end of game
"name" => "playerGameEnd",
"description" => clienttranslate('${actplayer} Game Over'),
"descriptionmyturn" => clienttranslate('${you} Game Over'),
"type" => "activeplayer",
"args" => "arg_playerTurn",
"possibleactions" => ["endGame"],
"transitions" => ["next" => STATE_END_GAME,"loopback" => STATE_PLAYER_GAME_END ] //
],
// End of Game states
// Final state.
// Please do not modify (and do not overload action/args methods).
STATE_END_GAME => [
"name" => "gameEnd",
"description" => clienttranslate("End of game"),"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd" ]

];

</pre>

Your game state machine: states.inc.php

2021-11-02T01:39:58Z

AmadanNaBriona: /* Diffrence between Single active and Multi active states */

{{Studio_Framework_Navigation}}

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

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

[http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine]

== Overall structure ==

The machine states are described by a PHP associative array.

Example:

<pre>
$machinestates = array(

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

// Note: ID=2 => your first state

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

== Syntax ==

=== id ===

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

IDs must be positive integers.

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

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

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

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

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

=== name ===

('''Mandatory''')

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

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

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

PHP example:
<pre>

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

</pre>

JS example:
<pre>
onEnteringState: function( stateName, args )
{
console.log( 'Entering state: '+stateName );

switch( stateName )
case 'myGameState':

// Do some stuff at the beginning at this game state
....

break;
</pre>

=== type ===

('''Mandatory''')

You can use 3 types of game states:
* activeplayer (1 player is active and must play.)
* multipleactiveplayer (1..N players can be active and must play.)
* game (No player is active. This is a transitional state to do something automatic specified by the game rules.)

'''Note:''' Make sure you don't mistype the value of this attribute. If you do (e.g. 'multiactiveplayer' instead of 'multipleactiveplayer'), things won't work, and you might have a hard time figuring out why.

=== description ===

('''Mandatory''')

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

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

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

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

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

Example of custom field:
<pre>

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

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

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

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

=== descriptionmyturn ===

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

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

In general, we have this situation:

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

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

Note 2: you can use ${otherplayer} to refer to some other player if you want this to be shown in player's color, but you must provide otherplayer_id as argument (along with otherplayer) to specify this player's id in this case or game won't load.

I.e.

"descriptionmyturn" => clienttranslate('${you} can follow action of ${otherplayer}'),

And this will have to be state arguments for this
<pre>
function arg_playerTurnFollow(){
return ['otherplayer'=> $this->getLeaderPlayerName(),
'otherplayer_id'=> $this->getLeaderPlayerId()
];
}
</pre>

=== action ===

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

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

Example:
In states.inc.php:
<pre>
28 => array(
"name" => "gameTurnNextPlayer",
"description" => clienttranslate('Updating some stuff...'),
"type" => "game",
"action" => "st_gameTurnNextPlayer",
</pre>
In mygame.game.php:
<pre>
function st_gameTurnNextPlayer() {
$player_id = $this->getActivePlayerId();
$next_player_id = $this->getPlayerAfter($player_id);
$this->giveExtraTime($next_player_id);
$this->incStat(1, 'turns_number', $next_player_id);
$this->incStat(1, 'turns_number');
$this->gamestate->changeActivePlayer($next_player_id);
$this->gamestate->nextState('next');
}
</pre>

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

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

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

Example for action in player state:
in states.inc.php:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'st_MultiPlayerInit',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "playPlace" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>
in mygame.game.php:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

=== transitions ===

('''Mandatory''')

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

Example:
<pre>
25 => array(
"name" => "myGameState",
"transitions" => array( "nextPlayer" => 27, "endRound" => 39 ),
....
}
</pre>

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

Example to jump to ID 27:
<pre>
In mygame.game.php:
$this->gamestate->nextState( "nextPlayer" );
</pre>

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

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

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

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

=== possibleactions ===

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

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

Example:

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

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

....

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

....

</pre>

=== args ===

(optional)

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

Example 1: in ''Reversi'', the list of possible moves during the playerTurn state.

Example 2: in ''Caylus'', the number of remaining king's favors to choose in the state where the player is choosing a favor.

Example 3: in ''Can't Stop'', the list of possible die combinations to be displayed to the active player so that he can choose from among them.

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

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

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

In states.inc.php, we specify an '''args''' argument for gamestate '''playerTurn''':
<pre>
10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn", // <==== HERE
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),
</pre>

It corresponds to a '''argPlayerTurn''' method in our PHP code (reversi.game.php):
<pre>
function argPlayerTurn() {
return array(
'possibleMoves' => self::getPossibleMoves()
);
}
</pre>

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

<pre>
onEnteringState: function( stateName, args ) {
console.log( 'Entering state: '+stateName );

switch( stateName ) {
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

==== Naming and API conventions ====

As a BGA convention, PHP methods called with "args" are prefixed by "arg" followed by state name (example: '''argPlayerTurn''').

All "arg*" methods are put into corresponding section of .game.php file commented as
//////////// Game state arguments

Arg method MUST return array. Return integer or string will result in some undebuggable exceptions.

Arg method MUST be defined in php if it is declared in state description, if you don't need it comment it out from the states.inc.php file (the '''args''' parameter). If you not sure if you need it or not you can keep it returning empty array until you figure it out.

function argPlayerTurn() {
return array(); // must be an array
}

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

You should NOT be calling getCurrentPlayer() in the context of this function, since state transitions are broadcasted to all player independent of who initiated it. Instead you should send information on per player basis (Note: if this is private info see section below).

If you using this function in multi-player state, you should not call getActivePlayer() either, you should send per player info:

function arg_playerTurn() {
$res = array ();
$players = $this->loadPlayersBasicInfos();
foreach ( $players as $player_id => $player_info ) {
$color = $player_info ['player_color'];
$res [$player_id] = array("color"=>$color);
}
return $res;
}

Note: you never need to send player color like this, this is just an example.

Note 2: you CAN call methods that return all active players if multi-player states if its relevant.

==== Other usages ====

You can use values returned by your "args" method to have some custom values in your "description"/"descriptionmyturn", i.e. in states.inc.php:

"descriptionmyturn" => clienttranslate('${you} must play ${color} disc'),

So arg function will be something like:

function argPlayerTurn() {
return array('color'=>this->getActivePlayerColor());
}

You can use args also in '''onUpdateActionButtons''' function on js side, however two important notes:
* it is just '''args''' (not args.args like in '''onEnteringState''')
* it is args of the current state, which may not be state you think it will be! This method is called during change of active player, which happens in some weird place especially during "multipleactiveplayer" states. If you pulling your hair thinking why its "undefined" on js side - check the current state.

==== Private info in args ====

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

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

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

<pre>
function argPlayerTurn() {
return array(
'_private' => array( // Using "_private" keyword, all data inside this array will be made private
'active' => array( // Using "active" keyword inside "_private", you select active player(s)
'somePrivateData' => self::getSomePrivateData() // will be send only to active player(s)
)
),
'possibleMoves' => self::getPossibleMoves() // will be sent to all players
);
}
</pre>

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

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

<pre>
function argPlayerTurn() {
$specific_player_id = ...; // calculate some-how
return array(
'_private' => array( // all data inside this array will be private
$specific_player_id => array( // will be sent only to that player
'somePrivateData' => self::getSomePrivateData()
)
),

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

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

It is also possible to use these private args in the "description" messages, like "${you} have to play ${_private.count} cards".

==== Translations in args ====
You can do the same as in notification by adding i18n parameter, i.e
<pre>
function argPlayerTurn() {
return [
'i18n' => ['terrainName' ],
'terrainName' => ($this->token_types[$terrain]['name']), // this should be defined in material.inc.php and with clienttranslate
'terrain' => $terrain,
];
}
</pre>

Than you can do something like this in state:
"descriptionmyturn" => clienttranslate('${you} must place a house on ${terrainName}'),

See more in [[Translations]]

=== updateGameProgression ===

(optional)

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

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

== Implementation Notes ==

=== Using Named Constants for States ===

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

EXAMPLE:

states.inc.php:

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

$machinestates = array(

...

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

=== Example of multipleactiveplayer state ===

This is an example of a multipleactiveplayer state:

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

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

Note: if you want exact this function its already defined in table class its called 'stMakeEveryoneActive'

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

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

=== Difference between Single active and Multi active states ===
In a classic "activePlayer" state:

* You cannot change the active player DURING the state. This is to ensure that during 1 activePlayer state, only ONE player is active
* As a consequence, you must set the active player BEFORE entering the activePlayer state
* In such sates on JS side onUpdateActionButtons is called before onEnteringState during game play (but after during reload, i.e. F5)
* Finally, during onEnteringState, on JS side, the active player is signaled as active and the information is reliable and usable.

In a "multiplePlayer" state:

* You can (and must) change the active players DURING the state
* During such a state, players can be activated/desactivated anytime during the state, giving you the maximum of possibilities.
* You shouldn't set active player before entering the state. But you can set it in "state initializer" php function (see example above st_MultiPlayerInit)
* Finally, during onEnteringState, on JS side, the active players are NOT active yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/inactive status.

=== Designing states ===

As a general rule you state machine should resemble "round/turn overview" from the game rule-book. Normally if book say its player turn and player can do multiple things during their turn it is still only
one player state (plus a game to switch player), not muliple states.

In a classic game (i.e. chess), there is only active player at any time, so it is simple playerTurn/gameTurn sequence and you only need 2 states.

[[File:Simplestates.png]]

In complex euro game there can be multiple rounds, and each round have phases which can be distinctly unique, i.e. in first phase everybody draws card and discard (multi-player), then player have one turn each (single-active), then another is resolution of actions from players and some of them may become active again, then there is round upkeep/reset. This would require one multi-player state for phase 1, pair of states for phase2 (singel-active + game), pair of states for phase3 and finally round-end/unkeep game state.

For pair of active player/game states you can make player state first, which transitions to game state, or the other way around, you start with game state which transition to active player state, its loop in any case but depends on how you want to do "phase" initiazations.

[[File:Eurogamestates.png]]

=== Complete examples ===

Example of simple game where player take turns

<pre>
if ( !defined('STATE_END_GAME')) { // guard since this included multiple times
define("STATE_PLAYER_TURN", 2);
define("STATE_GAME_TURN_NEXT_PLAYER", 3);
define("STATE_PLAYER_GAME_END", 4);
define("STATE_END_GAME", 99);
}

$machinestates = [
1 => [ // The initial state. Please do not modify.
"name" => "gameSetup",
"description" => "",
"type" => "manager",
"action" => "stGameSetup",
"transitions" => [ "" => STATE_PLAYER_TURN ] ],
// Game states
STATE_PLAYER_TURN => [ // main active player state
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must do something or pass'),
"descriptionmyturn" => clienttranslate('${you} must do something or pass'),
"type" => "activeplayer",
"args" => "arg_playerTurn",
"possibleactions" => [ "dosomething","pass" ],
"transitions" => [ "next" => STATE_GAME_TURN_NEXT_PLAYER,"last" => STATE_PLAYER_GAME_END ] //
],
STATE_GAME_TURN_NEXT_PLAYER => [ // next player state
"name" => "gameTurnNextPlayer",
"description" => clienttranslate('Upkeep...'),
"type" => "game", //
"action" => "st_gameTurnNextPlayer", //
"updateGameProgression" => true,
"transitions" => [ "next" => STATE_PLAYER_TURN,"loopback" => STATE_GAME_TURN_NEXT_PLAYER,
"last" => STATE_PLAYER_GAME_END ], // TODO replace with STATE_END_GAME, its there to use undo/restore during dev
],

STATE_PLAYER_GAME_END => [ // active player state for debugging end of game
"name" => "playerGameEnd",
"description" => clienttranslate('${actplayer} Game Over'),
"descriptionmyturn" => clienttranslate('${you} Game Over'),
"type" => "activeplayer",
"args" => "arg_playerTurn",
"possibleactions" => ["endGame"],
"transitions" => ["next" => STATE_END_GAME,"loopback" => STATE_PLAYER_GAME_END ] //
],
// End of Game states
// Final state.
// Please do not modify (and do not overload action/args methods).
STATE_END_GAME => [
"name" => "gameEnd",
"description" => clienttranslate("End of game"),"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd" ]

];

</pre>

Gamehelpladyandthetiger

2021-10-22T18:26:30Z

AmadanNaBriona: /* Contest End = */

== DOORS ==

''He was safe in his choice, for he knew''<br/>
''that the lady was in number two.''<br/>
''When he burst through her door,''<br/>
''he found out by the roar,''<br/>
''that tigers can be ladies too.''

--Tom Lang

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

(You may choose to guess or match a set before discarding.)

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

* Guess Color '''or''' Role: 1 gem
* Guess Color '''and''' Role: 5 gems
* Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ==

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-10-22T17:44:36Z

AmadanNaBriona:

== DOORS ==

''He was safe in his choice, for he knew''<br/>
''that the lady was in number two.''<br/>
''When he burst through her door,''<br/>
''he found out by the roar,''<br/>
''that tigers can be ladies too.''

--Tom Lang

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

(You may choose to guess or match a set before discarding.)

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

* Guess Color '''or''' Role: 1 gem
* Guess Color '''and''' Role: 5 gems
* Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-10-22T17:38:46Z

AmadanNaBriona:

— Tom Lang

== DOORS ==

''He was safe in his choice, for he knew''<br/>
''that the lady was in number two.''<br/>
''When he burst through her door,''<br/>
''he found out by the roar,''<br/>
''that tigers can be ladies too.''

--Tom Lang

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

* Guess Color '''or''' Role: 1 gem
* Guess Color '''and''' Role: 5 gems
* Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Anti-Stock

2021-10-05T00:16:27Z

AmadanNaBriona: /* Presentation */

== Overivew ==
If the [[Stock]] component works for you then great, you don't need this article. If you start tweaking it and you are doing something slightly more complex and you cannot find an answer, it may be best to not use it.
This article describes how to replace Stock.
What is Stock? It's a component that does a lot of stuff at once:
* It generates in-line attributes of an object the represents graphics and dimensions for "cards" (can be anything really).
* It also manages the layout of a single container of such cards, and cards within it - including animation.
* It also manages selections in that container.

Recipe to get rid of Stock (the gist):
* Create all cards as divs in the template file (with the help of view.php as needed)
* Create generic css classes for the cards defining images, sizing, etc. Create/generate a css class for each card type with background positioning - there are scripts in sharescode to generate grid positioning (which is what Stock does under the hood)
* Create a parent div for card placement and use dojo.place to move cards there. In css use your preferred layout for this, including margins, etc.
* Tricky one: When cards are moved during animations you have to use a special method; none of animation methods from BGA parent classes will work, as the card will not have absolute positioning. You can use methods from the sharedcode project or create your own (the trick is that during animation the object has to have absolute positioning, which is removed after the animation).

== Presentation ==
In modern JS the objects that we want to render will always be represented by '''div''' elements in the dom. This div will have a unique id, classes, and also custom data attributes which can be used for styling and selection.

Here is an example of some sort of card 1 of type card_21. Note that you probably don't need both card_21 as a class and as a data-num, you can use either for selection or styling.

<pre>
<div id="card_21_1" class="card card_21" data-num="21"></div>
</pre>

This is the 10 of hearts and king of clubs inside a hand in a game

<pre>
<div id="game" class="classic_deck">
<div id="hand" class="hand">
<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>
<div id="card_C_K" class="card" data-suit='C' data-rank="K"> </div>
</div>
</div>
</pre>

If you prefer not to use custom attributes you can do this:

<pre>
<div id="card_H_10" class="card_H_10 suit_H rank_10"> </div>
</pre>

Card id, does not have to be like this either, I use this one because it maps to my db, but if you are using the '''Deck''' component for cards in a "deck" table, you can use something like:

<pre>
<div id="deck_33" class="card_H_10 suit_H rank_10"> </div>
</pre>
where 33 is id which maps to database id of deck table.

Now we can use css to show graphics and defined size. Note unlike Stock - the size should not be bound in this component, your cards can have different sizes (for example in tooltips vs. in the hand).

We will use the BGA card stock https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg.

It has 15 columns.

<pre>
.card {
background-image: url('https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg'); /* don't do full url in your game, copy this file inside img folder */
background-size: 1500% auto; /* this mean size of background is 15 times bigger than size of card, because its sprite */
border-radius: 5%;
width: 10em;
height: 13.5em;
box-shadow: 0.1em 0.1em 0.2em 0.1em #555;
}

.card[data-rank="10"] { /* 10 is column number 10 - 2 because we start from 0 and first card is sprite is 2. The multiplier is (15 - 1) is because we have 15 columns. -1 is because % in CSS is weird like that. */
background-position-x: calc(100% / (15 - 1) * (10 - 2));
}
.card[data-rank="K"] { /* King will be number 13 in rank */
background-position-x: calc(100% / (15 - 1) * (13 - 2));
}

.card[data-suit="H"] { /* Hears row position is 1 (because we count from 0). Multiplier (4 - 1) is because we have 4 rows and -1 is because % in CSS is weird like that. */
background-position-y: calc(100% / (4 - 1) * (1));
}
.card[data-suit="C"] { /* Clubs row position is 2 */
background-position-y: calc(100% / (4 - 1) * (2));
}
</pre>

Now if you want to see these cards, we can put them in some specific component for example hand, and there we can define layout and sizing just for hand

<pre>
.hand .card {
font-size: 2.4rem;
display: inline-block;
}
</pre>
Working example: https://codepen.io/VictoriaLa/pen/rNwgWrB

To finish the deck you have to finish css for all rows/columns which whould be only 10-20 records, really easy and repetitive!
If you really cannot write that much css manually you can also generate it using php code (this is side kick command line - does not go to your game)
<pre>
<?php
// this simple script generates sprite css
// it has no params - fix inline to change what it generates

$from=1; // from index
$to=40+4; // to index
$maxcol=4; // number of columns in the sprite
$scol=$maxcol-1;
$srow=((int)(($to-$from)/$maxcol));
for ($num=$from;$num<=$to;$num++) {
$index=$num-$from;
$row=(int)($index/$maxcol);
$col=$index%$maxcol;
echo ".tech_E_$num { background-position: calc(100% / $scol * $col) calc(100% / $srow * $row);}\n";
}
?>
</pre>

And now if you want to user to have preferece for what deck style to use its just matter of change class from "classic_deck" to "fancy_deck" in our game parent div and adding in CSS

<pre>
.fancy_deck .card {
background-image: url('https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_DESIGN_COLORED.jpg');
}
</pre>

== Generating Dom Elements ==

=== Static - basic ===
You basically write all your cards in .tpl file. Just cut & paste you template and fix few classes. That is easiest!
In your js code you never create new element, you just move existing element inside dome. If you need a copy for tooltips, logs or button you can clone
one of them change id and add/remove class if needed.

<pre>
<div id="limbo" class="limbo">
<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>
<div id="card_C_K" class="card" data-suit='C' data-rank="K"> </div>
... rice and repeat ...
</div>
</pre>

=== Static - bga template engine ===
in .tpl
<div id="limbo" class="limbo">

<div id="card_{SUIT}_{RANK}" class="card card_{SUIT}_{RANK}" data-suit="{SUIT}" data-rank="{RANK}"></div>

</div>

in view.php
<div>
$this->page->begin_block($template, "deck_cards");
$ranks = [2,3,4,5,6,7,8,9,10,'J','Q','K','A'];
$suits = ['S','H','C','D'];
foreach ($ranks as $rank) {
foreach ($suits as $suit) {
$this->page->insert_block("deck_cards", [
'SUIT' => "$suit,
'RANK' => "$rank,
]);
}
}
</div>

=== Dynamic using .tpl thingy ===

In the js section of .tpl
<pre>
var jstpl_card = '<div id="card_{SUIT}_{RANK}" class="card card_{SUIT}_{RANK}" data-suit="{SUIT}" data-rank="{RANK}"></div>';
</pre>

in js:
let cardDiv = this.format_block('jstpl_card', {
SUIT : 'H',
RANK : 'A'
}); // this in js code somewhere before placing it

=== Dynamic using dojo ===
<pre>
let suit = 'H';
let rank = 'A';
let cardNode = dojo.create('div', {id: `card_${suit}_${rank}`, class: `card card_${suit}_${rank}`, dataSuit: suit, dataRank: rank});
dojo.place(cardNode, 'hand'); // place in hand for example
</pre>
Technically you can do it all in one line as "place" is 3rd parameter of dojo.create

=== Dynamic not using dojo ===
<pre>
let suit = 'H';
let rank = 'A';
let div = document.createElement('div');
div.id = `card_${suit}_${rank}`;
div.className = `card card_${suit}_${rank}`;
div.setAttribute('data-suit',suit);
div.setAttribute('data-rank',rank);
//console.log(div);
$('hand').appendChild(div);
</pre>

As you can see this is not most compact method, so you if you do that a lot probably create a function that generates this (which also would set a click handler and tooltip for example)

== Layout ==

You can use all web resources and powser of css to do any sort of fancy layout for your cards, you not bound to any predefined layouts.
The simplest would be display: inline-block as we already did above. You can also add margins to overlap cards for example
<pre>
.tableau {
position: relative;
width: 50em;
height: 30em;
outline: dashed 1px green;
transform: rotate(-90deg) scale(0.5);
padding: 1em;
display: flex;
justify-content: center;
flex-direction: row;
flex-wrap: wrap;
}

.tableau .card{
margin-right: -2em;
}

</pre>

In this example cards on tableu are smaller, rotated 90 degrees and overlaping.

https://codepen.io/VictoriaLa/pen/PojvWEV

[[File:Deck Layouts - codepen.io.png]]

== Selection and Click Handlers ==

To hookup selection or clicking, you have to manually hook up handler to all cards, which is easy

<pre>
document.querySelectorAll(".card").forEach(node=>node.addEventListener("click", (event) => {
var target = event.target;
target.classList.toggle('selected');
}
}));
</pre>

And you define class for selected in css
.selected {
outline: dashed blue 0.1em;
}

How if you need to do some action based on selection this can be in your "do something" button handler (this example below will create array of ids of cards)
<pre>
const card_ids = Array.from(document.querySelectorAll('.card.selected')).map(x=>x.id);
</pre>

If you need single selection, just add a call to remove all previous 'selected' from all card, before adding it.

If you don't need selection you can hook ajax call directly to handler above.

== Animation ==

The animation is the only tricky part because it does not come for free. The proper animation function is pretty lengthy so I won't even put it here.
Basically it short you would have to reparent out object without visual movement and then you can run animation on positions, and after it is done remove absolute positioning.

The simplier method is moving object itself, you can see code and example in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js
(slideToObjectRelative).

And more complex method moves "phantom" object on oversurface (which is neither parent of original object nor destination), code can found here (to use this your need 2 js methods for movement and classes for oversurface and oversurfacew > * from css):
https://codepen.io/VictoriaLa/pen/PojvWEV

Anti-Stock

2021-10-04T23:03:06Z

AmadanNaBriona: /* Overivew */

== Overivew ==
If the [[Stock]] component works for you then great, you don't need this article. If you start tweaking it and you are doing something slightly more complex and you cannot find an answer, it may be best to not use it.
This article describes how to replace Stock.
What is Stock? It's a component that does a lot of stuff at once:
* It generates in-line attributes of an object the represents graphics and dimensions for "cards" (can be anything really).
* It also manages the layout of a single container of such cards, and cards within it - including animation.
* It also manages selections in that container.

Recipe to get rid of Stock (the gist):
* Create all cards as divs in the template file (with the help of view.php as needed)
* Create generic css classes for the cards defining images, sizing, etc. Create/generate a css class for each card type with background positioning - there are scripts in sharescode to generate grid positioning (which is what Stock does under the hood)
* Create a parent div for card placement and use dojo.place to move cards there. In css use your preferred layout for this, including margins, etc.
* Tricky one: When cards are moved during animations you have to use a special method; none of animation methods from BGA parent classes will work, as the card will not have absolute positioning. You can use methods from the sharedcode project or create your own (the trick is that during animation the object has to have absolute positioning, which is removed after the animation).

== Presentation ==
In modern word the objects that we want to render will be always represented by div element in the dom. This div will have unique Id, classes and also custom data attributes which can be used for styling and selection.

This is some sort of card 1 of type card_21. Note that you probably don't need both card_21 as class and as data-num, you can use either for selection or styling.
<pre>
<div id="card_21_1" class="card card_21" data-num="21"></div>
</pre>

This is 10 of hearts and king of clubs inside a hand inside a game
<pre>
<div id="game" class="classic_deck">
<div id="hand" class="hand">
<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>
<div id="card_C_K" class="card" data-suit='C' data-rank="K"> </div>
</div>
</div>
</pre>

If you prefer not to use custom attributes you can do this
<pre>
<div id="card_H_10" class="card_H_10 suit_H rank_10"> </div>
</pre>

Card id, does not have to be like this either, I use this one because it maps to my db, but if you using Deck component for cards in "deck" table, you can use something like
<pre>
<div id="deck_33" class="card_H_10 suit_H rank_10"> </div>
</pre>
where 33 is id which maps to database id of deck table.

Now we can use css to show graphics and defined size. Note unlike stock - the size should not be bound this component, you cards can have different size for example in tooltips vs hand

We will use the BGA card stock https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg.
It has 15 columns.

<pre>
.card {
background-image: url('https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg'); /* don't do full url in your game, copy this file inside img folder */
background-size: 1500% auto; /* this mean size of background is 15 times bigger than size of card, because its sprite */
border-radius: 5%;
width: 10em;
height: 13.5em;
box-shadow: 0.1em 0.1em 0.2em 0.1em #555;
}

.card[data-rank="10"] { /* 10 is column number 10 - 2 because we start from 0 and first card is sprite is 2. The multiplier is (15 - 1) is because we have 15 columns. -1 is because % in CSS is weird like that. */
background-position-x: calc(100% / (15 - 1) * (10 - 2));
}
.card[data-rank="K"] { /* King will be number 13 in rank */
background-position-x: calc(100% / (15 - 1) * (13 - 2));
}

.card[data-suit="H"] { /* Hears row position is 1 (because we count from 0). Multiplier (4 - 1) is because we have 4 rows and -1 is because % in CSS is weird like that. */
background-position-y: calc(100% / (4 - 1) * (1));
}
.card[data-suit="C"] { /* Clubs row position is 2 */
background-position-y: calc(100% / (4 - 1) * (2));
}
</pre>

Now if you want to see these cards, we can put them in some specific component for example hand, and there we can define layout and sizing just for hand

<pre>
.hand .card {
font-size: 2.4rem;
display: inline-block;
}
</pre>
Working example: https://codepen.io/VictoriaLa/pen/rNwgWrB

To finish the deck you have to finish css for all rows/columns which whould be only 10-20 records, really easy and repetitive!
If you really cannot write that much css manually you can also generate it using php code (this is side kick command line - does not go to your game)
<pre>
<?php
// this simple script generates sprite css
// it has no params - fix inline to change what it generates

$from=1; // from index
$to=40+4; // to index
$maxcol=4; // number of columns in the sprite
$scol=$maxcol-1;
$srow=((int)(($to-$from)/$maxcol));
for ($num=$from;$num<=$to;$num++) {
$index=$num-$from;
$row=(int)($index/$maxcol);
$col=$index%$maxcol;
echo ".tech_E_$num { background-position: calc(100% / $scol * $col) calc(100% / $srow * $row);}\n";
}
?>
</pre>

And now if you want to user to have preferece for what deck style to use its just matter of change class from "classic_deck" to "fancy_deck" in our game parent div and adding in CSS

<pre>
.fancy_deck .card {
background-image: url('https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_DESIGN_COLORED.jpg');
}
</pre>

== Generating Dom Elements ==

=== Static - basic ===
You basically write all your cards in .tpl file. Just cut & paste you template and fix few classes. That is easiest!
In your js code you never create new element, you just move existing element inside dome. If you need a copy for tooltips, logs or button you can clone
one of them change id and add/remove class if needed.

<pre>
<div id="limbo" class="limbo">
<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>
<div id="card_C_K" class="card" data-suit='C' data-rank="K"> </div>
... rice and repeat ...
</div>
</pre>

=== Static - bga template engine ===
in .tpl
<div id="limbo" class="limbo">

<div id="card_{SUIT}_{RANK}" class="card card_{SUIT}_{RANK}" data-suit="{SUIT}" data-rank="{RANK}"></div>

</div>

in view.php
<div>
$this->page->begin_block($template, "deck_cards");
$ranks = [2,3,4,5,6,7,8,9,10,'J','Q','K','A'];
$suits = ['S','H','C','D'];
foreach ($ranks as $rank) {
foreach ($suits as $suit) {
$this->page->insert_block("deck_cards", [
'SUIT' => "$suit,
'RANK' => "$rank,
]);
}
}
</div>

=== Dynamic using .tpl thingy ===

In the js section of .tpl
<pre>
var jstpl_card = '<div id="card_{SUIT}_{RANK}" class="card card_{SUIT}_{RANK}" data-suit="{SUIT}" data-rank="{RANK}"></div>';
</pre>

in js:
let cardDiv = this.format_block('jstpl_card', {
SUIT : 'H',
RANK : 'A'
}); // this in js code somewhere before placing it

=== Dynamic using dojo ===
<pre>
let suit = 'H';
let rank = 'A';
let cardNode = dojo.create('div', {id: `card_${suit}_${rank}`, class: `card card_${suit}_${rank}`, dataSuit: suit, dataRank: rank});
dojo.place(cardNode, 'hand'); // place in hand for example
</pre>
Technically you can do it all in one line as "place" is 3rd parameter of dojo.create

=== Dynamic not using dojo ===
<pre>
let suit = 'H';
let rank = 'A';
let div = document.createElement('div');
div.id = `card_${suit}_${rank}`;
div.className = `card card_${suit}_${rank}`;
div.setAttribute('data-suit',suit);
div.setAttribute('data-rank',rank);
//console.log(div);
$('hand').appendChild(div);
</pre>

As you can see this is not most compact method, so you if you do that a lot probably create a function that generates this (which also would set a click handler and tooltip for example)

== Layout ==

You can use all web resources and powser of css to do any sort of fancy layout for your cards, you not bound to any predefined layouts.
The simplest would be display: inline-block as we already did above. You can also add margins to overlap cards for example
<pre>
.tableau {
position: relative;
width: 50em;
height: 30em;
outline: dashed 1px green;
transform: rotate(-90deg) scale(0.5);
padding: 1em;
display: flex;
justify-content: center;
flex-direction: row;
flex-wrap: wrap;
}

.tableau .card{
margin-right: -2em;
}

</pre>

In this example cards on tableu are smaller, rotated 90 degrees and overlaping.

https://codepen.io/VictoriaLa/pen/PojvWEV

[[File:Deck Layouts - codepen.io.png]]

== Selection and Click Handlers ==

To hookup selection or clicking, you have to manually hook up handler to all cards, which is easy

<pre>
document.querySelectorAll(".card").forEach(node=>node.addEventListener("click", (event) => {
var target = event.target;
target.classList.toggle('selected');
}
}));
</pre>

And you define class for selected in css
.selected {
outline: dashed blue 0.1em;
}

How if you need to do some action based on select this can be your do something button bandler (this will create array of ids of cards)
<pre>
const card_ids = Array.from(document.querySelectorAll('.card.selected')).map(x=>x.id);
</pre>

If you need single selection, just add a call to remove all previous 'selected' from all card, before adding it.

If you don't need selection you can hook ajax call directly to handler above.

== Animation ==

The animation is the only tricky part because it does not come for free. The proper animation function is pretty lengthy so I won't even put it here.
Basically it short you would have to reparent out object without visual movement and then you can run animation on positions, and after it is done remove absolute positioning.

The simplier method is moving object itself, you can see code and example in https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js
(slideToObjectRelative).

And more complex method moves "phantom" object on oversurface (which is neither parent of original object nor destination), code can found here (to use this your need 2 js methods for movement and classes for oversurface and oversurfacew > * from css):
https://codepen.io/VictoriaLa/pen/PojvWEV

Gamehelpladyandthetiger

2021-07-05T19:05:03Z

AmadanNaBriona: /* GUESSER */

Gamehelpladyandthetiger

2021-07-05T19:04:32Z

AmadanNaBriona: /* GUESSER */

— Tom Lang

== DOORS ==

''He was safe in his choice, for he knew''<br/>
''that the lady was in number two.''<br/>
''When he burst through her door,''<br/>
''he found out by the roar,''<br/>
''that tigers can be ladies too.''

--Tom Lang

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

# Guess Color '''or''' Role: 1 gem
# Guess Color '''and''' Role: 5 gems
# Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-07-05T19:03:37Z

AmadanNaBriona: /* DOORS */

— Tom Lang

== DOORS ==

''He was safe in his choice, for he knew''<br/>
''that the lady was in number two.''<br/>
''When he burst through her door,''<br/>
''he found out by the roar,''<br/>
''that tigers can be ladies too.''

--Tom Lang

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

Guess Color '''or''' Role: 1 gem
Guess Color '''and''' Role: 5 gems
Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-07-05T19:02:56Z

AmadanNaBriona: /* DOORS */

— Tom Lang

== DOORS ==

''He was safe in his choice, for he knew<br/>
that the lady was in number two.<br/>
When he burst through her door,<br/>
he found out by the roar,<br/>
that tigers can be ladies too.''

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

Guess Color '''or''' Role: 1 gem
Guess Color '''and''' Role: 5 gems
Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-07-05T19:01:52Z

AmadanNaBriona: /* DOORS */

— Tom Lang

== DOORS ==

''He was safe in his choice, for he knew

that the lady was in number two.

When he burst through her door,

he found out by the roar,

that tigers can be ladies too.''

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

Guess Color '''or''' Role: 1 gem
Guess Color '''and''' Role: 5 gems
Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-07-05T19:01:38Z

AmadanNaBriona:

— Tom Lang

== DOORS ==

''He was safe in his choice, for he knew
that the lady was in number two.
When he burst through her door,
he found out by the roar,
that tigers can be ladies too.''

=== Objective ===

To win, be the first player to earn 10 gems. Gems are earned by guessing your opponent’s identity, being guessed incorrectly, or scoring a set of cards which match your identity.

=== SETUP ===

One player is the Collector, the other player is the Guesser.

Each player is secretly dealt one of 4 identity cards: Red Lady, Blue Lady, Red Tiger, or Blue Tiger.

The Collector goes first.

=== COLLECTOR ===

Choose one card.

If you have a set of 4 cards matching your identity, reveal your Role and score 6 gems.

(''Example'': If you are the Red Lady, you will score 6 gems upon acquiring either 4 Red cards or 4 Ladies.)

=== GUESSER ===

Discard one card from the display.

You may then: (a) Guess your opponent's identity. (b) Match a set. (c) Pass.

'''Guessing'''

You may guess Color ''or'' Role ''or'' both,

Guess Color '''or''' Role: 1 gem
Guess Color '''and''' Role: 5 gems
Guess incorrectly: Collector scores 4 gems

'''Match a set'''

You may match a set from the '''Collector's''' cards. If the Collector has a set of four cards matching either your Color '''or''' your Role, you may reveal your identity and score 2 gems.

(''Example'': You are the Blue Tiger. If the Collector has collected either 4 blue cards or 4 Tigers, you may reveal your identity and score 2 gems.)

'''Pass'''

Play passes to the Collector.

If the Deck runs out, the Guesser scores 3 gems.

== Contest End ===

Each Contest (round) ends when either player scores gems. A new Contest begins, and each player is given a new identity.

== Game End ==

The first player to score 10 gems wins!

Gamehelpladyandthetiger

2021-07-05T18:52:45Z

AmadanNaBriona:

BGA Studio Cookbook

2021-05-22T17:05:12Z

AmadanNaBriona: /* Ajax Call wrapper */

This page is collection of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

__TOC__

== Visual Effects, Layout and Animation ==

=== Create pieces dynamically (using template) ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

=== Create pieces dynamically (using string concatenation) ===

'''Ingredients:''' ggg.js

Note: Not recommended

<pre>
div = "<div class='meeple "+color+"'></div>";
</pre>
=== Create all pieces statically ===

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

=== Use thematic fonts ===

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

=== Use player color in template ===

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?

You have to decide:
* If board does not fit you want scale whole thing down, the best way is probably use viewport (see https://en.doc.boardgamearena.com/Your_game_mobile_version)
* You can leave the board as is and make sure it is scrollable horizonatally
* You add custom scale just for the board (can add user controls - and hook to transform: scale())

I tried to auto-scale but this just does work, too many variables - browser zoom, 3d mode, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming...
Here is scaling functing for custom user scaling

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
onZoomPlus: function() {
this.my_zoom+=0.1;
this.zoommy('thething',this.my_zoom);
},

zoommy: function(node, zoom) {
node=$(node);
var width = 100 / zoom;
node.style.transformOrigin = "0 0";
node.style.transform = "scale(" + zoom + ")";
node.style.width = width + "%";
},
</pre>

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string function return becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Accessing images from js ===

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

This example actually writes "You" but you can replace this with player name as easily, drop translating function in this case

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou : function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

</pre>

=== Inject icon images in the log ===

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
self::DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
self::notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => self::getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => self::getLogsVPAmount($price),
'power_income' => self::getLogsPowerAmount($power_income),
'newScore' => self::getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

=== Inject images and styled html in the log ===

'''Ingredients:''' ggg.js, ggg.game.php

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;
break;
case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, you will loose your additional parameters, why? Because when game reloads it does not actually send same notifications, it sends special "hitstorical_log" notification where all parameters not listed in the message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 2 => 'zone_played' ]
);
</pre>

Now you can use zone_player in format_string_recursive even in historical logs. Note that for this to work, you currently need to define your own indexes for the 'preserve' array and avoid using 0 or 1.

=== High-Definition Graphics ===

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

=== Cool realistic shadow effect with CSS ===

==== Rectangles and circles ====

It is often nice to have a drop shadow around tiles and tokens, to separate them from the table visually. It is very easy to add a shadow to rectangular elements, just add this to your css:

<pre>
.xxx-tile {
box-shadow: 3px 3px 3px #000000a0;
}
</pre>

box-shadow obeys '''border-radius''' of the element, so it will look good for rounded rectangles, and hence also circles (if border-radius is set appropriately).

box-shadow also supports various other parameters and can be used to achieve effects such as glowing, borders, inner shadows etc. If you need to animate a box-shadow, you may be able to get better performance (avoiding redraws) if you attach the shadow to another element (possibly an ::after pseudo-element) and change only the '''opacity''' of that element.

==== Irregular Shapes ====

If you wish to make a shadow effect for game pieces that are not a rectangle, but your game pieces are drawn from rectangles in a PNG image, you can apply the shadow to the piece using any art package and save it inside the image. This usually will yield the best performance. Remember to account for the size of the shadow when you lay out images in the sprite sheet.

However that sometimes will not be an option, for example if the image needs to be rotated while the shadow remains offset in the same direction. In this case, one option is to not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

Beware that some browsers still do not always draw drop-shadow correctly. In particular, Safari frequently leaves bits of shadow behind when objects move around the screen. In Chrome, shadows sometimes flicker badly if another element is animating close by. Some of these correctness issues can be solved by adding '''isolation: isolate; will-change: filter;''' to affected elements, but this significantly affects redraw performance.

Beware of performance issues - particularly on Safari (MacOS, iPhone and iPad). Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>

==== Shadows with clip-path ====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Code Organization ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
// load my own module!!!
g_gamethemeurl + "modules/ggg_other.js" ], function(dojo,
declare) {

=== Including your own JavaScript module (II) ===

* Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php7 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

=== More readable JS: onEnteringState ===

If you have a lot of states onEnteringState and friends become rather wild, you can do this trick to call some method dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors ===

* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does that and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
self::setAjaxMode();
$this->game->actionCancel();
self::ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectatoe
switch (stateName) {
case 'playerTurnMuliPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/actionCancel.html", {}, this); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states.
Also when you do that sometimes you want to change the state prompt, see below 'Change state prompt'

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : "${you} must select location",
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).
=== Changing state prompt ===

State prompt is message displayed for player which usually comes from state description.
Sometimes you want to change it without changing state (one way is chaneg state but locally, see client states above).

Simple way just change the html
<pre>
setMainTitle: function(text) {
var main = $('pagemaintitletext');
main.innerHTML = text;
},
// usage
onMeeple: function(event) {
//...
this.setMainTitle(_('You must select where meeple is going'));
},
</pre>

This however will not work with parameters and will not draw You in color, if you want this its more sophisticated:

<pre>
setDescriptionOnMyTurn : function(text) {
this.gamedatas.gamestate.descriptionmyturn = text;
var tpl = dojo.clone(this.gamedatas.gamestate.args);
if (tpl === null) {
tpl = {};
}
var title = "";
if (this.isCurrentPlayerActive() && text !== null) {
tpl.you = this.divYou();
}
title = this.format_string_recursive(text, tpl);

if (!title) {
this.setMainTitle(" ");
} else {
this.setMainTitle(title);
}
},
</pre>

Note: this method uses setMainTitle defined above and divYou defined in another section of this wiki.

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch (self::getGameStateValue('playerTeams')) {
case self::TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case self::TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case self::TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case self::TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
self::DbQuery($sql);
self::reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
self::reloadPlayersBasicInfos();
</pre>

=== Send different notifications to active player vs everybody else ===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file (if you already overriding it merge obviously)
<pre>
/** @Override */
format_string_recursive: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id)
log = args.log_others;
return this.inherited(arguments); // you must call this to call super
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notifyAllPlayers('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

=== Send transient notifications without incrementing move ID ===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

; In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notifyAllPlayers('cardsPreview', '', $args);
</pre>

=== Ajax Call wrapper ===
'''Ingredients:''' ggg.js

Note current ajaxcall is super vebosy and prone to errors, I suggest using a helper function. It does a lot of stuff you must do anyways.
Most beginner mistakes come from missing part of this code (which is understandstandable - this is a huge snippet to clone every time).

<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = []; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server
if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, its is optional param - you rarely need it
}
},
</pre>

Usage:
<pre>
this.ajaxcallwrapper('pass'); // no args
this.ajaxcallwrapper('playCard', {card: card_id}); // with args
</pre>

Game interface logic: Game.js

2021-03-06T15:48:49Z

AmadanNaBriona: /* Players input */

{{Studio_Framework_Navigation}}

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 a change from the server and how it will show in the browser.

== File structure ==

The details of how the file is structured are described below with comments on the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

;onEnteringState(stateName, args)
This method is called each time we are entering into a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling arg* method use args.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.

'''Warning''': for multipleactiveplayer states:
the active players are NOT actives yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.
If you are doing initialization of some structure which do not depend on active player, you can just replace
if (this.isCurrentPlayerActive()) {
into
if (!this.isSpectator) {
for the main switch in that method.

;onLeavingState(stateName)
This method is called each time we are leaving a game state.
You can use this method to perform some user interface changes at this moment.

;onUpdateActionButtons(stateName, args)
In this method you can manage "action buttons" that are displayed in the action status bar.
To access state arguments passed via calling arg* method use args parameter. Note: args can be null! For game states and when you don't supply state args function it is null.
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of call would depends on either you get into that from transition from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]

== 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 a variable, not a function.
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains the initial set of data to init the game, created at game start or by 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 this is unnecessary).

; 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 the active player, or null if we are not in an "activeplayer" type state.

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

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; typeof g_replayFrom != 'undefined'
: Returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

---

You may consider making a function like this, to detect if the game is in a read-only state:

// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

== Dojo framework ==

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

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (before July 2020) ==

For performance reasons, when deploying a game the js code is minimized 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 declarations. The following syntax is invalid for ShrinkSafe: '''function myFunc(requiredArg, optionalArg = 'defaultValue') {}'''
* You should not use '''let''' or '''const''' to declare variables.

'''Tip:''' a developer encountering some problems with this has successfully used [http://plugins.netbeans.org/plugin/58580/jshint JSHint] on NetBeans to evaluate code to make it compatible for ECMAScript 3. With the plugin installed, set the below options in '''.jshintrc''' file, and then open '''Action Items''' window (in NetBeans):<pre>{ "maxerr": 999, "esversion": 3 }</pre>

'''Tip:''' some online tools also allow to convert between different versions of javascript, such as https://www.typescriptlang.org/play or https://babeljs.io/ or https://extendsclass.com/javascript-fiddle.html

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing and manipulating the DOM ==

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

The $() function is used to get an 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 the BGA Framework. You should not use the '''getElementById''' function.

'''dojo.style'''

With dojo.style you can modify the CSS property of any HTML element in 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 sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

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

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

'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications 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 without error.
* You can test whether you applied the CSS to an element with the '''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 changes in one line of code.

// ... and when we need to check if a square is a possible move on the 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.attr'''

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''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 (i.e., elements of class "token") on the board (i.e., the 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 HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if 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 values:

"replace" : (see description above).

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

"last" (default) : 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.

"after" : 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 : [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

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]]".

'''dojo.empty'''

Remove all children of the node element

'''dojo.destroy'''

Remove the element

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''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.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

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

'''Animation Callbacks'''

If you wish to run some code only after an animation has completed you can do this by linking a callback method.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));
animation_id.play();

…

callback_function: function(params) {
// this will be called after the animation ends
},
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

=== 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 methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>
Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.

'''this.connect'''
function(element, event, handler)

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

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.

'''this.connectClass'''
function( cssClassName, event, handler )

Same as connect(), but for all the nodes set with the specified cssClassName.
<pre>
this.connectClass('pet', 'onclick', 'onPet');
</pre>
'''this.disconnect'''
function( element, event )

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

'''this.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 (i.e: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not authorized (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.checkPossibleActions'''
function( action, nomessage )

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario.

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)

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

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions.

* 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 parameters in order the interface can be locked during the server call.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
// NB : usually not needed as changes must be handled by notifications
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)
// You should NOT make another ajaxcall in a callback in order not to create race conditions
} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = [];
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args,//
this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''this.isInterfaceLocked()'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.

'''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 Hearts 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>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</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', [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

== 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 should 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 browsers (see [[BGA_Studio_Guidelines|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 ===

As a general rule, 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 over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// 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.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.destroy();
} );

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback( function() { ... } );

=== 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" => clienttranslate("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, duration, offset_x, offset_y );
</pre>

'''anchor_id''': ID of the element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+'

'''duration''': animation duration in milliseconds

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.

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

text - what to put in bubble, can be html actually not just text

delay - in milliseconds is optional (default 0)

duration - in milliseconds is optional (default 3000)

custom_class - extra class to add to bubble is optional, if you need to override the default bubble style

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Update players score ==

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).

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>

Set a player score to a specific value with animation :

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

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_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 ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

; 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'.

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

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

== BGA Buttons ==

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<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 out ''Coloretto''.

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>');
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

Game interface logic: Game.js

2021-03-06T15:47:23Z

AmadanNaBriona: /* Players input */

{{Studio_Framework_Navigation}}

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 a change from the server and how it will show in the browser.

== File structure ==

The details of how the file is structured are described below with comments on the code skeleton provided to you.

Here is the basic structure:

* '''constructor''': here you can define global variables for your whole interface.
* '''setup''': this method is called when the page is refreshed, and sets up the game interface.
* '''onEnteringState''': this method is called when entering a new game state. You can use it to customize the view for each game state.
* '''onLeavingState''': this method is called when leaving a game state.
* '''onUpdateActionButtons''': called when entering a new state, in order to add action buttons to the status bar.
* ''(utility methods)'': this is where you can define your utility methods.
* ''(player's actions)'': this is where you can write your handlers for player actions on the interface (example: click on an item).
* '''setupNotifications''': this method associates notifications with notification handlers. For each game notification, you can trigger a javascript method to handle it and update the game interface.
* ''(notification handlers)'': this is where you define the notifications handlers associated with notifications in '''setupNotifications''', above.

More details:

;onEnteringState(stateName, args)
This method is called each time we are entering into a new game state.
You can use this method to perform some user interface changes at this moment.
To access state arguments passed via calling arg* method use args.args.
Typically you would do something only for active player, using this.isCurrentPlayerActive() check.

'''Warning''': for multipleactiveplayer states:
the active players are NOT actives yet so you must use onUpdateActionButtons to perform the client side operation which depends on a player active/unactive status.
If you are doing initialization of some structure which do not depend on active player, you can just replace
if (this.isCurrentPlayerActive()) {
into
if (!this.isSpectator) {
for the main switch in that method.

;onLeavingState(stateName)
This method is called each time we are leaving a game state.
You can use this method to perform some user interface changes at this moment.

;onUpdateActionButtons(stateName, args)
In this method you can manage "action buttons" that are displayed in the action status bar.
To access state arguments passed via calling arg* method use args parameter. Note: args can be null! For game states and when you don't supply state args function it is null.
This method is called when active or multiactive player changes. In classic "activePlayer" state this method is called before the onEnteringState state.
In multipleactiveplayer state it is a mess. The sequencing of call would depends on either you get into that from transition from reloading the whole game (i.e. F5).

See more details in [[Your_game_state_machine:_states.inc.php#Diffrence_between_Single_active_and_Multi_active_states]]

== 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 a variable, not a function.
: Note: If you want to hide an element from spectators, you should use [[Game_interface_stylesheet:_yourgamename.css#spectatorMode|CSS 'spectatorMode' class]].

; this.gamedatas
: Contains the initial set of data to init the game, created at game start or by 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 this is unnecessary).

; 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 the active player, or null if we are not in an "activeplayer" type state.

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

; this.bRealtime
: Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

; typeof g_replayFrom != 'undefined'
: Returns true if the game is in replay mode <i>during the game</i> (the game is ongoing but the user clicked "reply from this move" in the log)

; g_archive_mode
: Returns true if the game is in archive mode <i>after the game</i> (the game has ended)

; this.instantaneousMode
: Returns true during replay/archive mode if animations should be skipped. Only needed if you are doing custom animations. (The BGA-provided animation functions like <i>this.slideToObject()</i> automatically handle instantaneous mode.)
: Technically, when you click "replay from move #20", the system replays the game from the very beginning with moves 0 - 19 happening in instantaneous mode and moves 20+ happening in normal mode.

---

You may consider making a function like this, to detect if the game is in a read-only state:

// Returns true for spectators, instant replay (during game), archive mode (after game end)
isReadOnly: function () {
return this.isSpectator || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

== Dojo framework ==

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

The Dojo framework allows us to do complex things more easily. The BGA framework uses Dojo extensively.

To implement a game, you only need to use a few parts of the Dojo framework. All the Dojo methods you need are described on this page.

== Javascript minimization (before July 2020) ==

For performance reasons, when deploying a game the js code is minimized 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 declarations. The following syntax is invalid for ShrinkSafe: '''function myFunc(requiredArg, optionalArg = 'defaultValue') {}'''
* You should not use '''let''' or '''const''' to declare variables.

'''Tip:''' a developer encountering some problems with this has successfully used [http://plugins.netbeans.org/plugin/58580/jshint JSHint] on NetBeans to evaluate code to make it compatible for ECMAScript 3. With the plugin installed, set the below options in '''.jshintrc''' file, and then open '''Action Items''' window (in NetBeans):<pre>{ "maxerr": 999, "esversion": 3 }</pre>

'''Tip:''' some online tools also allow to convert between different versions of javascript, such as https://www.typescriptlang.org/play or https://babeljs.io/ or https://extendsclass.com/javascript-fiddle.html

== Javascript minimization (after July 2020) ==

For performance reasons, when deploying a game the javascript code is minimized using '''terser''' (https://github.com/terser/terser). This minifier works with modern javascript syntax. From your project "Manage game" page, you can now test a minified version of your javascript on the studio (and revert to the original).

NB: it has been reported that there is an issue with this minifier and percentage values for opacity.

== Accessing and manipulating the DOM ==

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

The $() function is used to get an 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 the BGA Framework. You should not use the '''getElementById''' function.

'''dojo.style'''

With dojo.style you can modify the CSS property of any HTML element in 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 sprites to transform an element to another)
dojo.style( 'my_element', 'backgroundPosition', '-20px -50px' );
</pre>

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

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

'''dojo.addClass''', '''dojo.removeClass''', '''dojo.hasClass''', '''dojo.toggleClass'''

In many situations, many small CSS property updates can be replaced by a CSS class change (i.e., you add a CSS class to your element instead of applying all modifications 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 without error.
* You can test whether you applied the CSS to an element with the '''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 changes in one line of code.

// ... and when we need to check if a square is a possible move on the 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.attr'''

With dojo.attr you can access or change the value of an attribute or property of any HTML element in your interface.

Exemple:
<pre>
// Get the title of a node
var title = dojo.attr( id, 'title' );
// Change the height of a node
dojo.attr( 'img_growing_tree', 'height', 100 );
</pre>

'''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 (i.e., elements of class "token") on the board (i.e., the 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 HTML code somewhere in your game interface without breaking something. It is much better to use than the '''innerHTML=''' method if 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 values:

"replace" : (see description above).

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

"last" (default) : 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.

"after" : 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 : [https://dojotoolkit.org/reference-guide/1.7/dojo/place.html]

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]]".

'''dojo.empty'''

Remove all children of the node element

'''dojo.destroy'''

Remove the element

dojo.query(".green", mynode).forEach(dojo.destroy); // this remove all subnode of class green from mynode

'''dojo.create'''

Create element

dojo.create("div", { class: "yellow_arrow" }, parent); // this creates div with class yellow_array and places it in "parent"

'''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.

Note 2: the slideTo methods are not compatible with CSS transform (scale, zoom, rotate...). If possible, avoid using CSS transform on nodes that are being slided. Eventually, the only possible solution to make these 2 compatible is to disable all CSS transform properties, use slideToObjectPos/placeOnObjectPos, and then apply them again.

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

'''Animation Callbacks'''

If you wish to run some code only after an animation has completed you can do this by linking a callback method.

<pre>
var animation_id = this.slideToObject( mobile_obj, target_obj, duration, delay );
dojo.connect(animation_id, 'onEnd', dojo.hitch(this, 'callback_function', parameters));
animation_id.play();

…

callback_function: function(params) {
// this will be called after the animation ends
},
</pre>

If you wish to call a second animation after the first (rather than general code) then you can use a dojo animation chain (see tutorial referenced above).

=== 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 methods.

Example: associate a click on an element ("my_element") with one of our methods ("onClickOnMyElement"):
<pre>
dojo.connect( $('my_element'), 'onclick', this, 'onClickOnMyElement' );
</pre>
Same idea but base on query (i.e. all element of 'pet' class)
dojo.query(".pet").connect('onclick', this, 'onPet');

Note: the methods described here are the only correct ways to associate a player input event to your code, and you should not use anything else.

'''this.connect'''
function(element, event, handler)

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

this.connect( $('my_element'), 'onclick', 'onClickOnMyElement' );

Or you can use an in-place handler

this.connect( $('my_element'), 'onclick', (e) => { console.log('boo'); } );

Note that this function stores the connection handler. That is the only real difference between '''this.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.disconnect() to prevent memory leaks.

'''this.connectClass'''
function( cssClassName, event, handler )

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

this.connectClass('pet', 'onclick', 'onPet');

'''this.disconnect'''
function( element, event )

Disconnect event handler (previously registered with this.connect or this.connectClass).

this.disconnect( $('my_element'), 'onclick');

Note: dynamic connect/disconnect is for advanced cases ONLY, you should always connect elements statically if possible, i.e. in setup() method.

'''this.disconnectAll'''

Disconnect all previously registed event handlers (registered via this.connect or this.connectClass)

'''this.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 (i.e: the action is listed as a "possibleaction" in current game state).

return false and display an error message if not authorized (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.checkPossibleActions'''
function( action, nomessage )

* this is independent of the player being active, so can be used instead of this.checkAction(). This is particularly useful for multiplayer states when the player is not active in a 'player may like to change their mind' scenario.

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)

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

This method must be used to send a player input to the game server. '''It should not be triggered programmatically''', especially not in loops, in callbacks, in notifications, or in onEnteringState/onUpdateActionButtons/onLeavingState, in order not to create race conditions.

* 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 parameters in order the interface can be locked during the server call.
** Note: Restricted parameter names (please don't use them):
*** "action"
*** "module"
*** "class"
* obj_callback: must be set to "this".
* callback: a function to trigger when the server returns and everything went fine (not used, as all data handling is done via notifications).
* callback_error: (optional and rarely used) a function to trigger when the server returns an error. if no error this function is called with parameter value false.

Usage:
<pre>
this.ajaxcall( '/mygame/mygame/myaction.html', { lock: true,
arg1: myarg1,
arg2: myarg2,
...
}, this, function( result ) {
// Do some stuff after a successful call
// NB : usually not needed as changes must be handled by notifications
// You should NOT modify the interface in a callback or it will most likely break the framework replays (or make it inaccurate)
// You should NOT make another ajaxcall in a callback in order not to create race conditions
} );
</pre>

Note: to reduce the boilerplate code you can define your own wrapper, which will do checking, locking and allow to skip parameters, for example
<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) {
args = [];
}
args.lock = true;

if (this.checkAction(action)) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args,//
this, (result) => { }, handler);
}
},
</pre>
This can be called like this which is a lot more compact
<pre>
this.ajaxcallwrapper('playDraw');
this.ajaxcallwrapper('playMove', {card: id})
</pre>

'''this.isInterfaceLocked()'''

When using "lock: true" in ajax call you can use this function to check if interface is in lock state (it will be locked during server call and notification processing).
This check can be used to block some other interactions which do not result in ajaxcall or if you want to suppress errors.

'''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 Hearts 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>

-----

It is also possible to control the delay timing dynamically (e.g., using notification args). As an example, maybe your notification 'cardPlayed' should pause for a different amount of time depending on the number or type of cards played.

For this case, use '''setSynchronous''' without specifying the duration and use '''setSynchronousDuration''' within the notification callback.

* NOTE: If you forget to invoke '''setSynchronousDuration''', the game will remain paused forever!

<pre>
setupNotifications: function () {
dojo.subscribe( 'cardPlayed', this, 'notif_cardPlayed' );
this.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

notif_cardPlayed: function (notif) {
// MUST call setSynchronousDuration

// Example 1: From notification args (PHP)
this.notifqueue.setSynchronousDuration(notif.args.duration);
...

// Or, example 2: Match the duration to a Dojo animation
var anim = dojo.fx.combine([
...
]);
anim.play();
this.notifqueue.setSynchronousDuration(anim.duration);
},
</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', [] );

'''simplePause''' - This notification will just delay other notifications, maybe useful if you know you need some extra time for animation or something. Requires a time parameter.

<pre>
self::notifyAllPlayers( 'simplePause', '', [ 'time' => 500] ); // time is in milliseconds
</pre>

== 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 should 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 browsers (see [[BGA_Studio_Guidelines|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 ===

As a general rule, 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 over the play zone. You should store the handler in a member variable to access it later
this.myDlg = new ebg.popindialog();
this.myDlg.create( 'myDialogUniqueId' );
this.myDlg.setTitle( _("my dialog title to translate") );
this.myDlg.setMaxWidth( 500 ); // Optional

// 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.setContent( html ); // Must be set before calling show() so that the size of the content is defined before positioning the dialog
this.myDlg.show();

// Now that the dialog has been displayed, you can connect your method to some dialog elements
// Example, if you have an "OK" button in the HTML of your dialog:
dojo.connect( $('my_ok_button'), 'onclick', this, function(evt){
evt.preventDefault();
this.myDlg.destroy();
} );

If necessary, you can remove the default top right corner 'close' icon, or replace the function called when it is clicked:
// Removes the default close icon
this.myDlg.hideCloseIcon();

// Replace the function call when it's clicked
this.myDlg.replaceCloseCallback( function() { ... } );

=== 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" => clienttranslate("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, duration, offset_x, offset_y );
</pre>

'''anchor_id''': ID of the element to place the animated score onto (without the '#')

'''color''': hexadecimal RGB representation of the color (should be the color of the scoring player), but without a leading '#'. For instance, 'ff0000' for red.

'''score''': numeric score to display, prefixed by a '+'

'''duration''': animation duration in milliseconds

'''offset_x''' and '''offset_y''': if both offset_x and offset_y are defined and not null, apply the following offset (in pixels) to the scoring animation

Note: if you want to display successively each score, you can use ''this.notifqueue.setSynchronous()'' function.

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

text - what to put in bubble, can be html actually not just text

delay - in milliseconds is optional (default 0)

duration - in milliseconds is optional (default 3000)

custom_class - extra class to add to bubble is optional, if you need to override the default bubble style

'''Warning''': if your bubble could overlap other active elements of the interface (buttons in particular), as it stays in place even after disappearing, you should use a custom class to give it the style "pointer-events: none;" in order to intercept click events.

Note: If you want this visually, but want to take complete control over this bubble and its animation (for example to make it permanent) you can just use div with 'discussion_bubble' class on it, and content of div is what will be shown.

== Update players score ==

The column player_score from the player table is automatically loaded into this.scoreCtrl and therefore into the stars location on the player board. This occurs sometime after the <gamename>.js setup() function. However this score must be updated as the game progresses through player notifications (notifs).

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>

Set a player score to a specific value with animation :

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

Typical usage would be (that will process 'score' notification):
<pre>
setupNotifications : function() {
...
dojo.subscribe('score', this, "notif_score");
},
notif_score: function(notif) {
this.scoreCtrl[notif.args.player_id].setValue(notif.args.player_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 ensure that the "this" object will be set when the callback is called.

NOTE: In modern JS there are lambdas that eliminate need for that, the example above will look like this
<pre>
this.confirmationDialog( _('Are you sure you want to make this?'), () => {
this.ajaxcall( '/mygame/mygame/makeThis.html', { lock:true }, this, (result) => {} );
} );
</pre>

; 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'.

;'''onScreenWidthChange()'''
:This function can be overridden in your game to manage some resizing on the client side when the browser window is resized. This function is also triggered at load time, so it can be used to adapt to the :viewport size at the start of the game too.

;'''updatePageTitle()'''
:This function allows to update the current page title and turn description according to the game state. If the current game state description this.gamedatas.gamestate.descriptionmyturn is modified before :calling the function, it allows to update the turn description without changing state.

Example from Terra Mystica:
<pre>
onClickFavorTile: function( evt ) {
...
if ( ... ) {
this.gamedatas.gamestate.descriptionmyturn = _('Special action: ') + _('Advance 1 space on a Cult track');
this.updatePageTitle();
this.removeActionButtons();
this.addActionButton( ... );
...
return;
}
...

}
</pre>

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

== BGA Buttons ==

You can create a custom button, but the BGA framework provides a standard button that requires only .css classes: '''bgabutton''' and '''bgabutton_${color}'''.

'''Examples:'''

<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 out ''Coloretto''.

== Sounds ==

Add a custom sound and make it load with your interface:

Add this in your template (.tpl) file:
<pre>
<audio id="audiosrc_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.mp3" preload="none" autobuffer></audio>
<audio id="audiosrc_o_<gamename>_<yoursoundname>" src="{GAMETHEMEURL}img/<gamename>_<yoursoundname>.ogg" preload="none" autobuffer></audio>
</pre>

Note: this is a requirement to provide both a mp3 and a ogg file.

Play the sound (from your .js file):

<pre>
playSound('<gamename>_<yoursoundname>');
</pre>

Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

<pre>
this.disableNextMoveSound();
</pre>

Note: it only disable the sound for the next move.

Main game logic: Game.php

2021-03-06T15:23:27Z

AmadanNaBriona: /* Only "winners" and "losers" */

{{Studio_Framework_Navigation}}

This is the main file for your game logic. Here you initialize the game, persist data, implement the rules and notify the client interface of changes.

== File Structure ==

The details of how the file is structured are described directly with comments in the code skeleton provided to you.

Here is the basic structure:

* Constructor: where you define global variables.
* setupNewGame: initial setup of the game. Takes an array of players, indexed by player_id. Structure of each player includes player_name, player_canal, player_avatar, and flags indicating admin/ai/premium/order/language/beginner.
* getAllDatas: where you retrieve all game data during a complete reload of the game. Returned value must include ['players'][playerId]['score'] for scores to populate when F5 is pressed.
* getGameProgression: where you compute the game progression indicator.
* Utility functions: your utility functions.
* Player actions: the entry points for players actions.
* Game state arguments: methods to return additional data on specific game states ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#args more info here]).
* Game state actions: the logic to run when entering a new game state ([http://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php#action more info here]).
* zombieTurn: what to do it's the turn of a zombie player.
* upgradeTableDb: function to migrate database if you change it after release on production.

== Accessing player information ==

'''Important''': In the following methods, be mindful of the difference between the "active" player and the "current" player. The '''active''' player is the player whose turn it is - not necessarily the player who sent a request! The '''current''' player is the player who sent the request and will see the results returned by your methods: not necessarily the player whose turn it is!

; getPlayersNumber()
: Returns the number of players playing at the table
: Note: doesn't work in setupNewGame (use count($players) instead).

; getActivePlayerId()
: Get the "active_player", whatever what is the current state type.
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multiplayer"
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; getActivePlayerName()
: Get the "active_player" name
: Note: avoid using this method in a "multiplayer" state because it does not mean anything.

; loadPlayersBasicInfos()
: Get an associative array with generic data about players (ie: not game specific data).
: The key of the associative array is the player id. The returned table is cached, so ok to call multiple times without performance concerns.
: The content of each value is:
: * player_name - the name of the player
: * player_color (ex: ff0000) - the color code of the player
: * player_no - the position of the player at the start of the game in natural table order, i.e. 1,2,3

; getCurrentPlayerId()
: Get the "current_player". The current player is the one from which the action originated (the one who sent the request).
: '''Be careful''': This is not necessarily the active player!
: In general, you shouldn't use this method, unless you are in "multiplayer" state.
: '''Very important''': in your setupNewGame and zombieTurn function, you must never use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message (these actions are triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to these actions).

; getCurrentPlayerName()
: Get the "current_player" name
: Be careful using this method (see above).

; getCurrentPlayerColor()
: Get the "current_player" color
: Be careful using this method (see above).

; isCurrentPlayerZombie()
: Check the "current_player" zombie status. If true, player is zombie, i.e. left or was kicked out of the game.

; getActivePlayerColor()
: This function does not seems to exist in API, if you need it here is implementation
function getActivePlayerColor() {
$player_id = self::getActivePlayerId();
$players = self::loadPlayersBasicInfos();
if( isset( $players[ $player_id ]) )
return $players[ $player_id ]['player_color'];
else
return null;
}

== Accessing the database ==

The main game logic should be the only point from which you should access the game database. You access your database using SQL queries with the methods below.

'''IMPORTANT'''

BGA uses [http://dev.mysql.com/doc/refman/5.0/en/sql-syntax-transactions.html database transactions]. This means that your database changes WON'T BE APPLIED to the database until your request ends normally (web request, not database request). Using transactions is in fact very useful for you; at any time, if your game logic detects that something is wrong (example: a disallowed move), you just have to throw an exception and all changes to the game situation will be removed. This also means that you need not (and in fact cannot) use your own transactions for multiple related database operations.

; DbQuery( $sql )
: This is the generic method to access the database.
: It can execute any type of SELECT/UPDATE/DELETE/REPLACE/INSERT query on the database.
: You should use it for UPDATE/DELETE/REPLACE/INSERT queries. For SELECT queries, the specialized methods below are much better.

; getUniqueValueFromDB( $sql )
: Returns a unique value from DB or null if no value is found.
: $sql must be a SELECT query.
: Raise an exception if more than 1 row is returned.

; getCollectionFromDB( $sql, $bSingleValue=false )
: Returns an associative array of rows for a sql SELECT query.
: The key of the resulting associative array is the first field specified in the SELECT query.
: The value of the resulting associative array is an associative array with all the field specified in the SELECT query and associated values.
: First column must be a primary or alternate key.
: The resulting collection can be empty.
: If you specified $bSingleValue=true and if your SQL query request 2 fields A and B, the method returns an associative array "A=>B"

Example 1:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
1234 => array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
1235 => array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)
</pre>
Example 2:
<pre>
self::getCollectionFromDB( "SELECT player_id id, player_name name FROM player", true );

Result:
array(
1234 => 'myuser0',
1235 => 'myuser1'
)

</pre>

; getNonEmptyCollectionFromDB( $sql )
: Same as getCollectionFromDB($sdl), but raise an exception if the collection is empty. Note: this function does NOT have 2nd argument as previous one does.

; getObjectFromDB( $sql )
: Returns one row for the sql SELECT query as an associative array or null if there is no result
: Raise an exception if the query return more than one row

Example:
<pre>
self::getObjectFromDB( "SELECT player_id id, player_name name, player_score score FROM player WHERE player_id='$player_id'" );

Result:
array(
'id'=>1234, 'name'=>'myuser0', 'score'=>1
)
</pre>

; getNonEmptyObjectFromDB( $sql )
: Similar to previous one, but raise an exception if no row is found

; getObjectListFromDB( $sql, $bUniqueValue=false )
: Return an array of rows for a sql SELECT query.
: The result is the same than "getCollectionFromDB" except that the result is a simple array (and not an associative array).
: The result can be empty.
: If you specified $bUniqueValue=true and if your SQL query request 1 field, the method returns directly an array of values.

Example 1:
<pre>
self::getObjectListFromDB( "SELECT player_id id, player_name name, player_score score FROM player" );

Result:
array(
array( 'id'=>1234, 'name'=>'myuser0', 'score'=>1 ),
array( 'id'=>1235, 'name'=>'myuser1', 'score'=>0 )
)
</pre>
Example 2:
<pre>
self::getObjectListFromDB( "SELECT player_name name FROM player", true );

Result:
array(
'myuser0',
'myuser1'
)

</pre>

; getDoubleKeyCollectionFromDB( $sql, $bSingleValue=false )
: Return an associative array of associative array, from a SQL SELECT query.
: First array level correspond to first column specified in SQL query.
: Second array level correspond to second column specified in SQL query.
: If bSingleValue = true, keep only third column on result

; DbGetLastId()
: Return the PRIMARY key of the last inserted row (see PHP mysql_insert_id function).

; DbAffectedRow()
: Return the number of row affected by the last operation

; escapeStringForDB( $string )
: You must use this function on every string type data in your database that contains unsafe data.
: (unsafe = can be modified by a player).
: This method makes sure that no SQL injection will be done through the string used.
: Note: if you using standard types in ajax actions, like AT_alphanum it is sanitized before arrival,
: this is only needed if you manage to get unchecked string, like in the games where user has to enter text as a response.

<pre>

</pre>

Note: see Editing [[Game database model: dbmodel.sql]] to know how to define your database model.

== Use globals ==

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

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

'''initGameStateLabels'''

This method should be located at the beginning of ''yourgamename.php.'' This is where you define the globals used in your game logic, by assigning them IDs.

You can define up to 80 globals, with IDs from 10 to 89 (inclusive). You must '''not''' use globals outside this range, as those values are used by other components of the framework.

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

'''setGameStateInitialValue( $value_label, $value_value )'''

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

'''getGameStateValue( $value_label )'''

Retrieve the current value of a global.

'''setGameStateValue( $value_label, $value_value )'''

Set the current value of a global.

'''incGameStateValue( $value_label, $increment )'''

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

Return the final value of the global.

== Game states and active players ==

=== Activate player handling ===

; $this->activeNextPlayer()
: Make the next player active in the natural player order.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->activePrevPlayer()
: Make the previous player active (in the natural player order).
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->gamestate->changeActivePlayer( $player_id )
: You can call this method to make any player active.
: Note: you CANNOT use this method in a "activeplayer" or "multipleactiveplayer" state. You must use a "game" type game state for this.

; $this->getActivePlayerId()
: Return the "active_player" id
: Note: it does NOT mean that this player is active right now, because state type could be "game" or "multipleactiveplayer"
: Note: avoid using this method in a "multipleactiveplayer" state because it does not mean anything.

=== Multiple activate player handling ===

; $this->gamestate->setAllPlayersMultiactive()
: All playing players are made active. Update notification is sent to all players (this will trigger '''onUpdateActionButtons''').
: Usually, you use this method at the beginning of a game state (e.g., "stGameState") which transitions to a ''multipleactiveplayer'' state in which multiple players have to perform some action. Do not use this method if you going to make some more changes in the active player list. (I.e., if you want to take away multipleactiveplayer status immediately afterwards, use setPlayersMultiactive instead.)

Example of usage:
<pre>
function st_MultiPlayerInit() {
$this->gamestate->setAllPlayersMultiactive();
}
</pre>

And this is the state declaration:
<pre>
2 => array(
"name" => "playerTurnPlace",
"description" => clienttranslate('Other player must place ships'),
"descriptionmyturn" => clienttranslate('${you} must place ships (click on YOUR SHIPS board to place)'),
"type" => "multipleactiveplayer",
'action' => 'multiPlayerDoSomething',
'args' => 'arg_playerTurnPlace',
"possibleactions" => array( "actionBla" ),
"transitions" => array( "next" => 4, "last" => 99)
),
</pre>

; $this->gamestate->setAllPlayersNonMultiactive( $next_state )
: All playing players are made inactive. Transition to next state

; $this->gamestate->setPlayersMultiactive( $players, $next_state, $bExclusive = false )
: Make a specific list of players active during a multiactive gamestate. Update notification is sent to all players whose state changed.
: "players" is the array of player id that should be made active.
: If "exclusive" parameter is not set or false it doesn't deactivate other previously active players. If its set to true, the players who will be multiactive at the end are only these in "$players" array

: In case "players" is empty, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise

; $this->gamestate->setPlayerNonMultiactive( $player_id, $next_state )
: During a multiactive game state, make the specified player inactive.
: Usually, you call this method during a multiactive game state after a player did his action. It is also possible to call it directly from multiplayer action handler.
: If this player was the last active player, the method trigger the "next_state" transition to go to the next game state.
: returns true if state transition happened, false otherwise
Example of usage (see state declaration of playerTurnPlace above):
<pre>
function actionBla($args) {
self::checkAction('actionBla');
// handle the action using $this->getCurrentPlayerId()
$this->gamestate->setPlayerNonMultiactive( $this->getCurrentPlayerId(), 'next');
}
</pre>

; $this->gamestate->getActivePlayerList()
: With this method you can retrieve the list of the active player at any time.
: During a "game" type gamestate, it will return a void array.
: During a "activeplayer" type gamestate, it will return an array with one value (the active player id).
: During a "multipleactiveplayer" type gamestate, it will return an array of the active players id.
: Note: you should only use this method in the latter case.

; $this->gamestate->updateMultiactiveOrNextState( $next_state_if_none )
: Sends update notification about multiplayer changes. All multiactive set* functions above do that, however if you want to change state manually using db queries for complex calculations, you have to call this yourself after. Do not call this if you calling one of the other setters above.
Example: you have player teams and you want to activate all players in one team
<pre>
$sql = "UPDATE player SET player_is_multiactive='0'";
self::DbQuery( $sql );
$sql = "UPDATE player SET player_is_multiactive='1' WHERE player_id='$player_id' AND player_team='$team_no'";
self::DbQuery( $sql );

$this->gamestate->updateMultiactiveOrNextState( 'error' );
</pre>

; updating database manually
: Use this helper function to change multiactive state without sending notification
<pre>
/**
* Changes values of multiactivity in db, does not sent notifications.
* To send notifications after use updateMultiactiveOrNextState
* @param number $player_id, player id <=0 or null - means ALL
* @param number $value - 1 multiactive, 0 non multiactive
*/
function dbSetPlayerMultiactive($player_id = -1, $value = 1) {
if (! $value)
$value = 0;
else
$value = 1;
$sql = "UPDATE player SET player_is_multiactive = '$value' WHERE player_zombie = 0 and player_eliminated = 0";
if ($player_id > 0) {
$sql .= " AND player_id = $player_id";
}
self::DbQuery($sql);
}
</pre>

=== States functions ===
; $this->gamestate->nextState( $transition )
: Change current state to a new state. Important: the $transition parameter is the name of the transition, and NOT the name of the target game state, see [[Your game state machine: states.inc.php]] for more information about states.

; $this->checkAction( $actionName, $bThrowException=true )
: Check if the current player can perform a specific action in the current game state, and optionally throw an exception if they can't.
: The action is valid if it is listed in the "possibleactions" array for the current game state (see game state description).
: This method MUST be the first one called in ALL your PHP methods that handle player actions, in order to make sure a player doesn't perform an action not allowed by the rules at the point in the game. It should not be called from methods where the current player is not necessarily the active player, otherwise it may fail with an "It is not your turn" exception.
: If "bThrowException" is set to "false", the function returns '''false''' in case of failure instead of throwing an exception. This is useful when several actions are possible, in order to test each of them without throwing exceptions.

; $this->gamestate->checkPossibleAction( $action )
: (rarely used)
: This works exactly like "checkAction" (above), except that it does NOT check if the current player is active.
: This is used specifically in certain game states when you want to authorize additional actions for players that are not active at the moment.
: Example: in ''Libertalia'', you want to authorize players to change their mind about the card played. They are of course not active at the time they change their mind, so you cannot use "checkAction"; use "checkPossibleAction" instead.

This is how PHP action looks that returns player to active state (only for multiplayeractive states). To be able to execute on js side do not checkAction on js side for this specific one.

function actionUnpass() {
$this->gamestate->checkPossibleAction('actionUnpass'); // player chane mind about passing while others were thinking
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

; $this->gamestate->state()
: Get an associative array of current game state attributes, see [[Your game state machine: states.inc.php]] for state attributes.
$state=$this->gamestate->state(); if( $state['name'] == 'myGameState' ) {...}

== Players turn order ==

'''getNextPlayerTable()'''

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

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

Example: if three player with ID 1, 2 and 3 are around the table, in this order, the method returns:
<pre>
array(
1 => 2,
2 => 3,
3 => 1,
0 => 1
);
</pre>

'''getPrevPlayerTable()'''

Same as above, but the associative array associate the previous player around the table. However there no 0 index here.

'''getPlayerAfter( $player_id )'''

Get player playing after given player in natural playing order.

'''getPlayerBefore( $player_id )'''

Get player playing before given player in natural playing order.

Note: There is no API to modify this order, if you have custom player order you have to maintain it in your database
and have custom function to access it.

'''createNextPlayerTable( $players, $bLoop=true )'''

Using $players array creates a map of current => next as in example from getNextPlayerTable(), however you can use custom order here.
Parmeter $bLoop is true if last player points to first, false otherwise.
In any case index 0 points to first player (first element of $players array). $players is array of player ids in desired order.

Example of usage:
<pre>
function getNextPlayerTableCustom() {
$starting = $this->getStartingPlayer(); // custom function to get starting player
$player_ids = $this->getPlayerIdsInOrder($starting); // custom function to create players array starting from starting player
return self::createNextPlayerTable($player_ids, false); // create next player table in custom order
}
</pre>

== Notify players ==

To understand notifications, please read [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] first.

'''IMPORTANT'''

Notifications are sent at the very end of the request, when it ends normally. It means that if you throw an exception for any reason (ex: move not allowed), no notifications will be sent to players.
Notifications sent between the game start (setupNewGame) and the end of the "action" method of the first active state will never reach their destination.

'''notifyAllPlayers( $notification_type, $notification_log, $notification_args )'''

Send a notification to all players of the game.

* notification_type:
A string that defines the type of your notification.

Your game interface Javascript logic will use this to know what is the type of the received notification (and to trigger the corresponding method).

* notification_log:
A string that defines what is to be displayed in the game log.

You can use an empty string here (""). In this case, nothing is displayed in the game log.

If you define a real string here, you should use "clienttranslate" method to make sure it can be translate.

You can use arguments in your notification_log strings, that refers to values defines in the "notification_args" argument (see below).
Note: Make sure you only use single quotes ('), otherwise PHP will try to interpolate the variable and will ignore the values in the args array.

* notification_args:
The arguments of your notifications, as an associative array.

This array will be transmitted to the game interface logic, in order the game interface can be updated.

Complete notifyAllPlayers example (from "Reversi"):

<pre>
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ),
array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );
</pre>

You can see in the example above the use of the "clienttranslate" method, and the use of 2 arguments "player_name" and "returned_nbr" in the notification log.

'''Important''': NO private data must be sent with this method, as a cheater could see it even it is not used explicitly by the game interface logic. If you want to send private information to a player, please use notifyPlayer below.

'''Important''': this array is serialized to be sent to the browsers, and will be saved with the notification to be able to replay the game later. If it is too big, it can make notifications slower / less reliable, and replay archives very big (to the point of failing). So as a general rule, you should send only the minimum of information necessary to update the client interface with no overhead in order to keep the notifications as light as possible.

Note: you CAN use some HTML inside your notification log, however it not recommended for many reasons:
* Its bad architecture, ui elements leak into server now you have to manage ui in many places
* If you decided to change something in ui in future version, old games reply and tutorials may not work, since they use stored notifications
* When you read log preview for old games its unreadable (this is log before you enter the game reply, useful for troubleshooting or game analysis)
* Its more data to transfer and store in db
* Its nightmare for translators, at least don't put HTML tags inside the "clienttranslate" method. You can use a notification argument instead, and provide your HTML through this argument.

If you still want to have pretty pictures in the log check this [[BGA_Studio_Cookbook#Inject_images_and_styled_html_in_the_log]].

If your notification contains some phrases that build programmatically you may need to use recursive notifications. In this case the argument can be not only the string but
an array itself, which contains 'log' and 'args', i.e.

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name} #${token_number}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_number'=>$number, 'i18n'=>['token_name'] ]
]
]);

Special handling of arguments:
* ${player_name} - this will be wrapped in html and text shown using color of the corresponding player, some colors also have reserved background. This will apply recursively as well.
* ${player_name2} - same

'''notifyPlayer( $player_id, $notification_type, $notification_log, $notification_args )'''

Same as above, except that the notification is sent to one player only.

This method must be used each time some private information must be transmitted to a player.

Important: the variable for player name must be ${player_name} in order to be highlighted with the player color in the game log. If you want a second player name in the log, name the variable ${player_name2}, etc.

== About random and randomness ==

A large number of board games rely on random, most often based on dice, cards shuffling, picking some item in a bag, and so on. This is very important to ensure a high level of randomness for each of these situations.

Here's are a list of techniques you should use in these situations, from the best to the worst.

=== Dice and bga_rand ===

'''bga_rand( min, max )'''
This is a BGA framework function that provides you a random number between "min" and "max" (inclusive), using the best available random method available on the system.

This is the preferred function you should use, because we are updating it when a better method is introduced.

As of now, bga_rand is based on the PHP function "random_int", which ensures a cryptographic level of randomness.

In particular, it is '''mandatory''' to use it for all '''dice throw''' (ie: games using other methods for dice throwing will be rejected by BGA during review).

Note: rand() and mt_rand() are deprecated on BGA and should not be used anymore, as their randomness is not as good as "bga_rand".

=== shuffle and cards shuffling ===

To shuffle items, like a pile of cards, the best way is to use the BGA PHP [[Deck]] component and to use "shuffle" method. This ensures that the best available shuffling method is used, and that if in the future we improve it your game will be up to date.

As of now, the Deck component shuffle method is based on PHP "shuffle" method, which has quite good randomness (even it is not as good as bga_rand). In consequence, we accept other shuffling methods during reviews, as long as they are based on PHP "shuffle" function (or similar, like "array_rand").

=== Other methods ===

Mysql "RAND()" function has not enough randomness to be a valid method to get a random element on BGA. This function has been used in some existing games and has given acceptable results, but now it should be avoided and you should use other methods instead.

== Game statistics ==

There are 2 types of statistics:
* a "player" statistic is a statistic associated to a player
* a "table" statistic is a statistic not associated to a player (global statistic for this game).

See [[Game statistics: stats.inc.php]] to see how you define statistics for your game.

'''initStat( $table_or_player, $name, $value, $player_id = null )'''

Create a statistic entry with a default value.

This method must be called for each statistic of your game, in your setupNewGame method.
If you neglect to call this for a statistic, and also do not update the value during the course of a certain game using setStat or incStat, the value of the stat will be undefined rather than 0. This will result in it being ignored at the end of the game, as if it didn't apply to that particular game, and excluded from cumulative statistics. As a consequence - if do not want statistic to be applied, do not init it, or call set or inc on it.

'$table_or_player' must be set to "table" if this is a table statistic, or "player" if this is a player statistic.

'$name' is the name of your statistic, as it has been defined in your stats.inc.php file.

'$value' is the initial value of the statistic. If this is a player statistic and if the player is not specified by "$player_id" argument, the value is set for ALL players.

'''setStat( $value, $name, $player_id = null )'''

Set a statistic $name to $value.

If "$player_id" is not specified, setStat consider it is a TABLE statistic.

If "$player_id" is specified, setStat consider it is a PLAYER statistic.

'''incStat( $delta, $name, $player_id = null )'''

Increment (or decrement) specified statistic value by $delta value. Same behavior as setStat function.

'''getStat( $name, $player_id = null )'''

Return the value of statistic specified by $name. Useful when creating derivative statistics such as average.

== Translations ==

See [[Translations]]

== Manage player scores and Tie breaker ==

=== Normal scoring ===

At the end of the game, players automatically get a rank depending on their score: the player with the biggest score is #1, the player with the second biggest score is #2, and so on...

During the game, you update player's score directly by updating "player_score" field of "player" table in database.

Examples:
<pre>

// +2 points to active player
self::DbQuery( "UPDATE player SET player_score=player_score+2 WHERE player_id='".self::getActivePlayerId()."'" );

// Set score of active player to 5
self::DbQuery( "UPDATE player SET player_score=5 WHERE player_id='".self::getActivePlayerId()."'" );

</pre>

Note: don't forget to notify the client side in order the score control can be updated accordingly.

=== Tie breaker ===

Tie breaker is used when two players get the same score at the end of a game.

Tie breaker is using "player_score_aux" field of "player" table. It is updated exactly like the "player_score" field.

Tie breaker score is displayed only for players who are tied at the end of the game. Most of the time, it is not supposed to be displayed explicitly during the game.

When you are using "player_score_aux" functionality, you must describe the formula to use in your gameinfos.inc.php file like this:

<pre>
'tie_breaker_description' => totranslate("Describe here your tie breaker formula"),
</pre>

This description will be used as a tooltip to explain to players how this auxiliary score has been calculated.

=== Co-operative game ===

To make everyone win/lose together in a full-coop game:

Add the following in gameinfos.inc.php :
'is_coop' => 1, // full cooperative

Assign a score of zero to everyone if it's a loss.
Assign the same score > 0 to everyone if it's a win.

=== Semi-coop ===

If the game is not full-coop, then everyone loses = everyone is tied. I.e. set score to 0 to everybody.

=== Only "winners" and "losers" ===

For some games, there is only a group (or a single) "winner", and everyone else is a "loser", with no "end of game rank" (1st, 2nd, 3rd...).

Examples:
* Coup
* Not Alone
* Werewolves
* Quantum

In this case:
* Set the scores so that the winner has the best score, and the other players have the same (lower) score.
* Add the following lines to gameinfos.inc.php:

<pre>
// If in the game, all losers are equal (no score to rank them or explicit in the rules that losers are not ranked between them), set this to true
// The game end result will display "Winner" for the 1st player and "Loser" for all other players
'losers_not_ranked' => true,
</pre>

Werewolves and Coup are implemented like this, as you can see here:
* https://boardgamearena.com/#!gamepanel?game=werewolves&section=lastresults
* https://boardgamearena.com/#!gamepanel?game=coupcitystate&section=lastresults

Adding this has the following effects:
* On game results for this game, "Winner" or "Loser" is going to appear instead of the usual "1st, 2nd, 3rd, ...".
* When a game is over, the result of the game will be "End of game: Victory" or "End of game: Defeat" depending on the result of the CURRENT player (instead of the usual "Victory of XXX").
* When calculating ELO points, if there is at least one "Loser", no "victorious" player can lose ELO points, and no "losing" player can win ELO point. Usually it may happened because being tie with many players with a low rank is considered as a tie and may cost you points. If losers_not_ranked is set, we prevent this behavior and make sure you only gain/loss ELO when you get the corresponding results.

Important: this SHOULD NOT be used for cooperative games (see is_coop parameter), or for 2 players games (it makes no sense in this case).

=== Solo ===

If game supports solo variant, a negative or zero score means defeat, a positive score means victory.

=== Player elimination ===

In some games, this is useful to eliminate a player from the game in order he/she can start another game without waiting for the current game end.

This case should be rare. Please don't use player elimination feature if some player just has to wait the last 10% of the game for game end. This feature should be used only in games where players are eliminated all along the game (typical examples: "Perudo" or "The Werewolves of Miller's Hollow").

Usage:

* Player to eliminate should NOT be active anymore (preferably use the feature in a "game" type game state).
* In your PHP code:
self::eliminatePlayer( <player_to_eliminate_id> );
* the player is informed in a dialog box that he no longer have to played and can start another game if he/she wants too (whith buttons "stay at this table" "quit table and back to main site"). In any case, the player is free to start & join another table from now.
* When your game is over, all players who have been eliminated before receive a "notification" (the small "!" icon on the top right of the BGA interface) that indicate them that "the game has ended" and invite them to review the game results.

=== Scoring Helper functions ===

These functions should have been API but they are not, just add them to your php game and use for every game.

// get score
function dbGetScore($player_id) {
return $this->getUniqueValueFromDB("SELECT player_score FROM player WHERE player_id='$player_id'");
}

// set score
function dbSetScore($player_id, $count) {
$this->DbQuery("UPDATE player SET player_score='$count' WHERE player_id='$player_id'");
}

// set aux score (tie breaker)
function dbSetAuxScore($player_id, $score) {
$this->DbQuery("UPDATE player SET player_score_aux=$score WHERE player_id='$player_id'");
}

// increment score (can be negative too)
function dbIncScore($player_id, $inc) {
$count = $this->dbGetScore($player_id);
if ($inc != 0) {
$count += $inc;
$this->dbSetScore($player_id, $count);
}
return $count;
}

== Reflexion time ==

; function giveExtraTime( $player_id, $specific_time=null )
: Give standard extra time to this player.
: Standard extra time depends on the speed of the game (small with "slow" game option, bigger with other options).
: You can also specify an exact time to add, in seconds, with the "specified_time" argument (rarely used).

== Undo moves ==

Please read our [[BGA Undo policy]] before.

'''Important''': Before using these methods, you must also add the following to your "gameinfos.inc.php" file, otherwise these methods are ineffective:
'db_undo_support' => true

; function undoSavepoint( )
: Save the whole game situation inside an "Undo save point".
: There is only ONE undo save point available (see [[BGA Undo policy]]). Cannot use in multiactivate state or in game state where next state is multiactive.
: Note: this function does not actually do anything when it is called, it only raises the flag to store the database AFTER transaction is over. So the actual state will be saved when you exit the function calling it (technically before first queued notification is sent, which matter if you transition to game state not to user state after), which may affect what you end up saved.

; function undoRestorePoint()
: Restore the situation previously saved as an "Undo save point".
: You must make sure that the active player is the same after and before the undoRestorePoint (ie: this is your responsibility to ensure that the player that is active when this method is called is exactly the same than the player that was active when the undoSavePoint method has been called).

function actionUndo() {
self::checkAction('actionUndo');
$this->undoRestorePoint();
$this->gamestate->nextState('next'); // transition to single player state (i.e. beginning of player actions for this turn)
}

== Managing errors and exceptions ==

Note: when you throw an exception, all database changes and all notifications are cancelled immediately. This way, the game situation that existed before the request is completely restored.

; throw new BgaUserException ( $error_message)
: Base class to notify a user error
: You must throw this exception when a player wants to do something that he is not allowed to do.
: The error message will be shown to the player as a "red message", so it must be translated.
: Throwing such an exception is NOT considered a bug, so it is not traced in BGA error logs.

Example from Gomoku:
<pre>
throw new BgaUserException( self::_("There is already a stone on this intersection, you can't play there") );
</pre>

; throw new BgaVisibleSystemException ( $error_message)
: You must throw this exception when you detect something that is not supposed to happened in your code.
: The error message is shown to the user as an "Unexpected error", in order that he can report it in the forum.
: The error message is logged in BGA error logs. If it happens regularly, we will report it to you.

; throw new BgaSystemException ( $error_message)
: Base class to notify a system exception. The message will be hidden from the user, but show in the logs. Use this if the message contains technical information.
: You shouldn't use this type of exception except if you think the information shown could be critical. Indeed: a generic error message will be shown to the user, so it's going to be difficult for you to see what happened.

== Zombie mode ==

When a player leaves a game for any reason (expelled, quit), he becomes a "zombie player". In this case, the results of the game won't count for statistics, but this is cool if the other players can finish the game anyway. That's why zombie mode exists: allow the other player to finish the game, even if the situation is not ideal.

While developing your zombie mode, keep in mind that:
* Do not refer to the rules, because this situation is not planned by the rules.
* Try to figure that you are playing with your friends and one of them has to leave: how can we finish the game without killing the spirit of the game?
* The idea is NOT to develop an artificial intelligence for the game.
* Do not try to end the game early, even in a two-player game. The zombie is there to allow the game to continue, not to end it. Trying to end the game is not supported by the framework and will likely cause unexpected errors.

Most of the time, the best thing to do when it is zombie player turn is to jump immediately to a state where he is not active anymore. For example, if he is in a game state where he has a choice between playing A and playing B, the best thing to do is NOT to choose A or B, but to pass. So, even if there's no "pass" action in the rules, add a "zombiepass" transitition in your game state and use it.

Each time a zombie player must play, your "zombieTurn" method is called.

Parameters:
* $state: the name of the current game state.
* $active_player: the id of the active player.

Most of the time, your zombieTurn method looks like this:

<pre>
function zombieTurn( $state, $active_player )
{
$statename = $state['name'];

if( $statename == 'myFirstGameState'
|| $statename == 'my2ndGameState'
|| $statename == 'my3rdGameState'
....
)
{
$this->gamestate->nextState( "zombiePass" );
}
else
throw new BgaVisibleSystemException( "Zombie mode not supported at this game state: ".$statename );
}
</pre>

Note that in the example above, all corresponding game state should implement "zombiePass" as a transition.

'''Very important''': your zombie code will be called when the player leaves the game. This action is triggered from the main site and propagated to the gameserver from a server, not from a browser. As a consequence, there is no current player associated to this action. In your zombieTurn function, you must '''never''' use getCurrentPlayerId() or getCurrentPlayerName(), otherwise it will fail with a "Not logged" error message.

== Player color preferences ==

BGA players (Club members) may now choose their preferred color for playing. For example, if they are used to play green for every board game, they can select "green" in their BGA preferences page.

Making your game compatible with colors preferences is very easy and requires only 1 line of PHP and 1 configuration change :

On your gameinfos.inc.php file, add the following lines :

// Favorite colors support : if set to "true", support attribution of favorite colors based on player's preferences (see reattributeColorsBasedOnPreferences PHP method)
// NB: this parameter is used only to flag games supporting this feature; you must use (or not use) reattributeColorsBasedOnPreferences PHP method to actually enable or disable the feature.
'favorite_colors_support' => true,

Then, on your main <your_game>.game.php file, find the "reloadPlayersBasicInfos" call in your "setupNewGame" method and replace :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reloadPlayersBasicInfos();

By :

$sql .= implode( $values, ',' );
self::DbQuery( $sql );
self::reattributeColorsBasedOnPreferences( $players, array( /* LIST HERE THE AVAILABLE COLORS OF YOUR GAME INSTEAD OF THESE ONES */"ff0000", "008000", "0000ff", "ffa500", "773300" ) );
self::reloadPlayersBasicInfos();

The "reattributeColorsBasedOnPreferences" method reattributes all colors, taking into account players color preferences and available colors.

Note that you must update the colors to indicate the colors available for your game.

2 important remarks :
* for some games (ex : Chess), the color has an influence on a mechanism of the game, most of the time by giving a special advantage to a player (ex : Starting the game). Color preference mechanism must NOT be used in such a case.
* your logic should NEVER consider that the first player has the color X, that the second player has the color Y, and so on. If this is the case, your game will NOT be compatible with reattributeColorsBasedOnPreferences as this method attribute colors to players based on their preferences and not based as their order at the table.

Colours currently listed as a choice in preferences:

* #ff0000 Red
* #008000 Green
* #0000ff Blue
* #ffa500 Yellow
* #000000 Black
* #ffffff White
* #e94190 Pink
* #982fff Purple
* #72c3b1 Cyan
* #f07f16 Orange
* #bdd002 Khaki green
* #7b7b7b Gray

== Legacy games API ==

For some very specific games ("legacy", "campaign"), you need to keep some informations from a game to another.

This should be an exceptional situation: the legacy API is costing resources on Board Game Arena databases, and is slowing down the game setup process + game end of game process. Please do not use it for things like:
* keeping a player preference/settings (=> player preferences and game options should be used instead)
* keeping a statistics, a score, or a ranking, while it is not planned in the physical board game, or while there is no added value compared to BGA statistics / rankings.

You should use it for:
* legacy games: when some components of the game has been altered in a previous game and should be kept as it is.
* "campaign style" games: when a player is getting a "reward" at the end of a game, and should be able to use it in further games.

Important: you cannot store more than 64k of data (serialized as JSON) per player per game. If you go over 64k, storeLegacyData function is going to FAIL, and there is a risk to create a major bug (= players blocked) in your game. You MUST make sure that no more than 64k of data is used for each player for your game. For example, if you are implementing a "campaign style" game and if you allow a player to start multiple campaign, you must LIMIT the number of different campaign so that the total data size to not go over the limit. We strongly recommend you to use this:

try
{
$this->storeLegacyTeamData( 'my_variable', $my_data );
}
catch( feException $e )
{
if( $e->getCode() == FEX_legacy_size_exceeded )
{
// Do something here to free some space in Legacy data (ex: by removing some variables)
}
else
throw $e;
}

; function storeLegacyData( $player_id, $key, $data, $ttl = 365 )
: Store some data associated with $key for the given user / current game
: In the opposite of all other game data, this data will PERSIST after the end of this table, and can be re-used
: in a future table with the same game.
: IMPORTANT: The only possible place where you can use this method is when the game is over at your table (last game action). Otherwise, there is a risk of conflicts between ongoing games.
: TTL is a time-to-live: the maximum, and default, is 365 days.
: In any way, the total data (= all keys) you can store for a given user+game is 64k (note: data is store serialized as JSON data)

; function retrieveLegacyData( $player_id, $key )
: Get data associated with $key for the current game
: This data is common to ALL tables from the same game for this player, and persist from one table to another.
: Note: calling this function has an important cost => please call it few times (possibly: only ONCE) for each player for 1 game if possible
: Note: you can use '%' in $key to retrieve all keys matching the given patterns

; function removeLegacyData( $player_id, $key )
: Remove some legacy data with the given key
: (useful to free some data to avoid going over 64k)

; function storeLegacyTeamData( $data, $ttl = 365 )
: Same as storeLegacyData, except that it stores some data for the whole team within the current table
: Ie: if players A, B and C are at a table, the legacy data will be saved for future table with (exactly) A, B and C on the table.
: This is useful for games which are intended to be played several time by the same team.
: Note: the data total size is still limited, so you must implement catch the FEX_legacy_size_exceeded exception if it happens

; function retrieveLegacyTeamData()
: Same as retrieveLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

; function removeLegacyTeamData()
: Same as removeLegacyData, except that it retrieves some data for the whole team within the current table (set by storeLegacyTeamData)

== Language dependent games API ==

This API is used for games that are heavily language dependent. Two most common use cases are:
* Games that have a language dependent component that are not necessarily translatable, typically a list of words. (Think of games like Codenames, Decrypto, Just One...)
* Games with massive communication where players would like to ensure that all participants speak the same language. (Think of games like Werewolf, The Resistance, maybe even dixit...)

If this option is used, the table created will be limited only to users that have specific language in their profile. Player starting the game would be able to chose one of the languages he speaks.

There is a new property language_dependency in gameinfos.inc.php which can be set like this:
'language_dependecy' => false, //or if the property is missing, the game is not language dependent
'language_dependecy' => true, //all players at the table must speak the same language
'language_dependecy' => array( 1 => 'en', 2 => 'fr', 3 => 'it' ), //1-based list of supported languages

In the gamename.game.php file, you can get the id of selected language with the method '''getGameLanguage'''.
; function getGameLanguage()
: Returns an index of the selected language as defined in gameinfos.inc.php.

Languages currently available on BGA are:
'ar' => array( 'name' => "العربية", 'code' => 'ar_AE' ), // Arabic
'be' => array( 'name' => "беларуская мова", 'code' => 'be_BY' ), // Belarusian
'bn' => array( 'name' => "বাংলা", 'code' => 'bn_BD' ), // Bengali
'bg' => array( 'name' => "български език", 'code' => 'bg_BG' ), // Bulgarian
'ca' => array( 'name' => "català", 'code' => 'ca_ES' ), // Catalan
'cs' => array( 'name' => "čeština", 'code' => 'cs_CZ' ), // Czech
'da' => array( 'name' => "dansk", 'code' => 'da_DK' ), // Danish
'de' => array( 'name' => "deutsch", 'code' => 'de_DE' ), // German
'el' => array( 'name' => "Ελληνικά", 'code' => 'el_GR' ), // Greek
'en' => array( 'name' => "English", 'code' => 'en_US' ), // English
'es' => array( 'name' => "español", 'code' => 'es_ES' ), // Spanish
'et' => array( 'name' => "eesti keel", 'code' => 'et_EE' ), // Estonian
'fi' => array( 'name' => "suomi", 'code' => 'fi_FI' ), // Finnish
'fr' => array( 'name' => "français", 'code' => 'fr_FR' ), // French
'he' => array( 'name' => "עברית", 'code' => 'he_IL' ), // Hebrew
'hi' => array( 'name' => "हिन्दी", 'code' => 'hi_IN' ), // Hindi
'hr' => array( 'name' => "Hrvatski", 'code' => 'hr_HR' ), // Croatian
'hu' => array( 'name' => "magyar", 'code' => 'hu_HU' ), // Hungarian
'id' => array( 'name' => "Bahasa Indonesia", 'code' => 'id_ID' ), // Indonesian
'ms' => array( 'name' => "Bahasa Malaysia", 'code' => 'ms_MY' ), // Malaysian
'it' => array( 'name' => "italiano", 'code' => 'it_IT' ), // Italian
'ja' => array( 'name' => "日本語", 'code' => 'ja_JP' ), // Japanese
'jv' => array( 'name' => "Basa Jawa", 'code' => 'jv_JV' ), // Javanese
'ko' => array( 'name' => "한국어", 'code' => 'ko_KR' ), // Korean
'lt' => array( 'name' => "lietuvių", 'code' => 'lt_LT' ), // Lithuanian
'lv' => array( 'name' => "latviešu", 'code' => 'lv_LV' ), // Latvian
'nl' => array( 'name' => "nederlands", 'code' => 'nl_NL' ), // Dutch
'no' => array( 'name' => "norsk", 'code' => 'nb_NO' ), // Norwegian
'oc' => array( 'name' => "occitan", 'code' => 'oc_FR' ), // Occitan
'pl' => array( 'name' => "polski", 'code' => 'pl_PL' ), // Polish
'pt' => array( 'name' => "português", 'code' => 'pt_PT' ), // Portuguese
'ro' => array( 'name' => "română", 'code' => 'ro_RO' ), // Romanian
'ru' => array( 'name' => "Русский язык", 'code' => 'ru_RU' ), // Russian
'sk' => array( 'name' => "slovenčina", 'code' => 'sk_SK' ), // Slovak
'sl' => array( 'name' => "slovenščina", 'code' => 'sl_SI' ), // Slovenian
'sr' => array( 'name' => "Српски", 'code' => 'sr_RS' ), // Serbian
'sv' => array( 'name' => "svenska", 'code' => 'sv_SE' ), // Swedish
'tr' => array( 'name' => "Türkçe", 'code' => 'tr_TR' ), // Turkish
'uk' => array( 'name' => "Українська мова", 'code' => 'uk_UA' ), // Ukrainian
'zh' => array( 'name' => "中文 (漢)", 'code' => 'zh_TW' ), // Traditional Chinese (Hong Kong, Macau, Taiwan)
'zh-cn' => array( 'name' => "中文 (汉)", 'code' => 'zh_CN' ), // Simplified Chinese (Mainland China, Singapore)

== Debugging and Tracing ==

To debug php code you can use some tracing functions available from the parent class such as debug, trace, error, warn, dump.

self::debug("Ahh!");
self::dump('my_var',$my_var);

See [[Practical_debugging]] section for complete information about debugging interfaces and where to find logs.

BGA Studio Cookbook

2021-01-29T23:18:21Z

AmadanNaBriona: /* Avoiding code in dojo declare style */

{{Studio_Framework_Navigation}}

This page is collection of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

== Visual Effects, Layout and Animation ==

=== Create pieces dynamically (using template) ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

=== Create pieces dynamically (using string concatenation) ===

'''Ingredients:''' ggg.js

Note: Not recommended

<pre>
div = "<div class='meeple "+color+"'></div>";
</pre>
=== Create all pieces statically ===

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

=== Use thematic fonts ===

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

=== Use player color in template ===

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?
Easiest thing I came up with is to scale whole content to fit (everything you declare in .tpl file). Tested or firefox and chrome.

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething" style="width: 1400px;">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
setup : function(gamedatas) {
console.log("Starting game setup");
...
this.interface_min_width = 740;
this.interface_max_width = 1400;
dojo.connect(window, "onresize", this, dojo.hitch(this, "adaptViewportSize"));
},

adaptViewportSize : function() {
var pageid = "page-content";
var nodeid = "thething";

var bodycoords = dojo.marginBox(pageid);
var contentWidth = bodycoords.w;

var browserZoomLevel = window.devicePixelRatio;
//console.log("zoom",browserZoomLevel);
if (contentWidth >= this.interface_max_width || browserZoomLevel >1 || this.control3dmode3d) {
dojo.style(nodeid,'transform','');
return;
}

var percentageOn1 = contentWidth / this.interface_max_width;
dojo.style(nodeid, "transform", "scale(" + percentageOn1 + ")");
},
</pre>

Note: this method does not seems to work to retina resolution displays, if you know better way let me know

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string function return becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Accessing images from js ===

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

This example actually writes "You" but you can replace this with player name as easily, drop translating function in this case

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou : function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

</pre>

=== Inject icon images in the log ===

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
self::DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
self::notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => self::getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => self::getLogsVPAmount($price),
'power_income' => self::getLogsPowerAmount($power_income),
'newScore' => self::getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

=== Inject images and styled html in the log ===

'''Ingredients:''' ggg.js, ggg.game.php

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;
break;
case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument. '''But''' 'zone_played' ''will not be available'' in the ''format_string_recursive'' method unless it is actually passed in the log message (i.e., in the string contained inside clienttranslate).

Now if you don't like raw log containing id instead of name but want name, and want substitution, you can use another parameter as id. The problem with that,
it will work at first, but if you reload game using F5 you will loose your additional parameters, why? Because when game reloads it does not actually send same
notifications, it sends special "hitstorical_log" notification where all parameters not listed in the "log" are removed. There is a hack (feature) to circumvent that,
called recursive parameters. I.e. you can send stuff like this:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_id'=>$token_id, 'i18n'=>['token_name'] ]
]
]);

and in format_log_recursive
var key = 'token_name';
if (typeof args[key] == 'string' && typeof args['token_id'] == 'string') {
args[key] = this.getTokenDiv('token_id', args);
}

=== High-Definition Graphics ===

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

=== Cool realistic shadow effect with CSS ===

If you wish to make a shadow effect for game pieces that are not rectangle, do not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

=== More readable JS: onEnteringState ===

If you have a lot of states onEnteringState and friends become rather wild, you can do this trick to call some method dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Game Modules ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
// load my own module!!!
g_gamethemeurl + "modules/ggg_other.js" ], function(dojo,
declare) {

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php7 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does how and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
self::setAjaxMode();
$this->game->actionCancel();
self::ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectatoe
switch (stateName) {
case 'playerTurnMuliPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/actionCancel.html", {}, this); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : "${you} must select location",
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch (self::getGameStateValue('playerTeams')) {
case self::TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case self::TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case self::TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case self::TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
self::DbQuery($sql);
self::reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
self::reloadPlayersBasicInfos();
</pre>

BGA Code Sharing

2021-01-29T04:17:33Z

AmadanNaBriona: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! 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)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
|}

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

Moved to [[Tools_and_tips_of_BGA_Studio]]

BGA Code Sharing

2021-01-29T04:16:49Z

AmadanNaBriona: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

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. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''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"
|-
! NON-GAME PROJECTS
! 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)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-

|}

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

Moved to [[Tools_and_tips_of_BGA_Studio]]

Game database model: dbmodel.sql

2021-01-23T17:30:36Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)
* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.

<strong><u>CAUTION:</u></strong> '''player_table_order''' is not guaranteed to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:30:15Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)
* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.

<strong><u>CAUTION:</u></strong> '''player_table_order''' is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:28:47Z

AmadanNaBriona: /* The player table */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)
* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/><strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

BGA Studio Cookbook

2021-01-23T17:27:07Z

AmadanNaBriona: /* Assigning Player Order */

{{Studio_Framework_Navigation}}

This page is collection of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

== Visual Effects, Layout and Animation ==

=== Create pieces dynamically (using template) ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

=== Create pieces dynamically (using string concatenation) ===

'''Ingredients:''' ggg.js

Note: Not recommended

<pre>
div = "<div class='meeple "+color+"'></div>";
</pre>
=== Create all pieces statically ===

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

=== Use thematic fonts ===

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

=== Use player color in template ===

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?
Easiest thing I came up with is to scale whole content to fit (everything you declare in .tpl file). Tested or firefox and chrome.

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething" style="width: 1400px;">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
setup : function(gamedatas) {
console.log("Starting game setup");
...
this.interface_min_width = 740;
this.interface_max_width = 1400;
dojo.connect(window, "onresize", this, dojo.hitch(this, "adaptViewportSize"));
},

adaptViewportSize : function() {
var pageid = "page-content";
var nodeid = "thething";

var bodycoords = dojo.marginBox(pageid);
var contentWidth = bodycoords.w;

var browserZoomLevel = window.devicePixelRatio;
//console.log("zoom",browserZoomLevel);
if (contentWidth >= this.interface_max_width || browserZoomLevel >1 || this.control3dmode3d) {
dojo.style(nodeid,'transform','');
return;
}

var percentageOn1 = contentWidth / this.interface_max_width;
dojo.style(nodeid, "transform", "scale(" + percentageOn1 + ")");
},
</pre>

Note: this method does not seems to work to retina resolution displays, if you know better way let me know

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string function return becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Accessing images from js ===

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

This example actually writes "You" but you can replace this with player name as easily, drop translating function in this case

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou : function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

</pre>

=== Inject icon images in the log ===

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
self::DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
self::notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => self::getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => self::getLogsVPAmount($price),
'power_income' => self::getLogsPowerAmount($power_income),
'newScore' => self::getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

=== Inject images and styled html in the log ===

'''Ingredients:''' ggg.js, ggg.game.php

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;
break;
case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument. '''But''' 'zone_played' ''will not be available'' in the ''format_string_recursive'' method unless it is actually passed in the log message (i.e., in the string contained inside clienttranslate).

Now if you don't like raw log containing id instead of name but want name, and want substitution, you can use another parameter as id. The problem with that,
it will work at first, but if you reload game using F5 you will loose your additional parameters, why? Because when game reloads it does not actually send same
notifications, it sends special "hitstorical_log" notification where all parameters not listed in the "log" are removed. There is a hack (feature) to circumvent that,
called recursive parameters. I.e. you can send stuff like this:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_id'=>$token_id, 'i18n'=>['token_name'] ]
]
]);

and in format_log_recursive
var key = 'token_name';
if (typeof args[key] == 'string' && typeof args['token_id'] == 'string') {
args[key] = this.getTokenDiv('token_id', args);
}

=== High-Definition Graphics ===

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

=== Cool realistic shadow effect with CSS ===

If you wish to make a shadow effect for game pieces that are not rectangle, do not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

=== More readable JS: onEnteringState ===

If you have a lot of states onEnteringState and friends become rather wild, you can do this trick to call some method dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Game Modules ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
// load my own module!!!
g_gamethemeurl + "modules/ggg_other.js" ], function(dojo,
declare) {

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes you can stub all the dojo define/declare stuff
and hook your class into that, so class if outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does how and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
self::setAjaxMode();
$this->game->actionCancel();
self::ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectatoe
switch (stateName) {
case 'playerTurnMuliPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/actionCancel.html", {}, this); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : "${you} must select location",
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Assigning Player Order ===

If you want to arbitrarily assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch (self::getGameStateValue('playerTeams')) {
case self::TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case self::TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case self::TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case self::TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
self::DbQuery($sql);
self::reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
self::reloadPlayersBasicInfos();
</pre>

Game database model: dbmodel.sql

2021-01-23T17:26:03Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/><strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:21:48Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/><strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

BGA Studio Cookbook

2021-01-23T17:17:45Z

AmadanNaBriona: /* Assorted Stuff */

{{Studio_Framework_Navigation}}

This page is collection of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

== Visual Effects, Layout and Animation ==

=== Create pieces dynamically (using template) ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

=== Create pieces dynamically (using string concatenation) ===

'''Ingredients:''' ggg.js

Note: Not recommended

<pre>
div = "<div class='meeple "+color+"'></div>";
</pre>
=== Create all pieces statically ===

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

=== Use thematic fonts ===

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

=== Use player color in template ===

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
global $g_user;
$cplayer = $g_user->get_id();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?
Easiest thing I came up with is to scale whole content to fit (everything you declare in .tpl file). Tested or firefox and chrome.

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething" style="width: 1400px;">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
setup : function(gamedatas) {
console.log("Starting game setup");
...
this.interface_min_width = 740;
this.interface_max_width = 1400;
dojo.connect(window, "onresize", this, dojo.hitch(this, "adaptViewportSize"));
},

adaptViewportSize : function() {
var pageid = "page-content";
var nodeid = "thething";

var bodycoords = dojo.marginBox(pageid);
var contentWidth = bodycoords.w;

var browserZoomLevel = window.devicePixelRatio;
//console.log("zoom",browserZoomLevel);
if (contentWidth >= this.interface_max_width || browserZoomLevel >1 || this.control3dmode3d) {
dojo.style(nodeid,'transform','');
return;
}

var percentageOn1 = contentWidth / this.interface_max_width;
dojo.style(nodeid, "transform", "scale(" + percentageOn1 + ")");
},
</pre>

Note: this method does not seems to work to retina resolution displays, if you know better way let me know

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string function return becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Accessing images from js ===

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

This example actually writes "You" but you can replace this with player name as easily, drop translating function in this case

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou : function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

</pre>

=== Inject icon images in the log ===

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
self::DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
self::notifyAllPlayers( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => self::getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => self::getLogsVPAmount($price),
'power_income' => self::getLogsPowerAmount($power_income),
'newScore' => self::getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

=== Inject images and styled html in the log ===

'''Ingredients:''' ggg.js, ggg.game.php

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited(arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;
break;
case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name}'),['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notifyAllPlayers('tokenPlaced',clienttranslate('Player placed ${token_name}'),array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument. '''But''' 'zone_played' ''will not be available'' in the ''format_string_recursive'' method unless it is actually passed in the log message (i.e., in the string contained inside clienttranslate).

Now if you don't like raw log containing id instead of name but want name, and want substitution, you can use another parameter as id. The problem with that,
it will work at first, but if you reload game using F5 you will loose your additional parameters, why? Because when game reloads it does not actually send same
notifications, it sends special "hitstorical_log" notification where all parameters not listed in the "log" are removed. There is a hack (feature) to circumvent that,
called recursive parameters. I.e. you can send stuff like this:

$this->notifyAllPlayers('playerLog',clienttranslate('Game moves ${token_name_rec}'),
['token_name_rec'=>['log'=>'${token_name}',
'args'=> ['token_name'=>clienttranslate('Boo'), 'token_id'=>$token_id, 'i18n'=>['token_name'] ]
]
]);

and in format_log_recursive
var key = 'token_name';
if (typeof args[key] == 'string' && typeof args['token_id'] == 'string') {
args[key] = this.getTokenDiv('token_id', args);
}

=== High-Definition Graphics ===

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

=== Cool realistic shadow effect with CSS ===

If you wish to make a shadow effect for game pieces that are not rectangle, do not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

=== More readable JS: onEnteringState ===

If you have a lot of states onEnteringState and friends become rather wild, you can do this trick to call some method dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Game Modules ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
// load my own module!!!
g_gamethemeurl + "modules/ggg_other.js" ], function(dojo,
declare) {

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes you can stub all the dojo define/declare stuff
and hook your class into that, so class if outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does how and hook it up.

In states.inc.php add an action to mmultipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
self::setAjaxMode();
$this->game->actionCancel();
self::ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectatoe
switch (stateName) {
case 'playerTurnMuliPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/actionCancel.html", {}, this); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : "${you} must select location",
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Assigning Player Order ===

If you want to arbitrarily assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table).

Example:
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch (self::getGameStateValue('playerTeams')) {
case self::TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case self::TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case self::TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case self::TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
self::DbQuery($sql);
self::reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
self::reloadPlayersBasicInfos();
</pre>

Game database model: dbmodel.sql

2021-01-23T17:14:15Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/><strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

Example:
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch (self::getGameStateValue('playerTeams')) {
case self::TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case self::TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case self::TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case self::TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
self::DbQuery($sql);
self::reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
self::reloadPlayersBasicInfos();
</pre>

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:11:38Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/><strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:11:23Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/>
<strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:11:08Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/>
<strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.</br/>
<strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T17:10:48Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/>
<strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.
<strong><u>CAUTION:</u></strong> This value is <u>not guaranteed</u> to be equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]

Game database model: dbmodel.sql

2021-01-23T00:05:47Z

AmadanNaBriona: /* Default tables */

{{Studio_Framework_Navigation}}

In this file you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

== Create your schema ==

To build this file, we recommend you to build the tables you need with the PhpMyAdmin tool (see BGA user guide), and then to export them and to copy/paste the content inside this file.

'''Note:''' you must not use for a column the same name as for the table, as the framework replay function relies on regexp substitution to save/restore a previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you dealing with games with 50-500 pieces!
** If you 5 tables for card game with 30 cards - it is overkill
* Database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: you have cards that have power, color, special abilities. In database you only need to store card type, all the other properties should not be there. Only exception - if it changes during the game.
* Columns should be permanent, independent of game data, i.e. location, type, position, row, etc
** Example: do not create columns like Counry1, Country2, Country3, ...
* Do not store translatable string in database, use integer number of "ident" to access properties
** I.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create separate module in php to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method handling database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE " . $this->table;
$sql .= " SET token_state='$state'";
$sql .= " WHERE token_key='$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

Important: by default, BGA creates 4 tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You 'must not modify' the schemas of the '''global''', '''stats''' or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

You may add columns to the '''player''' table. This is very practical to add simple values associated with players.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of default "player" table are:
* <strong>player_no</strong>: the index of player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this date with getActivePlayerName() or loadPlayersBasicInfos() methods)<br/><br/>

* <strong>player_score</strong>: the current score of the player (displayed in the player panel). You must update this field to update player's scores.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])<br/><br/>

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong><u>CAUTION:</u></strong> This value is currently <u>not guaranteed</u> to be actually equal to the rank of the player in the table. For example, in a 4-player game, if the table was full but the 3rd player leaves before the game starts, the 4th player becomes 3rd on this table <u>but</u> their player_table_no is still equal to 4! If another player then joins, their player_table_no will then be 5...<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read that values as ranks directly, but you can still deduce that <player B> was 1st on the table, then <player A> then <player C> then <player D> 😉

== CREATE TABLES ==
you can create tables, using engine InnoDB
<pre>
CREATE TABLE IF NOT EXISTS `hands`
(
`id` INT(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`player_id` TINYINT(1) NOT NULL,
`1` BOOL NOT NULL DEFAULT 1,
`2` BOOL NOT NULL DEFAULT 1,
`3` BOOL NOT NULL DEFAULT 1,
`4` BOOL NOT NULL DEFAULT 1,
`5` BOOL NOT NULL DEFAULT 1,
`6` BOOL NOT NULL DEFAULT 1,
`7` BOOL NOT NULL DEFAULT 1,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

'''Note''': if you put comments, you cannot do it in the same line as code.

Example:

<pre>
`3` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out `3` BOOL, and that code will not be executed.

== Link ==
You can add your Db inits in function SetupNewGame() from file 'gamename.game.php'

== Errors Log ==
To trace Database creation check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game in production, you should consult the [[Post-release phase#Updating the database schema|related section]]