Board Game Arena - User contributions [en]

BgaAnimations

2025-10-16T20:02:01Z

Vurtan: Added linebreak between Demo and Doc (always misclick)

{{Studio_Framework_Navigation}}

'''<big>[https://x.boardgamearena.net/data/game-libs/bga-animations/1.x/demo/index.html Demo]</big>'''

'''<big>[https://x.boardgamearena.net/data/game-libs/bga-animations/1.x/docs/index.html Doc]</big>'''

== Overview ==
'''bga-animations''' is a javascript component to handle different type of animations.

The lib can handle the scale & rotation of the containers when doing the animation (the Dojo animations in the "this" cannot).
It is also Promise-based, so easy to plug-in with the async notification functions.
The lib relies on the Element.animate function.

The game Reversi is an example of usage.

== Usage ==
Load the lib:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `game.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bgaAnimationsActive(),
});
</pre>

Example of usage:
<pre>
notif_moveMeeple: async function(args) {
const meepleDiv = document.getElementById(`player-meeple-${args.playerId}`);
const destinationDiv = document.getElementById(`table-slot-${args.slot}`);
await this.animationManager.slideAndAttach(meepleDiv, destinationDiv);
}

notif_scoreMeeple: async function(args) {
const meepleDiv = document.getElementById(`player-meeple-${args.playerId}`);
await this.animationManager.displayScoring(meepleDiv, args.sscore, this.gamedatas.players[args.playerId].color);
}
</pre>

Look at the demo page and the demo source code for a list of all possibilities!

== Versioning ==
The lib is using semver, so you can require 1.x to be sure to have the last fixes without risking a breaking change. Any breaking change will be noted on the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this lib, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-animations/1.x/dist/bga-animations.d.ts d.ts]''' file to put in on your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock",
getLibUrl('bga-animations', '1.x'),
],
function (dojo, declare, gamegui, counter, stock, BgaAnimations) {
(window as any).BgaAnimations = BgaAnimations; //trick
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.2''': fix error when a parallelAnimation is null

'''1.0.1''': Fix documentation

'''1.0.0''': Initial version
[[Category:Studio]]

BgaCards

2025-10-01T20:27:45Z

Vurtan: Added linebreak between Demo and Doc (always misclick)

{{Studio_Framework_Navigation}}

'''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/demo/index.html D<big>emo</big>]'''

'''<big>[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/docs/index.html Doc]</big>'''

== Overview ==
'''bga-cards''' is a javascript component to display cards.

The lib will handle associated animations (moving between stocks, flipping or rotating the cards).

The game Frenchtarot is an example of usage (with JS), or Verso (with TypeScript)

== Usage ==
Load the lib:
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
getLibUrl('bga-animations', '1.x'), // the lib uses bga-animations so this is required!
getLibUrl('bga-cards', '1.x'),
],
function (dojo, declare, gamegui, counter, BgaAnimations, BgaCards) { // note that the index of `BgaAnimations` must match the index of the define array
</pre>

In your game setup:
<pre>
// create the animation manager, and bind it to the `game.bgaAnimationsActive()` function
this.animationManager = new BgaAnimations.Manager({
animationsActive: () => this.bgaAnimationsActive(),
});

// create the card manager
this.cardsManager = new BgaCards.Manager({
animationManager: this.animationManager,
type: 'mygame-card',
getId: (card) => card.id,
setupFrontDiv: (card, div) => {
div.style.background = 'blue';
this.addTooltipHtml(div.id, `tooltip of ${card.type}`);
},
});
</pre>
Only setup an animation manager if you don't already have one, else re-use the same one.

Example of usage:
<pre>

// create the stock, in the game setup
this.cardStock = new BgaCards.LineStock(this.cardsManager, document.getElementById('card-stock'));
this.cardStock.addCards(gamedatas.cards); // cards should be something like [{ id: 1, type: 3, type_arg: 2, location: 'table', location_arg: 0 }]

notif_revealNewCards: async function(args) {
await this.cardStock.addCards(args.newCards); // similar form as above
}

</pre>

Look at the demo page and the demo source code for a list of all possibilities!

== Versioning ==
The lib is using semver, so you can require 1.x to be sure to have the last fixes without risking a breaking change. Any breaking change will be noted on the Changelog section.

== Using with TypeScript ==
If you use TypeScript and this lib, you can download the '''[https://x.boardgamearena.net/data/game-libs/bga-cards/1.x/dist/bga-cards.d.ts d.ts]''' file to put in on your game folder to benefit from auto-completion. Depending on the way you build, you might need to remove the last line (the export instruction) to be able to use it.

If your game class is not declared on the define callback, you will need to modify it with this trick (to avoid a "ReferenceError: BgaAnimations is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock",
getLibUrl('bga-animations', '1.x'),
],
function (dojo, declare, gamegui, counter, stock, BgaAnimations) {
(window as any).BgaAnimations = BgaAnimations; //trick
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.5''': fix selection of parent card if it contains a child card

'''1.0.4''': fix error on emptyHandMessage not defined

'''1.0.3''': fix emptyHandMessage conflicting with sort

'''1.0.2''': fix selection style override

'''1.0.1''': Fix documentation

'''1.0.0''': Initial version

[[Category:Studio]]

Gamehelpriftforce

2025-06-23T19:26:36Z

Vurtan:

== Overview ==
Riftforce is a 2 player game. You face up head to head, turn after turn.

If a player reaches 12 points the end of the game is triggered. Finally the player with the most points wins (of course).

The game starts with the guild selection and with players taking turns.

== Guild Selection ==
The base game contains 10 guilds. Each guild has a unique ability you can activate on your turn.
One guild is assigned randomly to every player. From the remaining 8 guilds, one is discarded. From the remaining 7 cards the players draft guilds until every player has 4 guilds.

For each guild, 4 elementals with 5 life points, 3 elementals with 6 life points, and 2 elementals with 7 life points are shuffled and 7 cards are drawn to start the game.

== Turn Overview ==
On your turn you perform 1 action. You can choose from these 3 possible actions:

*• Play Cards
*• Activate
*• Check & Draw

After that your opponent takes a turn, also choosing one action and then it comes back to you.

== Possible Actions ==

=== Play ===
Play up to 3 elementals from your hand to locations on your side of the Rift. They must either all show the same symbol or all show the same number.

You can play these elementals either

*• individually to three adjacent locations (1 elemental per location)
*• together in an order of your choice all to the same location

'''Note that the outermost locations on both ends are not considered adjacent to each other.'''

=== Activate ===
Select 1 elemental from your hand, show it face up and discard it your discard pile.

Activate up to 3 elementals that either

*• all show the same number
*• all show the same symbol

as the just discarded elemental.

The elementals you activate can be at any location and do not have to be adjacent to each other.

When you activate an elemental, it uses the ability described on its guild’s summoner. You must resolve all steps of the ability in order from top to bottom as much as you can.

When elementals change their position through abilities they are placed at the last position of the new location.

With most abilities you will place damage on the „first enemy”. This is the elemental closest to the location.

When you activate an elemental, resolve its ability completely and then check if you destroyed any elementals before activating your next elemental.

If the damage total on an elemental is equal to or higher than its number, that elemental is destroyed (discarded to the players discard pile). You gain 1 Riftforce for each destroyed enemy.

If an ability places more damage on an elemental than is needed to destroy it, the excess damage is not carried over to the next elemental.

=== Check & Draw ===
You can only choose this action if you have less than 7 elementals in your hand.

Check if you control any of the locations. You control a location if at least 1 of your elementals and no enemy is present there.

You gain 1 Riftforce for each controlled location.

If you choose this action only you can gain Riftforce even if your opponent controls locations at that moment.

Now draw elementals from your draw pile until you have 7 elementals in your hand.

== GAME END ==
As soon as a player reaches 12 Riftforce the game end is triggered.

After finishing the action completely, the opponent gets a last action if the player triggering the game end is the starting player. That way both of you get the same amount of actions.

In case of a tie, both of you perform another action and afterwards check if there is still a tie.
If the tie remains, repeat this step until the tie is broken and a winner is declared.

Game interface logic: Game.js

2024-10-05T16:09:01Z

Vurtan: Adding string interpolation info for setClientState

{{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 on state changes, in order to add action buttons to the status bar. Note: in a multipleactiveplayer state, it will be called when another player has become inactive.
* ''(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 ==

'''this.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) {
...
}

'''this.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;
}

'''this.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>

'''this.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()) ...

'''this.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()) ...

'''this.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 it is 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>

'''this.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>

'''Vanilla 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>

'''Vanilla 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>

'''Vanilla 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>

'''Vanilla 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 = ``;
'''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.

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.

'''this.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>

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

'''this.slideToObject(mobile_obj: ElementOrId, target_obj: ElementOrId, 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>

'''this.slideToObjectPos(mobile_obj: ElementOrId, target_obj: ElementOrId, 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>

'''this.slideTemporaryObject(mobile_obj_html: string, parent: ElementOrId, from: ElementOrId, to: ElementOrId, 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.
* 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===
'''this.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, 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>

'''this.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

'''this.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: Element, event: string, context: object, method: eventHandler): any'''

'''dojo.connect(element: Element, event: string, handler: 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 based 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.bgaPerformAction('actPlayPet', {card: id});
} else {
this.showMoveUnauthorized();
}
}
</pre>

'''this.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.
This function is mainly for permanent objects - if you just want to connect the temp object you should probably not use this method but use dojo.connect which won't require any clean-up.

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

Same as connect(), but for all the nodes set with the specified cssClassName.
this.connectClass('pet', 'onclick', 'onPet');
'''this.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.

'''this.disconnectAll(): void'''

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

this.disconnectAll();

=== Actions ===

'''this.bgaPerformAction(action: string, args?: object, options: object = { lock: true, checkAction: true }): Promise<void>'''

Triggers an action on the backend. This is a combination of checkAction and ajaxcall, returning a Promise which resoves when ajaxcall ends.

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.

* action: name of the action, as it is written in "possibleactions" of the current state.
* args: an object containing the call parameters to send to the action
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.

Example of a standard call without args:
this.bgaPerformAction('pass');

Example of a standard call with action args:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId });

Example of a call without checking action (because player is inactive in a multiactive state):

this.bgaPerformAction('actChangeMind', {}, { checkAction: false });

Example of a call without lock (because of a special action not directly related to the game flow):

this.bgaPerformAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with reaction to exception:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).catch(()=>{ this.selectedCardId = undefined; });

Example of call with reaction to success:
this.bgaPerformAction('actPlayCard', { id: this.selectedCardId }).then(()=>{ this.unselectAll(); });

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

''Note: bgaPerformAction is a simpler way to use ajax calls, ajaxcall stays in the doc for legacy reasons only and should not be used in new projects.''

Same warning as '''this.bgaPerformAction''' about using on user action only.

* 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. If an error occurred, the first parameter will be set to true, the second will contain the error message sent by the PHP back-end, and the third will contain an error code.
* 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/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

'''this.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( "actMyAction" ) ) {
// Do the action
}
}
</pre>

'''this.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( "actMyAction" ) ) {
// Do the action
}
}

'''this.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.
If you have not done so yet check what notification are in [[Main_game_logic:_yourgamename.game.php#Notifications]]

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

=== Subscribe to notifications ===

'''dojo.subscribe(notif_type: string, callback_obj: Object, handler: string|handler)'''
* notif_type - notification type/name send by php server
* callback_obj - usually this
* handler - if string method of callback_obj with name name is called, when notification is called, with notification object as parameter (see below)

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>
setupNotifications: function() {
...
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>
$this->notifyAllPlayers( "apples", clienttranslate('player takes ${count} apples'), [ "count" => 3 ] );
</pre>

JavaScript

<pre>
setupNotifications: function() {
dojo.subscribe( 'apples', this, 'notif_apples' );
},

notif_apples: function(notif) {
//You can access the "count" like this:
alert("count = " + notif.args.count);
}
</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>

You can also manually call this.notifqueue.setSynchronousDuration(0) once client operations are finished, but be careful that even fast replay still has a path to call it.

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

=== Adding static tooltips ===

'''this.addTooltip(nodeId: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number): void'''

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, see dynamic tooltips below.

'''this.addTooltipHtml(nodeId: string, html: string, delay?: number): void'''

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

'''this.addTooltipToClass(cssClass: string, helpStringTranslated: string, actionStringTranslated: string, delay?: number ): void'''

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: string, html: string, delay?: number): void'''

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.

=== Removing static tooltips ===

'''this.removeTooltip(nodeId: string): void'''

Remove a tooltip from the DOM node with given id.

=== Advanced tooltips ===

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

'''dynamic tooltips'''

See [[BGA_Studio_Cookbook#Dynamic_tooltips]]

'''tooltips on mobile'''

Tooltips is very unreliable on mobile, it is recommended to implement some other method to obtaining same information,
such as simple click handler in dedicated "Help" mode or provide dedicated clickable areas such as corner of card.

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

showMessage shows a message in a big rectangular area on the top of the screen of the current player, and it dissapears after few seconds (also it will be in the log in some cases).

* "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 custom type 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. The "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: function(event) {
if (checkIfPlayerTriesToFireOnThemselves(event)) {
this.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

'''this.showMoveUnauthorized(): void'''

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.showMoveUnauthorized();
return;
}
...
},
</pre>

== Dialogs ==

=== Confirmation dialog ===

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

'''this.confirmationDialog(message: string, yesHandler: (param: any) => void, noHandler?: (param: any) => void, param?: any): void'''

* message - message will be shown to user, use _() to translate
* yesHandler - non-optional handler to be called on yes
* noHandler - optional handler to called on no
* param - if specified, it will be passed to both handlers
NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers

How to display a confirmation dialog:
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"), () => {
this.bakeThePie();
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>
With param and both handlers
<pre>
this.confirmationDialog(_("Are you sure you want to bake a pie?"),
(ingredient) => this.bakeThePie(ingredient),
(ingredient) => console.log(`cancelled baking of ${ingredient}`),
'apple');
</pre>

=== Multiple choice dialog ===

You can use this dialog to give user a choice with small amount of options

'''this.multipleChoiceDialog(message: string, choices: string[], callback: (choice: number) => void): void'''
* message - message will be shown to user, use _() to translate
* choices - array of choices
* callback - non-optional handler to be called on choice made, the choice parameter is the INDEX of the choice from the array of choices

NOTE: this is async function, it does not return anything and you should not do anything after, you must do everything in handlers
NOTE: there is no cancel handler, so make sure you gave user a choice to get out of it

Example:
<pre>
const keys = ["0", "1", "5", "10"];
this.multipleChoiceDialog(_("How many bugs to fix?"), keys, (choice) => {
if (choice==0) return; // cancel operation, do not call server action
var bugchoice = keys[choice]; // choice will be 0,1,2,3 here
this.bgaPerformAction("fixBugs", { number: bugchoice });
});
return; // must return here
</pre>

=== Generic 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, (event) => {
event.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((event) => { ... });

=== 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 describes the table you want to display, line by line and column by column.

Example: display an 3x3 array of strings
<pre>
$table = [
[ "one", "two", "three" ], // This is my first line
[ "four", "five", "six" ], // This is my second line
[ "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 = [
[ "one", "two", [ "str" => clienttranslate("a string with an ${argument}"), "args" => [ 'argument' => 'argument_value' ] ] ],
[ "four", "five", "six" ],
[ "seven", "height", "nine" ]
];
</pre>

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

You can also use three extra attributes in the parameter array for the notification:
* '''header''': the content for this parameter displays 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 displays 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).

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

Note: currently id is not used - so you cannot access resulting div by id on js side

Note: any traslatable string have to be wrapped by clienttranslate() on top level OR it has to be recursive template.

DO NOT DO THIS:
<pre>
"footer" => '<div>'.clienttranslate( "The end" ).'</div>', // this will not work for translations!!!
</pre>

=== Scoring animated display ===

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

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

'''anchor_id''': ID of the html 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:

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

* anchor_id - where to attach the bubble
* text - what to put in bubble, can be html
* delay - delay in milliseconds (optional, default 0)
* duration - duration of animation in milliseconds (optional, default 3000)
* custom_class - extra class to add to bubble (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 ?? 0, notif.args.duration ?? 1000);
},
</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 ===

'''this.getPlayerPanelElement(player_id: number): HTMLElement'''

Returns the div in the player panel you can put your counters & other indicators in.

'''Example'''

At first, create a new "JS template" string in your JS file (example based on Gomoku project) :
<pre>
const jstpl_player_board = (id, color) => `<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
this.getPlayerPanelElement(player_id).innerHTML = jstpl_player_board(player.id, player.color);
}
</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.

=== Player order ===

'''this.updatePlayerOrdering(): void'''

This function makes sure that player order in player's panel matches this.gamedatas.playerorder and its normally called by framework.
You can call it yoursel if you change this.gamedatas.playerorder from notification.
Also you can override this function to change defaults OR insert a non-player panel [[BGA_Studio_Cookbook#Inserting_non-player_panel]].

=== Counters ===
Note: there is a bga component called "ebg/counter", this API is not using it. These methods below are declared right in the 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)
<pre>
<div class="counter" id="bread"></div>
<div class="counter" id="coin"></div>
</pre>
The "bread" div will be 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 ===

'''this.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.bgaPerformAction('actPass') );
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 handler 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 border, 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>

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

in example above the button will be place on object with id 'player_board'

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

'''this.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.

'''this.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

'''this.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]]

To add custom string interpolation for the state title, you can add them by using the args object like so:
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location for card {$card_number}"),
args: { card_number: 5 },
});
'''this.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

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

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

Note: this functional also will calls this.onUpdateActionButtons, if you want different buttons then state defaults, use method in example to replace them, if it becomes too clumsy use client states (see above)

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>

== User preferences ==
'''this.getGameUserPreference(pref_id)'''

Return the value of a user preference. It will return the value currently selected in the select combo box, in the top-right menu.

'''this.setGameUserPreference(pref_id, value)'''

Programmatically change a user preference. It will have the same effect as if the player changed the value in the select combo box, in the top-right menu.

'''this.onGameUserPreferenceChanged'''

A callback you can define if you want to be notified when a user changes a user preference.

Example:<pre>
onGameUserPreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</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.bgaPerformAction('makeThis');
} ) );
</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.bgaPerformAction( 'makeThis') );
</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 replay number in live game, it is set to undefined (i.e. not set) when it is not a replay 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 "replay 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"
}

'''getBgaEnvironment(): string'''
: Returns "studio" for studio and "prod" for production environment (i.e. where games current runs). Only useful for debbugging hooks.
Note: alpha server is also "prod"

[[Category:Studio]]

Gamehelproadtothreehoundred

2024-06-19T20:58:44Z

Vurtan:

== Introduction ==
In Road to 300, you will create a maze around yourself as you move through a 6-by-6 grid of squares collecting points. Can you collect 300 points before you run out of places to move?

Although designed as a solo game, here on BGA up to 8 players can compete for highest score.

== Round Procedure ==
At the beginning of each round, all three dice are rolled. You will choose 2 dice as coordinates to cross off the corresponding square on the board. Then use the last die's value to move on the board, earning the points shown on the square where you end up. When you run out of squares to move to, you are out of the game.

=== Step 1 - ROLL THE DICE: ===
Roll all three dice. ''This is done automatically by BGA.''

=== Step 2 - CROSS OUT A SQUARE ON THE BOARD: ===
Choose two of the dice, and cross out the square matching their coordinates. All possible coordinates will be highlighted on the player board for you. You will not be able to move through or move onto that square to score its points for the rest of the game.

'''You MUST cross out a square every round. You cannot cross out a square that is already crossed out or has a circle on it. If you are unable to cross off a new square, you must pass, as indicated by an X in your player info. When you pass a third time, you are out of the game.'''

=== Step 3 - MOVE: ===
Use the 3rd die to move to a new square on the board. You must take steps equal to the value of the die. If the die is 2, take 2 steps. You can change direction as much as you like while moving but no diagonals, backtracking, revisiting the same square, or moving through/onto a crossed square are permitted. All possible ending squares will be highlighted on the board for you to choose from. Collect points equal to the value of the square where you end your movement. A circle will appear on that square.

Your 1st step in the game will be onto a corner, with subsequent steps moving out from there.

Once you move onto a new square, your previously circled square will be crossed out. Like all squares with an X, you will not be able to move through or move onto it again.

== End of the Game ==
The game can end for you in two ways:

* You passed 3 times.
* You are unable to move the full number of steps shown on the movement die.

If you reached 300 or more points, you win Road to 300!

Gamehelpriftforce

2024-04-10T19:25:22Z

Vurtan: added game end

== Overview ==
Riftforce is a 2 player game. You face up head to head, turn after turn.

If a player reaches 12 points the end of the game is triggered. Finally the player with the most points win (of course).

The game starts with the guild selection and with players taking turns.

== Guild Selection ==
The base game contains 10 guilds. Each guild has a unique ability you can activate on your turn.
One guild is assigned randomly to every player. From the remaining 8 guilds, one is discarded. From the remaining 7 cards the players draft guilds until every player has 4 guilds.

== Turn Overview ==
On your turn you perform 1 action. You can choose from these 3 possible actions:

* Play Cards
* Activate
* Check & Draw

After that your opponent takes a turn, also choosing one action and then it comes back to you.

== Possible Actions ==

=== Play ===
Play up to 3 elementals from your hand to locations on your side of the Rift. They must either all show the same symbol or all show the same number.

You can play these elementals either

* individually to three adjacent locations (1 elemental per location)
* together in an order of your choice all to the same location

'''Note that the outermost locations on both ends are not considered adjacent to each other.'''

=== Activate ===
Select 1 elemental from your hand, show it face up and discard it your discard pile.

Activate up to 3 elementals that either

* all show the same number
* all show the same symbol

as the just discarded elemental.

The elementals you activate can be at any location and do not have to be adjacent to each other.

When you activate an elemental, it uses the ability described on its guild’s summoner. You must resolve all steps of the ability in order from top to bottom as much as you can.

When elementals change their position through abilities they are placed at the last position of the new location.

With most abilities you will place damage on the „first enemy”. This is the elemental closest to the location.

When you activate an elemental, resolve its ability completely and then check if you destroyed any elementals before activating your next elemental.

If the damage total on an elemental is equal to or higher than its number, that elemental is destroyed (discarded to the players discard pile). You gain 1 Riftforce for each destroyed enemy.

If an ability places more damage on an elemental than is needed to destroy it, the excess damage is not carried over to the next elemental.

=== Check & Draw ===
You can only choose this action if you have less than 7 elementals in your hand.

Check if you control any of the locations. You control a location if at least 1 of your elementals and no enemy is present there.

You gain 1 Riftforce for each controlled location.

If you choose this action only you can gain Riftforce even if your opponent controls locations at that moment.

Now draw elementals from your draw pile until you have 7 elementals in your hand.

== GAME END ==
As soon as a player reaches 12 Riftforce the game end is triggered.

After finishing the action completely, the opponent gets a last action if the player triggering the game end is the starting player. That way both of you get the same amount of actions.

Gamehelpriftforce

2024-04-10T19:22:15Z

Vurtan: formatting

== Overview ==
Riftforce is a 2 player game. You face up head to head, turn after turn.

If a player reaches 12 points the end of the game is triggered. Finally the player with the most points win (of course).

The game starts with the guild selection and with players taking turns.

== Guild Selection ==
The base game contains 10 guilds. Each guild has a unique ability you can activate on your turn.
One guild is assigned randomly to every player. From the remaining 8 guilds, one is discarded. From the remaining 7 cards the players draft guilds until every player has 4 guilds.

== Turn Overview ==
On your turn you perform 1 action. You can choose from these 3 possible actions:

* Play Cards
* Activate
* Check & Draw

After that your opponent takes a turn, also choosing one action and then it comes back to you.

== Possible Actions ==

=== Play ===
Play up to 3 elementals from your hand to locations on your side of the Rift. They must either all show the same symbol or all show the same number.

You can play these elementals either

* individually to three adjacent locations (1 elemental per location)
* together in an order of your choice all to the same location

'''Note that the outermost locations on both ends are not considered adjacent to each other.'''

=== Activate ===
Select 1 elemental from your hand, show it face up and discard it your discard pile.

Activate up to 3 elementals that either

* all show the same number
* all show the same symbol

as the just discarded elemental.

The elementals you activate can be at any location and do not have to be adjacent to each other.

When you activate an elemental, it uses the ability described on its guild’s summoner. You must resolve all steps of the ability in order from top to bottom as much as you can.

When elementals change their position through abilities they are placed at the last position of the new location.

With most abilities you will place damage on the „first enemy”. This is the elemental closest to the location.

When you activate an elemental, resolve its ability completely and then check if you destroyed any elementals before activating your next elemental.

If the damage total on an elemental is equal to or higher than its number, that elemental is destroyed (discarded to the players discard pile). You gain 1 Riftforce for each destroyed enemy.

If an ability places more damage on an elemental than is needed to destroy it, the excess damage is not carried over to the next elemental.

=== Check & Draw ===
You can only choose this action if you have less than 7 elementals in your hand.

Check if you control any of the locations. You control a location if at least 1 of your elementals and no enemy is present there.

You gain 1 Riftforce for each controlled location.

If you choose this action only you can gain Riftforce even if your opponent controls locations at that moment.

Now draw elementals from your draw pile until you have 7 elementals in your hand.

Gamehelpriftforce

2024-04-10T19:19:00Z

Vurtan: first version

=== Overview ===
Riftforce is a 2 player game. You face up head to head, turn after turn.
If a player reaches 12 points the end of the game is triggered. Finally the player with the most points win (of course :) ).

=== Guild Selection ===
The base game contains 10 guilds. Each guild has a unique ability you can activate on your turn.
One guild is assigned randomly to every player. From the remaining 8 guilds, one is discarded. From the remaining 7 cards the players draft guilds until every player has 4 guilds.

=== Turn Overview ===
On your turn you perform 1 action. You can choose from these 3 possible actions:
A) Play Cards
B) Activate
C) Check & Draw

After that your opponent takes a turn, also choosing one action and then it comes back to you.

=== Play ===
Play up to 3 elementals from your hand to locations on your side of the Rift. They must either all show the same symbol or all show the same number.
You can play these elementals either
-> individually to three adjacent locations (1 elemental per location)
-> together in an order of your choice all to the same location

*Note that the outermost locations on both ends are not considered adjacent to each other.*

=== Activate ===
Select 1 elemental from your hand, show it face up and discard it your discard pile.
Activate up to 3 elementals that either
-> all show the same number
-> all show the same symbol
as the just discarded elemental.

The elementals you activate can be at any location and do not have to be adjacent to each other.

When you activate an elemental, it uses the ability described on its guild’s summoner. You must resolve all steps of the ability in order from top to bottom as much as you can.
When elementals change their position through abilities they are placed at the last position of the new location.
With most abilities you will place damage on the „first enemy”. This is the elemental closest to the location.
When you activate an elemental, resolve its ability completely and then check if you destroyed any elementals before activating your next elemental.

If the damage total on an elemental is equal to or higher than its number, that elemental is destroyed (discarded to the players discard pile). You gain 1 Riftforce for each destroyed enemy.
If an ability places more damage on an elemental than is needed to destroy it, the excess damage is not carried over to the next elemental.

=== Check & Draw ===
You can only choose this action if you have less than 7 elementals in your hand.
Check if you control any of the locations. You control a location if at least 1 of your elementals and no enemy is present there.
You gain 1 Riftforce for each controlled location.

If you choose this action only you can gain Riftforce even if your opponent controls locations at that moment.
Now draw elementals from your draw pile until you have 7 elementals in your hand.

Gamehelproadtothreehoundred

2024-04-10T18:57:35Z

Vurtan: missing 3

== Introduction ==
Road to 300 is designed as a solo game. You win the game if you have 300 or more points at the end.
Here on BGA you can play it with other players. Therefore a small rules change is applied regarding the passing.

== Round Procedure ==
At the beginning of each round, the three dice get rolled.

You choose two dice to permanently cross a cell on the grid.

The other die is used to move on the game board. Cells where you end your movement will earn points at the end of the game.

If you cannot move according to the rules after a dice roll and crossing, the game is over.

=== Step 1 - Rolling: ===
Roll the three dice. -> Done here by BGA

=== Step 2 - Crossing a cell: ===
Use two of the rolled dice and cross the cell matching the coordinates. Which coordinates are possible are highlighted on the player board for you.

'''Important: You MUST cross a cell in every round. If you are unable to make a cross, you have to pass this round and you receive one X (shown in player info)'''

=== Step 3 - Marking the starting cell (skipped in Round 1!) ===
The cell where you start is now crossed out and is also permanently marked like the cells from Step 2. Since you ended your movment there, you still get those points at the end of the game. In this cell, there is now an X and a circle around the number.

'''Note. This step is skipped in the very first round of the game, as you start outside the grid.'''

=== Step 4 - Movement ===
The third die that is now left is used for movement.

The first step in the game must be on a 30.

As mentioned in Step 3, you start outside the grid and can only enter the grid via a 30.

In all subsequent rounds, you move cell by cell starting from the starting cell of the previous round. You move orthogonally, until you have covered the exact number of pips of the die in steps.

You may not enter cells multiple times within one round, and during movement and you may not move out of the grid.

However: It is allowed to change direction during movement, so you do not have to move all cells in one direction. Circle the number in the cell where you end your movement. This earns you points for the end of the game.

'''Important: Cells with an X and/or a circle around the number are blocked and cannot be entered during movement! If you realize in this step that you can no longer move according to the rules, you have to pass for the whole game and receive three X (shown in the player info)!'''

After that, start a new round at Step 1.

== End of the Game ==
The game can end for you, if you gather at least 3 passes (shown as X in the player info). This can happen in two ways:

* You gathered three X by passing in step 2
* You are unnable to move according to the rules in step 4 (which gives you three X)

At the end of the game sum up the number values of all cells that have both an X and a circle. This total value is your score.

If you have now reached 300 or more points, you win Road to 300!

== Final Note ==
It is important that a cell is marked first and then the movement takes place. Sometimes, in consideration, you might already mark a target cell with a circle and then strike a cell that was used on the way there. This is not allowed!

This is checked and validated by the BGA implementation for you.

Gamehelproadtothreehoundred

2024-04-10T18:47:19Z

Vurtan: removed :

== Introduction ==
Road to 300 is designed as a solo game. You win the game if you have 300 or more points at the end.
Here on BGA you can play it with other players. Therefore a small rules change is applied regarding the passing.

== Round Procedure ==
At the beginning of each round, the three dice get rolled.

You choose two dice to permanently cross a cell on the grid.

The other die is used to move on the game board. Cells where you end your movement will earn points at the end of the game.

If you cannot move according to the rules after a dice roll and crossing, the game is over.

=== Step 1 - Rolling: ===
Roll the three dice. -> Done here by BGA

=== Step 2 - Crossing a cell: ===
Use two of the rolled dice and cross the cell matching the coordinates. Which coordinates are possible are highlighted on the player board for you.

'''Important: You MUST cross a cell in every round. If you are unable to make a cross, you have to pass this round and you receive one X (shown in player info)'''

=== Step 3 - Marking the starting cell (skipped in Round 1!) ===
The cell where you start is now crossed out and is also permanently marked like the cells from Step 2. Since you ended your movment there, you still get those points at the end of the game. In this cell, there is now an X and a circle around the number.

'''Note. This step is skipped in the very first round of the game, as you start outside the grid.'''

=== Step 4 - Movement ===
The third die that is now left is used for movement.

The first step in the game must be on a 30.

As mentioned in Step 3, you start outside the grid and can only enter the grid via a 30.

In all subsequent rounds, you move cell by cell starting from the starting cell of the previous round. You move orthogonally, until you have covered the exact number of pips of the die in steps.

You may not enter cells multiple times within one round, and during movement and you may not move out of the grid.

However: It is allowed to change direction during movement, so you do not have to move all cells in one direction. Circle the number in the cell where you end your movement. This earns you points for the end of the game.

'''Important: Cells with an X and/or a circle around the number are blocked and cannot be entered during movement! If you realize in this step that you can no longer move according to the rules, you have to pass for the whole game and receive three X (shown in the player info)!'''

After that, start a new round at Step 1.

== End of the Game ==
The game can end for you, if you gather at least passes (shown as X in the player info).
This can happen in two ways:

* You gathered three X by passing in step 2
* You are unnable to move according to the rules in step 4 (which gives you three X)

At the end of the game sum up the number values of all cells that have both an X and a circle. This total value is your score.

If you have now reached 300 or more points, you win Road to 300!

== Final Note ==
It is important that a cell is marked first and then the movement takes place. Sometimes, in consideration, you might already mark a target cell with a circle and then strike a cell that was used on the way there. This is not allowed!

This is checked and validated by the BGA implementation for you.

Gamehelproadtothreehoundred

2024-04-10T18:45:49Z

Vurtan: formatting headlines

== Introduction ==
Road to 300 is designed as a solo game. You win the game if you have 300 or more points at the end.
Here on BGA you can play it with other players. Therefore a small rules change is applied regarding the passing.

== Round Procedure ==
At the beginning of each round, the three dice get rolled.

You choose two dice to permanently cross a cell on the grid.

The other die is used to move on the game board. Cells where you end your movement will earn points at the end of the game.

If you cannot move according to the rules after a dice roll and crossing, the game is over.

=== Step 1 - Rolling: ===
Roll the three dice. -> Done here by BGA

=== Step 2 - Crossing a cell: ===
Use two of the rolled dice and cross the cell matching the coordinates. Which coordinates are possible are highlighted on the player board for you.

'''Important: You MUST cross a cell in every round. If you are unable to make a cross, you have to pass this round and you receive one X (shown in player info)'''

=== Step 3 - Marking the starting cell (skipped in Round 1!) ===
The cell where you start is now crossed out and is also permanently marked like the cells from Step 2. Since you ended your movment there, you still get those points at the end of the game. In this cell, there is now an X and a circle around the number.

'''Note. This step is skipped in the very first round of the game, as you start outside the grid.'''

=== Step 4 - Movement ===
The third die that is now left is used for movement.

The first step in the game must be on a 30.

As mentioned in Step 3, you start outside the grid and can only enter the grid via a 30.

In all subsequent rounds, you move cell by cell starting from the starting cell of the previous round. You move orthogonally, until you have covered the exact number of pips of the die in steps.

You may not enter cells multiple times within one round, and during movement and you may not move out of the grid.

However: It is allowed to change direction during movement, so you do not have to move all cells in one direction. Circle the number in the cell where you end your movement. This earns you points for the end of the game.

'''Important: Cells with an X and/or a circle around the number are blocked and cannot be entered during movement! If you realize in this step that you can no longer move according to the rules, you have to pass for the whole game and receive three X (shown in the player info)!'''

After that, start a new round at Step 1.

== End of the Game: ==
The game can end for you, if you gather at least passes (shown as X in the player info).
This can happen in two ways:

* You gathered three X by passing in step 2
* You are unnable to move according to the rules in step 4 (which gives you three X)

At the end of the game sum up the number values of all cells that have both an X and a circle. This total value is your score.

If you have now reached 300 or more points, you win Road to 300!

== Final Note: ==
It is important that a cell is marked first and then the movement takes place. Sometimes, in consideration, you might already mark a target cell with a circle and then strike a cell that was used on the way there. This is not allowed!

This is checked and validated by the BGA implementation for you.

Gamehelproadtothreehoundred

2024-04-10T18:30:41Z

Vurtan: Moved to correct language

=== Introduction ===
Road to 300 is designed as a solo game. You win the game if you have 300 or more points at the end.
Here on BGA you can play it with other players. Therefore a small rules change is applied regarding the passing.

== Round Procedure ==
At the beginning of each round, the three dice get rolled.

You choose two dice to permanently cross a cell on the grid.

The other die is used to move on the game board. Cells where you end your movement will earn points at the end of the game.

If you cannot move according to the rules after a dice roll and crossing, the game is over.

=== Step 1 - Rolling: ===
Roll the three dice. -> Done here by BGA

=== Step 2 - Crossing a cell: ===
Use two of the rolled dice and cross the cell matching the coordinates. Which coordinates are possible are highlighted on the player board for you.

'''Important: You MUST cross a cell in every round. If you are unable to make a cross, you have to pass this round and you receive one X (shown in player info)'''

=== Step 3 - Marking the starting cell (skipped in Round 1!) ===
The cell where you start is now crossed out and is also permanently marked like the cells from Step 2. Since you ended your movment there, you still get those points at the end of the game. In this cell, there is now an X and a circle around the number.

'''Note. This step is skipped in the very first round of the game, as you start outside the grid.'''

=== Step 4 - Movement ===
The third die that is now left is used for movement.

The first step in the game must be on a 30.

As mentioned in Step 3, you start outside the grid and can only enter the grid via a 30.

In all subsequent rounds, you move cell by cell starting from the starting cell of the previous round. You move orthogonally, until you have covered the exact number of pips of the die in steps.

You may not enter cells multiple times within one round, and during movement and you may not move out of the grid.

However: It is allowed to change direction during movement, so you do not have to move all cells in one direction. Circle the number in the cell where you end your movement. This earns you points for the end of the game.

'''Important: Cells with an X and/or a circle around the number are blocked and cannot be entered during movement! If you realize in this step that you can no longer move according to the rules, you have to pass for the whole game and receive three X (shown in the player info)!'''

After that, start a new round at Step 1.

=== End of the Game: ===
The game can end for you, if you gather at least passes (shown as X in the player info).
This can happen in two ways:

* You gathered three X by passing in step 2
* You are unnable to move according to the rules in step 4 (which gives you three X)

At the end of the game sum up the number values of all cells that have both an X and a circle. This total value is your score.

If you have now reached 300 or more points, you win Road to 300!

=== Final Note: ===
It is important that a cell is marked first and then the movement takes place. Sometimes, in consideration, you might already mark a target cell with a circle and then strike a cell that was used on the way there. This is not allowed!

This is checked and validated by the BGA implementation for you.

Deck

2024-02-26T17:48:21Z

Vurtan: Document different result in getCardsInLocation

{{Studio_Framework_Navigation}}

"Deck" is one of the most useful component on the PHP side. With "Deck", you can manage the cards in your game on the server side.

Using "deck", you will be able to use the following features without writing a single SQL database request:
* Place cards in a pile, shuffle cards, draw cards one by one or many at a time.
* "Auto-reshuffle" the discard pile into the deck when the deck is empty.
* Move cards between different locations: hands of players, the table, etc.

== Using Deck: Hearts example ==

The Deck component is extensively used in the sample ''Hearts'' card game. You will find in "hearts.game.php" that the object "$this->cards" is used many times.

== Deck overview ==

With Deck component, you manage all cards of your game.

=== The 5 properties of each card ===

Using the Deck component, each card will have 5 properties:
* '''id''': This is the unique ID of each card.
* '''type''' and '''type_arg''': These two values define the type of your card (i.e., what sort of card is this?).
* '''location''' and '''location_arg''': These two values define where the card is at now.

The id, type, and type_arg properties are constants throughout the game. location and location_arg change when your cards move from one place to another in the game area.

'''id''' is the unique ID of each card. Two cards cannot have the same ID. IDs are generated automatically by the Deck component when you create cards during the Setup phase of your game.

'''type''' and '''type_arg''' defines the type of your card.

'''type''' is a short string, and '''type_arg''' is an integer.

You can use these two values as you like to make sure you will be able to identify the different cards in the game. See usage of "type" and "type_arg" below.

Examples of usage of "type" and "type_arg":
* In ''Hearts'', "type" represents the color (suite) of the card (1 to 4) and "type_arg" is the value of the card (1, 2, ... 10, J, Q, K).
* In ''Seasons'', "type" represents the type of the card (e.g., 1 is Amulet of Air, 2 is Amulet of Fire, etc...). type_arg is not used.
* In ''Takenoko'', a Deck component is used for objective cards. "type" is the kind of objective (irrigation/panda/plot) and "type_arg" is the ID of the specific objective to realize (e.g., "green bamboo x4"). Note that a second Deck component is used in ''Takenoko'' to manage the "garden plot" pile.

'''location''' and '''location_arg''' define where a card is at now. '''location''' is a short string, and '''location_arg''' is an integer.

You can use 'location' and 'location_arg' as you like, to move your card within the game area.

There are 3 special 'location' values that Deck manages automatically. You can choose to use these locations or not, depending on your needs:
* 'deck': the 'deck' location is a standard draw deck. Cards are placed face down in a stack and are drawn in sequential order during the game. 'location_arg' is used to specify where the card is located within the stack (the card with the highest location_arg value is the next to be drawn).
* 'hand': the 'hand' location represents cards in a player's hand. 'location_arg' is set to the ID of each player.
* 'discard': the 'discard' location is used for discard piles. Card in 'discard' may be reshuffled into the deck if needed (see "autoreshuffle").

Tips: using the Deck component, you will use generic properties ("location", "type_arg",...) for specific purposes in your game. Thus, during the design step before realizing your game, take a few minutes to write down the exact meaning of each of these generic properties in the context of your game.

=== Create a new Deck component ===

For each Deck component in your game, you need to create a dedicated table in the SQL database. This table has a standard format. In practice, if you just want to have a Deck component named "card", you can copy/paste the following into your "dbmodel.sql" file:

<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: the database schema of this table does not have to be exactly what is listed above. You can increase the size of the fields or add more fields. For additional fields
you just have to do manual queries.

In particular, if you are going to have deck locations specific to individual players, you may wish to use their player IDs in the card_location field. Those IDs can be 8+ characters long, leaving only 8 characters for the rest of the name if you use the varchar(16). If you exceed the size of the field, it will get silently truncated, which can be very difficult to troubleshoot!

Once you have done this (and restarted your game), you can declare the Deck component in your PHP code in your class constructor. For ''Hearts'' for example, I added to the "Hearts()" method:

<pre>
$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
</pre>

Note that we specify "card" here: the name of our previously created table. This means you can create several "Deck" components with multiple tables:

<pre>
$this->firstKindCards = self::getNew( "module.common.deck" );
$this->firstKindCards ->init( "first_kind_card" );
$this->secondKindCards = self::getNew( "module.common.deck" );
$this->secondKindCards ->init( "second_kind_card" );
</pre>

Most of the time this is not useful; a Deck component should manage all objects of the same kind (i.e., all cards in the game).
Note that you need to create a table for each "Deck", table name should be "first_kind_card" but the fields must remain "card_id", "card_type" and so on.

Afterwards, we can initialize your "Deck" by creating all the cards of the game. Generally, this is done only once during the game, in the "setupNewGame" method.

The "Deck" component provides a fast way to initialize all your cards at once: createCards. Here is how it is used for "Hearts":<pre>
// Create cards
$cards = array();
foreach( $this->colors as $color_id => $color ) // spade, heart, diamond, club
{
for( $value=2; $value<=14; $value++ ) // 2, 3, 4, ... K, A
{
$cards[] = array( 'type' => $color_id, 'type_arg' => $value, 'nbr' => 1);
}
}

$this->cards->createCards( $cards, 'deck' );
</pre>

As you can see, "createCards" takes a description of all cards of the game. For each type of card, you have to specify its "type", "type_arg" and the number of cards to create ("nbr"). "createCards" create all cards and place them into the "deck" location (as specified in the second argument).

Now, you are ready to use "Deck"!

=== Simple examples using Deck ===

(Most examples are from "Hearts" game)

<pre>
// In "getAllDatas', we need to send to the current player all the cards he has in hand:
$result['hand'] = $this->cards->getCardsInLocation( 'hand', $player_id );
</pre>

<pre>
// At some time we want to check if all the cards (52) are in player's hands:
if( $this->cards->countCardInLocation( 'hand' ) == 52 )
// do something
</pre>

<pre>
// When a player plays a card in front of him on the table:
$this->cards->moveCard( $card_id, 'cardsontable', $player_id );

// Note the use of the custom location 'cardsontable' here to keep track of cards on the table.
</pre>

<pre>
// This is a new hand: let's gather all cards from everywhere in the deck:
$this->cards->moveAllCardsInLocation( null, "deck" );

// And then shuffle the deck
$this->cards->shuffle( 'deck' );

// And then deal 13 cards to each player
// Deal 13 cards to each players
// Create deck, shuffle it and give 13 initial cards
$players = self::loadPlayersBasicInfos();
foreach( $players as $player_id => $player )
{
$cards = $this->cards->pickCards( 13, 'deck', $player_id );

// Notify player about his cards
self::notifyPlayer( $player_id, 'newHand', '', array(
'cards' => $cards
) );
}

// Note the use of "notifyPlayer" instead of "notifyAllPlayers": new cards is a private information ;)
</pre>

== Deck component reference ==

=== Initializing Deck component ===

'''init( $table_name )'''

Initialize the Deck component.

Argument:
* table_name: name of the DB table used by this Deck component.

Must be called before any other Deck method.

Usually, init is called in your game constructor.

HINT: Create the deck object self::getNew and do the init call in the constructor or you will get "$this->cards" as an invalid reference later.

Example with Hearts:

<pre>
function Hearts( )
{
(...)

$this->cards = self::getNew( "module.common.deck" );
$this->cards->init( "card" );
}
</pre>

'''createCards( $cards, $location='deck', $location_arg=null )'''

Create card items in your deck component. Usually, all card items are created once, during the setup phase of the game.

"cards" describe all cards that need to be created. "cards" is an array with the following format:

<pre>
// Create 1 card of type "1" with type_arg=99,
// and 4 cards of type "2" with type_arg=12,
// and 2 cards of type "3" with type_arg=33

$cards = array(
array( 'type' => 1, 'type_arg' => 99, 'nbr' => 1 ),
array( 'type' => 2, 'type_arg' => 12, 'nbr' => 4 ),
array( 'type' => 3, 'type_arg' => 33, 'nbr' => 2 )
...
);
</pre>

Note: During the "createCards" process, Deck generates unique IDs for all card items.

Note: createCards is optimized to create a lot of cards at once. Do not use it to create cards one by one.

If "$location" and "$location_arg" arguments are not set, newly created cards are placed in the "deck" location. If "location" (and optionally location_arg) is specified, cards are created for this specific location.

Note: 'location' and 'location_arg' can not be set individually, it does not read these values from the passed array of cards.

HINT: Be sure to do the createCards in setupNewGame. Doing createCards in the constructor will throw database errors.

=== Card standard format ===

When Deck component methods are returning one or several cards, the following format is used:

<pre>
array(
'id' => .., // the card ID
'type' => .., // the card type
'type_arg' => .., // the card type argument
'location' => .., // the card location
'location_arg' => .. // the card location argument
);
</pre>

=== Picking cards ===

'''pickCard( $location, $player_id )'''

Pick a card from a "pile" location (ex: "deck") and place it in the "hand" of specified player.

Return the card picked or "null" if there are no more card in given location.

The return value is an array of the card data elements (id, type, type_arg...) for that card.

This method supports auto-reshuffle (see "auto-reshuffle" below).

'''pickCards( $nbr, $location, $player_id )'''

Pick "$nbr" cards from a "pile" location (ex: "deck") and place them in the "hand" of specified player.

Return an array with the cards picked (indexed by the card ID), or "null" if there are no more card in given location.

Note that the number of cards picked can be less than "$nbr" in case there are not enough cards in the pile location.

This method supports auto-reshuffle (see "auto-reshuffle" below). In case there are not enough cards in the pile, all remaining cards are picked first, then the auto-reshuffle is triggered, then the other cards are picked.

'''pickCardForLocation( $from_location, $to_location, $location_arg=0 )'''

This method is similar to 'pickCard', except that you can pick a card for any sort of location and not only the "hand" location.

* from_location is the "pile" style location from where you are picking a card.
* to_location is the location where you will place the card picked.
* if "location_arg" is specified, the card picked will be set with this "location_arg".

This method supports auto-reshuffle (see "auto-reshuffle" below).

'''pickCardsForLocation( $nbr, $from_location, $to_location, $location_arg=0, $no_deck_reform=false )'''

This method is similar to 'pickCards', except that you can pick cards for any sort of location and not only the "hand" location.

* from_location is the "pile" style location from where you are picking some cards.
* to_location is the location where you will place the cards picked.
* if "location_arg" is specified, the cards picked will be set with this "location_arg".
* if "no_deck_reform" is set to "true", the auto-reshuffle feature is disabled during this method call.

This method supports auto-reshuffle (see "auto-reshuffle" below).

=== Moving cards ===

'''moveCard( $card_id, $location, $location_arg=0 )'''

Move the specific card to given location.

* card_id: ID of the card to move.
* location: location where to move the card.
* location_arg: if specified, location_arg where to move the card. If not specified "location_arg" will be set to 0.

'''moveCards( $cards, $location, $location_arg=0 )'''

Move the specific cards to given location.

* cards: an array of IDs of cards to move.
* location: location where to move the cards.
* location_arg: if specified, location_arg where to move the cards. If not specified "location_arg" will be set to 0.

'''insertCard( $card_id, $location, $location_arg )'''

Move a card to a specific "pile" location where card are ordered.

If location_arg place is already taken, increment all cards after location_arg in order to insert new card at this precise location.

(note: insertCardOnExtremePosition method below is more useful in most of the case)

'''insertCardOnExtremePosition( $card_id, $location, $bOnTop )'''

Move a card on top or at bottom of given "pile" type location. (Lower numbers: bottom of the deck. Higher numbers: top of the deck.)

(note: Filling an empty location this way with N cards creates "location_arg"s from 1 to N if "$bOnTop" is true and -1 to -N if "$bOnTop" is false. This can cause off-by-one errors for code intended to run on a deck generated by "shuffle( $location )" which generates "location_arg"s from 0 to N - 1.)

'''moveAllCardsInLocation( $from_location, $to_location, $from_location_arg=null, $to_location_arg=0 )'''

Move all cards in specified "from" location to given location.

* from_location: where to take the cards. If null, cards from all locations will be move.
* to_location: where to put the cards
* from_location_arg (optional): if specified, only cards with given "location_arg" are moved.
* to_location_arg (optional): if specified, cards moved "location_arg" is set to given value. Otherwise "location_arg" is set to 0.

Note: if you want to keep "location_arg" untouched, you should use "moveAllCardsInLocationKeepOrder" below.

'''moveAllCardsInLocationKeepOrder( $from_location, $to_location )'''

Move all cards in specified "from" location to given "to" location. This method does not modify the "location_arg" of cards.

'''playCard( $card_id )'''

Move specified card at the top of the "discard" location.

Note: this is an alias for: insertCardOnExtremePosition( $card_id, "discard", true )

=== Get cards informations ===

'''getCard( $card_id )'''

Get specific card information.

Return null if this card is not found.

'''getCards( $cards_array )'''

Get specific cards information.

$cards_array is an array of card IDs.

If some cards are not found or if some card IDs are specified multiple times, the method throws an (unexpected) Exception.

'''getCardsInLocation( $location, $location_arg = null, $order_by = null )'''

Get all cards in specific location, as an array. Return an empty array if the location is empty.

* location (string): the location where to get the cards.
* location_arg (optional): if specified, return only cards with the specified "location_arg".
* order_by (optional): if specified, returned cards are ordered by the given database field. Example: "card_id" or "card_type".
Using the "order_by" parameter changes the resulting array. Without parameter you get an associative array with the "card_id", with the paramter you get a simple indexed array.

'''countCardInLocation( $location, $location_arg=null )'''

Return the number of cards in specified location.

* location (string): the location where to count the cards.
* location_arg (optional): if specified, count only cards with the specified "location_arg".

'''countCardsInLocations()'''

Return the number of cards in each location of the game.

The method returns an associative array with the format "location" => "number of cards".

Example:
<pre>
array(
'deck' => 12,
'hand' => 21,
'discard' => 54,
'ontable' => 3
);
</pre>

'''countCardsByLocationArgs( $location )'''

Return the number of cards in each "location_arg" for the given location.

The method returns an associative array with the format "location_arg" => "number of cards".

Example: count the number of cards in each player's hand:
<pre>
countCardsByLocationArgs( 'hand' );

// Result:
array(
122345 => 5, // player 122345 has 5 cards in hand
123456 => 4 // and player 123456 has 4 cards in hand
);
</pre>

'''getPlayerHand( $player_id )'''

Get all cards in given player hand.

Note: This is an alias for:
getCardsInLocation( "hand", $player_id )

'''getCardOnTop( $location )'''

Get the card on top of the given ("pile" style) location, or null if the location is empty.

Note that the card pile won't be "auto-reshuffled" if there is no more card available.

'''getCardsOnTop( $nbr, $location )'''

Get the "$nbr" cards on top of the given ("pile" style) location.

The method return an array with at most "$nbr" elements (or a void array if there is no card in this location).

Note that the card pile won't be "auto-reshuffled" if there is not enough cards available.

'''getExtremePosition( $bGetMax ,$location )'''

(rarely used)

Get the position of cards at the top of the given location / at the bottom of the given location.

Of course this method works only on location in "pile" where you are using "location_arg" to specify the position of each card (example: "deck" location).

If bGetMax=true, return the location of the top card of the pile.

If bGetMax=false, return the location of the bottom card of the pile.

'''getCardsOfType( $type, $type_arg=null )'''

Get all cards of a specific type (rarely used).

Return an array of cards, or an empty array if there is no cards of the specified type.

* type: the type of cards
* type_arg: if specified, return only cards with the specified "type_arg".

'''getCardsOfTypeInLocation( $type, $type_arg=null, $location, $location_arg = null )

Get all cards of a specific type in a specific location (rarely used).

Return an array of cards, or an empty array if there is no cards of the specified type.

* type: the type of cards
* type_arg: if specified, return only cards with the specified "type_arg".
* location (string): the location where to get the cards.
* location_arg (optional): if specified, return only cards with the specified "location_arg".

=== Shuffling ===

'''shuffle( $location )'''

Shuffle all cards in specific location.

Shuffle only works on locations where cards are on a "pile" (ex: "deck").

Please note that all "location_arg" will be reset to reflect the new order of the cards in the pile.

=== Auto-reshuffle ===

To enable auto-reshuffle you must do "$this->cards->autoreshuffle = true" during the setup of the component (often in the ''_construct'' function when you ''init()'' the Deck object).

Every time a card must be retrieved from the "deck" location, if it is empty the "discard" location will be automatically reshuffled into the "deck" location.

If you need to notify players when the deck is shuffled, you can setup a callback method using this feature: $this->cards->autoreshuffle_trigger = array('obj' => $this, 'method' => 'deckAutoReshuffle');

If you need to use other locations than "deck" and "discard" for auto-reshuffle feature, you can configure it this way: $this->cards->autoreshuffle_custom = array('deck' => 'discard'); (replace 'deck' and 'discard' with your custom locations).

[[Category:Studio]]