Board Game Arena - User contributions [en]

Using Typescript and Scss

2026-02-01T15:31:10Z

Vagabond: Add note that the switch to ES modules means the global JS game object changes.

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.
There is also untested 3rd party project that aims to automate some of the steps below, you can look at this instead [[BGA Type Safe Template]].

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''
<pre>
{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "rollup -c",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "rollup -c -w",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"@rollup/plugin-typescript": "^12.3.0",
"rollup": "^4.53.3",
"sass": "^1.71.0",
"tslib": "^2.8.1",
"typescript": "^5.3.3"
}
}
</pre>

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

IMPORTANT: exclude node_modules/ subfolder from auto-sync to remote folder (whatever system you use for that).

For Typescript compilation we also need to set up <code>rollup.config.mjs</code> and <code>tsconfig.json</code> on the root folder.

'''rollup.config.mjs'''
<pre>
import typescript from '@rollup/plugin-typescript';

export default {
input: 'src/<yourgamename>.ts',
output: {
file: 'modules/js/Game.js',
format: 'es',
sourcemap: false,
inlineDynamicImports: true,
},
plugins: [
typescript({
tsconfig: './tsconfig.json',
}),
],
treeshake: false,
};
</pre>

'''tsconfig.json'''
<pre>
{
"compilerOptions": {
"target": "ES2020",
"module": "ES2022",
"moduleResolution": "node",
"lib": ["dom", "esnext"],
"sourceMap": false,
"rootDir": "src"
},
"include": [
"*.d.ts",
"src/**/*.d.ts",
"src/**/*.ts"
]
}
</pre>

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

Note: if you're using SFTP and have "bga-framework.d.ts" in the ignore list - remove it and resync. You will need this file.

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look at [https://studio.boardgamearena.com/projects castlecombo] code for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/yourgamename.d.ts'''

<pre>
interface YourGameNamePlayer extends Player {
cards: Card[]; // any information you add on each result['players']
}

interface YourGameNameGamedatas extends Gamedatas<YourGameNamePlayer> {
// Add here variables you set up in getAllDatas
discardedCards: { [row: number]: Card[] };
remainingCardsInDecks: { [row: number]: number };
tableCards: { [row: number]: Card[] };
}
</pre>
Not: the Generic typing is optional.

'''src/yourgamename.ts'''

<pre>
class Game {

public bga: Bga;
private gamedatas: YourGameNameGamedatas;

constructor(bga: Bga<YourGameNameGamedatas>) {
this.bga = bga;
}

public setup(gamedatas: YourGameNameGamedatas) {
this.gamedatas = gamedatas;
this.setupNotifications();
}
public setupNotifications() {}
}
</pre>

Don't forget to sync the bga-framework.d.ts from your FTP folder regularly to get the last version.

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.

Example:
<pre>
@use 'variables' as v;

/* the other files */
@use "./Animations";
@use "./Board";

#ebd-body {
background-image: url(img/woodbg.jpg);
background-repeat: repeat;
}
@each $key, $val in v.$colors-list {
.fgcolor#{$key} {
color: #{$val};
}

</pre>

Your SCSS code can be (should be) splitted in multiple files, for example:

'''variables.scss'''
<pre>
$colors-list: (
_6cd0f6: #6cd0f6, // blue
_ef58a2: #ef58a2, // pink
_ffcc02: #ffcc02, // yellow
_a0d28c: #a0d28c // green
);
</pre>

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continuously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup standard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Make sure that your sftp.json file has a "watcher" section to detect and upload changes made outside of the VSCode IDE.

<pre>
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
</pre>

=== Exclusions from auto-upload ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To have a code completion for framework classes, dojo, stock, etc, you'll need to make sure bga-framework.d.ts file is added to your tsconfig.

== Using the new libs ==
To use the new front libs (bga-autofit, bga-score-sheet, ...), it's recommended to created a dedicated file that will be responsible of all imports, than you'll import when you need it

'''libs.ts'''
<pre>
import type { BgaAnimations as BgaAnimationsType } from "../bga-animations";
import type { BgaCards as BgaCardsType } from "../bga-cards";

const BgaAnimations: typeof BgaAnimationsType = await globalThis.importEsmLib('bga-animations', '1.x');
const BgaCards: typeof BgaCardsType = await globalThis.importEsmLib('bga-cards', '1.x');

export { BgaAnimations, BgaCards };
</pre>

Then you can use them in your files using import:
<pre>
import { BgaCards } from './libs';
export class MyCardManager extends BgaCards.Manager<Card> { ... }
</pre>

For class property typings, use:
<pre>
public animationManager: InstanceType<typeof BgaAnimations.Manager>;

// in your setup:
this.animationManager = new BgaAnimations.Manager({ ... });
</pre>

If you need to load old libs, you can do it this way:
<pre>
const [Counter, Stock] = await importDojoLibs(["ebg/counter", "ebg/stock"]);

export { Counter, Stock };
</pre>

== migrating from old way (ES5 build to gamename.js) ==

the new setup described in this page use explicit import/export that were not used before. But we don't need to explicitely list all files anymore.

For example, if you have a file for MyCardManager and a file for MyGame, you'll need to do this:

'''MyCardManager.ts'''
<pre>
export class MyCardManager { ... }
</pre>

'''MyGame.ts'''
<pre>
import { MyCardManager } from "./MyCardManager";

export class Game implements Bga {
public cardManager: MyCardManager;
</pre>

== Browser console info ==

Using ES modules, your game object is no longer merged into the <code>gameui</code> global. Instead, your game object is available as <code>gameui.GameModule</code>.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless
* https://github.com/NevinAF/bga-ts-template

[[Category:Studio]]

I wish I knew this when I started

2026-02-01T14:57:39Z

Vagabond: Update browser console access for module-based games

This page contains most "I wish I knew this before..." moments (in regards to BGA studio game development). One line per statement please with doc references. Docs link can be outside of BGA wiki.
Most of this is already documented on BGA wiki in details, search wiki or google for generic subject to find more info.

* Browser caches images and css, to force re-cache use Ctrl+F5 or Ctrl+Shift+R, and sometimes it's not enough so go to the web console > Network > check "disable cache"
* Browser has powerful embeded dev tools for inspection of dom, css and js, you can debug js right in browser (F12)
* You don't have to login with another dev account to play test the game under development, little colored arrows on studio player panel switch between test accounts
* You can run PHP functions from chat
* You can change style of elements (css) depending on their parent, sibling or other properties of the element
* You cannot save php state in global variables between actions, all data has to be stored in db
* Ajax actions in BGA do not use the traditional request-response model of a normal application. The ajax response does not contain any payload and instead you must send a notification ($this->notify->all) to communicate the response to appropriate players.
* Almost every change you make to the game via sending notifications must also be included in getAllDatas (e.g., in case a player loads/refreshes the game during the middle of play).
* You can easily scale elements by using "em" as unit for width/height and varying font-size, i.e. .meeple {width: 2em;height: 2.5em;font-size: 20px;}
* You can access your javascript methods / properties in the browser console using '''''gameui.GameModule.<yourMethod>''''' (or '''''gameui.<yourMethod>''''' for older games not using JS modules, i.e. not using <code>modules/js/Game.js</code>)
* To interactively debug JS issues you can put '''''debugger;''''' statement in your code, enable dev tools (F12) and reload. It will hit breakpoint.
* To quickly try a fix you can edit css, js and html directly in browser dev tool window, no reload required (just don't forget to copy it back to your code after)
* To spell check all your translatable strings use Project Check from control panel - it will generate all strings, you can cut & paste this in online spell checker (or just use Firefox - it has embedded spell checker).
* To remove inline style property from dom node $(token).style.removeProperty("position"); or dojo.style('token', 'position', null);

[[Category:Studio]]

Game interface logic: Game.js

2026-01-20T13:35:45Z

Vagabond: added a "bga." where it was needed

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

'''Note:''' this file is now named Game.js, located in the modules/js directory. If you see it named yourgamename.js in the root dir, it's the legacy usage. In the legacy usage, the declaration is a bit different, as it uses define and declare to instanciate a JS object, while the new way exports a class (using ES Modules).
The new class doesn't extends gameui, so if you need to access some things from gameui that don't exist in the sub-components described above, you must use this.gameui.xx.

== Framework sub-components ==
The framework is now split into multiple sub-components to group the related functions : statusBar, sounds, gameArea, playerPanels, images, userPreferences, players, actions, notifications, dialogs. All are available in the bga object sent to the constructor (or in this.bga for the legacy way).

To make it accessible on the Game class, make it a property like this:
<pre>
constructor(bga){
this.bga = bga;
</pre>
In <mygamename>.js (the obsolete filename), this.bga is already set.

== 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. <i>The function is optional, and not needed if you use JS State classes.</i>
* '''onLeavingState''': this method is called when leaving a game state. <i>The function is optional, and not needed if you use JS State classes.</i>
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a MULTIPLE_ACTIVE_PLAYER state, it will be called when another player has become inactive. <i>The function is optional, and not needed if you use JS State classes.</i>
* ''(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.players.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 MULTIPLE_ACTIVE_PLAYER 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.players.isCurrentPlayerActive()) with (!this.players.isCurrentPlayerSpectator())
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 ACTIVE_PLAYER state this method is called before the onEnteringState state.
In MULTIPLE_ACTIVE_PLAYER 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]]

== States ==

=== JS State classes ===
To split the code of the Game class, you can create dedicated classes for each state you handle on the front side (some states like NextPlayer don't need to be handled on the JS side).

'''this.bga.states.register(stateIdOrName: string|number, stateClass: Object): void'''

This method links a state class to a state name. It should be used in the Game constructor like this:
<pre>
// Declare the State classes
this.bga.states.register('PlayerTurn', new PlayerTurn(this, this.bga));
</pre>

When a state class is declared like this, the framework will call its onEnteringState... functions automatically. Example of JS State class:
<pre>
class PlayerTurn {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

/**
* This method is called each time we are entering the game state. You can use this method to perform some user interface changes at this moment.
*/
onEnteringState(args, isCurrentPlayerActive) {
}

/**
* This method is called each time we are leaving the game state. You can use this method to perform some user interface changes at this moment.
*/
onLeavingState(args, isCurrentPlayerActive) {
}

/**
* This method is called each time the current player becomes active or inactive in a MULTIPLE_ACTIVE_PLAYER state. You can use this method to perform some user interface changes at this moment.
* on MULTIPLE_ACTIVE_PLAYER states, you may want to call this function in onEnteringState using `this.onPlayerActivationChange(args, isCurrentPlayerActive)` at the end of onEnteringState.
* If your state is not a MULTIPLE_ACTIVE_PLAYER one, you can delete this function.
*/
onPlayerActivationChange(args, isCurrentPlayerActive) {
}

// put custom functions only use on this state here
}
</pre>

'''this.bga.states.getCurrentMainStateName(): string;'''

Get the current main state name (ignoring private states)

'''this.bga.states.getCurrentPlayerStateName(): string;'''

Get the current player state name (private state name if there is one)

'''this.bga.states.logger: Function'''

You can write <code>this.bga.states.logger = console.log</code> to show debug information about state changes in the console. Remove before going to production!

'''this.bga.states.getStateClass(stateName: string): Object'''

Get a state class (instance) by state name.

'''this.bga.states.getCurrentMainStateClass(): Object;'''

Get the current main state class (instance) (ignoring private states)

'''this.bga.states.getCurrentPlayerStateClass(): Object;'''

Get the current player state class (instance) (private state if there is one)

'''this.bga.states.getStateClasses(): Object[];'''

Returns the registered state classes (instances)

===Client states===

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

Client states don't have a matching PHP class. They can be used with JS State classes, as long as the stateName declared in setClientState matches the registered JS State class.

'''this.bga.states.setClientState(stateName: string, args: Object): void;'''

Example:
this.bga.states.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.bga.states.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location for card {$card_number}"),
args: { card_number: 5 },
});

'''this.bga.states.restoreServerGameState(): void;'''

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

'''this.bga.states.isOnClientState(): boolean;'''

Returns if the current state is a client state

== Dojo framework ==

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

To implement a game, you don't need to use the outdated Dojo framework, as vanilla JS is now able to do the same things. Some example of Dojo will stay on this page to help you read old games code.

== 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.bga.players.getCurrentPlayerId(): number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)

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

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.bga.players.isCurrentPlayerSpectator() || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

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

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

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

'''this.bga.players.getFormattedPlayerName(playerId): string'''
Get the HTML code to display the player name, in bold, with color (and color_back if needed)

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

'''this.bga.players.getPlayer(playerId): object'''
Return the player data stored in gamedatas.players. Can be undefined, if the player isn't at this table (spectator).

'''this.bga.players.getActivePlayer(): object'''
Same as getPlayer for the active player.

'''this.bga.players.getCurrentPlayer(): object'''
Same as getPlayer for the current player.

== Accessing and manipulating the DOM ==

=== Main game area ===

'''this.bga.gameAre.getElement(): HTMLElement'''

Returns the div of the game area to put the game template into.

'''Example'''
Add this piece of code in your JS file, at the beginning of the setup function, to set the template :

<pre>
const html = `<div>
<div class="round-counter">${_('Round')} ${gamedatas.currentRound}/${gamedatas.totalRound}</div>
<div>...anything else in your game template...</div>
</div>`;
this.bga.gameAre.getElement().insertAdjacentHTML('beforeend', html);
</pre>

=== 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.bga.gameui.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.bga.gameui.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.bga.gameui.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.bga.gameui.format_string(name: string, args: object): string'''

This bga function just substitute variables in a string, i.e.
<pre>
var div = this.bga.gameui.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.bga.gameui.format_string_recursive'''

This bga function is similar to this.gameui.bga.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.bga.gameui.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.bga.gameui.placeOnObject( "my_new_token", "overall_player_board_"+this.bga.players.getCurrentPlayerId() );

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

'''this.bga.gameui.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.bga.gameui.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.bga.gameui.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 ==
<big>A new lib for animations has been added to the framework: '''[[BgaAnimations]]'''. ''We recommend to use it instead of the animations listed above.''</big>

'''this.bga.gameui.bgaAnimationsActive()'''

Function to know if animations should be played. Animations should not be played in instantaneousMode (fast-replay mode), or if the tab is not displayed in the browser.
Returns a boolean saying if animations should be played.

<pre>
if (this.bga.gameui.bgaAnimationsActive()) {
// play an animation
} else {
// just apply the end situation of the animation
}
</pre>

Note: if you use framework animation functions listed above, they already handle this check so you don't need it. It's useful if you write custom 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.bga.gameui.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.bga.gameui.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.bga.gameui.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.bga.gameui.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.bga.gameui.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.bga.gameui.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

Note: slideTemporaryObject triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.slideTemporaryObject(...).promise</code>.

===Destroy===
'''this.bga.gameui.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

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.bga.gameui.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.bga.gameui.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

Note: slideToObjectAndDestroy triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.slideToObjectAndDestroy(...).promise</code>.

'''this.bga.gameui.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''Animation'''

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

Example:
<pre>
this.bga.gameui.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

Note: fadeOutAndDestroy triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.fadeOutAndDestroy(...).promise</code>.

===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.bga.gameui.rotateTo(node: string | Element, degree: number): Animation'''

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 '''this.bga.gameui.rotateInstantTo''' with same signature which does not animate

Note: rotateTo triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.rotateTo(...).promise</code>.

===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.bga.gameui.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).

'''this.bga.gameui.bgaPlayDojoAnimation(anim)'''
* anim - the dojo animation
Play a dojo animation and returns a promise resolved when it ends.

Examples:
<pre>
const anim = this.bga.gameui.slideToObject(`disc_${x}${y}`, `square${x}_${y}`);
await this.bga.gameui.bgaPlayDojoAnimation(anim);
</pre>
<pre>
const anim = dojo.fx.chain([
dojo.fadeOut( { node: discDiv } ),
dojo.fadeIn( { node: discDiv } ),
]);
await this.bga.gameui.bgaPlayDojoAnimation(anim);
</pre>

== 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.bga.actions.performAction('actPlayPet', {card: id});
} else {
this.bga.dialogs.showMoveUnauthorized();
}
}
</pre>

'''this.bga.gameui.connect(element: ElementOrId, event: string, method: eventHandler): void'''

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

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

Or you can use an in-place handler

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

Note that this function stores the connection handler. That is the only real difference between '''this.bga.gameui.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.bga.gameui.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.bga.gameui.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.bga.gameui.connectClass('pet', 'onclick', 'onPet');
'''this.bga.gameui.disconnect(element: ElementOrId, event: string): void'''

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

this.bga.gameui.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.bga.gameui.disconnectAll(): void'''

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

this.bga.gameui.disconnectAll();

=== Actions ===

'''this.bga.actions.performAction(action: string, args?: object, options: { lock: boolean, checkAction: boolean, checkPossibleActions?: boolean, ignoreDefaultErrorHandler?: boolean }): Promise<void>'''

Triggers an asynchronous action call in the php backend. Check more of what actions and arguments are possible in [[Main_game_logic:_Game.php#Actions_(autowired)]] docs.

This method must be used to send a player's 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.

Parameters:

* 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, can be undefined/omitted if action has no parameters. Note: the following arg names are forbidden : <code>$args / $activePlayerId/ $active_player_id / $currentPlayerId / $current_player_id</code> to not mess with [https://en.doc.boardgamearena.com/State_classes:_State_directory#Functions_act* magic params].
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.
** lock: (true by default) locks the user interface before any other action can be executed, that prevents user clicking on more buttons while this action is in progress. Set to false if you want to handle locking by yourself.
** checkAction: (true by default) check that action specified by "action" parameter in list of possible actions and user is active, only set to false in rare cases when some special out of turn actions are allowed.

Important: this is asynchronous action, this means you should not be doing anything after this line of code except returning; If you want to do something after the call is resolved, use promise handlers - catch and then, see examples below.

Example of a standard call without args:
this.bga.actions.performAction('pass');

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

Example of a call without checking action (because player is inactive in a multiactive state):
this.bga.actions.performAction('actChangeMind', {}, { checkAction: false, checkPossibleActions: true });

Example of a call without lock (because of a special action not directly related to the game flow):
this.bga.actions.performAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with an array of ids (to be used with #[IntArrayParam]) :
this.bga.actions.performAction('actPlayCards', { ids: this.selectedCardIds });

Example of call with aJSON object (to be used with #[JsonParam], note the "stringify") :
this.bga.actions.performAction('actPlanComplexStuff', { answer: JSON.stringify(this.theJsonObject) });

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

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

Technical note:
* This is a combination of checkAction and ajaxcall, returning a Promise which resolves when ajaxcall ends.
* The function return void promise - the php callback cannot return any result, any results must be handled via the notification mechanism if needed
* In case there is an error - error message itself handled by framework, you can use error in catch({ message, args }) but you should not be showing it - this is done already, except if you've set ignoreDefaultErrorHandler: true
* If you migrate from this.bgaPerformAction and are using catch on the promise, the result will now be { message, args } instead of args, allowing you to get the args you sent in the exception.

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

''Note: this.bga.actions.performAction 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.bga.actions.performAction''' 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.bga.actions.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

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

'''this.bga.actions.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.bga.actions.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.bga.actions.checkAction, this function does NOT take interface locking into account

* if action is not in list of 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.bga.actions.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.bga.gameui.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if the 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.bga.actions.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.bga.gameui.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.

'''this.bga.notifications.setupPromiseNotifications(params = undefined)'''
* params - the call parameters, by default { prefix: 'notif_', minDuration: 500, minDurationNoText: 1, logger: null, ignoreNotifications: [], onStart: undefined, onEnd: undefined, }.
Auto-detect all notifications declared on the game object (functions starting with `notif_`) and register them with dojo.subscribe.

Registered notifications will be synchronous and will have a minimum duration (if animations are active, by default 500ms with text and 1ms without).

If the notification function returns a Promise, the notification will end when the promise AND the minimum durations are over.
If the notification function does not return a promise, it is considered as already resolved as soon as the minimum durations are over.

In case of a notification function returning a Promise, the dev is responsible to make it resolve instantaneously if animations are not active.

See `bgaAnimationsActive` to know if animations are active : https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Animations

See `bgaPlayDojoAnimation` to handle dojo animations with promises : https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Animation_Callbacks

<pre>
setupNotifications: function() {
this.bga.notifications.setupPromiseNotifications();
},
notif_playedCard: async function(args) {
await this.getPlayerTable(args.playerId).playCard(args.card);
}
</pre>

Example of setting custom values for all params :
<pre>
setupNotifications: function() {
this.bga.notifications.setupPromiseNotifications({
prefix: 'notif_', // default is 'notif_'
minDuration: 1200, // for longer animations (500 by default)
minDurationNoText: 1,
handlers: [this.notificationsManager], // if you write your notif function in a subclass instead of this (default this)
logger: console.log, // show notif debug informations on console. Could be console.warn or any custom debug function (default null = no logs)
ignoreNotifications: ['updateAutoPlay'], // the notif_updateAutoPlay function will be ignored by bgaSetupPromiseNotifications. You'll need to subscribe to it manually
onStart: (notifName, msg, args) => $('pagemaintitletext').innerHTML = `${_('Animation for:')} ${msg}`,
onEnd: (notifName, msg, args) => $('pagemaintitletext').innerHTML = '',
});
}
</pre>

'''this.bga.gameui.wait(delay)'''
* delay - the time to wait, in milliseconds
Return a Promise that resolves at the end of a given number of ms. If animations are not active, resolve instantaneously.

<pre>
await this.bga.gameui.wait(500); // wait 500ms before continuing in an async function
</pre>

=== Subscribe to notifications manually ===

'''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 "notify->all" or "notify->player" 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->notify->all( "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|Notify->all]] 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 ===

NOTE: With the new <code>_private</code> arg in $this->notify->all, you should not need to ignore notifications anymore. See https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Sending_private_data_to_some_players for the new way of handling private data in notifications.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

<u>If you need this function and you are in the Dev Discord, please read [https://discord.com/channels/753304735615811584/1448596273081876530/1448596273081876530 This thread] that might avoid the usage of '''setIgnoreNotificationCheck.'''</u>

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.bga.gameui.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => notif.args.player_id == this.bga.players.getCurrentPlayerId() );
</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]].

=== Handle manually 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.bga.gameui.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.bga.gameui.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

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

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

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

You can also manually call this.bga.gameui.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.bga.gameui.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.bga.players.getCurrentPlayerId()) /* or any other condition */ )</pre>

then you CANNOT do

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

as, when the ignored check passes, the notification handler, in which `this.bga.gameui.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.bga.gameui.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
$this->notify->all( '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>
$this->notify->all( '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.bga.gameui.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.bga.gameui.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.bga.gameui.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.bga.gameui.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.bga.gameui.addTooltip.
this.bga.gameui.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

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

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

== Banners ==

The framework comes with predefined banners.

=== Last turn banner ===
When someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.bga.gameArea.addLastTurnBanner(message?: string, args?: any): void;'''

If message is unset, default is "This is the last turn!". For args example, see the addWinConditionBanner example that works the same way.

Example:
<pre>
this.bga.gameArea.addLastTurnBanner(
_('This is the last turn! (deck is empty)')
);
</pre>
[[File:Last turn banner example.png|center]]

If the action triggering the last turn banner is cancelled, you can remove the banner by using

'''this.bga.gameArea.removeLastTurnBanner(): void;'''

=== Win condition banner ===
When the game has multiple win conditions, use this function to display a message detailing which win condition was reached.

'''this.bga.gameArea.addWinConditionBanner(message?: string, args?: any): void;'''

Example:
<pre>
const winConditionText = _('${player_name} reached the Victory space of the Fame track and wins the game by being the most celebrated Monster!');
this.bga.gameArea.addWinConditionBanner(
winConditionText,
{ 'player_name': this.bga.players.getFormattedPlayerName(winnerId) }
);
</pre>
[[File:Win condition banner example.png|center]]

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure the player get the message. For example, explain why the player cannot do an action he can usually do when he clicks an element, if you don't need the PHP to validate the possibility.

'''this.bga.dialogs.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 disappears 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.bga.gameui.format_string_recursive(notif.log, notif.args);
this.bga.dialogs.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.bga.dialogs.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

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

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.bga.dialogs.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.bga.dialogs.confirmation(message: string): Promise<boolean>'''

* message - message will be shown to user, use _() to translate
NOTE: this is an async function, you must handle the consequence in the result of the promise

How to display a confirmation dialog:
<pre>
this.bga.dialogs.confirmation(_("Are you sure you want to bake a pie?")).then(result => {
if (result) {
this.bakeThePie();
}
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

If you're migrating from this.confirmationDialog, you'll need to move the callback function into the <code>then</code> as it's now Promise-based

=== Multiple choice dialog ===

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

'''this.bga.dialogs.multipleChoice(message: string, choices: string[]): Promise<string | null>'''
* message - message will be shown to user, use _() to translate
* choices - array of choices

NOTE: this is an async function, you must handle the consequence in the result of the promise. If the user cancels, it returns null.

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

If you're migrating from this.multipleChoiceDialog, you'll need to move the callback function into the <code>then</code> as it's now Promise-based

=== 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.gameui.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->notify->all( "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->notify->all( "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 translatable 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.bga.gameui.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.bga.gameui.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.bga.gameui.notifqueue.setSynchronous('displayScoring', duration );
this.bga.gameui.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.bga.gameui.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.bga.gameui.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.bga.gameui.format_string_recursive(notif.args.text, notif.args.args);
this.bga.gameui.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 ==

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

'''this.bga.playerPanels.getElement(player_id: number): HTMLElement'''

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

'''Example'''
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
const html = `<div class="cp_board">
<div id="stoneicon_p${player.id}" class="gmk_stoneicon gmk_stoneicon_${player.color}"></div><span id="stonecount_p${player.id}">0</span>
</div>`;
this.bga.playerPanels.getElement(player_id).insertAdjacentHTML('beforeend', html);
}
</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 change the content of the <code>html</code> variable when "player_id" is different than "this.bga.players.getCurrentPlayerId()".

=== Adding a player panel for an automata ===

'''this.bga.playerPanels.addAutomataPlayerPanel(id: number, name: string, params: Object): void'''

The id is the automata id, used to setup the player panel score counter and getPlayerPanelElement. 0 or negative value is recommended, to avoid conflict with real player ids.

Parameters:
*id: the automata id, used to setup the player panel score counter and getPlayerPanelElement. 0 or negative value is recommended, to avoid conflict with real player ids.
*name: the name of the automata
*params: object optionally containing one or more of the following:
**color: string - the automata player color (default black)
**iconClass: string - the class, or list of classes separated by spaces, to apply to the player picture.
**score: number - the automata score (default undefined, will display '-')

Example from Glow, with the automata Tom when playing solo :
<pre>
this.bga.playerPanels.addAutomataPlayerPanel(0, 'Tom', {
iconClass: 'tom-avatar',
score: gamedatas.tom.score,
});
</pre>

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

'''this.bga.gameui.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.bga.gameui.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

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

Enable all player panels that has been disabled before.

=== Player order ===

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

'''this.bga.playerPanels.getScoreCounter(player_id: number): Counter'''

Returns the score counter on the player panel.

To create other counters on the player panel, please use the "ebg/counter" library, documented at [[Counter]].

== 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 with the Game.js file:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x');
const [Counter, Stock] = await importDojoLibs(["ebg/counter", "ebg/stock"]);
</pre>

Example with the legacy way if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.bga.gameui.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

'''''Deprecated, use [https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar this.bga.statusBar.addActionButton] instead'''''

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( stateName, args ) {
if (this.players.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.bga.statusBar.addActionButton(_('Give selected cards'), () => this.onGiveCards() );
this.bga.statusBar.addActionButton(_('Pass'), () => this.actions.performAction('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.

===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.bga.gameui.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(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.bga.gameui.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.bga.gameui.addActionButton('play_button_id', _('Play 1 to 3 cards'), () => this.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.bga.gameui.addActionButton( 'commit_button', _('Confirm'), () => this.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 at the root 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. Images in a subfolder of img are NOT preloaded by default.

'''this.bga.images.dontPreloadImage(image_file_name: string)'''

'''this.bga.images.dontPreloadImages(image_file_names: string[])'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory. dontPreloadImages is the same for multiple images at once.

Examples of use:
<pre>
// don't preload a particular image
this.bga.images.dontPreloadImage( 'cards.png' );

// don't preload a list of unused images (gamedatas.clans contains the number of the clans used in this game).
this.bga.images.dontPreloadImages([1,2,3,4,5,6].filter(clan => !gamedatas.clans.include(clan)).map(clan => `clan${clan}.png`));
</pre>

'''this.bga.images.preloadImage(image_file_name: string)'''

'''this.bga.images.preloadImages(image_file_names: string[])'''

Opposite of dontPreloadImage, useful only for images that are not in the root img folder
Example of use:
<pre>
// preload a particular image
if (gamedatas.expansionActive) {
this.bga.images.preloadImages(['expansion/board.jpg', 'expansion/new-cards.jpg']);
}
</pre>

==Sounds ==

'''this.bga.sounds.load(id: string, label: string, fileName: string = undefined): void'''

Load a sound and register its id. Filename is without the extension. If fileName is unset, it will use the same as the id.

In any case, the sound should be placed on your img folder and exist bothe with the mp3 and ogg format/extension.

Examples :
<pre>
this.bga.sounds.load('play'); // will load play.ogg / play.mp3 in the img dir, and will be playable with id `play`
this.bga.sounds.load('claw', 'smash'); // will load smash.ogg / smash.mp3 in the img dir, and will be playable with id `claw`
</pre>

'''this.bga.sounds.play(id: string): void'''
Play a sound by its id, loaded in the setup with ''this.sounds.load''

Examples :
<pre>
this.bga.sounds.play('play');
this.bga.sounds.play('claw');
</pre>

'''this.bga.gameui.disableNextMoveSound(): void'''
Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

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

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

== Status bar ==

=== Status bar text ===

;'''this.bga.statusBar.setTitle(title: string, args?: object)'''
Update the page title (aka status bar prompt). Can handle ${you} and ${actplayer} and any other var you would pass as args.
<pre>
if (args.mandatory_card_name) {
const mandatoryCardTitle = this.bga.players.isCurrentPlayerActive() ? _('${you} must take ${mandatory_card_name}') : _('${actplayer} must take ${mandatory_card_name}');
this.bga.statusBar.setTitle(mandatoryCardTitle, args);
}
</pre>
As opposed to <code>updatePageTitle</code>, it doesn't trigger the call <code>onUpdateActionButtons</code>.

;'''this.bga.gameui.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)

<b>DEPRECATED:</b> use this.bga.statusBar.setTitle instead.

=== Status bar buttons ===
;'''this.bga.statusBar.addActionButton(label: string, callback: Function, params?: object): HTMLButtonElement'''

Parameters:
*label: the label to be shown, can be html. If label if used pass traslated string, i.e. _('Yes')
*callback: function to call on click, cannot be method name it has to be function
*params: object optionally containing one of more of the following:
**color: string - can be <code>primary</code> (default) (blue), <code>secondary</code> (gray), <code>alert</code> (red)
**id: string - is the dom element id to set. If null/undefined, the button will not have an id, but you can still manipulate it by storing the reference to the DOM Element returned by the function
**classes: string|string[] - i.e <code>'disabled blinking'</code> or <code>['disabled', 'blinking']</code>.
**destination: ElementOrId - the DOM Element to add the button to. If not specified, will add it to the status bar.
**title: string - plain text description of the label. Should be set when the button label is an icon, for accessibility.
**disabled: boolean - makes the button disabled. Will prevent the callback to be executed
**tooltip: string - the tooltip of the button
**confirm: string | Function - the confirm message to display before triggering the callback, if set (or function handler, see example below).
**autoclick: boolean if the button should be auto clicked after a small delay (for Confirmation buttons).

Example of a standard call without params:
this.bga.statusBar.addActionButton(_('Pass'), () => this.bga.actions.performAction('actPass', {}));

Example of a standard call with params:
this.bga.statusBar.addActionButton(_('Pass'), () => this.bga.actions.performAction('actPass', {}), {
id: 'my_button',
color: 'secondary',
classes: 'my-outline-class'
disabled: true,
tooltip: _('You cannot pass'),
confirm: _('Are you sure to pass?'),
});

Note: the confirm parameter can be a string or a function that returns a string or null

Example of a standard call with params:
this.bga.statusBar.addActionButton(_('Discard Selected Cards'), () => this.bga.actions.performAction('actDiscard', { cardIds: this.getSelectedCardIds().join(',') }), {
confirm: () => {
if (this.getSelectedCardIds().length === 0) { // no card is selected, show the warning
return _('Are you sure you don't want to discard any cards?');
} else { // cards are selected, do not show the warning
return null;
}
}
});

Example of confirm button with autoclick animation:
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: true
});
// if you have a user preference to auto-confirm
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: this.bga.userPreferences.get(100) == 1, // adapt to your user preference id and values
});

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

==User preferences ==
'''this.bga.userPreferences.get(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.bga.userPreferences.set(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.bga.userPreferences.onChange'''

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

Example:<pre>
// in your Game constructor
this.bga.userPreferences.onChange = (pref_id, pref_value) => this.myGamePreferenceChanged(pref_id, pref_value);

myGamePreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

'''this.bga.userPreferences.toggleVisibility(pref_id, visible)'''

Hide or show a user preference.

Example:<pre>
myGamePreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 101:
// if pref 101 is "Confirm moves" and 102 is "Countdown timer on confirm", we hide the countdown user preference when confirm moves is disabled.
this.bga.userPreferences.toggleVisibility(102, prefValue != 2);
break;
}
}
</pre>

== Including classes from external files ==
You can declare multiple classes in the Game.js file, as long as you export a Game class in the end.

If you want to split your code into multiple js files, export the classes of the file using <code>export class PlayerManager {...}</code>. You can export multiple classes from the same file file that way.

Then you can import the class in the Game.js file using <code>import { PlayerManager, PlayerTable } from "./PlayerManager.js";</code> at the top of the file.

==Other useful stuff ==

;'''this.bga.gameui.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.bga.gameui.bRealtime
:Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

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

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

;this.bga.gameui.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 the bga-animations, bga-cards, bga-dice libs and <i>this.bga.gameui.slideToObject()</i> and similar 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.

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

[[Category:Studio]]

Game interface logic: Game.js

2026-01-20T13:24:45Z

Vagabond: addActionButton examples include args object to bgaPerformAction to help delineate the settings object to addActionButton.

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

'''Note:''' this file is now named Game.js, located in the modules/js directory. If you see it named yourgamename.js in the root dir, it's the legacy usage. In the legacy usage, the declaration is a bit different, as it uses define and declare to instanciate a JS object, while the new way exports a class (using ES Modules).
The new class doesn't extends gameui, so if you need to access some things from gameui that don't exist in the sub-components described above, you must use this.gameui.xx.

== Framework sub-components ==
The framework is now split into multiple sub-components to group the related functions : statusBar, sounds, gameArea, playerPanels, images, userPreferences, players, actions, notifications, dialogs. All are available in the bga object sent to the constructor (or in this.bga for the legacy way).

To make it accessible on the Game class, make it a property like this:
<pre>
constructor(bga){
this.bga = bga;
</pre>
In <mygamename>.js (the obsolete filename), this.bga is already set.

== 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. <i>The function is optional, and not needed if you use JS State classes.</i>
* '''onLeavingState''': this method is called when leaving a game state. <i>The function is optional, and not needed if you use JS State classes.</i>
* '''onUpdateActionButtons''': called on state changes, in order to add action buttons to the status bar. Note: in a MULTIPLE_ACTIVE_PLAYER state, it will be called when another player has become inactive. <i>The function is optional, and not needed if you use JS State classes.</i>
* ''(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.players.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 MULTIPLE_ACTIVE_PLAYER 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.players.isCurrentPlayerActive()) with (!this.players.isCurrentPlayerSpectator())
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 ACTIVE_PLAYER state this method is called before the onEnteringState state.
In MULTIPLE_ACTIVE_PLAYER 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]]

== States ==

=== JS State classes ===
To split the code of the Game class, you can create dedicated classes for each state you handle on the front side (some states like NextPlayer don't need to be handled on the JS side).

'''this.bga.states.register(stateIdOrName: string|number, stateClass: Object): void'''

This method links a state class to a state name. It should be used in the Game constructor like this:
<pre>
// Declare the State classes
this.bga.states.register('PlayerTurn', new PlayerTurn(this, this.bga));
</pre>

When a state class is declared like this, the framework will call its onEnteringState... functions automatically. Example of JS State class:
<pre>
class PlayerTurn {
constructor(game, bga) {
this.game = game;
this.bga = bga;
}

/**
* This method is called each time we are entering the game state. You can use this method to perform some user interface changes at this moment.
*/
onEnteringState(args, isCurrentPlayerActive) {
}

/**
* This method is called each time we are leaving the game state. You can use this method to perform some user interface changes at this moment.
*/
onLeavingState(args, isCurrentPlayerActive) {
}

/**
* This method is called each time the current player becomes active or inactive in a MULTIPLE_ACTIVE_PLAYER state. You can use this method to perform some user interface changes at this moment.
* on MULTIPLE_ACTIVE_PLAYER states, you may want to call this function in onEnteringState using `this.onPlayerActivationChange(args, isCurrentPlayerActive)` at the end of onEnteringState.
* If your state is not a MULTIPLE_ACTIVE_PLAYER one, you can delete this function.
*/
onPlayerActivationChange(args, isCurrentPlayerActive) {
}

// put custom functions only use on this state here
}
</pre>

'''this.bga.states.getCurrentMainStateName(): string;'''

Get the current main state name (ignoring private states)

'''this.bga.states.getCurrentPlayerStateName(): string;'''

Get the current player state name (private state name if there is one)

'''this.bga.states.logger: Function'''

You can write <code>this.bga.states.logger = console.log</code> to show debug information about state changes in the console. Remove before going to production!

'''this.bga.states.getStateClass(stateName: string): Object'''

Get a state class (instance) by state name.

'''this.bga.states.getCurrentMainStateClass(): Object;'''

Get the current main state class (instance) (ignoring private states)

'''this.bga.states.getCurrentPlayerStateClass(): Object;'''

Get the current player state class (instance) (private state if there is one)

'''this.bga.states.getStateClasses(): Object[];'''

Returns the registered state classes (instances)

===Client states===

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

Client states don't have a matching PHP class. They can be used with JS State classes, as long as the stateName declared in setClientState matches the registered JS State class.

'''this.bga.states.setClientState(stateName: string, args: Object): void;'''

Example:
this.bga.states.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.bga.states.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location for card {$card_number}"),
args: { card_number: 5 },
});

'''this.bga.states.restoreServerGameState(): void;'''

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

'''this.bga.states.isOnClientState(): boolean;'''

Returns if the current state is a client state

== Dojo framework ==

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

To implement a game, you don't need to use the outdated Dojo framework, as vanilla JS is now able to do the same things. Some example of Dojo will stay on this page to help you read old games code.

== 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.bga.players.getCurrentPlayerId(): number'''
id of the player who is looking at the game. The player may not be part of the game (i.e. spectator)

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

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.bga.players.isCurrentPlayerSpectator() || typeof g_replayFrom != 'undefined' || g_archive_mode;
}

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

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

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

'''this.bga.players.getFormattedPlayerName(playerId): string'''
Get the HTML code to display the player name, in bold, with color (and color_back if needed)

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

'''this.bga.players.getPlayer(playerId): object'''
Return the player data stored in gamedatas.players. Can be undefined, if the player isn't at this table (spectator).

'''this.bga.players.getActivePlayer(): object'''
Same as getPlayer for the active player.

'''this.bga.players.getCurrentPlayer(): object'''
Same as getPlayer for the current player.

== Accessing and manipulating the DOM ==

=== Main game area ===

'''this.bga.gameAre.getElement(): HTMLElement'''

Returns the div of the game area to put the game template into.

'''Example'''
Add this piece of code in your JS file, at the beginning of the setup function, to set the template :

<pre>
const html = `<div>
<div class="round-counter">${_('Round')} ${gamedatas.currentRound}/${gamedatas.totalRound}</div>
<div>...anything else in your game template...</div>
</div>`;
this.bga.gameAre.getElement().insertAdjacentHTML('beforeend', html);
</pre>

=== 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.bga.gameui.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.bga.gameui.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.bga.gameui.format_block('jstpl_player_board', player ); // var jstpl_player_board = ... is defined in .tpl file
Note: result is trimmed

'''this.bga.gameui.format_string(name: string, args: object): string'''

This bga function just substitute variables in a string, i.e.
<pre>
var div = this.bga.gameui.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.bga.gameui.format_string_recursive'''

This bga function is similar to this.gameui.bga.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.bga.gameui.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.bga.gameui.placeOnObject( "my_new_token", "overall_player_board_"+this.bga.players.getCurrentPlayerId() );

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

'''this.bga.gameui.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.bga.gameui.slideToObjectPos'', since coordinates are calculated based on the center of objects.

'''this.bga.gameui.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 ==
<big>A new lib for animations has been added to the framework: '''[[BgaAnimations]]'''. ''We recommend to use it instead of the animations listed above.''</big>

'''this.bga.gameui.bgaAnimationsActive()'''

Function to know if animations should be played. Animations should not be played in instantaneousMode (fast-replay mode), or if the tab is not displayed in the browser.
Returns a boolean saying if animations should be played.

<pre>
if (this.bga.gameui.bgaAnimationsActive()) {
// play an animation
} else {
// just apply the end situation of the animation
}
</pre>

Note: if you use framework animation functions listed above, they already handle this check so you don't need it. It's useful if you write custom 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.bga.gameui.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.bga.gameui.slideToObject( "some_token", "some_place_on_board" ).play();
</pre>

'''this.bga.gameui.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.bga.gameui.slideToObjectPos( "some_token", "some_place_on_board", 0, 10 ).play();
</pre>

'''this.bga.gameui.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.bga.gameui.slideTemporaryObject( '<div class="token_icon"></div>', 'tokens', 'my_origin_div', 'my_target_div' );
</pre>

Note: slideTemporaryObject triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.slideTemporaryObject(...).promise</code>.

===Destroy===
'''this.bga.gameui.slideToObjectAndDestroy(mobile_obj: ElementOrId, target_obj: ElementOrId, duration?: number, delay?: number): Animation'''

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.bga.gameui.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.bga.gameui.slideToObjectAndDestroy( "some_token", "some_place_on_board", 1000, 0 );
</pre>

Note: slideToObjectAndDestroy triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.slideToObjectAndDestroy(...).promise</code>.

'''this.bga.gameui.fadeOutAndDestroy( node: string | Element, duration?: number, delay?: number):''' '''Animation'''

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

Example:
<pre>
this.bga.gameui.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

Note: fadeOutAndDestroy triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.fadeOutAndDestroy(...).promise</code>.

===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.bga.gameui.rotateTo(node: string | Element, degree: number): Animation'''

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 '''this.bga.gameui.rotateInstantTo''' with same signature which does not animate

Note: rotateTo triggers the animation, you don't have to call <code>.play()</code> on it. It returns an Dojo animation with an extra `promise` field, allowing you to do <code>await this.bga.gameui.rotateTo(...).promise</code>.

===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.bga.gameui.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).

'''this.bga.gameui.bgaPlayDojoAnimation(anim)'''
* anim - the dojo animation
Play a dojo animation and returns a promise resolved when it ends.

Examples:
<pre>
const anim = this.bga.gameui.slideToObject(`disc_${x}${y}`, `square${x}_${y}`);
await this.bga.gameui.bgaPlayDojoAnimation(anim);
</pre>
<pre>
const anim = dojo.fx.chain([
dojo.fadeOut( { node: discDiv } ),
dojo.fadeIn( { node: discDiv } ),
]);
await this.bga.gameui.bgaPlayDojoAnimation(anim);
</pre>

== 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.bga.actions.performAction('actPlayPet', {card: id});
} else {
this.bga.dialogs.showMoveUnauthorized();
}
}
</pre>

'''this.bga.gameui.connect(element: ElementOrId, event: string, method: eventHandler): void'''

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

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

Or you can use an in-place handler

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

Note that this function stores the connection handler. That is the only real difference between '''this.bga.gameui.connect''' and '''dojo.connect'''. If you plan to destroy the element you connected, you '''must''' call this.bga.gameui.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.bga.gameui.connectClass(cssClassName: string, event: string, method: eventHandler): void'''

Same as connect(), but for all the nodes set with the specified cssClassName.
this.bga.gameui.connectClass('pet', 'onclick', 'onPet');
'''this.bga.gameui.disconnect(element: ElementOrId, event: string): void'''

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

this.bga.gameui.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.bga.gameui.disconnectAll(): void'''

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

this.bga.gameui.disconnectAll();

=== Actions ===

'''this.bga.actions.performAction(action: string, args?: object, options: { lock: boolean, checkAction: boolean, checkPossibleActions?: boolean, ignoreDefaultErrorHandler?: boolean }): Promise<void>'''

Triggers an asynchronous action call in the php backend. Check more of what actions and arguments are possible in [[Main_game_logic:_Game.php#Actions_(autowired)]] docs.

This method must be used to send a player's 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.

Parameters:

* 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, can be undefined/omitted if action has no parameters. Note: the following arg names are forbidden : <code>$args / $activePlayerId/ $active_player_id / $currentPlayerId / $current_player_id</code> to not mess with [https://en.doc.boardgamearena.com/State_classes:_State_directory#Functions_act* magic params].
* options: options to tweak the call with some defaults. Default is <code>{ lock: true, checkAction: true }</code>.
** lock: (true by default) locks the user interface before any other action can be executed, that prevents user clicking on more buttons while this action is in progress. Set to false if you want to handle locking by yourself.
** checkAction: (true by default) check that action specified by "action" parameter in list of possible actions and user is active, only set to false in rare cases when some special out of turn actions are allowed.

Important: this is asynchronous action, this means you should not be doing anything after this line of code except returning; If you want to do something after the call is resolved, use promise handlers - catch and then, see examples below.

Example of a standard call without args:
this.bga.actions.performAction('pass');

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

Example of a call without checking action (because player is inactive in a multiactive state):
this.bga.actions.performAction('actChangeMind', {}, { checkAction: false, checkPossibleActions: true });

Example of a call without lock (because of a special action not directly related to the game flow):
this.bga.actions.performAction('actSetAutoBid', { alwaysBidUntil: 500 }, { lock: false, checkAction: false });

Example of call with an array of ids (to be used with #[IntArrayParam]) :
this.bga.actions.performAction('actPlayCards', { ids: this.selectedCardIds });

Example of call with aJSON object (to be used with #[JsonParam], note the "stringify") :
this.bga.actions.performAction('actPlanComplexStuff', { answer: JSON.stringify(this.theJsonObject) });

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

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

Technical note:
* This is a combination of checkAction and ajaxcall, returning a Promise which resolves when ajaxcall ends.
* The function return void promise - the php callback cannot return any result, any results must be handled via the notification mechanism if needed
* In case there is an error - error message itself handled by framework, you can use error in catch({ message, args }) but you should not be showing it - this is done already, except if you've set ignoreDefaultErrorHandler: true
* If you migrate from this.bgaPerformAction and are using catch on the promise, the result will now be { message, args } instead of args, allowing you to get the args you sent in the exception.

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

''Note: this.bga.actions.performAction 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.bga.actions.performAction''' 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.bga.actions.ajaxcall( '/mygame/mygame/actMyAction.html', { lock: true,
arg1: myarg1,
arg2: myarg2
}, this, (result)=>{} );
</pre>

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

'''this.bga.actions.checkPossibleActions(action: string): boolean'''

* this is independent of the player being active, so can be used instead of this.bga.actions.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.bga.actions.checkAction, this function does NOT take interface locking into account

* if action is not in list of 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.bga.actions.checkPossibleActions( "actMyAction" ) ) {
// Do the action
}
}

'''this.bga.gameui.checkLock(nomessage?: boolean): boolean'''

When using "lock: true" in ajax call you can use this function to check if the 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.bga.actions.checkAction(...), this is for advanced cases.

It will also show error unless nomessage is set to true

function onChangeMyMind( evt ) {
if( this.bga.gameui.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.

'''this.bga.notifications.setupPromiseNotifications(params = undefined)'''
* params - the call parameters, by default { prefix: 'notif_', minDuration: 500, minDurationNoText: 1, logger: null, ignoreNotifications: [], onStart: undefined, onEnd: undefined, }.
Auto-detect all notifications declared on the game object (functions starting with `notif_`) and register them with dojo.subscribe.

Registered notifications will be synchronous and will have a minimum duration (if animations are active, by default 500ms with text and 1ms without).

If the notification function returns a Promise, the notification will end when the promise AND the minimum durations are over.
If the notification function does not return a promise, it is considered as already resolved as soon as the minimum durations are over.

In case of a notification function returning a Promise, the dev is responsible to make it resolve instantaneously if animations are not active.

See `bgaAnimationsActive` to know if animations are active : https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Animations

See `bgaPlayDojoAnimation` to handle dojo animations with promises : https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Animation_Callbacks

<pre>
setupNotifications: function() {
this.bga.notifications.setupPromiseNotifications();
},
notif_playedCard: async function(args) {
await this.getPlayerTable(args.playerId).playCard(args.card);
}
</pre>

Example of setting custom values for all params :
<pre>
setupNotifications: function() {
this.bga.notifications.setupPromiseNotifications({
prefix: 'notif_', // default is 'notif_'
minDuration: 1200, // for longer animations (500 by default)
minDurationNoText: 1,
handlers: [this.notificationsManager], // if you write your notif function in a subclass instead of this (default this)
logger: console.log, // show notif debug informations on console. Could be console.warn or any custom debug function (default null = no logs)
ignoreNotifications: ['updateAutoPlay'], // the notif_updateAutoPlay function will be ignored by bgaSetupPromiseNotifications. You'll need to subscribe to it manually
onStart: (notifName, msg, args) => $('pagemaintitletext').innerHTML = `${_('Animation for:')} ${msg}`,
onEnd: (notifName, msg, args) => $('pagemaintitletext').innerHTML = '',
});
}
</pre>

'''this.bga.gameui.wait(delay)'''
* delay - the time to wait, in milliseconds
Return a Promise that resolves at the end of a given number of ms. If animations are not active, resolve instantaneously.

<pre>
await this.bga.gameui.wait(500); // wait 500ms before continuing in an async function
</pre>

=== Subscribe to notifications manually ===

'''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 "notify->all" or "notify->player" 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->notify->all( "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|Notify->all]] 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 ===

NOTE: With the new <code>_private</code> arg in $this->notify->all, you should not need to ignore notifications anymore. See https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Sending_private_data_to_some_players for the new way of handling private data in notifications.

'''setIgnoreNotificationCheck(notif_type: string, predicate: ((notif: Notif)=>boolean))'''

<u>If you need this function and you are in the Dev Discord, please read [https://discord.com/channels/753304735615811584/1448596273081876530/1448596273081876530 This thread] that might avoid the usage of '''setIgnoreNotificationCheck.'''</u>

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.bga.gameui.notifqueue.setIgnoreNotificationCheck( 'dealCard', (notif) => notif.args.player_id == this.bga.players.getCurrentPlayerId() );
</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]].

=== Handle manually 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.bga.gameui.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.bga.gameui.notifqueue.setSynchronous( 'cardPlayed' ); // wait time is dynamic
...
},

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

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

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

You can also manually call this.bga.gameui.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.bga.gameui.notifqueue.setIgnoreNotificationCheck( 'myNotif', (notif) => (notif.args.player_id == this.bga.players.getCurrentPlayerId()) /* or any other condition */ )</pre>

then you CANNOT do

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

as, when the ignored check passes, the notification handler, in which `this.bga.gameui.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.bga.gameui.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
$this->notify->all( '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>
$this->notify->all( '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.bga.gameui.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.bga.gameui.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.bga.gameui.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.bga.gameui.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.bga.gameui.addTooltip.
this.bga.gameui.addTooltipToClass( 'meeple', _('This is A Meeple'), _('Click to tickle') );

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

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

== Banners ==

The framework comes with predefined banners.

=== Last turn banner ===
When someone fulfills one of the end of the game conditions, so this is the last turn.

'''this.bga.gameArea.addLastTurnBanner(message?: string, args?: any): void;'''

If message is unset, default is "This is the last turn!". For args example, see the addWinConditionBanner example that works the same way.

Example:
<pre>
this.bga.gameArea.addLastTurnBanner(
_('This is the last turn! (deck is empty)')
);
</pre>
[[File:Last turn banner example.png|center]]

If the action triggering the last turn banner is cancelled, you can remove the banner by using

'''this.bga.gameArea.removeLastTurnBanner(): void;'''

=== Win condition banner ===
When the game has multiple win conditions, use this function to display a message detailing which win condition was reached.

'''this.bga.gameArea.addWinConditionBanner(message?: string, args?: any): void;'''

Example:
<pre>
const winConditionText = _('${player_name} reached the Victory space of the Fame track and wins the game by being the most celebrated Monster!');
this.bga.gameArea.addWinConditionBanner(
winConditionText,
{ 'player_name': this.bga.players.getFormattedPlayerName(winnerId) }
);
</pre>
[[File:Win condition banner example.png|center]]

== Warning messages ==

Sometimes, there is something important that is happening in the game and you have to make sure the player get the message. For example, explain why the player cannot do an action he can usually do when he clicks an element, if you don't need the PHP to validate the possibility.

'''this.bga.dialogs.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 disappears 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.bga.gameui.format_string_recursive(notif.log, notif.args);
this.bga.dialogs.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.bga.dialogs.showMessage(_('This is your own board silly!'), 'error');
return;
}
...
},
</pre>

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

Shows predefined user error that move is unauthorized now

<pre>
onPet: function(event) {
if (checkPet(event)==false) {
this.bga.dialogs.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.bga.dialogs.confirmation(message: string): Promise<boolean>'''

* message - message will be shown to user, use _() to translate
NOTE: this is an async function, you must handle the consequence in the result of the promise

How to display a confirmation dialog:
<pre>
this.bga.dialogs.confirmation(_("Are you sure you want to bake a pie?")).then(result => {
if (result) {
this.bakeThePie();
}
});
return; // nothing should be called or done after calling this, all action must be done in the handler
</pre>

If you're migrating from this.confirmationDialog, you'll need to move the callback function into the <code>then</code> as it's now Promise-based

=== Multiple choice dialog ===

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

'''this.bga.dialogs.multipleChoice(message: string, choices: string[]): Promise<string | null>'''
* message - message will be shown to user, use _() to translate
* choices - array of choices

NOTE: this is an async function, you must handle the consequence in the result of the promise. If the user cancels, it returns null.

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

If you're migrating from this.multipleChoiceDialog, you'll need to move the callback function into the <code>then</code> as it's now Promise-based

=== 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.gameui.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->notify->all( "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->notify->all( "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 translatable 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.bga.gameui.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.bga.gameui.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.bga.gameui.notifqueue.setSynchronous('displayScoring', duration );
this.bga.gameui.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.bga.gameui.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.bga.gameui.showBubble('meeple_2', _('Hello'), 0, 1000, 'pink_bubble');
</pre>

<pre>
notif_speechBubble(notif) {
var html = this.bga.gameui.format_string_recursive(notif.args.text, notif.args.args);
this.bga.gameui.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 ==

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

'''this.bga.playerPanels.getElement(player_id: number): HTMLElement'''

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

'''Example'''
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
const html = `<div class="cp_board">
<div id="stoneicon_p${player.id}" class="gmk_stoneicon gmk_stoneicon_${player.color}"></div><span id="stonecount_p${player.id}">0</span>
</div>`;
this.bga.playerPanels.getElement(player_id).insertAdjacentHTML('beforeend', html);
}
</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 change the content of the <code>html</code> variable when "player_id" is different than "this.bga.players.getCurrentPlayerId()".

=== Adding a player panel for an automata ===

'''this.bga.playerPanels.addAutomataPlayerPanel(id: number, name: string, params: Object): void'''

The id is the automata id, used to setup the player panel score counter and getPlayerPanelElement. 0 or negative value is recommended, to avoid conflict with real player ids.

Parameters:
*id: the automata id, used to setup the player panel score counter and getPlayerPanelElement. 0 or negative value is recommended, to avoid conflict with real player ids.
*name: the name of the automata
*params: object optionally containing one or more of the following:
**color: string - the automata player color (default black)
**iconClass: string - the class, or list of classes separated by spaces, to apply to the player picture.
**score: number - the automata score (default undefined, will display '-')

Example from Glow, with the automata Tom when playing solo :
<pre>
this.bga.playerPanels.addAutomataPlayerPanel(0, 'Tom', {
iconClass: 'tom-avatar',
score: gamedatas.tom.score,
});
</pre>

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

'''this.bga.gameui.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.bga.gameui.enablePlayerPanel(player_id:number): void'''

Enable a player panel that has been disabled before.

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

Enable all player panels that has been disabled before.

=== Player order ===

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

'''this.bga.playerPanels.getScoreCounter(player_id: number): Counter'''

Returns the score counter on the player panel.

To create other counters on the player panel, please use the "ebg/counter" library, documented at [[Counter]].

== 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 with the Game.js file:
<pre>
const BgaAnimations = await importEsmLib('bga-animations', '1.x');
const [Counter, Stock] = await importDojoLibs(["ebg/counter", "ebg/stock"]);
</pre>

Example with the legacy way if you are using "ebg.stock":
<pre>
define([
"dojo","dojo/_base/declare",
"ebg/stock" /// <=== we are using ebg.stock module
],
</pre>

== BGA Buttons ==

=== Basic Button ===

'''this.bga.gameui.addActionButton(id: string, label: string, method: string | eventhandler, destination?: string, blinking?: boolean, color?: string): void'''

'''''Deprecated, use [https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar this.bga.statusBar.addActionButton] instead'''''

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( stateName, args ) {
if (this.players.isCurrentPlayerActive()) {
switch( stateName ) {
case 'giveCards':
this.bga.statusBar.addActionButton(_('Give selected cards'), () => this.onGiveCards() );
this.bga.statusBar.addActionButton(_('Pass'), () => this.actions.performAction('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.

===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.bga.gameui.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(id, div, handler, bcolor, tooltip) {
if (typeof bcolor == "undefined") {
bcolor = "gray";
}
// this will actually make a transparent button id color = gray
this.bga.gameui.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.bga.gameui.addActionButton('play_button_id', _('Play 1 to 3 cards'), () => this.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.bga.gameui.addActionButton( 'commit_button', _('Confirm'), () => this.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 at the root 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. Images in a subfolder of img are NOT preloaded by default.

'''this.bga.images.dontPreloadImage(image_file_name: string)'''

'''this.bga.images.dontPreloadImages(image_file_names: string[])'''

Using dontPreloadImage, you tell the interface to not preload a specific image in your img directory. dontPreloadImages is the same for multiple images at once.

Examples of use:
<pre>
// don't preload a particular image
this.bga.images.dontPreloadImage( 'cards.png' );

// don't preload a list of unused images (gamedatas.clans contains the number of the clans used in this game).
this.bga.images.dontPreloadImages([1,2,3,4,5,6].filter(clan => !gamedatas.clans.include(clan)).map(clan => `clan${clan}.png`));
</pre>

'''this.bga.images.preloadImage(image_file_name: string)'''

'''this.bga.images.preloadImages(image_file_names: string[])'''

Opposite of dontPreloadImage, useful only for images that are not in the root img folder
Example of use:
<pre>
// preload a particular image
if (gamedatas.expansionActive) {
this.bga.images.preloadImages(['expansion/board.jpg', 'expansion/new-cards.jpg']);
}
</pre>

==Sounds ==

'''this.bga.sounds.load(id: string, label: string, fileName: string = undefined): void'''

Load a sound and register its id. Filename is without the extension. If fileName is unset, it will use the same as the id.

In any case, the sound should be placed on your img folder and exist bothe with the mp3 and ogg format/extension.

Examples :
<pre>
this.bga.sounds.load('play'); // will load play.ogg / play.mp3 in the img dir, and will be playable with id `play`
this.bga.sounds.load('claw', 'smash'); // will load smash.ogg / smash.mp3 in the img dir, and will be playable with id `claw`
</pre>

'''this.bga.sounds.play(id: string): void'''
Play a sound by its id, loaded in the setup with ''this.sounds.load''

Examples :
<pre>
this.bga.sounds.play('play');
this.bga.sounds.play('claw');
</pre>

'''this.bga.gameui.disableNextMoveSound(): void'''
Disable the standard "move" sound for this move (to replace it with your custom sound):

Add this to your notification handler:

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

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

== Status bar ==

=== Status bar text ===

;'''this.bga.statusBar.setTitle(title: string, args?: object)'''
Update the page title (aka status bar prompt). Can handle ${you} and ${actplayer} and any other var you would pass as args.
<pre>
if (args.mandatory_card_name) {
const mandatoryCardTitle = this.bga.players.isCurrentPlayerActive() ? _('${you} must take ${mandatory_card_name}') : _('${actplayer} must take ${mandatory_card_name}');
this.bga.statusBar.setTitle(mandatoryCardTitle, args);
}
</pre>
As opposed to <code>updatePageTitle</code>, it doesn't trigger the call <code>onUpdateActionButtons</code>.

;'''this.bga.gameui.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)

<b>DEPRECATED:</b> use this.bga.statusBar.setTitle instead.

=== Status bar buttons ===
;'''this.bga.statusBar.addActionButton(label: string, callback: Function, params?: object): HTMLButtonElement'''

Parameters:
*label: the label to be shown, can be html. If label if used pass traslated string, i.e. _('Yes')
*callback: function to call on click, cannot be method name it has to be function
*params: object optionally containing one of more of the following:
**color: string - can be <code>primary</code> (default) (blue), <code>secondary</code> (gray), <code>alert</code> (red)
**id: string - is the dom element id to set. If null/undefined, the button will not have an id, but you can still manipulate it by storing the reference to the DOM Element returned by the function
**classes: string|string[] - i.e <code>'disabled blinking'</code> or <code>['disabled', 'blinking']</code>.
**destination: ElementOrId - the DOM Element to add the button to. If not specified, will add it to the status bar.
**title: string - plain text description of the label. Should be set when the button label is an icon, for accessibility.
**disabled: boolean - makes the button disabled. Will prevent the callback to be executed
**tooltip: string - the tooltip of the button
**confirm: string | Function - the confirm message to display before triggering the callback, if set (or function handler, see example below).
**autoclick: boolean if the button should be auto clicked after a small delay (for Confirmation buttons).

Example of a standard call without params:
this.bga.statusBar.addActionButton(_('Pass'), () => this.bga.actions.performAction('actPass', {}));

Example of a standard call with params:
this.bga.statusBar.addActionButton(_('Pass'), () => this.bga.actions.performAction('actPass', {}), {
id: 'my_button',
color: 'secondary',
classes: 'my-outline-class'
disabled: true,
tooltip: _('You cannot pass'),
confirm: _('Are you sure to pass?'),
});

Note: the confirm parameter can be a string or a function that returns a string or null

Example of a standard call with params:
this.bga.statusBar.addActionButton(_('Discard Selected Cards'), () => this.bga.actions.performAction('actDiscard', { cardIds: this.getSelectedCardIds().join(',') }), {
confirm: () => {
if (this.getSelectedCardIds().length === 0) { // no card is selected, show the warning
return _('Are you sure you don't want to discard any cards?');
} else { // cards are selected, do not show the warning
return null;
}
}
});

Example of confirm button with autoclick animation:
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: true
});
// if you have a user preference to auto-confirm
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: this.userPreferences.get(100) == 1, // adapt to your user preference id and values
});

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

==User preferences ==
'''this.bga.userPreferences.get(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.bga.userPreferences.set(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.bga.userPreferences.onChange'''

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

Example:<pre>
// in your Game constructor
this.bga.userPreferences.onChange = (pref_id, pref_value) => this.myGamePreferenceChanged(pref_id, pref_value);

myGamePreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 201:
document.getElementsByTagName('html')[0].classList.toggle('dark-background', pref_value == 2);
break;
}
}
</pre>

'''this.bga.userPreferences.toggleVisibility(pref_id, visible)'''

Hide or show a user preference.

Example:<pre>
myGamePreferenceChanged: function(pref_id, pref_value) {
switch (pref_id) {
case 101:
// if pref 101 is "Confirm moves" and 102 is "Countdown timer on confirm", we hide the countdown user preference when confirm moves is disabled.
this.bga.userPreferences.toggleVisibility(102, prefValue != 2);
break;
}
}
</pre>

== Including classes from external files ==
You can declare multiple classes in the Game.js file, as long as you export a Game class in the end.

If you want to split your code into multiple js files, export the classes of the file using <code>export class PlayerManager {...}</code>. You can export multiple classes from the same file file that way.

Then you can import the class in the Game.js file using <code>import { PlayerManager, PlayerTable } from "./PlayerManager.js";</code> at the top of the file.

==Other useful stuff ==

;'''this.bga.gameui.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.bga.gameui.bRealtime
:Return true if the game is in realtime. Note that having a distinct behavior in realtime and turn-based should be exceptional.

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

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

;this.bga.gameui.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 the bga-animations, bga-cards, bga-dice libs and <i>this.bga.gameui.slideToObject()</i> and similar 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.

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

[[Category:Studio]]

BGA Studio Migration Guide

2026-01-07T13:58:47Z

Vagabond: Add dojo.stopEvent()

This page is only for people who started long time ago and now need to re-write older projects into more modern versions.
Also if you trying to fix older game you may have to look here.

==Overview==
See announcement here https://studio.boardgamearena.com/forum/viewtopic.php?f=12&t=45248

📌 This symbol: direct information about migration
== Structural changes==

'''''gameoptions.inc.php''''' => gameoptions.json, gamepreferences.json

Previously, options and preferences were specified in a single gameoptions.inc.php file.

Now options and preferences are 2 json files, follow Migration steps on this page https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Migration

See [[#User preferences]] and [[#Game options]] for API changes.

When building the game with this file you will see deprecation warning: The file gameoptions.inc.php is deprecated. click "Reload game options configuration" to generate the JSON content you can then put on a gameoptions.json and gamepreferences.json file. Then you can safely delete the gameoptions.inc.php file.

'''''<gamename>.game.php''''' => modules/php/Game.php

Move and refactor, see section [[BGA Studio Migration Guide#Namespaced game class|Namespaced game class]]

'''<gamename>.action.php => remove'''

See section [[BGA Studio Migration Guide#Autowire game actions|Autowire game actions]]

'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' => remove

See section [[BGA Studio Migration Guide#Removal of view and template|Removal of view and template]]

'''gameinfos.inc.php'''

File still there. Deprecated keys '''designer''', '''artist''', '''year''', '''presentation''', '''tags''', '''complexity''', '''strategy''', '''luck''', '''diplomacy''', '''is_beta''' are no longer in use. Please remove these keys and use the Game Metadata Manager instead.

'''''material.inc.php''''' => optional

See section [[#Material]]

'''''states.inc.php''''' => modules/php/States

See section [[#States]]

'''stats.inc.php''' => stats.json

Deprecation warning: The file stats.inc.php is deprecated. click "Reload statistics configuration" to generate the JSON content you can then put on a stats.json file. Then you can safely delete the stats.inc.php file.

'''<gamename>.js'''

Equivalent file is in modules/js/Game.js, it is ES6 js class (yay) and no dojo mess.
There are also massive API changes, see bottom sections

==IDE Support==
A new _ide_helper.php file is now provided in every project dir, allowing IDE to provide syntax error highlighting for the framework functions. This file is regularly updated to match the latest framework updates.

Same with bga-framework.d.ts for those using TypeScript.

📌 Sync the files from the FTP dir to your local copy to benefit from it. Most of the IDE like Visual Studio Code should handle _ide_helper.php if you already followed https://en.doc.boardgamearena.com/Setting_up_BGA_Development_environment_using_VSCode

==Game configuration ==

===User preferences===

Access to user preferences and listener: https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#User_preferences

📌
*If you had a custom function called <code>setupPreferences()</code> reading the <select> values, you can now use <code>onGameUserPreferenceChanged</code> instead.
*If you had a copy of the user preferences on a DB table, it's not needed anymore. Remove all support of writing to this table. Replace access to this table with
$pref = $this->userPreferences->get($playerId, $prefCode) ?? $defaultValue;
*If you used $this->player_preferences - replace the use with use of proper API

====Instant cssPref on user preferences====
A reload is not needed anymore to apply cssPref on a user preference change.

📌 Remove forceReload: true if it was only set to update the cssPref. The player will appreciate to not reload the whole page!

===Game options===

New functions to access the table options (game options) without hassle

https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Game_Options

📌
*Remove declaration of game options from "<code>initGameStateLabels</code>"
* Instead of using <code>$this->getGameStateValue</code> or <code>$this->gamestate->table_globals</code> use
$this->tableOptions->get(int $optionId)

This new object can also return the Real-time/Turn-based setting: https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Reflexion_time

==Server parts (php, sql, etc)==

===PHP migration===

Oct 2025: The migration was made from PHP7.4 to PHP8.4 new syntax and functions.

New projects are generated using the strict mode

📌

*Replace all <code>self::</code> to <code>$this-></code> - The new project template has been updated to remove this bad practice (that may be unsupported in a future PHP version)

*Add <code>declare(strict_types=1);</code> to all .php files and fix compiler warnings (if you use IDE it will detect it before upload).

===Namespaced game class===
Game class from '''''<gamename>.game.php''''' are now namespaced (and moved to modules/php/Game.php) and can autoload other classes of the same namespace

[[Main game logic: Game.php#Creating other classes]]

📌 The class file should be moved to modules/php/Game.php and adopted

(In examples below YourGameName is NOT verbatim its your game name)

* Move YourGameName.game.php to modules/php (create this dir if does not exists)
* Rename to Game.php
* Find the place below the copyright and add

declare(strict_types=1);
namespace Bga\Games\YourGameName;

* Remove
require_once APP_GAMEMODULE_PATH . "module/table/table.game.php";

* Find you class declaration change YouGameName to Game (verbatim) and change extends

class Game extends \Bga\GameFramework\Table

* All references to non-namespaced classes in this file should be defined on top of the file with "use", for example "use \BgaUserException;" as it is this non-namespaced exception is used in the zombieTurn function.

* All includes with relative path will need to be updated too.

* The material.inc.php to have be moved and included directly (see below)

Multiple functions of "Table" base class are now deprecated, see how to migrate in corresponding section

* notifyAllPlayers
*notifyPlayer
* mysql_fetch_assoc
** Deprecation warning: mysql_fetch_assoc function detected. It is deprecated, and may be removed someday. Please replace it by standard framework DB functions!
*Table (class access without namespace)
*isMutiactiveState (misspelled version)
*...

===Material===
Material file '''material.inc.php''' is now optional. You can define all your material directly in php class. If you still like to keep it, and using namespaced Game.php you have to move it to subfolder and include directly [[Game material description: material.inc.php#Move it to modules/php]]

=== Autowire game actions===
Simplify the action calls by removing '''<gamename>.action.php''' file

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29

📌 Autowired actions needs to start with "act", so it's risky to change them (if you change all actions names in the states.php, game, action and JS file, Real-time players will call the old name until they refresh. So, it needs to be done in two steps with duplicates on back side, or to be deployed when there is no Realt-time table running.

When migration is done, the action.php file can be deleted.

Deprecation warning: Actions detected on .action.php file. You can now use [[Main game logic: Game.php#Actions (autowired)|Auto-wired actions]] to avoid pass-through functions in .action.php file. If you transform your project to use only auto-wired actions, you can then delete the .action.php file.

=== Notifications===
Functions notifyAllPlayers and notifyPlayer from main game.php are deprecated

📌 Replace <code>$this->notifyAllPlayers</code> with <code>$this->notify->all</code>
and Replace <code>$this->notifyPlayer</code> with <code>$this->notify->player</code>

====Notification Decorators====
New notify function that handles decorators, reducing the duplicate code on notification args.

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Notification_decorators

====Notification args consistency====
Previously, when you sent an arg that was transformed by format_string_recursive or bgaFormatText, the args object was mutated and you got the transformed value in the notif_ handler.

The solution was to send the values in 2 different names like this:

[
'roundNumber' => $roundNumber, // number, to update the round counter
'round_number' => $roundNumber, // number that will be transformed to string by bgaFormatText, when shown in bold in the logs
]
📌 Do not duplicate the value, as the notif_ handler will now get unmutated args

===Deprecated getGameName===
The getGameName() function is now useless in the Game PHP file and can be deleted

📌 Delete the getGameName function in the Game PHP file.

Deprecation warning: getGameName function detected. It is deprecated. You can delete it, it is not used anymore

=== Deprecated APP_* Classes ===
Deprecation warning:

Reference to old APP_* class detected.

We recommend you to use composition instead of extend:

Pass `private Game $game` in the constructor of your object that need to access Table functions

If it's too complicated, at least replace APP_Object/APP_GameClass by APP_DbObject as APP_Object/APP_GameClass may be removed soon and don't contain anything more than APP_DbObject.

Don't hesitate to ask for help in the Dev Discord or in the Dev forum if you don't know how to do it!
class Tokens extends APP_GameClass {
becomes:
class Tokens extends \APP_DbObject {

=== Deprecated translation functions ===

On php side translation story is simplified

* totranslate function is not longer needed and can be replaced with clienttranslate
* $this->_() - can also be replaced with clienttranslate when use for non parameterized exceptions strings like

throw new \BgaUserException(clienttranslate('You must choose 3 cards'));

See [[Translations]]

=== Deprecated getNew ===
Function getNew that was only used to create new deck object is now deprecated, use $this->deckFactory->createDeck('') instead

=== Stats ===

The stats function such as initStat, setStat and getStat are also deprecated in favor of access via the objects <code>$this->tableStats and $this->playerStats</code>
See https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_Game.php#Game_statistics

===Legacy===
New object to access the legacy functions, removing the need to manually decode the JSON result when getting the values.

[[Main game logic: Game.php#Legacy games API|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Legacy_games_API]]

📌 Use $this->legacy->actionname instead of $this->actionnameLegacy and remove JSON decoding on getters

===Any Globals===
New database table and API to handle any type variables instead of numerical values only

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Use_globals

📌 If you had custom tables just for that you can drop them and use standard table

=== Server Counters ===
2 new counter classes have been added to easily handle the various counters your game might have. You also have 2 prebuilt counters: playerScore and playerScoreAux, to handle the scoring values, so you don't need to update manually the DB when setting the scores.

https://en.doc.boardgamearena.com/PlayerCounter_and_TableCounter

📌 Replace setting player_score/player_score_aux using db queries with use of $this->playerScore and $this->playerScoreAux. Remove the notifications, or part of notifications, updating the scoreCtrl counter (if you had some custom notification you may still need them).
===Updated Zombie Mode documentation and recommendations===
We now recommend making the zombie player playing randomly, instead of passing as a default. A new "Zombie Mode level" field has been added to the Game Metadata Manager, to indicated the Zombie Mode you implemented in your game.

https://en.doc.boardgamearena.com/Zombie_Mode

===View and template files: deprecated===
'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' are now optional and are not generated anymore on a new project. The new project templates demonstrate how to work without them.

📌 The DOM should be built on the JS side to remove the view/template files, so it can be complicated for old projects using them intensively. It would look like this:
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<nowiki><span>${_('My translated text')}</span></nowiki><nowiki><div id="player-tables"></div></nowiki>
`);

See more in [[#Access template elements]]

====Forbid access to global BGA variables and direct DB access on action/view files====
If you did not remove action and view files, you cannot longer use some stuff in them, such $g_user global and db access functions.

A new getCurrentPlayerId() function has been added to those action/view classes for easier migration

📌 Replace $g_user->get_id() by $this-> getCurrentPlayerId()

Replace DB calls by $this->game->DbQuery() (and such...)

===States===
There is now a way to describe each game state in a State class, that will handle all logic and description of the state. It helps splitting the code into multiple files, instead of one big Game.php file.

https://en.doc.boardgamearena.com/State_classes:_State_directory

📌 Create a State class for each state of the game (except 1 and 99 if they are still described in states.inc.php), move the state definition in it, and adapt the "st", "arg", "actXXX" and "zombie" functions in the class. When all classes are migrated, you can remove the states.inc.php file in the FTP folder.

==== If still using states.php====
The new class GameStateBuilder helps you build the state machine, allowing auto-completion, and avoid typo errors on state types. Complete example: 📌 https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php

States 1 and 99, that must not be changed, are now optional.

📌 Replace the array definition by GameStateBuilder use. You can remove the declaration of states 1 and 99.

Note: it's only useful if you don't migrate to State classes described above

==Client parts (js, html, css) ==
===Main class===
File is moved from yourgamename.js to modules/js/Game.js and has a different structure
https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js
It won't be easy to convert this, maybe best just to use old one which still works, but move when you write a new game.

===Deprecated ajaxcall ===
Introduced function bgaPerformAction to replace ajaxcall and checkAction combination, with a simpler syntax:

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Actions

Deprecation warning: The <code>ajaxcall</code> function is deprecated, check [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|the]] <code>bgaPerformAction</code> [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|function]].

📌 Replace combination of checkAction/ajaxcall by bgaPerformAction. Beware of the options (3rd param) if it was an ajaxcall without checkAction.
===Access to DOM elements ===
New functions getPlayerPanelElement(player_id) and this.getGameAreaElement()

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Adding_stuff_to_player%27s_panel

📌 Code like dojo.place(html, player_board_${player.id}); would be replaced by this.getGameAreaElement().insertAdjacentHTML('beforeend', html);
===Notification setup===
Notifications can now be automatically scanned and called without needing to register them one by one. They'll handle Promises, so they end synchronously when the Promise resolves.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Notifications

A wait function has been added to return a Promise when a delay is passed (compatible with fast-replay mode)

A new utility function has been added to support Promises for old Dojo animations

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Animation_Callbacks

📌 Dojo.subscribe calls in setupNotifications must be removed if bgaSetupPromiseNotifications is used. Notif_ function should be async and return a Promise, make sure they wait for the expected amount of time if the sync setup was using a numerical duration

If you used Dojo animation, make them Promise compatible with "await this.bgaPlayDojoAnimation(dojoAnim);"

===Status bar manipulation===
Function to change the title from the JS
https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar

📌 Replace direct title div manipulation with this.statusBar.setTitle(title: string, args?: object), and benefit from replacement of ${actplayer}/${you}/... (see example in the link above).

This also includes a new function to create action buttons, that are more screen-reader compatible than the previous version. The new button parameters also allow you to set a confirm popin or an autoclick for confirmation buttons

📌 Replace this.addActionButton by this.statusBar.addActionButton. Notice the parameters have changed, so they need to be adapted too! Remove manual setActionTimer or manual confirm with the new parameters.

===Dojo usage===
Dojo usage has been reduced to minimum in the new project template and the doc, as native JS is now able to do almost the same things, with better performance and more knowledge for newcomers of the native (vanilla) JS.

📌 Replace dojo by vanilla JS where possible
{| class="wikitable"
! Dojo API
! Category
! Description
! Vanilla JS Replacement
|-
| <code>dojo.byId("id")</code>
| DOM Selection
| Selects a single DOM element by its ID.
| <code>document.getElementById("id")</code>
|-
| <code>dojo.query("selector")</code>
| DOM Selection
| Selects a collection of DOM elements using CSS selectors.
| <code>document.querySelectorAll("selector")</code> or <code>document.querySelector("selector")</code>
|-
| <code>dojo.connect(node, "onclick", fn)</code>
| Event Handling
| Connects an event handler to a DOM element.
| <code>node.addEventListener("click", fn)</code>
|-
| <code>dojo.disconnect(handle)</code>
| Event Handling
| Removes an event handler created with <code>dojo.connect</code>.
| <code>handle.remove()</code> for event listeners, or <code>node.removeEventListener("click", fn)</code>
|-
| <code>dojo.stopEvent(evt)</code>
| Event Handling
| Prevents propagation and default action for an event.
| <code>evt.preventDefault(); evt.stopPropagation();</code>
|-
| <code>dojo.place(node, parent, "last")</code>
| DOM Manipulation
| Places a DOM node inside a parent node at a specific position.
| <code>parent.appendChild(node)</code>, when using raw html <code>parent.insertAdjacentHTML('beforeend', html)</code>
|-
| <code>dojo.create("tag", props, parent)</code>
| DOM Manipulation
| Creates a new DOM element with optional properties.
| <code>document.createElement("tag")</code>, then set properties and use <code>parent.appendChild()</code>
|-
| <code>dojo.style(node, "color", "red")</code>
| Styling
| Sets an inline CSS property on a DOM node. <b>CAUTION:</b> <code>dojo.style(node, "left")</code> (and "right", "width", etc) return lengths in pixels as numbers, not the set CSS style.
| <code>node.style.color = "red"</code>
|-
| <code>dojo.hasClass(node, "className")</code>
| Styling
| Checks if a DOM node has a specific CSS class.
| <code>node.classList.contains("className")</code>
|-
| <code>dojo.addClass(node, "className")</code>
| Styling
| Adds a CSS class to a DOM node.
| <code>node.classList.add("className")</code>
|-
| <code>dojo.removeClass(node, "className")</code>
| Styling
| Removes a CSS class from a DOM node.
| <code>node.classList.remove("className")</code>
|-
| <code>dojo.forEach(array, fn)</code>
| Array Utilities
| Iterates over an array.
| <code>array.forEach(fn)</code>
|-
| <code>dojo.map(array, fn)</code>
| Array Utilities
| Transforms an array by applying a function to each element.
| <code>array.map(fn)</code>
|-
| <code>dojo.fadeOut, dojo.fadeIn</code>
| Animations
| Various animations
| Use https://en.doc.boardgamearena.com/BgaAnimations or CSS animations
|-
| <code>dojo.hitch(this, "functionName")</code>
| Variable scoping
| Binds <code>this</code> (or other variable) in a callback
| <code>functionName.bind(this)</code>
|-
|<code>dojo.destroy(node)</code>
|DOM Manipulation
|Destroys a DOM element
|<code>node.remove()</code>
|-
|<code>dojo.indexof(array,value)</code>
|Array Utilities
|index of the item in the array,
|<code>array.indexof(value) or array.indexof(test)</code>
|}

===Sound loading===
New functions load/play have been added for the sounds:

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Sounds

📌 Replace template loading of sounds and global function playSound

===Formatting of log message using bgaFormatText===
This function, if defined, will allow you to insert HTML in the logs without overriding format_string_recursive. Example: 📌https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Define_this.bgaFormatText%28%29_method

📌 Replace the override of format_string_recursive by bgaFormatText (the last line will change)

===Automata player panel===
A new framework function to add a player panel for your game automas https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Adding_a_player_panel_for_an_automata

📌 Replace manually created automata player panel with this new function

===New JS libraries===
New JS libraries are created to help you design your games, especially for components that you will find on numerous games. See [[Studio#BGA Studio game components reference]]

📌 Replace manually created animation, stocks, etc with components (check the link above, don't want to duplicate it here)

===CSS imports===
Default BGA imports are auto-included, if you find this code and comment in .css you can delete it
@import url(../../../css/csslayer.css);
/* Note: you must not use any @import directive other than this one */

===Future support of dark mode===
BGA doesn't support dark mode yet. To have some games compatible when we do, we added a theme data tag you can use as described here:

https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css#Support_of_the_Dark_mode

BGA Studio Migration Guide

2026-01-06T14:49:24Z

Vagabond: Add caution to Dojo usage section about dojo.style returning lengths as raw pixel numbers, not the set CSS style.

This page is only for people who started long time ago and now need to re-write older projects into more modern versions.
Also if you trying to fix older game you may have to look here.

==Overview==
See announcement here https://studio.boardgamearena.com/forum/viewtopic.php?f=12&t=45248

📌 This symbol: direct information about migration
== Structural changes==

'''''gameoptions.inc.php''''' => gameoptions.json, gamepreferences.json

Previously, options and preferences were specified in a single gameoptions.inc.php file.

Now options and preferences are 2 json files, follow Migration steps on this page https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Migration

See [[#User preferences]] and [[#Game options]] for API changes.

When building the game with this file you will see deprecation warning: The file gameoptions.inc.php is deprecated. click "Reload game options configuration" to generate the JSON content you can then put on a gameoptions.json and gamepreferences.json file. Then you can safely delete the gameoptions.inc.php file.

'''''<gamename>.game.php''''' => modules/php/Game.php

Move and refactor, see section [[BGA Studio Migration Guide#Namespaced game class|Namespaced game class]]

'''<gamename>.action.php => remove'''

See section [[BGA Studio Migration Guide#Autowire game actions|Autowire game actions]]

'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' => remove

See section [[BGA Studio Migration Guide#Removal of view and template|Removal of view and template]]

'''gameinfos.inc.php'''

File still there. Deprecated keys '''designer''', '''artist''', '''year''', '''presentation''', '''tags''', '''complexity''', '''strategy''', '''luck''', '''diplomacy''', '''is_beta''' are no longer in use. Please remove these keys and use the Game Metadata Manager instead.

'''''material.inc.php''''' => optional

See section [[#Material]]

'''''states.inc.php''''' => modules/php/States

See section [[#States]]

'''stats.inc.php''' => stats.json

Deprecation warning: The file stats.inc.php is deprecated. click "Reload statistics configuration" to generate the JSON content you can then put on a stats.json file. Then you can safely delete the stats.inc.php file.

'''<gamename>.js'''

Equivalent file is in modules/js/Game.js, it is ES6 js class (yay) and no dojo mess.
There are also massive API changes, see bottom sections

==IDE Support==
A new _ide_helper.php file is now provided in every project dir, allowing IDE to provide syntax error highlighting for the framework functions. This file is regularly updated to match the latest framework updates.

Same with bga-framework.d.ts for those using TypeScript.

📌 Sync the files from the FTP dir to your local copy to benefit from it. Most of the IDE like Visual Studio Code should handle _ide_helper.php if you already followed https://en.doc.boardgamearena.com/Setting_up_BGA_Development_environment_using_VSCode

==Game configuration ==

===User preferences===

Access to user preferences and listener: https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#User_preferences

📌
*If you had a custom function called <code>setupPreferences()</code> reading the <select> values, you can now use <code>onGameUserPreferenceChanged</code> instead.
*If you had a copy of the user preferences on a DB table, it's not needed anymore. Remove all support of writing to this table. Replace access to this table with
$pref = $this->userPreferences->get($playerId, $prefCode) ?? $defaultValue;
*If you used $this->player_preferences - replace the use with use of proper API

====Instant cssPref on user preferences====
A reload is not needed anymore to apply cssPref on a user preference change.

📌 Remove forceReload: true if it was only set to update the cssPref. The player will appreciate to not reload the whole page!

===Game options===

New functions to access the table options (game options) without hassle

https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Game_Options

📌
*Remove declaration of game options from "<code>initGameStateLabels</code>"
* Instead of using <code>$this->getGameStateValue</code> or <code>$this->gamestate->table_globals</code> use
$this->tableOptions->get(int $optionId)

This new object can also return the Real-time/Turn-based setting: https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Reflexion_time

==Server parts (php, sql, etc)==

===PHP migration===

Oct 2025: The migration was made from PHP7.4 to PHP8.4 new syntax and functions.

New projects are generated using the strict mode

📌

*Replace all <code>self::</code> to <code>$this-></code> - The new project template has been updated to remove this bad practice (that may be unsupported in a future PHP version)

*Add <code>declare(strict_types=1);</code> to all .php files and fix compiler warnings (if you use IDE it will detect it before upload).

===Namespaced game class===
Game class from '''''<gamename>.game.php''''' are now namespaced (and moved to modules/php/Game.php) and can autoload other classes of the same namespace

[[Main game logic: Game.php#Creating other classes]]

📌 The class file should be moved to modules/php/Game.php and adopted

(In examples below YourGameName is NOT verbatim its your game name)

* Move YourGameName.game.php to modules/php (create this dir if does not exists)
* Rename to Game.php
* Find the place below the copyright and add

declare(strict_types=1);
namespace Bga\Games\YourGameName;

* Remove
require_once APP_GAMEMODULE_PATH . "module/table/table.game.php";

* Find you class declaration change YouGameName to Game (verbatim) and change extends

class Game extends \Bga\GameFramework\Table

* All references to non-namespaced classes in this file should be defined on top of the file with "use", for example "use \BgaUserException;" as it is this non-namespaced exception is used in the zombieTurn function.

* All includes with relative path will need to be updated too.

* The material.inc.php to have be moved and included directly (see below)

Multiple functions of "Table" base class are now deprecated, see how to migrate in corresponding section

* notifyAllPlayers
*notifyPlayer
* mysql_fetch_assoc
** Deprecation warning: mysql_fetch_assoc function detected. It is deprecated, and may be removed someday. Please replace it by standard framework DB functions!
*Table (class access without namespace)
*isMutiactiveState (misspelled version)
*...

===Material===
Material file '''material.inc.php''' is now optional. You can define all your material directly in php class. If you still like to keep it, and using namespaced Game.php you have to move it to subfolder and include directly [[Game material description: material.inc.php#Move it to modules/php]]

=== Autowire game actions===
Simplify the action calls by removing '''<gamename>.action.php''' file

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29

📌 Autowired actions needs to start with "act", so it's risky to change them (if you change all actions names in the states.php, game, action and JS file, Real-time players will call the old name until they refresh. So, it needs to be done in two steps with duplicates on back side, or to be deployed when there is no Realt-time table running.

When migration is done, the action.php file can be deleted.

Deprecation warning: Actions detected on .action.php file. You can now use [[Main game logic: Game.php#Actions (autowired)|Auto-wired actions]] to avoid pass-through functions in .action.php file. If you transform your project to use only auto-wired actions, you can then delete the .action.php file.

=== Notifications===
Functions notifyAllPlayers and notifyPlayer from main game.php are deprecated

📌 Replace <code>$this->notifyAllPlayers</code> with <code>$this->notify->all</code>
and Replace <code>$this->notifyPlayer</code> with <code>$this->notify->player</code>

====Notification Decorators====
New notify function that handles decorators, reducing the duplicate code on notification args.

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Notification_decorators

====Notification args consistency====
Previously, when you sent an arg that was transformed by format_string_recursive or bgaFormatText, the args object was mutated and you got the transformed value in the notif_ handler.

The solution was to send the values in 2 different names like this:

[
'roundNumber' => $roundNumber, // number, to update the round counter
'round_number' => $roundNumber, // number that will be transformed to string by bgaFormatText, when shown in bold in the logs
]
📌 Do not duplicate the value, as the notif_ handler will now get unmutated args

===Deprecated getGameName===
The getGameName() function is now useless in the Game PHP file and can be deleted

📌 Delete the getGameName function in the Game PHP file.

Deprecation warning: getGameName function detected. It is deprecated. You can delete it, it is not used anymore

=== Deprecated APP_* Classes ===
Deprecation warning:

Reference to old APP_* class detected.

We recommend you to use composition instead of extend:

Pass `private Game $game` in the constructor of your object that need to access Table functions

If it's too complicated, at least replace APP_Object/APP_GameClass by APP_DbObject as APP_Object/APP_GameClass may be removed soon and don't contain anything more than APP_DbObject.

Don't hesitate to ask for help in the Dev Discord or in the Dev forum if you don't know how to do it!
class Tokens extends APP_GameClass {
becomes:
class Tokens extends \APP_DbObject {

=== Deprecated translation functions ===

On php side translation story is simplified

* totranslate function is not longer needed and can be replaced with clienttranslate
* $this->_() - can also be replaced with clienttranslate when use for non parameterized exceptions strings like

throw new \BgaUserException(clienttranslate('You must choose 3 cards'));

See [[Translations]]

=== Deprecated getNew ===
Function getNew that was only used to create new deck object is now deprecated, use $this->deckFactory->createDeck('') instead

=== Stats ===

The stats function such as initStat, setStat and getStat are also deprecated in favor of access via the objects <code>$this->tableStats and $this->playerStats</code>
See https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_Game.php#Game_statistics

===Legacy===
New object to access the legacy functions, removing the need to manually decode the JSON result when getting the values.

[[Main game logic: Game.php#Legacy games API|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Legacy_games_API]]

📌 Use $this->legacy->actionname instead of $this->actionnameLegacy and remove JSON decoding on getters

===Any Globals===
New database table and API to handle any type variables instead of numerical values only

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Use_globals

📌 If you had custom tables just for that you can drop them and use standard table

=== Server Counters ===
2 new counter classes have been added to easily handle the various counters your game might have. You also have 2 prebuilt counters: playerScore and playerScoreAux, to handle the scoring values, so you don't need to update manually the DB when setting the scores.

https://en.doc.boardgamearena.com/PlayerCounter_and_TableCounter

📌 Replace setting player_score/player_score_aux using db queries with use of $this->playerScore and $this->playerScoreAux. Remove the notifications, or part of notifications, updating the scoreCtrl counter (if you had some custom notification you may still need them).
===Updated Zombie Mode documentation and recommendations===
We now recommend making the zombie player playing randomly, instead of passing as a default. A new "Zombie Mode level" field has been added to the Game Metadata Manager, to indicated the Zombie Mode you implemented in your game.

https://en.doc.boardgamearena.com/Zombie_Mode

===View and template files: deprecated===
'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' are now optional and are not generated anymore on a new project. The new project templates demonstrate how to work without them.

📌 The DOM should be built on the JS side to remove the view/template files, so it can be complicated for old projects using them intensively. It would look like this:
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<nowiki><span>${_('My translated text')}</span></nowiki><nowiki><div id="player-tables"></div></nowiki>
`);

See more in [[#Access template elements]]

====Forbid access to global BGA variables and direct DB access on action/view files====
If you did not remove action and view files, you cannot longer use some stuff in them, such $g_user global and db access functions.

A new getCurrentPlayerId() function has been added to those action/view classes for easier migration

📌 Replace $g_user->get_id() by $this-> getCurrentPlayerId()

Replace DB calls by $this->game->DbQuery() (and such...)

===States===
There is now a way to describe each game state in a State class, that will handle all logic and description of the state. It helps splitting the code into multiple files, instead of one big Game.php file.

https://en.doc.boardgamearena.com/State_classes:_State_directory

📌 Create a State class for each state of the game (except 1 and 99 if they are still described in states.inc.php), move the state definition in it, and adapt the "st", "arg", "actXXX" and "zombie" functions in the class. When all classes are migrated, you can remove the states.inc.php file in the FTP folder.

==== If still using states.php====
The new class GameStateBuilder helps you build the state machine, allowing auto-completion, and avoid typo errors on state types. Complete example: 📌 https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php

States 1 and 99, that must not be changed, are now optional.

📌 Replace the array definition by GameStateBuilder use. You can remove the declaration of states 1 and 99.

Note: it's only useful if you don't migrate to State classes described above

==Client parts (js, html, css) ==
===Main class===
File is moved from yourgamename.js to modules/js/Game.js and has a different structure
https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js
It won't be easy to convert this, maybe best just to use old one which still works, but move when you write a new game.

===Deprecated ajaxcall ===
Introduced function bgaPerformAction to replace ajaxcall and checkAction combination, with a simpler syntax:

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Actions

Deprecation warning: The <code>ajaxcall</code> function is deprecated, check [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|the]] <code>bgaPerformAction</code> [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|function]].

📌 Replace combination of checkAction/ajaxcall by bgaPerformAction. Beware of the options (3rd param) if it was an ajaxcall without checkAction.
===Access to DOM elements ===
New functions getPlayerPanelElement(player_id) and this.getGameAreaElement()

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Adding_stuff_to_player%27s_panel

📌 Code like dojo.place(html, player_board_${player.id}); would be replaced by this.getGameAreaElement().insertAdjacentHTML('beforeend', html);
===Notification setup===
Notifications can now be automatically scanned and called without needing to register them one by one. They'll handle Promises, so they end synchronously when the Promise resolves.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Notifications

A wait function has been added to return a Promise when a delay is passed (compatible with fast-replay mode)

A new utility function has been added to support Promises for old Dojo animations

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Animation_Callbacks

📌 Dojo.subscribe calls in setupNotifications must be removed if bgaSetupPromiseNotifications is used. Notif_ function should be async and return a Promise, make sure they wait for the expected amount of time if the sync setup was using a numerical duration

If you used Dojo animation, make them Promise compatible with "await this.bgaPlayDojoAnimation(dojoAnim);"

===Status bar manipulation===
Function to change the title from the JS
https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar

📌 Replace direct title div manipulation with this.statusBar.setTitle(title: string, args?: object), and benefit from replacement of ${actplayer}/${you}/... (see example in the link above).

This also includes a new function to create action buttons, that are more screen-reader compatible than the previous version. The new button parameters also allow you to set a confirm popin or an autoclick for confirmation buttons

📌 Replace this.addActionButton by this.statusBar.addActionButton. Notice the parameters have changed, so they need to be adapted too! Remove manual setActionTimer or manual confirm with the new parameters.

===Dojo usage===
Dojo usage has been reduced to minimum in the new project template and the doc, as native JS is now able to do almost the same things, with better performance and more knowledge for newcomers of the native (vanilla) JS.

📌 Replace dojo by vanilla JS where possible
{| class="wikitable"
! Dojo API
! Category
! Description
! Vanilla JS Replacement
|-
| <code>dojo.byId("id")</code>
| DOM Selection
| Selects a single DOM element by its ID.
| <code>document.getElementById("id")</code>
|-
| <code>dojo.query("selector")</code>
| DOM Selection
| Selects a collection of DOM elements using CSS selectors.
| <code>document.querySelectorAll("selector")</code> or <code>document.querySelector("selector")</code>
|-
| <code>dojo.connect(node, "onclick", fn)</code>
| Event Handling
| Connects an event handler to a DOM element.
| <code>node.addEventListener("click", fn)</code>
|-
| <code>dojo.disconnect(handle)</code>
| Event Handling
| Removes an event handler created with <code>dojo.connect</code>.
| <code>handle.remove()</code> for event listeners, or <code>node.removeEventListener("click", fn)</code>
|-
| <code>dojo.place(node, parent, "last")</code>
| DOM Manipulation
| Places a DOM node inside a parent node at a specific position.
| <code>parent.appendChild(node)</code>, when using raw html <code>parent.insertAdjacentHTML('beforeend', html)</code>
|-
| <code>dojo.create("tag", props, parent)</code>
| DOM Manipulation
| Creates a new DOM element with optional properties.
| <code>document.createElement("tag")</code>, then set properties and use <code>parent.appendChild()</code>
|-
| <code>dojo.style(node, "color", "red")</code>
| Styling
| Sets an inline CSS property on a DOM node. <b>CAUTION:</b> <code>dojo.style(node, "left")</code> (and "right", "width", etc) return lengths in pixels as numbers, not the set CSS style.
| <code>node.style.color = "red"</code>
|-
| <code>dojo.hasClass(node, "className")</code>
| Styling
| Checks if a DOM node has a specific CSS class.
| <code>node.classList.contains("className")</code>
|-
| <code>dojo.addClass(node, "className")</code>
| Styling
| Adds a CSS class to a DOM node.
| <code>node.classList.add("className")</code>
|-
| <code>dojo.removeClass(node, "className")</code>
| Styling
| Removes a CSS class from a DOM node.
| <code>node.classList.remove("className")</code>
|-
| <code>dojo.forEach(array, fn)</code>
| Array Utilities
| Iterates over an array.
| <code>array.forEach(fn)</code>
|-
| <code>dojo.map(array, fn)</code>
| Array Utilities
| Transforms an array by applying a function to each element.
| <code>array.map(fn)</code>
|-
| <code>dojo.fadeOut, dojo.fadeIn</code>
| Animations
| Various animations
| Use https://en.doc.boardgamearena.com/BgaAnimations or CSS animations
|-
| <code>dojo.hitch(this, "functionName")</code>
| Variable scoping
| Binds <code>this</code> (or other variable) in a callback
| <code>functionName.bind(this)</code>
|-
|<code>dojo.destroy(node)</code>
|DOM Manipulation
|Destroys a DOM element
|<code>node.remove()</code>
|-
|<code>dojo.indexof(array,value)</code>
|Array Utilities
|index of the item in the array,
|<code>array.indexof(value) or array.indexof(test)</code>
|}

===Sound loading===
New functions load/play have been added for the sounds:

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Sounds

📌 Replace template loading of sounds and global function playSound

===Formatting of log message using bgaFormatText===
This function, if defined, will allow you to insert HTML in the logs without overriding format_string_recursive. Example: 📌https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Define_this.bgaFormatText%28%29_method

📌 Replace the override of format_string_recursive by bgaFormatText (the last line will change)

===Automata player panel===
A new framework function to add a player panel for your game automas https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Adding_a_player_panel_for_an_automata

📌 Replace manually created automata player panel with this new function

===New JS libraries===
New JS libraries are created to help you design your games, especially for components that you will find on numerous games. See [[Studio#BGA Studio game components reference]]

📌 Replace manually created animation, stocks, etc with components (check the link above, don't want to duplicate it here)

===CSS imports===
Default BGA imports are auto-included, if you find this code and comment in .css you can delete it
@import url(../../../css/csslayer.css);
/* Note: you must not use any @import directive other than this one */

===Future support of dark mode===
BGA doesn't support dark mode yet. To have some games compatible when we do, we added a theme data tag you can use as described here:

https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css#Support_of_the_Dark_mode

BGA Studio Migration Guide

2026-01-03T15:31:38Z

Vagabond: /* Dojo usage */

This page is only for people who started long time ago and now need to re-write older projects into more modern versions.
Also if you trying to fix older game you may have to look here.

==Overview==
See announcement here https://studio.boardgamearena.com/forum/viewtopic.php?f=12&t=45248

📌 This symbol: direct information about migration
== Structural changes==

'''''gameoptions.inc.php''''' => gameoptions.json, gamepreferences.json

Previously, options and preferences were specified in a single gameoptions.inc.php file.

Now options and preferences are 2 json files, follow Migration steps on this page https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Migration

See [[#User preferences]] and [[#Game options]] for API changes.

When building the game with this file you will see deprecation warning: The file gameoptions.inc.php is deprecated. click "Reload game options configuration" to generate the JSON content you can then put on a gameoptions.json and gamepreferences.json file. Then you can safely delete the gameoptions.inc.php file.

'''''<gamename>.game.php''''' => modules/php/Game.php

Move and refactor, see section [[BGA Studio Migration Guide#Namespaced game class|Namespaced game class]]

'''<gamename>.action.php => remove'''

See section [[BGA Studio Migration Guide#Autowire game actions|Autowire game actions]]

'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' => remove

See section [[BGA Studio Migration Guide#Removal of view and template|Removal of view and template]]

'''gameinfos.inc.php'''

File still there. Deprecated keys '''designer''', '''artist''', '''year''', '''presentation''', '''tags''', '''complexity''', '''strategy''', '''luck''', '''diplomacy''', '''is_beta''' are no longer in use. Please remove these keys and use the Game Metadata Manager instead.

'''''material.inc.php''''' => optional

See section [[#Material]]

'''''states.inc.php''''' => modules/php/States

See section [[#States]]

'''stats.inc.php''' => stats.json

Deprecation warning: The file stats.inc.php is deprecated. click "Reload statistics configuration" to generate the JSON content you can then put on a stats.json file. Then you can safely delete the stats.inc.php file.

'''<gamename>.js'''

Equivalent file is in modules/js/Game.js, it is ES6 js class (yay) and no dojo mess.
There are also massive API changes, see bottom sections

==IDE Support==
A new _ide_helper.php file is now provided in every project dir, allowing IDE to provide syntax error highlighting for the framework functions. This file is regularly updated to match the latest framework updates.

Same with bga-framework.d.ts for those using TypeScript.

📌 Sync the files from the FTP dir to your local copy to benefit from it. Most of the IDE like Visual Studio Code should handle _ide_helper.php if you already followed https://en.doc.boardgamearena.com/Setting_up_BGA_Development_environment_using_VSCode

==Game configuration ==

===User preferences===

Access to user preferences and listener: https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#User_preferences

📌
*If you had a custom function called <code>setupPreferences()</code> reading the <select> values, you can now use <code>onGameUserPreferenceChanged</code> instead.
*If you had a copy of the user preferences on a DB table, it's not needed anymore. Remove all support of writing to this table. Replace access to this table with
$pref = $this->userPreferences->get($playerId, $prefCode) ?? $defaultValue;
*If you used $this->player_preferences - replace the use with use of proper API

====Instant cssPref on user preferences====
A reload is not needed anymore to apply cssPref on a user preference change.

📌 Remove forceReload: true if it was only set to update the cssPref. The player will appreciate to not reload the whole page!

===Game options===

New functions to access the table options (game options) without hassle

https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json#Game_Options

📌
*Remove declaration of game options from "<code>initGameStateLabels</code>"
* Instead of using <code>$this->getGameStateValue</code> or <code>$this->gamestate->table_globals</code> use
$this->tableOptions->get(int $optionId)

This new object can also return the Real-time/Turn-based setting: https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Reflexion_time

==Server parts (php, sql, etc)==

===PHP migration===

Oct 2025: The migration was made from PHP7.4 to PHP8.4 new syntax and functions.

New projects are generated using the strict mode

📌

*Replace all <code>self::</code> to <code>$this-></code> - The new project template has been updated to remove this bad practice (that may be unsupported in a future PHP version)

*Add <code>declare(strict_types=1);</code> to all .php files and fix compiler warnings (if you use IDE it will detect it before upload).

===Namespaced game class===
Game class from '''''<gamename>.game.php''''' are now namespaced (and moved to modules/php/Game.php) and can autoload other classes of the same namespace

[[Main game logic: Game.php#Creating other classes]]

📌 The class file should be moved to modules/php/Game.php and adopted

(In examples below YourGameName is NOT verbatim its your game name)

* Move YourGameName.game.php to modules/php (create this dir if does not exists)
* Rename to Game.php
* Find the place below the copyright and add

declare(strict_types=1);
namespace Bga\Games\YourGameName;

* Remove
require_once APP_GAMEMODULE_PATH . "module/table/table.game.php";

* Find you class declaration change YouGameName to Game (verbatim) and change extends

class Game extends \Bga\GameFramework\Table

* All references to non-namespaced classes in this file should be defined on top of the file with "use", for example "use \BgaUserException;" as it is this non-namespaced exception is used in the zombieTurn function.

* All includes with relative path will need to be updated too.

* The material.inc.php to have be moved and included directly (see below)

Multiple functions of "Table" base class are now deprecated, see how to migrate in corresponding section

* notifyAllPlayers
*notifyPlayer
* mysql_fetch_assoc
** Deprecation warning: mysql_fetch_assoc function detected. It is deprecated, and may be removed someday. Please replace it by standard framework DB functions!
*Table (class access without namespace)
*isMutiactiveState (misspelled version)
*...

===Material===
Material file '''material.inc.php''' is now optional. You can define all your material directly in php class. If you still like to keep it, and using namespaced Game.php you have to move it to subfolder and include directly [[Game material description: material.inc.php#Move it to modules/php]]

=== Autowire game actions===
Simplify the action calls by removing '''<gamename>.action.php''' file

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Actions_%28autowired%29

📌 Autowired actions needs to start with "act", so it's risky to change them (if you change all actions names in the states.php, game, action and JS file, Real-time players will call the old name until they refresh. So, it needs to be done in two steps with duplicates on back side, or to be deployed when there is no Realt-time table running.

When migration is done, the action.php file can be deleted.

Deprecation warning: Actions detected on .action.php file. You can now use [[Main game logic: Game.php#Actions (autowired)|Auto-wired actions]] to avoid pass-through functions in .action.php file. If you transform your project to use only auto-wired actions, you can then delete the .action.php file.

=== Notifications===
Functions notifyAllPlayers and notifyPlayer from main game.php are deprecated

📌 Replace <code>$this->notifyAllPlayers</code> with <code>$this->notify->all</code>
and Replace <code>$this->notifyPlayer</code> with <code>$this->notify->player</code>

====Notification Decorators====
New notify function that handles decorators, reducing the duplicate code on notification args.

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Notification_decorators

====Notification args consistency====
Previously, when you sent an arg that was transformed by format_string_recursive or bgaFormatText, the args object was mutated and you got the transformed value in the notif_ handler.

The solution was to send the values in 2 different names like this:

[
'roundNumber' => $roundNumber, // number, to update the round counter
'round_number' => $roundNumber, // number that will be transformed to string by bgaFormatText, when shown in bold in the logs
]
📌 Do not duplicate the value, as the notif_ handler will now get unmutated args

===Deprecated getGameName===
The getGameName() function is now useless in the Game PHP file and can be deleted

📌 Delete the getGameName function in the Game PHP file.

Deprecation warning: getGameName function detected. It is deprecated. You can delete it, it is not used anymore

=== Deprecated APP_* Classes ===
Deprecation warning:

Reference to old APP_* class detected.

We recommend you to use composition instead of extend:

Pass `private Game $game` in the constructor of your object that need to access Table functions

If it's too complicated, at least replace APP_Object/APP_GameClass by APP_DbObject as APP_Object/APP_GameClass may be removed soon and don't contain anything more than APP_DbObject.

Don't hesitate to ask for help in the Dev Discord or in the Dev forum if you don't know how to do it!
class Tokens extends APP_GameClass {
becomes:
class Tokens extends \APP_DbObject {

=== Deprecated translation functions ===

On php side translation story is simplified

* totranslate function is not longer needed and can be replaced with clienttranslate
* $this->_() - can also be replaced with clienttranslate when use for non parameterized exceptions strings like

throw new \BgaUserException(clienttranslate('You must choose 3 cards'));

See [[Translations]]

=== Deprecated getNew ===
Function getNew that was only used to create new deck object is now deprecated, use $this->deckFactory->createDeck('') instead

=== Stats ===

The stats function such as initStat, setStat and getStat are also deprecated in favor of access via the objects <code>$this->tableStats and $this->playerStats</code>
See https://en.doc.boardgamearena.com/index.php?title=Main_game_logic:_Game.php#Game_statistics

===Legacy===
New object to access the legacy functions, removing the need to manually decode the JSON result when getting the values.

[[Main game logic: Game.php#Legacy games API|https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Legacy_games_API]]

📌 Use $this->legacy->actionname instead of $this->actionnameLegacy and remove JSON decoding on getters

===Any Globals===
New database table and API to handle any type variables instead of numerical values only

https://en.doc.boardgamearena.com/Main_game_logic:_Game.php#Use_globals

📌 If you had custom tables just for that you can drop them and use standard table

=== Server Counters ===
2 new counter classes have been added to easily handle the various counters your game might have. You also have 2 prebuilt counters: playerScore and playerScoreAux, to handle the scoring values, so you don't need to update manually the DB when setting the scores.

https://en.doc.boardgamearena.com/PlayerCounter_and_TableCounter

📌 Replace setting player_score/player_score_aux using db queries with use of $this->playerScore and $this->playerScoreAux. Remove the notifications, or part of notifications, updating the scoreCtrl counter (if you had some custom notification you may still need them).
===Updated Zombie Mode documentation and recommendations===
We now recommend making the zombie player playing randomly, instead of passing as a default. A new "Zombie Mode level" field has been added to the Game Metadata Manager, to indicated the Zombie Mode you implemented in your game.

https://en.doc.boardgamearena.com/Zombie_Mode

===View and template files: deprecated===
'''''<gamename>.view.php, <gamename>_<gamename>.tpl''''' are now optional and are not generated anymore on a new project. The new project templates demonstrate how to work without them.

📌 The DOM should be built on the JS side to remove the view/template files, so it can be complicated for old projects using them intensively. It would look like this:
this.getGameAreaElement().insertAdjacentHTML('beforeend', `
<nowiki><span>${_('My translated text')}</span></nowiki><nowiki><div id="player-tables"></div></nowiki>
`);

See more in [[#Access template elements]]

====Forbid access to global BGA variables and direct DB access on action/view files====
If you did not remove action and view files, you cannot longer use some stuff in them, such $g_user global and db access functions.

A new getCurrentPlayerId() function has been added to those action/view classes for easier migration

📌 Replace $g_user->get_id() by $this-> getCurrentPlayerId()

Replace DB calls by $this->game->DbQuery() (and such...)

===States===
There is now a way to describe each game state in a State class, that will handle all logic and description of the state. It helps splitting the code into multiple files, instead of one big Game.php file.

https://en.doc.boardgamearena.com/State_classes:_State_directory

📌 Create a State class for each state of the game (except 1 and 99 if they are still described in states.inc.php), move the state definition in it, and adapt the "st", "arg", "actXXX" and "zombie" functions in the class. When all classes are migrated, you can remove the states.inc.php file in the FTP folder.

==== If still using states.php====
The new class GameStateBuilder helps you build the state machine, allowing auto-completion, and avoid typo errors on state types. Complete example: 📌 https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php

States 1 and 99, that must not be changed, are now optional.

📌 Replace the array definition by GameStateBuilder use. You can remove the declaration of states 1 and 99.

Note: it's only useful if you don't migrate to State classes described above

==Client parts (js, html, css) ==
===Main class===
File is moved from yourgamename.js to modules/js/Game.js and has a different structure
https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js
It won't be easy to convert this, maybe best just to use old one which still works, but move when you write a new game.

===Deprecated ajaxcall ===
Introduced function bgaPerformAction to replace ajaxcall and checkAction combination, with a simpler syntax:

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Actions

Deprecation warning: The <code>ajaxcall</code> function is deprecated, check [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|the]] <code>bgaPerformAction</code> [[/en.doc.boardgamearena.com/Game interface logic: yourgamename.js#Actions|function]].

📌 Replace combination of checkAction/ajaxcall by bgaPerformAction. Beware of the options (3rd param) if it was an ajaxcall without checkAction.
===Access to DOM elements ===
New functions getPlayerPanelElement(player_id) and this.getGameAreaElement()

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Adding_stuff_to_player%27s_panel

📌 Code like dojo.place(html, player_board_${player.id}); would be replaced by this.getGameAreaElement().insertAdjacentHTML('beforeend', html);
===Notification setup===
Notifications can now be automatically scanned and called without needing to register them one by one. They'll handle Promises, so they end synchronously when the Promise resolves.

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Notifications

A wait function has been added to return a Promise when a delay is passed (compatible with fast-replay mode)

A new utility function has been added to support Promises for old Dojo animations

https://en.doc.boardgamearena.com/Game_interface_logic:_Game.js#Animation_Callbacks

📌 Dojo.subscribe calls in setupNotifications must be removed if bgaSetupPromiseNotifications is used. Notif_ function should be async and return a Promise, make sure they wait for the expected amount of time if the sync setup was using a numerical duration

If you used Dojo animation, make them Promise compatible with "await this.bgaPlayDojoAnimation(dojoAnim);"

===Status bar manipulation===
Function to change the title from the JS
https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Title_bar

📌 Replace direct title div manipulation with this.statusBar.setTitle(title: string, args?: object), and benefit from replacement of ${actplayer}/${you}/... (see example in the link above).

This also includes a new function to create action buttons, that are more screen-reader compatible than the previous version. The new button parameters also allow you to set a confirm popin or an autoclick for confirmation buttons

📌 Replace this.addActionButton by this.statusBar.addActionButton. Notice the parameters have changed, so they need to be adapted too! Remove manual setActionTimer or manual confirm with the new parameters.

===Dojo usage===
Dojo usage has been reduced to minimum in the new project template and the doc, as native JS is now able to do almost the same things, with better performance and more knowledge for newcomers of the native (vanilla) JS.

📌 Replace dojo by vanilla JS where possible
{| class="wikitable"
! colspan="undefined" |Dojo API
! colspan="undefined" |Category
! colspan="undefined" |Description
! colspan="undefined" |Vanilla JS Replacement
|-
| colspan="undefined" |<code>dojo.byId("id")</code>
| colspan="undefined" |DOM Selection
| colspan="undefined" |Selects a single DOM element by its ID.
| colspan="undefined" |<code>document.getElementById("id")</code>
|-
| colspan="undefined" |<code>dojo.query("selector")</code>
| colspan="undefined" |DOM Selection
| colspan="undefined" |Selects a collection of DOM elements using CSS selectors.
| colspan="undefined" |<code>document.querySelectorAll("selector")</code> or <code>document.querySelector("selector")</code>
|-
| colspan="undefined" |<code>dojo.connect(node, "onclick", fn)</code>
| colspan="undefined" |Event Handling
| colspan="undefined" |Connects an event handler to a DOM element.
| colspan="undefined" |<code>node.addEventListener("click", fn)</code>
|-
| colspan="undefined" |<code>dojo.disconnect(handle)</code>
| colspan="undefined" |Event Handling
| colspan="undefined" |Removes an event handler created with <code>dojo.connect</code>.
| colspan="undefined" |<code>handle.remove()</code> for event listeners, or <code>node.removeEventListener("click", fn)</code>
|-
| colspan="undefined" |<code>dojo.place(node, parent, "last")</code>
| colspan="undefined" |DOM Manipulation
| colspan="undefined" |Places a DOM node inside a parent node at a specific position.
| colspan="undefined" |<code>parent.appendChild(node)</code>
|-
| colspan="undefined" |<code>dojo.create("tag", props, parent)</code>
| colspan="undefined" |DOM Manipulation
| colspan="undefined" |Creates a new DOM element with optional properties.
| colspan="undefined" |<code>document.createElement("tag")</code>, then set properties and use <code>parent.appendChild()</code>
|-
| colspan="undefined" |<code>dojo.style(node, "color", "red")</code>
| colspan="undefined" |Styling
| colspan="undefined" |Sets an inline CSS property on a DOM node.
| colspan="undefined" |<code>node.style.color = "red"</code>
|-
| colspan="undefined" |<code>dojo.hasClass(node, "className")</code>
| colspan="undefined" |Styling
| colspan="undefined" |Checks if a DOM node has a specific CSS class.
| colspan="undefined" |<code>node.classList.contains("className")</code>
|-
| colspan="undefined" |<code>dojo.addClass(node, "className")</code>
| colspan="undefined" |Styling
| colspan="undefined" |Adds a CSS class to a DOM node.
| colspan="undefined" |<code>node.classList.add("className")</code>
|-
| colspan="undefined" |<code>dojo.removeClass(node, "className")</code>
| colspan="undefined" |Styling
| colspan="undefined" |Removes a CSS class from a DOM node.
| colspan="undefined" |<code>node.classList.remove("className")</code>
|-
| colspan="undefined" |<code>dojo.forEach(array, fn)</code>
| colspan="undefined" |Array Utilities
| colspan="undefined" |Iterates over an array.
| colspan="undefined" |<code>array.forEach(fn)</code>
|-
| colspan="undefined" |<code>dojo.map(array, fn)</code>
| colspan="undefined" |Array Utilities
| colspan="undefined" |Transforms an array by applying a function to each element.
| colspan="undefined" |<code>array.map(fn)</code>
|-
| colspan="undefined" |<code>dojo.fadeOut, dojo.fadeIn</code>
| colspan="undefined" |Animations
| colspan="undefined" |Various animations
| colspan="undefined" |Use https://en.doc.boardgamearena.com/BgaAnimations or CSS animations
|-
| colspan="undefined" |<code>dojo.hitch(this, "functionName")</code>
| colspan="undefined" |Variable scoping
| colspan="undefined" |Binds <code>this</code> (or other variable) in a callback
| colspan="undefined" |<code>functionName.bind(this)</code>
|}

===Sound loading===
New functions load/play have been added for the sounds:

https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Sounds

📌 Replace template loading of sounds and global function playSound

===Formatting of log message using bgaFormatText===
This function, if defined, will allow you to insert HTML in the logs without overriding format_string_recursive. Example: 📌https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Define_this.bgaFormatText%28%29_method

📌 Replace the override of format_string_recursive by bgaFormatText (the last line will change)

===Automata player panel===
A new framework function to add a player panel for your game automas https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js#Adding_a_player_panel_for_an_automata

📌 Replace manually created automata player panel with this new function

===New JS libraries===
New JS libraries are created to help you design your games, especially for components that you will find on numerous games. See [[Studio#BGA Studio game components reference]]

📌 Replace manually created animation, stocks, etc with components (check the link above, don't want to duplicate it here)

===CSS imports===
Default BGA imports are auto-included, if you find this code and comment in .css you can delete it
@import url(../../../css/csslayer.css);
/* Note: you must not use any @import directive other than this one */

===Future support of dark mode===
BGA doesn't support dark mode yet. To have some games compatible when we do, we added a theme data tag you can use as described here:

https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css#Support_of_the_Dark_mode

BgaAnimations

2025-12-06T13:32:11Z

Vagabond: Add a developer note about CSS

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

== Developer notes ==

For all elements which will be animated, it is recommended to use CSS class selectors to style them (not, e.g., ID or parent-based selectors). This is because the animations typically clone the element to animate (giving it a new ID), and the DOM parentage may change as well. Symptoms that this address are things like <code>slideOutAndDestroy</code> simply causing the element to disappear, or <code>slideAndAttach</code> causing the element to "jump" to the destination.

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

'''1.0.1''': Fix documentation

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

BGA Studio Cookbook

2025-10-23T17:41:21Z

Vagabond: For tooltips in logs, add how to accomplish addToLog using promise-based notifications.

This page is a cookbook of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

==== Create pieces dynamically (using template) ====

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

==== Create pieces dynamically (using string concatenation) ====

'''Ingredients:''' ggg.js

<pre>
div = "<div class='meeple_"+color+"'></div>";
</pre>

or modern way

<pre>
div = `<div class='meeple_${color}'></div>`;
</pre>

==== Create all pieces statically ====

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

==== Use player color in template ====

NOTE: view.php is deprecated, its best to generate html from .js

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
$cplayer = $this->getCurrentPlayerId();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Status bar ===

==== Changing state prompt ====

State prompt is message displayed for player which usually comes from state description.
Sometimes you want to change it without changing state (one way is change state but locally, see client states above).

Simple way just change the html
<pre>
setMainTitle: function(text) {
$('pagemaintitletext').innerHTML = text;
},
// usage
onMeeple: function(event) {
//...
this.setMainTitle(_('You must select where meeple is going'));
},
</pre>

This however will not work with parameters and will not draw You in color, if you want this its more sophisticated:

<pre>
setDescriptionOnMyTurn : function(text) {
this.gamedatas.gamestate.descriptionmyturn = text;
var tpl = dojo.clone(this.gamedatas.gamestate.args);
if (tpl === null) {
tpl = {};
}
var title = "";
if (this.isCurrentPlayerActive() && text !== null) {
tpl.you = this.divYou();
}
title = this.format_string_recursive(text, tpl);

if (!title) {
this.setMainTitle(" ");
} else {
this.setMainTitle(title);
}
},
</pre>

Note: this method uses '''setMainTitle''' defined above and '''divYou''' defined in another section of this wiki.

=== Animation ===

==== Attach to new parent without destroying the object ====

BGA function attachToNewParent for some reason destroys the original, if you want similar function that does not you can use this
ggg.js

<pre>
/**
* This method will attach mobile to a new_parent without destroying, unlike original attachToNewParent which destroys mobile and
* all its connectors (onClick, etc)
*/
attachToNewParentNoDestroy: function (mobile_in, new_parent_in, relation, place_position) {

const mobile = $(mobile_in);
const new_parent = $(new_parent_in);

var src = dojo.position(mobile);
if (place_position)
mobile.style.position = place_position;
dojo.place(mobile, new_parent, relation);
mobile.offsetTop;//force re-flow
var tgt = dojo.position(mobile);
var box = dojo.marginBox(mobile);
var cbox = dojo.contentBox(mobile);
var left = box.l + src.x - tgt.x;
var top = box.t + src.y - tgt.y;

mobile.style.position = "absolute";
mobile.style.left = left + "px";
mobile.style.top = top + "px";
box.l += box.w - cbox.w;
box.t += box.h - cbox.h;
mobile.offsetTop;//force re-flow
return box;
},
</pre>

==== Animation on oversurface ====
If you use non-absolute position for your game elements (i.e you use layouts) - you cannot really use BGA animation functions. After years of fidding with different options I use
techique which I call animation on oversurface that works when parents use different zoom, rotation, etc

* You need another layer on top of everything - oversurface
* We create copy of the object on oversurface - to move
* We move the real object on final position - but make it invisible for now
* We move the phantom to final position applying required zoom and rotation (using css animation), then destroy it
* When animation is done we make original object visible in new position

The code is bit complex it can be found here

https://codepen.io/VictoriaLa/pen/gORvdJo

Game using it: century, ultimaterailroads

==== Scroll element into view ====
Ingredients: game.js

This function will scroll given node (div) into view and respect replays and archive mode

<pre>
scrollIntoViewAfter: function (node, delay) {
if (this.instantaneousMode || this.inSetup) {
return;
}
if (typeof g_replayFrom != "undefined") {
$(node).scrollIntoView();
return;
}
if (!delay) delay = 0;
setTimeout(() => {
$(node).scrollIntoView({ behavior: "smooth", block: "center" });
}, delay);
},
</pre>

==== Set Auto-click timer for buttons (setAutoClick) ====

Sets up auto-click for a button after a timeout, with the new progress-bar animation. Works in both JS and TS. You can pass the optional parameters (see code comments) or simply call as:
<pre>this.setAutoClick(document.getElementById('someID');</pre>

Note: use it only if this.statusBar.addActionButton(..., { autoclick: true }) doesn't fit your needs! Don't hesitate to tell BGA why it doesn't fit your needs.

<b>JavaScript</b>
<pre>
/**
* Sets up auto-click functionality for a button after a timeout period
* @param button - The button HTML element to auto-click
* @param timeoutDuration - Optional base duration in ms before auto-click occurs (default: 5000)
* @param randomIncrement - Optional random additional ms to add to timeout (default: 2000)
* @param autoClickID - Optional ID for the auto-click events, multiple buttons can therefore point to the same autoClick event
* @param onAnimationEnd - Optional callback that returns boolean to control if click should occur (default: true)
*/
setAutoClick: function(button, timeoutDuration = 5000, randomIncrement = 2000, autoClickID = null, onAnimationEnd = () => true) {
const totalDuration = timeoutDuration + Math.random() * randomIncrement;
this.setAutoClick.timeouts = this.setAutoClick.timeouts || {};

if(!autoClickID){
this.setAutoClick.autoClickIncrement = this.setAutoClick.autoClickIncrement || 1;
autoClickID = 'auto-click-' + this.setAutoClick.autoClickIncrement++;
}
this.setAutoClick.timeouts[autoClickID] = this.setAutoClick.timeouts[autoClickID] || [];

button.style.setProperty('--bga-autoclick-timeout-duration', `${totalDuration}ms`);
button.classList.add('bga-autoclick-button');

const stopDoubleTrigger = () => {
if(!this.setAutoClick.timeouts[autoClickID]) return;
this.setAutoClick.timeouts[autoClickID].forEach(timeout => clearTimeout(timeout));
delete this.setAutoClick.timeouts[autoClickID];
}
button.addEventListener('click', stopDoubleTrigger, true);

this.setAutoClick.timeouts[autoClickID].push(
setTimeout(() => {
stopDoubleTrigger();
if (!document.body.contains(button)) return;
const customEventResult = onAnimationEnd();
if (customEventResult) button.click();
}, totalDuration)
);
},
</pre>

<b>TypeScript</b>
<pre>
/**
* Sets up auto-click functionality for a button after a timeout period
* @param button - The button HTML element to auto-click
* @param timeoutDuration - Optional base duration in ms before auto-click occurs (default: 5000)
* @param randomIncrement - Optional random additional ms to add to timeout (default: 2000)
* @param autoClickID - Optional ID for the auto-click events, multiple buttons can therefore point to the same autoClick event
* @param onAnimationEnd - Optional callback that returns boolean to control if click should occur (default: true)
*/
public setAutoClick(button: HTMLDivElement, timeoutDuration: number = 5000, randomIncrement: number = 2000, autoClickID: string = null, onAnimationEnd: () => boolean = () => true){
const fn = this.setAutoClick as typeof this.setAutoClick & {
timeouts?: Record<string, number[]>;
autoClickIncrement?: number;
};
fn.timeouts = fn.timeouts || {};

const totalDuration = timeoutDuration + Math.random() * randomIncrement;

if(!autoClickID){
fn.autoClickIncrement = fn.autoClickIncrement || 1;
autoClickID = 'auto-click-' + fn.autoClickIncrement++;
}

fn.timeouts[autoClickID] = fn.timeouts[autoClickID] || [];

button.style.setProperty('--bga-autoclick-timeout-duration', `${totalDuration}ms`);
button.classList.add('bga-autoclick-button');

const stopDoubleTrigger = () => {
if(!fn.timeouts[autoClickID]) return;
fn.timeouts[autoClickID].forEach(timeout => clearTimeout(timeout));
delete fn.timeouts[autoClickID];
}
button.addEventListener('click', stopDoubleTrigger, true);

fn.timeouts[autoClickID].push(
setTimeout(() => {
stopDoubleTrigger();
if (!document.body.contains(button)) return;
const customEventResult = onAnimationEnd();
if (customEventResult) button.click();
}, totalDuration)
);
}
</pre>

=== Logs ===

==== Inject icon images in the log ====

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
$this->playerScore->inc($player_id, -$price);
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
$this->notify->all( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => $this->getPlayerNameById($player_id),
'power_tokens' => $power_tokens,
'vp_price' => $this->getLogsVPAmount($price),
'power_income' => $this->getLogsPowerAmount($power_income),
'newScore' => $this->playerScore->get($player_id),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

==== Inject images and styled html in the log ====

{{InfoBox|title=Warning — Translation|maxWidth=500|color=#c00|body='''In order to prevent interference with the translation process, keep in mind that you must only apply modifications to the args object, and not try to substitute the keys (the <code>${player_name}</code> parts of your string) in the log string.'''}}

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? You can use client side log injection to intercept log arguments (which come from the server) and replace them with html on the client side. Here are three different method you can use to achieve this.

===== Define <code>this.bgaFormatText()</code> method =====

'''Ingredients:''' ggg.js, ggg.game.php

I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Declare this function to inject html into log items. */

bgaFormatText : function(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
const keys = ['place_name','token_name'];

for (let i in keys) {
const key = keys[i];
if (args[key]) args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return { log, args };
},
</pre>

'''Important:''' In the ''bgaFormatText'' method, the 'args' parameter will only contain arguments passed to it from the notify method in Game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;

case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

Game.php:

$this->notify->all('playerLog', clienttranslate('Game moves ${token_name}'), ['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''bgaFormatText'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notify->all('tokenPlaced', clienttranslate('Player placed ${token_name}'), array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, you will loose your additional parameters, why? Because when game reloads it does not actually send same notifications, it sends special "hitstorical_log" notification where all parameters not listed in the message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notify->all('tokenPlaced', clienttranslate('Player placed ${token_name}'), array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 'zone_played' ]
);
</pre>

Now you can use zone_played in bgaFormatText even in historical logs.

===== Use <code>:formatFunction</code> option provided by <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

The above method will work in most of the cases, but if you use dotted keys such as <code>${card.name}</code> (which is supported by the framework, for private state args), the key won't be substituted because the <code>key in arg</code> test will fail. If so you need to rely either on this way, or the one after.

'''WARNING:''' using this method on an already advanced project will require you to go through all your notifications to change keys !

Under the hood, the '''this.format_string_recursive()''' function calls the '''dojo.string.substitute''' method which substitutes <code>${keys}</code> with the value provided. If you take a look at the [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] and [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] you can notice that the key can be suffixed with a colon (<code>:</code>) followed by a function name. This will allow you to specify directly in the substitution string which keys need HTML injection.

First of all, you need to define your formatting function in the ggg.js file:
<pre>
[[ggg.js]]
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
}
}
</pre>

Obviously you need to define the appropriate templates in the ggg_ggg.tpl file:
<pre>
[[ggg_ggg.tpl]]
let jstpl_HTMLLogElement1 = '<div class="log-element log-element-1-${value}"></div>';
let jstpl_HTMLLogElement2 = '<div class="log-element log-element-2-${value}"></div>';
...
</pre>
And the appropriate classes in ggg.css.

Then you need to add the <code>dojo/aspect</code> module at the top of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And you also need to add the following code in your <code>contructor</code> method in the ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){

// ... skipped code ...
let gameObject = this; //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) { //This allows you to modify the arguments of the dojo.string.substitute method before they're actually passed to it
return [template, map, transform, gameObject];
});

Now you're all set to inject HTML in your logs. To actually achieve this, you must specify the function name with the key like so:

<nowiki>[[ggg.game.php]]</nowiki>
$this->notify->all("notificationName", clienttranslate("This log message contains ${plainTextArgument} and the following will receive HTML injection: ${html_injected_argument1:getTokenDiv}"), [
"plainTextArgument" => "some plain text here",
"html_injected_argument1" => "some value used by getTokenDiv",
]);

You're not limited writing only one function, you can write as many functions as you like, and have them each inject a specific type of HTML. You just need to specify the relevant function name after the column in the substitution key.

===== Use <code>transform</code> argument of <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

This method is also relying on the use of <code>dojo.string.substitute</code> by the framework, and will use the <code>transform</code> argument, which, accordting to [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] and [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] will be run on all the messages going through dojo.string.substitute.

'''WARNING:''' This method will be applied to all strings that go through dojo.string.substitute. As such you must take extra care not to substitute keys that may be used by the framework (i.e. ${id}). In order to do so, a good practise would be to prefix all keys that need substitution with a trigram of the game name.

Since all the keys will be fed to the tranform function, by default, it must return the value, substituted or not per your needs. You can define the function like this in the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
default:
return value; //Needed otherwise regular strings won't appear since since the value isn't returned by the function
}
}

The templates must be defined in the ggg_ggg.tpl file and the corresponding CSS classes in the ggg.css file.

You need to add the following code at the beginning of the ggg.js file:
<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...
And the following code to the <code>constructor</code> method in ggg.js:
<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
// ... skipped code ...
let transformFunction = dojo.hitch(this, "getTokenDiv"); //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) {
if (undefined === transform) { //Check for a transform function presence, just in case
return [template, map, transformFunction];
}
});
Then you're all set for log injection, no need to change anything on the PHP side.

==== Processing logs on re-loading ====

You rarely need to process logs when reloading, but if you want to do something fancy you may have to do it after logs are loaded.
Logs are loaded asyncronously so you have to listen for logs to be fully loaded.
Unfortunately there is no direct way of doing it so this is the hack.

'''Hack alert''' - this extends undocumented function and may be broken when framework is updated

'''Ingredients:''' ggg.js

<pre>
/*
* [Undocumented] Override BGA framework functions to call onLoadingLogsComplete when loading is done
@Override
*/
setLoader: function(image_progress, logs_progress) {
this.inherited(arguments); // required, this is "super()" call, do not remove
//console.log("loader", image_progress, logs_progress)
if (!this.isLoadingLogsComplete && logs_progress >= 100) {
this.isLoadingLogsComplete = true; // this is to prevent from calling this more then once
this.onLoadingLogsComplete();
}
},

onLoadingLogsComplete: function() {
console.log('Loading logs complete');
// do something here
},
</pre>

====Overriding format_string_recursive to inject HTML into log, including adding tooltips to log====

'''Ingredients:''' ggg.js

I'm using cards as an example but this will work with any type of resource or game element. The first step is to override format_string_recursive. You can find info about this in this [https://bga-devs.github.io/blog/posts/translations-summary/ excellent guide]. We will replace the return line from the guide with this:
return this.logInject(text);
The purpose of logInject() is to catch pre-coded text from your notifications, siphon out the meaningful info so that you can manipulate it on the front end, and then replace that pre-coded text in the log with whatever html you desire, as well as adding a tooltip to the element you're injecting. Here is a simplified version of logInject():
logInject: function (log_entry) {
const card_regex = /\[\w+-*\w* *\w*$\d+$\]/g; // this will catch a card name in the log formatted like so: [card_name(card_type_arg)] -You may need to adjust the regex to catch your card names
const cards_to_replace = log_entry.matchAll(card_regex);
for (let card of cards_to_replace) {
const match = card[0];
const left_parenthesis = match.indexOf('(');
const card_type_arg = match.slice(left_parenthesis+1, match.length-2);
const card_span = this.getHTMLForLog(card_type_arg, 'card');
log_entry = log_entry.replace(match, card_span);
}
return log_entry;
}
getHTMLForLog() takes the card_type_arg and uses it to create the <nowiki><span> to be injected into the log that you can then attach a tooltip to:</nowiki>
getHTMLForLog: function (item, type) { // in this example, item refers to the card_type_arg
switch(type) {
case 'card':
this.log_span_num++; // adds a unique num to the span id so that duplicate card names in the log have unique ids
const card_name = this.gamedatas['cards'][item]['description']; // or wherever you store your translated card name
const item_type = 'card_tt';
return `<nowiki><span id="${this.log_span_num}_item_${item}" class="${item_type} item_tooltip">${card_name}</span></nowiki>`;
}
}
If you only want to add some HTML to your log and don't care about the tooltips, you can remove the item_tooltip class from the above and stop here. If you want tooltips, you'll need a function to add them:
addTooltipsToLog: function() {
<nowiki> </nowiki> const item_elements = dojo.query('.item_tooltip:not(.tt_processed)');
<nowiki> </nowiki> Array.from(item_elements).forEach(ele => {
<nowiki> </nowiki> const ele_id = ele.id;
<nowiki> </nowiki> ele.classList.add('tt_processed'); // prevents tooltips being re-added to previous log entries
<nowiki> </nowiki> if (ele.classList.contains('card_tt')) {
<nowiki> </nowiki> const card_type_arg = ele_id.slice(-3).replace(/^\D+/g, <nowiki>''</nowiki>); // extracts the card_type_arg from the span id
<nowiki> </nowiki> this.cardTooltip(ele_id, card_type_arg)
<nowiki> </nowiki> }
<nowiki> </nowiki> });
}
cardTooltip() is just however you want to create and add your tooltip. Mine is below:
cardTooltip: function (ele, card_type_arg) {
const card = this.gamedatas.cards[card_type_arg];
const bg_pos = card['x_y'];
const skill = dojo.string.substitute("${skill}", { skill: card['skill'] });
const description = dojo.string.substitute("${description}", { description: card['description'] });
const html = `<nowiki><div style="margin-bottom: 5px; display: inline;"><strong>${description}</strong></nowiki><nowiki></div></nowiki>
<nowiki><span style="font-size: 10px; margin-left: 5px;">${skill}</span></nowiki>
<nowiki><div class="asset asset_tt" style="background-position: -${bg_pos[0]}% -${bg_pos[1]}%; margin-bottom: 5px;"></div></nowiki>`;
this.addTooltipHTML(ele, html, 1000);
}
And finally, you need to connect addTooltipsToLog. Using the new promise-based notifications you can supply the `onEnd` param like
this.bgaSetupPromiseNotifications({ onEnd: this.addTooltipsToLog.bind(this) });
Or, if you're not using them, you can attach to the notifqueue so it is called whenever the log is updated like
dojo.connect(this.notifqueue, 'addToLog', () => {
this.addTooltipsToLog();
});
You can expand this to cover multiple types of tooltips. For example, I have it set up for cards: formatted in log as [card_name(card_type_arg)], hexes: formatted as {pitch_name(pitch_type_arg)}, objectives: formatted as ==objective_name(objective_type_arg)==, etc.

===Player Panel===

====Inserting non-player panel====
'''This should be avoided. The new guideline is to avoid it in new games and remove it from old games.'''

'''Ingredients:''' ggg.js, ggg_ggg.tpl

If you want to insert non-player panel on the right side (for example to hold extra preferences, zooming controls, etc)

this can go pretty much anywhere in template it will be moved later

ggg_ggg.tpl:
<pre>
<div class='player_board_config' id="player_board_config">

<button id="zoom-out" class=" fa fa-search-minus fa-2x config-control"></button>
<button id="zoom-in" class=" fa fa-search-plus fa-2x config-control"></button>
<button id="show-settings" class="fa fa-cog fa-2x config-control "></button>
</div>
</pre>

some hackery required in js

ggg.js:
<pre>
/* @Override */
updatePlayerOrdering() {
this.inherited(arguments);
dojo.place('player_board_config', 'player_boards', 'first');
},
</pre>

===Images and Icons ===

==== Accessing images from js ====

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

====High-Definition Graphics====

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

====Using CSS to create different colors of game pieces if you have only white piece====

<pre>
background-color: #${color};
background-blend-mode: multiply;
background-image: url( 'img/mypiece.png');
mask: url('img/mypiece.png');
-webkit-mask: url('img/mypiece.png');
</pre>

where ${color} - is color you want

Note: piece has to be white (shades of gray). Sprite can be used too, just add add background-position as usual.

==== Accessing player avatar URLs ====

<pre>
getPlayerAvatar(playerId) {
let avatarURL = '';

if (null != $('avatar_' + playerId)) {
let smallAvatarURL = dojo.attr('avatar_' + playerId, 'src');
avatarURL = smallAvatarURL.replace('_32.', '_184.');
}
else {
avatarURL = 'https://x.boardgamearena.net/data/data/avatar/default_184.jpg';
}

return avatarURL;
},
</pre>

Note: This gets avatar URLs at 184x184 resolution. You can also use 92, 50, and 32 depending on which resolution you want.

====Adding Image buttons====

Its pretty trivial but just in case you need a working function:

ggg.js:
<pre>
addImageActionButton: function (id, div_html, handler) { // div_html is string not node
this.addActionButton(id, div_html, handler, '', false, 'gray');
dojo.style(id, "border", "none"); // remove ugly border
dojo.addClass(id, "bgaimagebutton"); // add css class to do more styling
return $(id); // return node for chaining
},

</pre>
Example of usage:
<pre>
this.addImageActionButton('button_coin',"<div class='coin'></div>", ()=>{ alert('Ha!'); });
</pre>

=== Other Fluff===

====Use thematic fonts====

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

'''Content Security Policy'''

BGA runs a Content Security Policy which will limit the origins from which you can load external fonts, in order to prevent license abuse.

The CSP is a whitelist of allowed origins. To see the list, view the response headers of any page on Studio, and look for the "Content-Security-Policy" header.

You will specifically want to check for the font-src token within these headers, and limit any external fonts to these sources.

'''This list is subject to change''' but as of the time of writing, the only acceptabled external sites are use.typekit.net and fonts.gstatic.com.

=== Scale to fit for big boards===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?

You have to decide:
* If board does not fit you want scale whole thing down, the best way is probably use viewport (see https://en.doc.boardgamearena.com/Your_game_mobile_version)
*You can leave the board as is and make sure it is scrollable horizonatally
*You add custom scale just for the board (can add user controls - and hook to transform: scale())

I tried to auto-scale but this just does work, too many variables - browser zoom, 3d mode, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming...
Here is scaling functing for custom user scaling

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
onZoomPlus: function() {
this.setZoom(this.zoom + 0.1);
},
onZoomMinus: function() {
this.setZoom(this.zoom - 0.1);
},

setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
var inner = document.getElementById("thething");

if (zoom == 1) {
inner.style.removeProperty("transform");
inner.style.removeProperty("width");
} else {
inner.style.transform = "scale(" + zoom + ")";
inner.style.transformOrigin = "0 0";
inner.style.width = 100 / zoom + "%";
}
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
this.onScreenWidthChange();
},
</pre>

===Dynamic tooltips===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string returned by getContent() becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

===Rendering text with players color and proper background===

'''Ingredients:''' ggg.js

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou: function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

/* Implementation of proper colored player name with background in case of white or light colors */

divColoredPlayer: function(player_id) {
var color = this.gamedatas.players[player_id].color;
var color_bg = "";
if (this.gamedatas.players[player_id] && this.gamedatas.players[player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[player_id].color_back + ";";
}
var div = "<span style=\"color:#" + color + ";" + color_bg + "\">" + this.gamedatas.players[player_id].name + "</span>";
return div;
},
</pre>

===Cool realistic shadow effect with CSS===

====Rectangles and circles====

It is often nice to have a drop shadow around tiles and tokens, to separate them from the table visually. It is very easy to add a shadow to rectangular elements, just add this to your css:

<pre>
.xxx-tile {
box-shadow: 3px 3px 3px #000000a0;
}
</pre>

box-shadow obeys '''border-radius''' of the element, so it will look good for rounded rectangles, and hence also circles (if border-radius is set appropriately).

box-shadow also supports various other parameters and can be used to achieve effects such as glowing, borders, inner shadows etc. If you need to animate a box-shadow, you may be able to get better performance (avoiding redraws) if you attach the shadow to another element (possibly an ::after pseudo-element) and change only the '''opacity''' of that element.

==== Irregular Shapes ====

If you wish to make a shadow effect for game pieces that are not a rectangle, but your game pieces are drawn from rectangles in a PNG image, you can apply the shadow to the piece using any art package and save it inside the image. This usually will yield the best performance. Remember to account for the size of the shadow when you lay out images in the sprite sheet.

However that sometimes will not be an option, for example if the image needs to be rotated while the shadow remains offset in the same direction. In this case, one option is to not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

Beware that some browsers still do not always draw drop-shadow correctly. In particular, Safari frequently leaves bits of shadow behind when objects move around the screen. In Chrome, shadows sometimes flicker badly if another element is animating close by. Some of these correctness issues can be solved by adding '''isolation: isolate; will-change: filter;''' to affected elements, but this significantly affects redraw performance.

Beware of performance issues - particularly on Safari (MacOS, iPhone and iPad). Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>For Safari, it is usually better to simply disable drop-shadow completely: [[Game interface stylesheet: yourgamename.css#Warning: using drop-shadow]].

====Shadows with clip-path====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

==Game Model and Database design ==

===Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
*(meeple,zone)
*(die, zone, sideup)
*(resource cube/money token/vp token,player home zone)
*(token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
*(resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
!token_key
!token_location
!token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
| 5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
!token_key
!token_location
!token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
!player_id
!resource_key
!resource_count
|-
| 123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
!token_id
!token_type
!token_arg
!token_location
!token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

*Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
*Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
*The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
*The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
*As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
*So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
*For dynamic information we should try to reduce amount of fields we need
**we need at least a field for card, so its one
**we need to know what zone cards belong to, its 2
**and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
*In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

==Game Elements==

===Resource===

A game resource, such as "wood," is usually infinite and represented by a count allocated to a specific player or supply.

If a resource can be placed on location, use the "Meeple" model described below.

For a working example, you can check out: [https://codepen.io/VictoriaLa/pen/emYgLzR CodePen Example] (ui only).

====Representation in Database====
In a minimalistic "tokens" database, it would look like this (e.g., the red player has 3 wood):

{| class="wikitable"
|+token
!token_key
!token_location
! token_state
|-
|wood_ff0000
|
|3
|-
|wood_supply
|
|40
|}

The second row you need to store the resource in the supply (if it's counted).

If you don't like this solution can use bga_globals table for this or create your own resource table.

Its not recommened to extend player table to store this information.

====Representation in Material File (material.inc.php)====
In the material file, you can define some information about resources. For instance, you can specify that it's of type "resource" and call it "Wood" in English, along with a tooltip:
<pre>
$this->token_types = [
...
'wood' => [
'name' => clienttranslate('Wood'),
'tooltip' => clienttranslate('Game resource used for building houses'),
'type' => 'resource',
'max' => 40
]
];
</pre>

====HTML Representation====
In HTML, this would look something like this within the player panel. Using the data attribute instead of a CDATA value is much more flexible:
<pre>
<div id="wood_ff0000" class="resource wood" data-value="3"></div>
</pre>

==== JavaScript Handling ====
When you get the object from the server, one of the tokens will be sent in the array like this:
<pre>
token = {
key: 'wood_ff0000',
location: '-',
state: '3'
}
</pre>

You can create a corresponding `<div>` in the `setup()` method of `game.js` as follows:
<pre>
const playerColor = token.key.split('_')[1];
const resType = token.key.split('_')[0];
const tokenInfo = this.gamedatas.token_types[resType]; // token_types is the structure from the material file sent to the client
const div = `<div id="${token.key}" class="${resType} ${tokenInfo.type} ${token.key}" data-value="${token.state}"></div>`;

if (playerColor != 'supply') {
document.querySelector(`#player_board_${this.getPlayerIdByColor(playerColor)} > .player-board-game-specific-content`).insertAdjacentHTML('beforeend',div);
this.addTooltip(token.key, _(tokenInfo.name) + " " + _(tokenInfo.tooltip), "");
}
</pre>

When you receive an update notification (assuming you get the same "token" object), you can simply update the `data-value`:
<pre>
document.querySelector(`#${token.key}`).dataset.value = token.state;
</pre>

To display the resource in the game log, you can format it like this:
<pre>
Player gains <div class="resource wood" data-value="1"></div>
</pre>
For more on injecting icon images in the log, see: [[BGA_Studio_Cookbook#Inject_icon_images_in_the_log]]

====Graphic Representation (.css)====
To properly display the resource image, it is preferable to use an image sprite that includes all resources,
usually it will be .png as these objects have shape.
This how will .css look like with horizontal sprite image:

<pre>
.resource {
background-image: url(https://en.doc.boardgamearena.com/images/d/d3/Cubes.png);
background-repeat: no-repeat;
background-size: cover; /* auto-scale */
aspect-ratio: 1/1; /* that will keep heigh in sync */
width: 32px; /* default size, specific location should override */
}

.wood {
/* Since the sprite is a horizontal row of 11 cubes and 9 is the brown cube position */
background-position: calc(100% / (11 - 1) * 9) 0%;
}
</pre>

To show a text overlay with the resource value, you can use the following CSS:
<pre>
.resource[data-value]:after {
content: attr(data-value);
width: 100%;
height: 100%;
position: absolute;
font-size: xx-large;
text-align: center;
text-shadow: 2px 0 2px #fff, 0 -2px 2px #fff, 0 2px 2px #fff, -2px 0 2px #fff;
}
</pre>

This solution is fully scalable — you only need to specify the size where you want it displayed.
For example:
<pre>
.player_board_content > .resource {
width: 40px;
position: relative;
}
</pre>

Note: if you have that board that tracks the resource on resource tracker - you can show this IN ADDITION of showing resource on player panel.

====Selection and Actions====
It is best to put buttons with resource images on the status bar, rather than having the player click on the player panel.

For animation:
*Can use move animation to animate resourced gained or played from the board location to the player panel
*Can use "vapor" animation to show resource gained from the board

===Meeple===

A meeple is a game piece, typically representing a "worker," depicted as a human-shaped figure in a specific color assigned to a player.

The key distinction between meeples and traditional resources is that meeples are placed on locations and can exist
in at least two states — standing or lying down.

This concept also applies to similar pieces like "houses," "animeeples," "ships," and others.

====Representation in Database====
In a simplified "tokens" database, it might be represented like this
(e.g., the red player's first meeple is on action spot 1, while the white meeple remains in supply):

{| class="wikitable"
|+token
!token_key
!token_location
! token_state
|-
|meeple_ff0000_1
|actionspot_1
|1
|-
|meeple_ffffff_1
| supply
|0
|}

====Representation in Material File (material.inc.php)====

Here we define some properties, for example name can be used in notification and as tooltip, type can be used to create the div by
javascript, 'create' - can be used by server to create 8 meeples of this type in database and set location to 'supply_ff0000'

<pre>
$this->token_types = [
...
'meeple_ff0000' => [
'name' => clienttranslate('Red Worker'),
'type' => 'meeple meeple_ff0000',
'create' => 8,
'location' => 'supply_ff0000'
]
];
</pre>

====HTML Representation ====
In HTML, this would look something like this.
<pre>
<div id="meeple_ff0000_1" class="meeple meeple_ff0000" data-state="1"></div>
</pre>

====JavaScript Handling ====
When you get the object from the server, each meeple object will be similar to this:
<pre>
meeple = {
key: 'meeple_ff0000_1',
location: 'actionslot_1',
state: '1'
}
</pre>

You can create a corresponding `<div>` in the `setup()` method of `game.js` as follows:
<pre>
const playerColor = token.key.split('_')[1];
const resType = token.key.split('_')[0];
const tokenInfo = this.gamedatas.token_types[resType]; // token_types is the structure from the material file sent to the client
const div = `<div id="${token.key}" class="${tokenInfo.type} ${token.key}" data-state="${token.state}"></div>`;

$(token.location).insertAdjacentHTML('beforeend',div);
this.addTooltip(token.key, _(tokenInfo.name) + " " + _(tokenInfo.tooltip), "");
$(token.key).addEventListener('onclick',(ev)=>this.onMeepleClick(ev));

</pre>

When you receive an update notification (assuming you get the same "token" object), you either create it if not exists or animate:
<pre>
if ($(token.key)) {
// exists
$(token.key).dataset.state = token.state; // update state
this.moveToken(token.key, token.location); // animate to new location (custom functon), see [[BGA_Studio_Cookbook#Animation]]
} else {
// crate meeple using code in previous section
}

</pre>

==== Graphic Representation (.css)====

Use same sprite technique from Resource section above.

When placed on the board it will look good with shadow, but its not recommended on mobile

filter: drop-shadow(black 5px 5px 5px);

To represent "laying down" meeple, you have to use a different sprite image, which you will apply based on data attribute

<pre>
.meeple[data-state="1"] {
background-image: url(...);
}
</pre>

You can also rotate you div, but it will look lame.
Other options include changing its shading, adding overlay (i.e. sad face) and so on.

====Selection and Actions====
To show user that meeple is active it best to use drop-shadow as image as non-square, however this may be very slow.
For simplier case use box shadow.

<pre>
.active_slot {
filter: drop-shadow(0px 0px 10px blue);
cursor: pointer;
}

/* draw a circle around game element for selection */
.active_slot_simple:after {
content: " ";
width: 110%;
top: -5%;
left: -5%;
aspect-ratio: 1/1;
position: absolute;
border-radius: 50%;
box-shadow: 0px 0px 4px 3px #64b4ff;
}

</pre>

See code example at https://codepen.io/VictoriaLa/pen/emYgLzR

When a meeple is gained from the supply, you can display a meeple icon on the status bar button
instead of showing the supply on the board.

===Dice ===
The 2D dice can use similar handing as meeple but it has 6 states instead of 2.

IMPORTANT: Never roll dice using javascript. All dice rolling must be done using bga_rand() function in php.

====Representation in Database====
In a simplified "tokens" database, it might be represented like this

{| class="wikitable"
|+token
!token_key
!token_location
!token_state
|-
|die_black
|actionspot_1
|1
|-
|die_red
|supply
|6
|}

====Representation in Material File (material.inc.php)====

Similar to resource and meeple above

====HTML Representation====

<pre>
<div id="die_black" class="die" data-state="1"></div>
</pre>

====JavaScript Handling (.js)====
See meeple section

====Graphic Representation (.css)====
For dice we would usually use N x 6 sprite, and since the sides are square - the .jpg format is better (it is smaller then png)

<pre>
.die {
background-image: url(https://en.doc.boardgamearena.com/images/c/c5/64_64_dice.jpg);
background-size: 600%;
background-repeat: no-repeat;
aspect-ratio: 1/1;
width: 64px;
border-radius: 5%; /* looks better with rounded corders */
}
.die[data-state="3"] {
background-position: calc(100% / 5 * 2) 0%;
}
</pre>

The 3D dice a bit tricker to create but its feasible, see https://codepen.io/VictoriaLa/pen/QWBBbwz for an example.

Also multiple examples on N-sided dice can be found on [[BGA_Code_Sharing]]

====Selection and Actions====
Since it is a square its a lot easier to make a square selection highlight

<pre>
.die.active_slot {
box-shadow: 0px 0px 4px 4px blue;
}
</pre>

===Card===

Cards are the most complex game resource, they can be located in various zones, stacked, tapped, put face down and can have arbitrary complete abilities.
If you have square tiles - it can be treated the same as cards.

====Representation in Database====

In a simplified "tokens" database, it might be represented like this

{| class="wikitable"
|+token
!token_key
!token_location
!token_state
|-
|card_project_123
|tableau_ff0000
|1
|-
|card_corp_p1
| deck_corp
|6
|}

Means project card is player red tableau and state 1 means it has been used for example,
and second card of corproration file in in deck at position 6 from the top.

When duplcates are in play you need to add extra unique disambigator in the key.

Usually cards will have numeric id associated with type, but it this number is per expansition, so leave the space for expansion identifier in there also.

Another option use [[Deck]] component.

====Representation in Material====

All the card properties which do not change during the game can be put in material file (or its alternative)

This is example from terraforming mars
<pre>
'card_main_81' => [ //
'location' => 'deck_main',
'create' => 'single',
'num' => 81,
'name' => clienttranslate('Ganymede Colony'),
't' => 1,
'r' => "city('Ganymede Colony')",
'cost' => 20,
'tags' => 'Space City Jovian',
'vp' => 'tagJovian',
'deck' => 'Basic',
'text' => clienttranslate('Place a city tile ON THE RESERVED AREA [for Ganymede Colony].'),
'text_vp' => clienttranslate('1 VP per Jovian tag you have.'),
],
</pre>

====HTML Representation====

There is 2 main options:
* Use exact cards images in english
*Use cards images WITHOUT text

The 3d option is completely redo the graphic layout that game designed did already, but I won't go there

The first option is very simple and similar to other resources and meeple

<pre>
<div id="card_project_123" class="card card_project card_project_123" data-state="1"></div>
</pre>

The second option means you can add translated text instead
<pre>
<div id="card_project_123" class="card card_project card_project_123" data-state="1" data-cost="22">
<div class="card_name">Ganymede Colony</div>
<div class="card_text">Place a city tile ON THE RESERVED AREA [for Ganymede Colony].</div>
<div class="card_cost"></div>
</div>
</pre>

In the example above card_cost is also rendered as this can change during the game (even printed value is the same),
it would be rendered using data-cost attribute.

Instead of using class you can also use state even if it is static

<div id="card_H_10" class="card" data-suit="H" data-rank="10"> </div>

Note: to make flip animation you effectively need to make a "3d" card and provide both faces with separate graphics,
which makes more complex div. See examples at [[BgaCards]].

Note: you can also use [[Stock]] component that handles html, js, css, layout and selection at the same time. If do that skip sections below.

====JavaScript Handling (.js)====
You will get the server data which looks like this

<pre>
card = {
key: 'card_project_123',
location: 'tableau_ff0000',
state: '1'
}
</pre>

<pre>
createCard(token: Token) {
// token_types is the structure from the material file sent to the client
const tokenInfo = this.gamedatas.token_types[token.key];
const div = `
<div id="${token.key}" class="${tokenInfo.type} ${token.key}" data-state="${token.state}">
<div class="card_name">${_(tokenInfo.name)}</div>
<div class="card_text">${_(tokenInfo.text)}</div>
</div>`;

$(token.location).insertAdjacentHTML('beforeend',div);
this.addTooltipHtml(token.key, this.getTooptipHtmlForToken(token));
$(token.key).addEventListener("onclick", (ev) => this.onCardClick(ev));
}
</pre>

When you receive an update notification (assuming you get the same "token" object), you either create it if not exists or animate:
<pre>
if ($(token.key)) {
// exists
$(token.key).dataset.state = token.state; // update state
$(token.key).dataset.cost = token.cost; // update cost (discounted cost)
this.moveCard(token.key, token.location); // animate to new location (custom functon), see [[BGA_Studio_Cookbook#Animation]]
} else {
this.createCard(token);
}
</pre>

====Graphic Representation (.css)====

For this html
<pre>
<div id="game" class="classic_deck">
<div id="hand" class="hand">
<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>
<div id="card_C_K" class="card" data-suit='C' data-rank="K"> </div>
</div>
</div>
</pre>

This is example css using sprite image of playing cards
<pre>
.card {
background-image: url('https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg'); /* don't do full url in your game, copy this file inside img folder */

background-size: 1500% auto; /* this mean size of background is 15 times bigger than size of card, because its sprite */
border-radius: 5%;
width: 10em;
height: 13.5em;
box-shadow: 0.1em 0.1em 0.2em 0.1em #555;
}

.card[data-rank="10"] { /* 10 is column number 10 - 2 because we start from 0 and first card is sprite is 2. The multiplier is (15 - 1) is because we have 15 columns. -1 is because % in CSS is weird like that. */
background-position-x: calc(100% / (15 - 1) * (10 - 2));
}
.card[data-rank="K"] { /* King will be number 13 in rank */
background-position-x: calc(100% / (15 - 1) * (13 - 2));
}
.card[data-suit="H"] { /* Hears row position is 1 (because we count from 0). Multiplier (4 - 1) is because we have 4 rows and -1 is because % in CSS is weird like that. */
background-position-y: calc(100% / (4 - 1) * (1));
}
.card[data-suit="C"] { /* Clubs row position is 2 */
background-position-y: calc(100% / (4 - 1) * (2));
}
</pre>
See code at https://codepen.io/VictoriaLa/pen/mdMzRxa

====Selection and Actions====

Since it is a square its a lot easier to make a square selection highlight

<pre>
.card.active_slot {
box-shadow: 0px 0px 4px 4px blue;
}
</pre>

==== Card Layouts====
There are two options - you use [[Stock]] component or don't, see [[Anti-Stock]] for details on how to do your own layouts.

This is comprehensive example of various card layouts and animations
https://thoun.github.io/bga-cards/demo/index.html

===Hex Tiles===
From data perspective hex tiles exactly the same as cards.
From visualization there is a small trick.

CSS:
<pre>
.hex {
width: var(--hex-width);
aspect-ratio: 1 / 1.1193;
border-radius: 30%;
background-color: yellow; /* this is just for demo, use proper .png file for this */
clip-path: polygon(50% 0, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);
}

.hex.active_slot_simple {
background-color: rgba(86, 207, 110, 0.4);
}
.hex.active_slot {
filter: drop-shadow(0px 0px 10px blue);
}
</pre>

===Tetris Tiles===
You can use clip-path for actual shape and svg path for outline
See example at https://codepen.io/VictoriaLa/pen/OJmoZGw

===Track===

Tracker can be represented as "resource" in database - in this case its just number, or similar to "meeple" in which case
the location will have the "number" associated with position on track

In a simplified "tokens" database, it might be represented like this

{| class="wikitable"
|+token
!token_key
!token_location
!token_state
|-
|tracker_o
| scale_o_1
|0
|-
|tracker_t
| scale_t_10
|0
|}

The tracker location in this case may have some properties in material file, for example to trigger game effect when we land on this spot

<pre>
'scale_t' => [
'index_start' => 0,
'max' => 20,
'value_start' => -30,
'value_step' => 2,
'slot_type' => 'slot slot_t'
],
'scale_t_10' => [
'r' => 'ocean',
'param' => 't',
'tooltp' => clienttranslate('Place an ocean'),
'value' => 0
],
</pre>

The track in this case can be generated as series of slots (create in js)
<pre>
for(let i=trackInfo.index_start,value = trackInfo.value_start;i<trackInfo.index_start+trackInfo.max;i++,value+=trackInfo.value_step) {
$(trackInfo.key).insertAdjacentHTML('beforeend',`<div id="${trackInfo.key}_${i}" class="${trackInfo.slot_type} data-value=${value}"></div>`);
this.addTooltip(`${trackInfo.key}_${i}`, _(tokenInfo.tooltip), "");
}
</pre>

Then use regular move animation to move tracker into position on track.

==Code Organization==

===Including your own JavaScript module===
'''Ingredients:''' ggg.js, modules/ggg_other.js

*Create ggg_other.js in modules/ folder and sync
<pre>
define([
"dojo", "dojo/_base/declare"
], function( dojo, declare )
{
return declare("bgagame.other", null, { // null here if we don't want to inherit from anything
constructor: function(){},
mystuff: function(){},
});

});

</pre>
*Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
g_gamethemeurl + "modules/ggg_other.js" // load my own module!!!
], function(dojo,
declare) {

use it

foo = new bgagame.other();

===Including your own JavaScript module (II) ===

*Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

===Including your own PHP module===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

*Create ggg_other.php in modules/ folder and sync
*Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

===Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php8.4 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

===Avoiding code in dojo declare style===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args?.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

===More readable JS: onEnteringState===

If you have a lot of states in onEnteringState or onUpdateActionButtons and friends - it becomes rather wild, you can do this trick to call some methods dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors===

*[[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
*[[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

===PHP Migration===

'''Ingredients:''' */php, modules/*.php

BGA recently migrated to from 7.4 to 8.2 then 8.4.
New php has new rules and deprecations.

There is a tool that can help you do the migration automation, which is php module called rector https://getrector.com/.
Below is the recipe that converts variables in strings like ${var} (which is deprecated) to {$var}.

1. Install the module
composer global require --dev rector/rector
2. Go to your project directory, commit your code first before this!

3. Create a rector.php file on top level with the following content:
<pre>
<?php

use Rector\Config\RectorConfig;
use Rector\Php82\Rector\Encapsed\VariableInStringInterpolationFixerRector;

return RectorConfig::configure()
->withPaths([
__DIR__
])
// A. whole set
//->withPreparedSets(typeDeclarations: true)
// B. or few rules
->withRules([
VariableInStringInterpolationFixerRector::class
]);
</pre>
4. Dry run (mine is on linux, not sure where global install on windows)
~/.config/composer/vendor/bin/rector process --dry-run

5. If happy re-run without --dry-run

6. Can remove rector.php now (or can do different rules)

==Backend==

===Assigning Player Order===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

<div style="padding: 1em; background: #FFCDD2; color: #B71C1C">
<b>WARNING:</b> To prevent unfair advantage (e.g. collusion), the random order must be the default option and <b>non-random options should be limited to friendly mode.</b>
</div>

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch ($this->getGameStateValue('playerTeams')) {
case $this->TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case $this->TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case $this->TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case $this->TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
$this->DbQuery($sql);
$this->reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
$this->reloadPlayersBasicInfos();
</pre>

===Send different notifications to active player vs everybody else===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file
<pre>
bgaFormatText: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id) {
log = args.log_others;
}
return { log, args }; // you must return this so the framework can handle the default formatting
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notify->all('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

===Send transient notifications without incrementing move ID===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

;In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notify->all('cardsPreview', '', $args);
</pre>

Note: you cannot have code that send notification or even changes state after this, and you cannot reset this variable back either because it only takes effect when you exit action handling function

==Assorted Stuff==

===Out-of-turn actions: Un-pass===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does that and hook it up.

In states.inc.php add an action to MULTIPLE_ACTIVE_PLAYER state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
$this->setAjaxMode();
$this->game->actionCancel();
$this->ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectator
switch (stateName) {
case 'playerTurnMultiPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.bgaPerformAction("actionCancel", null, { checkAction: false }); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

Note: same technique can be used to do other out-of-turn actions, such as re-arranging cards in hand, exchanging resources, etc (i.e. if permitted by rules, such as "at any time player can...")

===Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states.
Also when you do that sometimes you want to change the state prompt, see below 'Change state prompt'

===Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
*When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
*When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
*Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
*When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
*Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
*Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
*The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

===Action Stack - Using Client States===

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access.

Examples:
*Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
*Ultimate Railroads - action taking game where effects can be executed in any order
*Lewis and Clark - card game where actions executed as queue

There is two ways of implementing it - on the server or the client.
For the server see article below.
The requirement for client side stack implementation is - all action can be undone, which means
* No dice rolls
* No card drawn
* No other players interaction

No snippets are here, as this will be too complex but basically flow is:
*You have a action/effect stack (queue/list) as js object attached to "this", i.e. this.unprocessed_actions
*When player plays a card, worker, etc, you read the effect of that card from the material file (client copy), and place into stack
*Then we call dispatch method which pulls the next action from the stack and change client state accordinly, i.e. this.setClientState("client_playerGainsCubes")
* When players acts on it - the action is removed from the stack and added to "server action arguments" list, this is another object which be used to send ajax call, i.e. this.clientStateArgs
*If nothing left in stack we can submit the ajax call assembling parameters from collected arguments (that can include action name)
*This method allows cheap undo - by restoring server state you will wipe out all user actions (but if you need intermediate aninmation you have to handle it yourself)

Code can be found in Ultimate Railroads game (but it is random access list - so it a bit complex) and Lewis and Clark (complexity - user can always deny part of any effect)

===Action Stack - Using Server States===

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
*Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
*After action processing is finished switch to game state which is "dispatcher"
*Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response. The "top" can be choice of multiple actions, in this case player has to chose one before resolving the effect.
*Player state knows about the stack and pulls arguments (argX) from the effect arguments of the db
*Player action should clear up the top effect, and can possibly add more effects, then switch to "dispatcher" state again
*If stack is empty, dispatcher can either pick next player itself or use another game state which responsible for picking next player

Code can be found in Tapestry and Terraforming Mars.
===Custom error/exception handling in JavaScript ===

;In ggg.php
Throw \BgaUserException with some easy-to-identify prefix such as "!!!" and a custom error code. DO NOT TRANSLATE this message text. The exception will rollback database transaction and cancel all changes (including any notifications).
<pre>
function foo(bool $didConfirm = false): void
{
// do processing for the user's move
// afterwards, you determine this move will end the game
// so you want to rollback the transaction and require the user to confirm the move first

if ($gameIsEnding && !$didConfirm) {
throw new \BgaUserException('!!!endGameConfirm', 9001);
}
}
</pre>

;In ggg.js
Override framework function showMessage to suppress the red banner message and gamelog message when you detect the "!!!" prefix
<pre>
/* @Override */
showMessage: function (msg, type) {
if (type == "error" && msg && msg.startsWith("!!!")) {
return; // suppress red banner and gamelog message
}
this.inherited(arguments);
},
</pre>

Deal with the error in your callback:
<pre>
fooAction: function (didConfirm) {
var data = {
foo: "bar",
didConfirm: !!didConfirm,
};
this.bgaPerformAction("fooAction", data).catch((error, errorMsg) => {
if (error && errorMsg == "!!!endGameConfirm") {
// your custom error handling goes here
// for example, show a confirmation dialog and repeat the action with additional param
this.confirmationDialog(
_("Doing the foo action now will end the game"),
() => this.fooAction(true)
);
}
});
},
</pre>

For custom global error handling, you could modify ajaxcallwrapper:
<pre>
ajaxcallwrapper: function (action, args, handler) {
if (!args) args = {};
args.lock = true;
args.version = this.gamedatas.version;
if (this.checkAction(action)) {
this.bgaPerformAction(
action,
args
).catch((error, errorMsg, errorCode) => {
if (error && errorMsg == "!!!checkVersion") {
this.infoDialog(
_("A new version of this game is now available"),
_("Reload Required"),
() => {
window.location.reload();
},
true
);
} else {
if (handler) handler(error, errorMsg, errorCode);
}
}
);
}
},
</pre>

===Force players to refresh after new deploy===

When you deploy a new version of your game, the PHP backend code is immediately updated but the JavaScript/HTML/CSS frontend code *does not update* for active players until they manually refresh the page (F5) in their browser. Obviously this is not ideal. In the best case, real-time tables don't see your shiny new enhancements. In the worst case, your old JS code isn't compatible with your new PHP code and the game breaks in strange ways (any bug reports filed will be false positives and unable to reproduce). To avoid any problems, you should force all players to immediately reload the page following a new deploy.

By throwing a "visible" exception (simplest solution), you'll get something like this which instructs the user to reload:

[[File:Force-refresh.png|950x950px]]

Or, if you combine this technique with the above custom error handling technique, you could do something a bit nicer. You could show a dialog box and automatically refresh the page when the user clicks "OK":

[[File:Reload-required.png|500x500px]]
; In ggg.php
Transmit the server version number in <code>getAllDatas()</code>.
<pre>
protected function getAllDatas(): array
{
$players = $this->getCollectionFromDb("SELECT player_id id, player_score score FROM player");
return [
'players' => $players,
'version' => intval($this->gamestate->table_globals[300]), // <-- ADD HERE
...
];
}
</pre>

Create a helper function to fail if the client and server versions mismatch. Note the version check uses <code>!=</code> instead of <code><</code> so it can support rollback to a previous deploy as well. ;-)
<pre>
public function checkVersion(int $clientVersion): void
{
if ($clientVersion != intval($this->gamestate->table_globals[300])) {
// Simplest way is to throw a "visible" exception
// It's ugly but comes with a "click here" link to refresh
throw new BgaVisibleSystemException($this->_("A new version of this game is now available. Please reload the page (F5)."));

// For something prettier, throw a "user" exception and handle in JS
// (see BGA cookbook section above on custom error handling)
throw new \BgaUserException('!!!checkVersion');
}
}
</pre>

Every action requires a parameter <code>int $version</code> and a call to <code>$this->checkVersion()</code> as the first line. The version check should happen before anything else, even before checking if the action is allowed (since possible actions could change between versions). If you are using auto-wired "act" action functions, modify each to start like this:
<pre>
#[CheckAction(false)]
public function actXxx(int $version, ...) {
$this->checkVersion($version);
$this->checkAction('actXxx'); // or $this->gamestate->checkPossibleAction('actXxx');
...
}
</pre>

;In ggg.js
Transmit the version (from gamedatas) as a parameter with every ajax call. For example, if you're already using a wrapper function for every ajax call, add it like this:
<pre>
ajaxcallwrapper: function (action, args) {
if (!args) args = {};
args.version = this.gamedatas.version; // <-- ADD HERE
this.bgaPerformAction(action, args);
},
</pre>

===Disable / lock table creation for new deploy===

If you are deploying a major new game version, especially if it involves upgrading production game databases, you may have a lot of angry players if you break their tables. Depending on your changes, you may be able to restore the previous version and fix the tables easily.

However, if a new deploy turns out bad and players created turn-based tables while it was live, it may be quite difficult to fix those tables, since they were created from a bad deploy.

The solution? You can announce in your game group that you are locking table creation, and then in your new version, add an impossible startcondition to an existing option.
Note: This only makes sense if you have a few games running in real time mode in the time of deployment, otherwise it won't achieve much, unless you wait at least a day for other turn based games to break (or not)

Here is an example of an option with only 2 values (if you don't have options at all you have to create a fake option to use this method, if you have more values - you have to list them all):

;In gameoptions.json
<pre>
"startcondition": {
"0": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ],
"1": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ]
},
</pre>
;In gameoptions.inc.php (older method if you have it in php)
<pre>
// TODO NEXT remove after testing deploy to upgrade, here 0 and 1 - replace with values of your option!
'startcondition' => [
0 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
1 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
],
</pre>

* Be sure to click "Reload game options configuration" after making this change, then test in studio (test that you cannot create any table)
* Deploy to production
*Now, when a player attempts to create a new table, they will see a red error bar with your "Maintenance in progress" message.
*Wait for screaming (if you have real times games in progress waiting 15 min probably ok, if you have only turn based games, probably a day)
*Once you confirm the new deploy looks good, you can revert the change in gameoptions.inc.php and do another deploy.

===Local Storage===

There is not much you can store in localStorage (https://developer.mozilla.org/docs/Web/API/Window/localStorage), since most stuff should be stored either in game db or in user prefrences,
but some stuff makes sense to store there, for example "zoom" level (if you use custom zooming). This setting really affect this specific host and specific browser, setting it localStorage makes most sense.

game.js
<pre>
setup: function (gamedatas) {
let zoom = localStorage.getItem(`${this.game_name}_zoom`);
this.setZoom(zoom);
...
},
</pre>
In this case setZoom is custom function to actually set it.
When zoom changed, for example when some buttons pressed, store current value (but sanitize it so it never so bad that game cannot be viewed

<pre>
setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
... do actual zooming stuff
},
</pre>

===Capture client JavaScript errors in the "unexpected error" log===

PHP (backend) errors are recorded in the "unexpected error" log, but JavaScript (frontend) errors are only available in the browser itself. This means you have no visibility about things that go wrong in the client... unless you make clients report their errors to the server.

;In actions.php:
<pre>
public function jsError()
{
$this->setAjaxMode(false);
$this->game->jsError($_POST['userAgent'], $_POST['msg']);
$this->ajaxResponse();
}
</pre>

; In game.php:
<pre>
public function jsError($userAgent, $msg): void
{
$this->error("JavaScript error from User-Agent: $userAgent\n$msg // ");
}
</pre>

;In game.js:
<pre>
define(["dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter"], function (dojo, declare) {
const uniqJsError = {};
...

return declare("bgagame.nowboarding", ebg.core.gamegui, {
...
/* @Override */
onScriptError(msg) {
if (!uniqJsError[msg]) {
uniqJsError[msg] = true;
console.error("⛔ Reporting JavaScript error", msg);
this.ajaxcall(
"/" + this.game_name + "/" + this.game_name + "/jsError.html",
{
msg,
userAgent: navigator.userAgent,
},
this,
() => {},
() => {},
"post"
);
}
this.inherited(arguments);
},
</pre>

==Algorithms ==

===Generate permutations in lexicographic order===

Use this when you have an array like [1, 2, 3, 4] and need to loop over some/all 24 permutations of possible ordering. This type of [https://www.php.net/manual/en/language.generators.syntax.php generator function] computes each possibility one at a time, making it vastly more efficient than either a normal iteration or recursive function that produce all possibilities up front.

<pre>
function generatePermutations(array $array): Generator
{
// https://en.wikipedia.org/wiki/Permutation#Generation_in_lexicographic_order
// Sort the array and this is the first permutation
sort($array);
yield $array;

$count = count($array);
do {
// Find the largest index k where a[k] < a[k + 1]
// End when no such index exists
$found = false;
for ($k = $count - 2; $k >= 0; $k--) {
$kvalue = $array[$k];
$knext = $array[$k + 1];
if ($kvalue < $knext) {
// Find the largest index l greater than k where a[k] < a[l]
for ($l = $count - 1; $l > $k; $l--) {
$lvalue = $array[$l];
if ($kvalue < $lvalue) {
// Swap a[k] and a[l]
[$array[$k], $array[$l]] = [$array[$l], $array[$k]];

// Reverse the sequence from a[k + 1] up to and including the final element
$reverse = array_reverse(array_slice($array, $k + 1));
array_splice($array, $k + 1, $count, $reverse);
yield $array;

// Restart with the new array to find the next permutation
$found = true;
break 2;
}
}
}
}
} while ($found);
}
</pre>

Usage:
<pre>
$cash = [4, 1, 2, 3, 4];
foreach ($this->generatePermutations($cash) as $p) {
// your code here to evaluate permutation $p
// first iteration: $p = [1, 2, 3, 4, 4]
// last (60th) iteration: $p = [4, 4, 3, 2, 1]
// break from loop once you achieve your goal
}
</pre>

[[Category:Studio]]

Game database model: dbmodel.sql

2025-09-27T13:04:38Z

Vagabond: Added a section on AUTO_INCREMENT behavior.

{{Studio_Framework_Navigation}}

In this file, you specify the database schema of your game.

This file contains SQL queries that will be executed during the creation of your game table.

'''Note:''' you can't change the database schema during the game.

__TOC__

== Create your schema ==

To build this file, we recommend you build the tables you need with the PhpMyAdmin tool (see the BGA user guide), and then export them and copy/paste the content to this file.

'''Note:''' the name of a column must not be the same as the name of the table, as the framework replay function relies on regexp substitution to save/restore the previous state in a clone table with another name.

Example: Deck component, see [[Deck]]

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Example: Euro Game. See details on database design for euro game at [[BGA_Studio_Cookbook#Database_for_The_euro_game]]
<pre>
CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Rules you should follow:

* Do not overcomplicate, you are dealing with games with 50-500 pieces!
** If you have 5 tables for a card game with 30 cards - it is overkill
* The database should only be storing dynamic data, all static data should be stored in material.php.inc
** Example: if you have cards that have power, color, and special abilities. In the database, you only need to store the card type, all the other properties should not be there. The only exception is if it changes during the game.
* Columns should be permanent, independent of the game data, i.e. location, type, position, row, etc.
** Example: do not create columns such as Country1, Country2, Country3, etc.
* Do not store translatable strings in the database, use an integer number of "ident" to access properties
** i.e. card type should be "22" or "bob_cat", instead of "Bob's cat"
* Create a separate module in PHP to handle all database queries, do a lot of type checking to prevent SQL injections

Example of method to handle a database query:

<pre>
// Set token state
function setTokenState($token_key, $state) {
self::checkState($state); // ensure state is number
self::checkKey($token_key); // ensure key is alphanum
$sql = "UPDATE `{$this->table}`";
$sql .= " SET `token_state` = '$state'";
$sql .= " WHERE `token_key` = '$token_key'"; // don't need to escape anymore since we checked key before
self::DbQuery($sql);
return $state;
}
</pre>

== Default tables ==

By default, BGA creates four tables for your game: '''global''', '''stats''', '''gamelog''', and '''player'''.

You '''MUST NOT MODIFY''' the schemas of the '''global''', '''stats''', or '''gamelog''' tables (and you must not access them directly with SQL queries in your PHP code).

=== The '''player''' table ===

You may add columns to the '''player''' table. It is very practical to add simple values associated with players. '''NB:''' you must not alter existing columns created by the framework.

Example:
<pre>
ALTER TABLE `player` ADD `player_reserve_size` SMALLINT UNSIGNED NOT NULL DEFAULT '7';
</pre>

The commonly used columns of the default "player" table are:
* <strong>player_no</strong>: the index of a player in natural playing order (starting with 1)
* <strong>player_id</strong> (int)
* <strong>player_name</strong>: (note: it is better to access this data with the getActivePlayerName() or loadPlayersBasicInfos() methods)
* <strong>player_score</strong>: the current score of a player (displayed in the player panel). You must update this field to update a player's score.
* <strong>player_score_aux</strong>: the secondary score, used as a tie breaker. You must update this field according to tie breaking rules of the game (see also: [[Main_game_logic:_yourgamename.game.php#Manage_player_scores_and_Tie_breaker|Manage_player_scores_and_Tie_breaker]])

* <strong>player_table_order</strong>: gives an indication of the rank of the player by order of arrival in the lobby (starting with 1). It is not the same as player_no (which is the player order <u>within</u> the game). player_table_order is useful for setting custom teams if desired in a game option (for instance, 1st-2nd vs 3rd-4th).<br/><strong>Note:</strong> player_table_order ''only exists during game initialization'' (in the '''setupNewGame''' function). It is not added as a column in the '''players''' Db table.

<strong><u>CAUTION:</u></strong> '''player_table_order''' is not guaranteed to be equal to the rank of the player in the table. For example, in a four-player game, if the table was full but the third player leaves before the game starts, the fourth player becomes the third on this table <u>but</u> their player_table_no is still equal to four! If another player then joins, their player_table_no will then be 5.<br />Thus, it is essential to normalize these values first in the game setup if you wish to use them to prevent bugs at game launch. For example, if the set of player_table_order are <player A>: 3, <player B>: 2, <player C>: 5, <player D>: 7, you see that you can't read those values as ranks directly, but you can still deduce that <player B> was first on the table, then <player A>, then <player C>, and then <player D> 😉

See [https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Assigning_Player_Order Assigning Player Order] in the '''BGA Studio Cookbook''' for an example.

== CREATE TABLES ==
You can create tables, using engine InnoDB.
See examples above on how to create tables.
Pay attention to the following:
* Always add IF NOT EXISTS
* Always set ENGINE=InnoDB DEFAULT CHARSET=utf8
* Define primary keys
* If you create NOT NULL fields after the game has gone into production, make sure you took care of the database migration

'''Note''': if you use comments, then you must not do it in the same line as the code.

Example:

<pre>
`activated` BOOL NOT NULL DEFAULT 1, -- activated or not
</pre>

will also comment out the whole column `activated` BOOL, and that code will not be executed.

== PHP ==
Database initialization should be in the function setupNewGame() in 'gamename.game.php'.

Database schema migration should be in the function upgradeTableDb(), see below.

Warning: all CREATE/ALTER tables and views should be in dbmodel.sql. Do not call these queries from PHP to avoid implicit commits https://dev.mysql.com/doc/refman/5.7/en/implicit-commit.html
which will cause issues. The only time you can do such queries from PHP is in the upgradeTableDb() method.

== Errors Log ==
To trace Database creation, check the logs that you can access in /admin/studio.

== Post-release database modification ==
If you want to modify your database schema after the first release of your game to production, then you should implement the upgradeTableDb() method, see [[Post-release phase#Updating the database schema|Updating the database schema after release]]

== Uses and misuses of AUTO_INCREMENT ==

AUTO_INCREMENT is not particularly well-named; it's best to think of it as simply guaranteeing uniqueness of a column value. Try to design your schema and model so you don't require strictly-increasing-by-one identifiers; do not assume that the next row inserted will have a value one larger than the current maximum.

While it does generally produce consecutive values, it does not guarantee contiguous generation (i.e. you can end up with "skipped" numbers). Technically you can even end up with later-number rows being inserted earlier (you'd likely only notice or care about that if you also had a "creation_timestamp" column, though, and wanted it to be "in sync" with the auto_incremented column).
More details can be found [https://dev.mysql.com/doc/refman/8.4/en/innodb-auto-increment-handling.html#innodb-auto-increment-configurable here]

[[Category:Studio]]

Counter

2024-10-27T16:37:16Z

Vagabond: Update example to avoid use of format_block(), and actually works; use getPlayerPanelElement() instead of using the overall playerboard div.

{{Studio_Framework_Navigation}}

This is very simple control that allow to set/get numeric value from inner html of div/span, and provides animation on from/to value. It is used for the built-in scoreboard element scoreCtrl.

== Dependency ==

Don't forget to add '''ebg/counter''' as a dependency (this should be standard in the new game template):

// in your game js
define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter" /// <==== HERE],

== Setup a counter ==

<pre>
var counter = new ebg.counter();
counter.create(targetId);
</pre>

Where '''targetId''' either string or dom element, which already exists in the template, which will be used to display the counter value.
For example:
<pre>
<span id="my_counter"></span>
</pre>

In reality you will have a counter per player, so probably want to create a counter per player, in this case target Id can be 'hand_size_player_' + player_id and you create it in the loop for all players and store as class member. See example below on how to inject per-player sections.

== API ==
;create(target)
:associate counter with existing target DOM element

;getValue()
:return current value

;incValue(by);
:increment value by "by" and animate from previous value

;setValue(value);
:set value, no animation

;toValue(value);
:set value with animation

;disable()
:Sets the value to "-". Note it just changes display value once, it does not actually disable it, i.e. if you set it again, it will be shown again

;speed
:Duration of the animation, default is 100
const x = new ebg.counter()
x.speed = 300; // to make it slower

Typescript declaration (if you need it for ide)
<pre>
declare class Counter {
speed: number; // duration of the animation, default is 100ms

create(target: string): void; // associate counter with existing target DOM element
getValue(): number; // return current value
incValue(by: number): number; // increment value by "by" and animate from previous value
setValue(value: number): void; // set value, no animation
toValue(value: number): void; // set value with animation
disable(): void; // Sets value to "-"
}
</pre>

== Players panels ==

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

First, create a new JS template string function and variables to hold your counter(s) in your template (tpl) file.

<pre>
stone_counters: {},
jstpl_player_board: function(player) {
return
`<div class="cp_board">
<div id="stoneicon_p${player.player_id}" class="gmk_stoneicon gmk_stoneicon_${player.player_color}"></div>
<span id="stonecount_p${player.player_id}">0</span>
</div>`;
},
</pre>

Then, add this piece of code in the '''setup''' function of your JS file to add this template to each player panel:

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

// Setting up players boards if needed
var player_board_div = this.getPlayerPanelElement(player_id);
dojo.place( jstpl_player_board( player ), player_board_div );

// create counter per player
this.stone_counters[player_id] = new ebg.counter();
this.stone_counters[player_id].create( 'stonecount_p'+player_id );
}
</pre>

Often, you have to distinguish between the current player and other players. In this case, create another JS template (ex: jstpl_otherplayer_board) and use it where "player_id" is different than "this.player_id".

[[Category:Studio]]

Game interface logic: Game.js

2024-10-27T16:28:46Z

Vagabond: /* Counters */

{{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 ===
Please use the "ebg/counter" library, documented at [[Counter]].

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

Game interface logic: Game.js

2024-10-27T16:28:09Z

Vagabond: Point people at `ebg.Counter` instead of describing the older legacy counters API.

{{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 ===
Please use the "ebg/counter", documented at [[Counter]].

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