Board Game Arena - User contributions [en]

Gamehelpvintagerevival

2026-10-08T12:52:00Z

Firgon: layout

In '''Vintage Revival''', you run a workshop, in which you salvage an repair vintage items and arrange them in a collection.

The three goal cards at the right show you how to score points. You also score for repairing items and placing inventory tiles.

The game is played over 5 rounds. Each round comprises 3 phases:

# Draw vintage items: Each player gets a hand of 4 tiles, one each of sizes 2x2, 2x4, 3x2, and 3x3.
# In four draft turns, players keep and place 1 tile from hand and pass the rest: clockwise in odd rounds, counter-clockwise in even rounds.
# After placing 4 tiles in a round, each player may place 1 inventory tile (from 5 at the start of the game) or 2 spare parts of their choice.

==== Anatomy of vintage items: ====

===== Repair cost: =====
There are 1 or 2 symbols at the top left (cog, screw, or wire) showing what the item needs to count for scoring.

===== Spare parts: =====
The up to 4 dark symbols at the bottom show what you get from the item if you salvage it (see next section).

===== Sparkles: =====
Tiles with sparkles are considered rare and count for the goal card at the bottom.

===== Decade: =====
50s to 90s, also reflected by the wallpaper color in the background. Relevant for the goal card in the middle.

=== Placing tiles: ===
When you select a tile in the draft, you must make a choice:

* Place it face down as a parts donor to get spare parts (shown at the bottom of the tile).

OR

* Place it face up to potentially score points (once it is fully repaired).

When placing a face-down tile ADJACENT to a face-up one or vice versa, if the face-up tile needs spare parts from the face-down tile, they are automatically transferred.

If there is a choice, you must select it yourself by clicking the spare part and the target icon.

An item is considered fully repaired if all of its cost icons are covered by spare part tokens.

Empty parts donors (face-down tiles) are removed automatically, if possible. Your collection may never split into multiple separated parts.

You may place a new tile over a parts donor (thus, removing the parts donor and any remaining spare parts on it) if it keeps your collection in one chunk.

=== Inventory tiles: ===
At the end of each round, you can either place an inventory tile or 2 spare parts anywhere in your collection.

There are 5 inventory tiles to choose from, each scoring for items that touch it depending on a condition:

* Bookcase: tiles of the same color (the most common color touching it will be selected automatically)
* Chandelier: different item types (like phone, lamp, or sewing machine - regardless of decade); note that computer and typewriter are considered the same type
* Painting: different colors
* Plant: different tile sizes (2x2, 2x4, 3x2, and 3x3)
* Sofa: tiles of the same tile size (the most common tile size will be selected automatically)

If you don't place an inventory tile, you will have a greater selection later but you can only ever place 1 per round.

=== Scoring: ===

* '''Goals''' - according to the conditions on the cards; the table tells you how many points you get

* '''Inventory tiles''' - 1, 3, 6, or 10 points for 1, 2, 3, or 4 eligible tiles touching it, respectively
* '''Repaired items''' - 1 point for every fully repaired item Parts donors and items that have not been fully repaired do not count for scoring at all - as if they were not there.

In your player info box, you will see a live score during the game with "(max #)" indicating how many points you'd get if all current tiles were repaired.

Gamehelpforestshufflesmokymountains

2026-07-06T17:57:28Z

Firgon: Created page with "===Overview=== In '''Forest Shuffle: Smoky Mountains''', you create a forest according to your own vision—will you focus on densely planted tree lines or varied river landscapes? Skillfully place animals and plants on trees and along rivers to earn the most points. Whether a mighty predator, a humble gatherer, or a water dweller, every creature has its own unique preferences. ===How does this game differ from Forest Shuffle?=== Forest Shuffle: Smoky Mountains is a st..."

===Overview===
In '''Forest Shuffle: Smoky Mountains''', you create a forest according to your own vision—will you focus on densely planted tree lines or varied river landscapes? Skillfully place animals and plants on trees and along rivers to earn the most points. Whether a mighty predator, a humble gatherer, or a water dweller, every creature has its own unique preferences.

===How does this game differ from Forest Shuffle?===
Forest Shuffle: Smoky Mountains is a standalone game in the Forest Shuffle universe. The following features are different from the base game:

• '''River cards''' introduce a new card type to the game.

• River cards are played horizontally as '''individual rivers''' or attached '''below a tree'''.

• Some species can only live in water and must therefore be attached to river cards. They may not be attached to trees.

===Game Flow===
Choose one of two actions:

A) '''Draw 2 cards''': Either from the '''clearing''' or the '''deck'''; you may combine these as you wish. You may never have more than 10 cards in your hand.

B) '''Play 1 card''': Pay the '''cost''' by placing the corresponding number of cards from your hand into the clearing, and play a card from your hand into your forest. If applicable, carry out its '''effect''' or '''bonus'''.

===Trees and Rivers===
Trees always show exactly one species. When you play a tree, you can either place it '''separately''' in your forest '''<u>or'''</u> place another card from your hand face down as a '''universal river under this tree'''. Whenever you play a tree (with or without a universal river), you then reveal the top card of the deck and place it in the clearing. Trees, rivers, and trees with rivers have a different number of '''slots''' where '''split cards''' can be attached:

• '''Trees without a river''' have four slots: one each at the top, bottom, left, and right.

• '''Rivers''' also have four slots: two at the top and two at the bottom.

• '''Trees with a river''' have five slots: one each at the top, left, and right, and two at the bottom.

===Animals and Plants===
The split cards show different animals and plants. When playing a split card, you must place it in an empty slot on the corresponding side of a tree or river in your forest. Some split cards show the '''water requirement''' below their cost.

• Trees without a river only accept cards '''<u>without'''</u> water requirement.

• Stand-alone rivers only accept cards '''<u>with'''</u> water requirement.

• Trees with a river accept '''<u>any cards'''</u> (with or without water requirement) at the top and to the left and right. Below the river, however, you may place only cards '''<u>with'''</u> water requirement.

===Effects and Bonuses===
These are resolved after playing a card. First the effect, then the bonus.

• '''Effects''' are activated whenever you pay for and play a card. '''Immediate effects''' are activated immediately after playing, and '''permanent effects''' are activated whenever their condition is met.

• '''Bonuses''' are only activated if you pay for the card '''with matching cards'''. To do this, all cards you use to pay must show the same tree symbol as the card just played.

===Checking the Clearing===
If there are 10 or more cards in the clearing at the end of your turn, the clearing is emptied (cards are removed from the game).

===Special Case===
If you are unable to perform either of the two actions, reveal your hand cards. Then place two of them into your cave and draw 2 new cards from the deck into your hand. This ends your turn.

===End of the Game===
As soon as the '''3rd Winter card''' is revealed from the deck, the game ends '''immediately'''.

Gamehelparctica

2026-05-18T18:57:21Z

Firgon: Created page with "==OVERVIEW:== In ARCTICA, players must develop their ecosystem by playing Fauna and putting animal species on the Arctic map, in order to score the most Biodiversity Points at the end of the game. ====ACTIVE PLAYER:==== # Place the action pawn on an available space of the action board. Each space is connected to two action wheels. You must then rotate one of the two connected wheels by one quarter turn, in either direction. # You then perform the two actions linked t..."

==OVERVIEW:==
In ARCTICA, players must develop their ecosystem by playing Fauna and putting animal species on the Arctic map, in order to score the most Biodiversity Points at the end of the game.

====ACTIVE PLAYER:====

# Place the action pawn on an available space of the action board. Each space is connected to two action wheels. You must then rotate one of the two connected wheels by one quarter turn, in either direction.
# You then perform the two actions linked to your action pawn, in the order of your choice.

====NON ACTIVE PLAYERS:====

As soon as the active player has chosen their two actions, you may, simultaneously with the other non-active players, choose one action among the two selected.

== ACTIONS: ==
=== Fauna ===
[[Fichier:Fauna action.png|gauche|sans_cadre|90x90px]]This action allows you to play a Fauna card into your ecosystem:

Pay its cost, shown in the bottom-left corner of the card, by discarding a number of cards from your hand equal to its cost. 

The card will either go to:

* the left of your player board if the animal is long-generation (black background under the cost)
* the right if the animal is short-generation (orange background under the cost)

Resolve all effects shown in the Flash banner (to the right of the lightning bolt). Each animal also places one token of its type into the corresponding wheel in the next available space. (If there are no spaces for an animal token, the card is unplayable). 

Note: Some cards have placement requirements shown just above the cost. You must have the required badges before playing the card.

=== Reproduction ===
[[Fichier:Reproduction.png|gauche|sans_cadre|80x80px]]
This action allows you to reproduce one of the two species currently on top of your short-generation or long-generation columns:

Choose the animal to reproduce, which will add one species token to the corresponding wheel, in the next available space. (If full, the Reproduce action cannot be taken).

The card used for reproduction is then placed at the back of its column. 

''Note: You cannot do the Reproduce action with your two starting Generation Cards.''

=== Ability ===
[[Fichier:Ability.png|gauche|sans_cadre|84x84px]]
This action allows you to use the ability of one of the two species on top of your short or long-generation columns.

Choose the animal whose ability you want to use.

Resolve all effects shown in the top-left banner of the card.

The card used for an ability is then placed at the back of its column. 
=== Flora x2 ===
[[Fichier:Flora x2.png|gauche|sans_cadre|158x158px]]Gain 2 Flora, which are placed on your long-generation wheel, in the next available spaces. If the wheel is full, the Flora tokens are placed directly in your release area.

=== Migration x2 ===
[[Fichier:Migration action.png|gauche|sans_cadre|98x98px]]Perform 2 movements on the Arctic Circle (surrounding the action board). For each movement:

Choose one of your animal tokens on the Arctic Circle to be moved one space clockwise.

Gain the bonus shown on the destination space.

Note: When one of your animal tokens reaches Ice tile number #6, there is no automatic bonus. However you may optionally pay 1 Flora each for any number of your animal tokens present. For each Flora spent: gain 3 Biodiversity Points and return one of your animal tokens on ice tile #6 to your release area. Note 2: Birds and terrestrial mammals cannot end a movement on a space without an ice tile. They always move to the next space, gaining only the bonus of the arrival tile.
=== Draw ===
[[Fichier:Draw 2 cards.png|gauche|sans_cadre|90x90px]]Gain 2 cards. You may never exceed 9 cards in hand.

=== Rotate Wheels + 1 Card ===
[[Fichier:Rotate wheels + 1 Card.png|sans_cadre|134x134px]]

All your wheels rotate by one step, and you gain 1 card.

=== Rotate Wheels + 1 Migration ===
[[Fichier:Migration +. 1 card action.png|gauche|sans_cadre|157x157px]]

All your wheels rotate by one step, and perform 1 movement on the Arctic Circle.

=== Colony Action ===
[[Fichier:Colony.png|gauche|sans_cadre|90x90px]]
This action allows players to place animal tokens from their release area onto the central map.
If the Active Player chooses this action, it is not simultaneous. Players take turns, one after another, clockwise starting with the Active Player.

Steps:

1) Pay 1 Flora.

2) Choose a single species type from your release area.

3) Place as many tokens of that species as you wish on the central board, in spaces for that species type.

4) Gain the bonus on the space, if any, or pay its cost if required.

5) If you create a connection with another token:

-both players gain the connection bonus shown between the two spaces.

-If you connect with one of your own tokens already on the map, you gain the bonus only once. 

== END OF ROUND: ==
After 5 Active Player action selections, the round ends.

---During rounds 1, 2, and 3, only 2 regions are affected.

---During the fourth and final round, all 3 regions are affected.  

=== 1) Ice Melt ===
The ice tile with the number of the current round is removed. 

Any animal tokens on that tile are returned to the player’s reserve.

=== 2) Majority ===
In each affected region, a majority is checked. 

The player with the most animal tokens in that region scores the highest reward. (The distribution of majority rewards is shown on the current end-of-round card.)

=== 3) Collapse (from round 2 onward) ===
If you have no available tokens of a species left in your supply (you start the game with 6 of each family), that species collapses.

When a collapse occurs:

1) Discard 3 of your tokens of that species (your choice) from the map or your player board.

2) Gain 4 cards and 2 Flora. 

=== 4) Endangered Animals ===
Pay 1 Flora for each endangered badge in your ecosystem. 

If you cannot or do not wish to pay, you must destroy one card with an endangered badge in your ecosystem.

=== 5) Events ===
An event tile covers part of each affected region.

--- Each region is divided into 3 sub-regions; only one is affected randomly.

--- Animal tokens in that sub-region are discarded unless their owner pays 1 Flora to save them.

--- If saved, the token flees to the northern Arctic Circle and you gain the bonus of the arrival tile.

--- If the token is in the central sub-region, its owner chooses the destination space.

--- Birds and terrestrial mammals cannot flee to a space without an ice tile; pay 1 additional Flora to move them to the next ice-covered space. 

== END OF GAME: ==
At the end of the fourth round:

---Gain 1 Biodiversity Point for each animal token on your player board.

---Gain 1 Biodiversity Point for each pair of 2 Flora tokens on your player board.

---Gain all Biodiversity Points shown on the cards in your ecosystem. 

The player with the most Biodiversity Points wins the game. In case of a tie, the player with the most Fauna cards in their ecosystem wins. If there’s still a tie, the tied players share the victory.

Gamehelpgretchensgarden

2026-03-20T09:19:01Z

Firgon: Created page with "Over the course of 12 rounds, you try to build the most valuable succulent collection. ==Action Phase== On your turn, choose one of four actions: '''Note:''' BGA will only show you actions that are available to you at the moment. Set up will be provided according to official rules and player count. For reference, please refer to the official rule book. '''1. Buy''': Buy a plant or pot from the market and add it to your collection, using leaves from your '''Money Tre..."

Over the course of 12 rounds, you try to build the most valuable succulent collection.

==Action Phase==

On your turn, choose one of four actions:

'''Note:''' BGA will only show you actions that are available to you at the moment. Set up will be provided according to official rules and player count. For reference, please refer to the official rule book.

'''1. Buy''': Buy a plant or pot from the market and add it to your collection, using leaves from your '''Money Tree''' as currency. Money tree is the only one with this ability, so you want to keep it well stocked.

'''2. Cut''': Cut an opponent’s plant and add it to your collection. To do so, the opposing plant must have at least 1 leaf and there must be at least 1 copy of that plant left in the supply.

'''3. Tend''': This action consists of two parts, “Moving” and “Watering and Growth”. Carry them out in any order:
*<u>Moving:</u> Displace up to 2 plants one after the other or swap 2 plants.
*<u>Watering and Growth:</u> Gain 2 water from the supply and distribute that water together with any water from your '''watering can''' on your pots, placing any excess water in the watering can. Then carry out an ''additional Growth phase'' (see “Growth Phase” below).

'''4. Flower''': Flower a plant in your collection. To do so, it must be in a same-colored pot or a wild pot and the '''Flower''' of that color must still be available. There is only one '''Flower''' of each color. Place the matching Flower on the plant. From now on, that beauty wants to be left untouched: it cannot receive any more water, nor grow, nor be moved or cut.

The following phases are played simultaneously by all players:

==Weather Phase==
Gain water according to the current weather card and distribute that water on your pots or watering can. There are 12 weather cards and they act as round counter for 12 rounds in total.

==Growth Phase==
'''Note:''' BGA carries out this phase automatically.

Water turns to leaves in pots full of water: water drops will be flipped to become leaves automatically.

'''Note:''' Regard the total of leaves your pot allows (= number on the top left of any pot card). Any access your pot can not hold will go back to the supply.

==Clean-Up Phase==
'''Note:''' BGA carries out this phase automatically.

*All cards in the market gain one additional leaf or water token. Plants with 4 leaves and pots with more water than they can hold get discarded. Then the market gets replenished.

*Reveal a new weather card.

*Pass the start player marker clockwise to the next player.

==Game End and Scoring==

The game ends after 12 rounds. You get points in the following categories:
*'''1 point''' for each leaf on your plants, except the money tree.
*'''7 points''' for each Flower in your collection.
*Points for certain plant colors according to their printed '''effect''': purple, yellow, orange, red, and special plants. To get an overview on scoring conditions, use mouse over or refer to the appendix.
*'''2 points''' for each pot in your collection, including the three pots you started your collection with.

Gamehelptipperary

2026-03-17T16:13:04Z

Firgon: /* Objective */ Thomas was probably an IA and had totally invented new rules.

== Objective ==
Build the most prosperous Irish county by strategically placing landscape tiles. Players earn points through territory expansion, resource management, and various bonuses. The player with the highest total score after 12 rounds wins.

== Components & Key Terms ==

* '''Landscape Tiles:''' Feature various symbols, including sheep, ruins, distilleries, bogs, and meadows.
* '''The Wheel:''' Determines which of the five offer stacks players must choose from each round.
* '''Bonus Tiles:''' Special rewards earned by connecting at least two bog symbols.

== Gameplay ==
The game lasts 12 rounds (reduced to 10 rounds in a 5-player game). Each round consists of two main steps:

# '''Drafting Tiles:''' The active player spins the wheel. The pointer indicates the specific stack from which all players must select their tile.
# '''Placing Tiles:''' The selected tile must be placed adjacent to the starting space or a previously placed tile.

== Symbol Resolutions ==

* '''Distilleries:''' When a distillery is placed adjacent to a grain field (or vice versa), you produce whiskey and advance your barrel one step on the track. This progress can also grant you additional sheep.
* '''Ruins:''' Creating a row of three ruins allows you to activate bonus "filler" tiles during end-game scoring.
* '''Sheep:''' Sheep form flocks. Only your largest continuous flock will score points at the end of the game.
* '''Bogs:''' Placing at least two bogs adjacently creates a "Protected Area," awarding you a bonus tile.

== End of Game & Scoring ==
After the final round, players calculate their scores based on the following:

* '''Meadows:''' Score your largest rectangular, gapless area of meadow fields (Length x Width).
* '''Sheep:''' 1 point per sheep in your largest continuous flock. The player with the overall largest flock receives a +5 point bonus.
* '''Exploration:''' A 5-point bonus is awarded if you entirely surround your starting castle tile.
* '''Whiskey:''' Points are awarded based on your barrel’s final position on the whiskey scale.
* '''Stone Circles:''' Each stone circle scores between 1 and 4 points.

The player with the highest total score is declared the winner.

Game interface logic: Game.js

2026-03-16T19:19:31Z

Firgon: /* Notifications */ Add the second way to write notification functions

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

'''this.bga.players.getPlayerAvatarUrl(playerId, size): string'''
Return the player avatar url. The size of the avatar can be 32, 50, 92 or 184 (default). Set playerId 0 to get the default avatar.

== Accessing and manipulating the DOM ==

=== Main game area ===

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

'''Vanilla JS style'''
document.getElementById('my_element').style.display='none'; // set
const display = document.getElementById('my_element').style.display; // get
document.getElementById('my_element').style.removeProperty('display'); // remove

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

(DEPRECATED, prefer native JS) With dojo.style you can modify the CSS property of any HTML element in your interface.
dojo.style( 'my_element', 'display', 'none' ); // set

'''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
document.querySelectorAll(`.${aclass}`).style.styleName = styleValue; // native JS
dojo.query(`.${aclass}`).style(styleName, styleValue); // dojo, deprecated

=== Classes ===
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).
document.getElementById(token_id).classList.add('possibleMove'); // add class
document.getElementById(token_id).classList.remove('possibleMove'); // remove class
document.getElementById(token_id).classList.toggle('possibleMove'); // toggle class, classList.toggle('possibleMove', args.isPossibleMove); to do add/remove based on a boolean
const myclasses = ['a','b'];
document.getElementById(token_id).classList.add(...myclasses); // add 2 classes / a dynamic number of classes
document.querySelectorAll(".hand .card").forEach(elem => elem.classList.add('possibleMove')); // add classes to a querySelectorAll result

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 '''classList.contains''' method.

Deprecated dojo functions:
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

=== Element data ===

With dataset you can access or change the value of an attribute or property of any HTML element in your interface.
document.getElementById(token).dataset.tokenColor='red'; // CSS selector: .token[data-token-color="red"] { ... }

The difference with classes is that a data can only have one value, so setting tokenColor to green will remove red automatically, while using classes you would need to remove token_color_red and add token_color_green.

=== Queries ===

'''Native JS query'''
const cards = document.querySelectorAll(".hand .card");// all cards in all hands
const cards = document.getElementById('hand').querySelectorAll(".card");// all cards in specific hand
const card = document.querySelector(".hand .card");// first card or null if none (super handy)

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

(deprecated) 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>

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

Side note : you can receive the full notification data as second argument of the notification function. You can access that way to the message of the notification (but also, more technical data like : move_id, table_id, uid...)

<pre> notif_playedCard: async function(args, notif) {
const notif_message = notif.log;
}
</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>

'''Using Notifications in JS State Classes'''

You can put the notification function (notif_doSomething) in your JS State Class and register this with 'handlers' :
<pre>
setupNotifications: function() {
this.bga.notifications.setupPromiseNotifications({
(...)
handlers: [this, ...this.bga.states.getStateClasses()],
(...)
});
}
</pre>

Warning : if the same notif_doSomething is defined is Game.js and several State classes, they all will be called!

'''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->bga->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->bga->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->bga->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->bga->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->bga->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->bga->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 [[#Status bar buttons|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'''.

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

'''this.bga.images.getImgUrl(filename?: string): string'''

Returns the URL of an image, if you need to set it in JS (usually they will be referenced in the CSS file and don't need JS).
Example of use:
<pre>
const boardImgUrl = this.bga.images.getImgUrl('board.jpg');
const expansionBoardImgUrl = this.bga.images.getImgUrl('expansion/board.jpg'); // you can use subfolders
const imgUrl = this.bga.images.getImgUrl(); // you can use empty, and append the image file name later on : it will return the URL until `img/`
</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 | { abortSignal: AbortSignal, pausable: 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
});

Example of confirm button with autoclick animation and a pause button:
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: { pausable: 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 ? { pausable: true } : null, // adapt to your user preference id and values
});

Example of confirm button with autoclick animation and a button to stop the timer: (use ONLY if pausable setting isn't enough)
const abortController = new AbortController();
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: { abortSignal: abortController.signal }
});
this.bga.statusBar.addActionButton(_("Let me think!"), () => abortController.abort(), { color: 'secondary' });

Example of confirm button with autoclick animation and a button to stop the timer, and a user preference about timer: (use ONLY if pausable setting isn't enough)
const isUsingTimer = this.bga.userPreferences.get(100) == 1;
const abortController = new AbortController();
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: isUsingTimer ? { abortSignal: abortController.signal } : false
});
if (isUsingTimer) {
this.bga.statusBar.addActionButton(_("Let me think!"), () => abortController.abort(), { color: 'secondary' });
}

Note: the button label can be HTML, if you want to put some images on the label.

;'''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-03-16T19:16:35Z

Firgon: /* Notifications */

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

'''this.bga.players.getPlayerAvatarUrl(playerId, size): string'''
Return the player avatar url. The size of the avatar can be 32, 50, 92 or 184 (default). Set playerId 0 to get the default avatar.

== Accessing and manipulating the DOM ==

=== Main game area ===

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

'''Vanilla JS style'''
document.getElementById('my_element').style.display='none'; // set
const display = document.getElementById('my_element').style.display; // get
document.getElementById('my_element').style.removeProperty('display'); // remove

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

(DEPRECATED, prefer native JS) With dojo.style you can modify the CSS property of any HTML element in your interface.
dojo.style( 'my_element', 'display', 'none' ); // set

'''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
document.querySelectorAll(`.${aclass}`).style.styleName = styleValue; // native JS
dojo.query(`.${aclass}`).style(styleName, styleValue); // dojo, deprecated

=== Classes ===
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).
document.getElementById(token_id).classList.add('possibleMove'); // add class
document.getElementById(token_id).classList.remove('possibleMove'); // remove class
document.getElementById(token_id).classList.toggle('possibleMove'); // toggle class, classList.toggle('possibleMove', args.isPossibleMove); to do add/remove based on a boolean
const myclasses = ['a','b'];
document.getElementById(token_id).classList.add(...myclasses); // add 2 classes / a dynamic number of classes
document.querySelectorAll(".hand .card").forEach(elem => elem.classList.add('possibleMove')); // add classes to a querySelectorAll result

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 '''classList.contains''' method.

Deprecated dojo functions:
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

=== Element data ===

With dataset you can access or change the value of an attribute or property of any HTML element in your interface.
document.getElementById(token).dataset.tokenColor='red'; // CSS selector: .token[data-token-color="red"] { ... }

The difference with classes is that a data can only have one value, so setting tokenColor to green will remove red automatically, while using classes you would need to remove token_color_red and add token_color_green.

=== Queries ===

'''Native JS query'''
const cards = document.querySelectorAll(".hand .card");// all cards in all hands
const cards = document.getElementById('hand').querySelectorAll(".card");// all cards in specific hand
const card = document.querySelector(".hand .card");// first card or null if none (super handy)

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

(deprecated) 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>

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

You can receive the full notification data as second arguments of the function. You can access that way to the message of the notification (but also, more technical data like : move_id, table_id, uid...)

<pre>
notif_playedCard: async function(args, notif) {
}
</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>

'''Using Notifications in JS State Classes'''

You can put the notification function (notif_doSomething) in your JS State Class and register this with 'handlers' :
<pre>
setupNotifications: function() {
this.bga.notifications.setupPromiseNotifications({
(...)
handlers: [this, ...this.bga.states.getStateClasses()],
(...)
});
}
</pre>

Warning : if the same notif_doSomething is defined is Game.js and several State classes, they all will be called!

'''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->bga->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->bga->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->bga->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->bga->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->bga->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->bga->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 [[#Status bar buttons|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'''.

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

'''this.bga.images.getImgUrl(filename?: string): string'''

Returns the URL of an image, if you need to set it in JS (usually they will be referenced in the CSS file and don't need JS).
Example of use:
<pre>
const boardImgUrl = this.bga.images.getImgUrl('board.jpg');
const expansionBoardImgUrl = this.bga.images.getImgUrl('expansion/board.jpg'); // you can use subfolders
const imgUrl = this.bga.images.getImgUrl(); // you can use empty, and append the image file name later on : it will return the URL until `img/`
</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 | { abortSignal: AbortSignal, pausable: 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
});

Example of confirm button with autoclick animation and a pause button:
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: { pausable: 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 ? { pausable: true } : null, // adapt to your user preference id and values
});

Example of confirm button with autoclick animation and a button to stop the timer: (use ONLY if pausable setting isn't enough)
const abortController = new AbortController();
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: { abortSignal: abortController.signal }
});
this.bga.statusBar.addActionButton(_("Let me think!"), () => abortController.abort(), { color: 'secondary' });

Example of confirm button with autoclick animation and a button to stop the timer, and a user preference about timer: (use ONLY if pausable setting isn't enough)
const isUsingTimer = this.bga.userPreferences.get(100) == 1;
const abortController = new AbortController();
this.bga.statusBar.addActionButton(_('Confirm'), () => this.bga.actions.performAction('actConfirm', {}), {
autoclick: isUsingTimer ? { abortSignal: abortController.signal } : false
});
if (isUsingTimer) {
this.bga.statusBar.addActionButton(_("Let me think!"), () => abortController.abort(), { color: 'secondary' });
}

Note: the button label can be HTML, if you want to put some images on the label.

;'''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]]

Gamehelpdragonoverload

2026-01-26T16:37:59Z

Firgon: Created page with "Try to win the majority of the habitats Playing a card Players take turns playing a card into a habitat on their side of the board either face-up or face-down. They can only play cards into habitats that are not full. A habitat is full when it has 3 cards. When playing a card face up, it must match the habitat it is placed in. When playing a card face down, it is not required to match the habitat. Players can only play a total of 3 face-down cards on their side of the..."

Try to win the majority of the habitats

Playing a card

Players take turns playing a card into a habitat on their side of the board either face-up or face-down. They can only play cards into habitats that are not full. A habitat is full when it has 3 cards.

When playing a card face up, it must match the habitat it is placed in.
When playing a card face down, it is not required to match the habitat. Players can only play a total of 3 face-down cards on their side of the board.
After playing a card, the opponent must take the card from the habitat‘s breeding zone (card on the board in the middle) into their hand and a new card is added to the breeding zone.

Check for habitat majority

After playing a card into a habitat, check the habitat majority. Players win a habitat by having the highest value of combined card value (only face-up cards) in that habitat. If so, move the habitat marker onto their side of the board. Otherwise, it stays where it is.

Game end

There are 3 ways to end the game.

If a player has all 5 animal tokens on their side of the board – they win the game immediately.
If a player cannot play a card – they lose the game immediately.
If both sides of the board are full (3 cards in each habitat).
If the game ends by both sides becoming full – players now reveal all their face-down cards and check the habitat majority in each of the 5 habitats. If the revealed card matches the habitat it is added to the total value, if not its value is 0.

The habitat marker is moved to the side with the highest value.
But if the value is double (or more) than their opponents, the habitat is overpopulated and the other player wins that habitat instead.
The player with the most habitats wins the game.

Bugsclarification forestshuffledartmoor

2025-10-07T09:28:36Z

Firgon: Created page with "== Please do not post bug report if "all bonuses don't work" (and sometimes, even if "one bonus doesn't work"). == ==== Bonuses are not Effects ==== You probably need to ckeck in the rules the difference between "Effect" (which is always triggered when you pay to place a card) and "Bonus" (which is triggered only if you pay with and only with matching cards). Bonus and effect are NEVER triggered if you place a card freely thanks to the effect (or the bonus) of an othe..."

== Please do not post bug report if "all bonuses don't work" (and sometimes, even if "one bonus doesn't work"). ==

==== Bonuses are not Effects ====

You probably need to ckeck in the rules the difference between "Effect" (which is always triggered when you pay to place a card) and "Bonus" (which is triggered only if you pay with and only with matching cards).

Bonus and effect are NEVER triggered if you place a card freely thanks to the effect (or the bonus) of an other card.

==== Shrubs are not Trees ====
Another one of the main reasons for "fake bug report" is a confusion between SHRUB and TREE. All cards that refer to "tree" doesn't work with "shrub" (ants, mushrooms, fat dormouse...)

Gamehelpforestshuffleprototype

2025-08-15T08:57:18Z

Firgon: Created page with "The '''Forest Shuffle Prototype''' is now being used for internal tests of the Forest Shuffle: Dartmoor Solo mode. This prototype follows the FS Solo Mode rules (outlined below). At the beginning of the game, you’ll choose one of the 15 objectives. Then the game will display the thresholds required to earn a bronze, silver, or gold medal. The game automatically plays Anna’s turns (Automa), but note that it '''DOES NOT CHECK''' if you’ve met the objective a..."

The '''Forest Shuffle Prototype''' is now being used for internal tests of the Forest Shuffle: Dartmoor Solo mode.

This prototype follows the FS Solo Mode rules (outlined below).

At the beginning of the game, you’ll choose one of the 15 objectives. Then the game will display the thresholds required to earn a bronze, silver, or gold medal.
The game automatically plays Anna’s turns (Automa), but note that it '''DOES NOT CHECK''' if you’ve met the objective at the end of the game.

After each game, please report the following to Maren:
* Which challenge you played, whether you completed it or not (and how close you were to succeeding).
* Your score.
* Any side strategies you used.
* Additional comments or feedback.

== Rules ==

==== Game Preparation ====
Set up the game as usual, with the following changes:
- Return cards from the draw pile to the box as you would for a 2-player game (45 cards).
- Use only **one winter card**, shuffled with the last 10 cards of the draw pile.
- Draw 6 cards into your hand and take **Cave 3**. In solo play, Cave 3 is always used, and its effect is resolved before the game begins.
- Shuffle the 20 Automa cards to form a face-down Automa deck.
- Choose a challenge and decide which medal level to aim for: **bronze, silver, or gold.** This determines your goal and minimum score.
- You always take the first turn.

====Course of Play ====
- Play your turns as normal.
- On each of Anna’s turns, reveal the top card of the Automa deck and carry out its action.

Gamehelpghostsgalore

2025-08-13T14:13:02Z

Firgon:

In Ghosts Galore, each player builds a ghost train by placing 9 tiles in a 3x3 grid. Tiles show track (straights, curves, double curves, and bridges) and up to 3 monsters of 9 different types, each of which scores in a particular way. Your goal is to score the most points by the end of the game from monsters, track, and printed points on the tiles.

== The Interface ==

When you open the game, you see your game board first and the other players' game boards next to or below it, depending on your screen size. Notice the little '''HELP''' button to the right of your board: By clicking it, a point overview sheet will slide open and tell you how each element of the game scores. If live scoring is enabled, you will see a scoring sheet at the bottom of the display at all times, which will tally your scores as you place tiles. Live scoring will '''NOT''' consider your hidden tile (see the "How to Play" section below on what that is) except when the game is over.

== How To Play ==

Over the course of 8 rounds, players will be drafting 1 tile each from a pool of tiles and place them in their grid any way they like. On the 9th and final round of the game, you will be placing your so-called "hidden tile", which you can see at the top right of the screen in an own area called "Your Hidden Tile".

Each round, a different player will begin and they will be prompted a single option in the status bar: to pick a tile from the deck. Either click that button or the draw pile to draw a tile from the deck, which will appear face up next to the pile. Then choose:
# Either you like the tile and place it in your grid, by clicking on the tile first, then on a space in your grid (or a different one if you misclick). You can rotate the tile via arrows that will appear to the left and right of the tile once it is selected. Confirm your placement by clicking the "Confirm" button in the status bar.
# Or click "Pass" in the status bar to wait and see what other tiles will appear that round. This does not skip your turn, it merely postpones it. All players will be placing 1 tile per round, at some point during that round.

Tiles that are passed on will appear in the "Tiles Available on the Table" section in the center of the screen. Once there are tiles there, the prompt at the start of a turn will let you choose whether you want to either pick a tile from the deck or an available one from the table.
# To pick a tile from the deck, again, click the "Pick" button or the draw pile. Once you do that, you cannot change your mind. You must either place the newly revealed tile or "Pass" and wait until it is your turn again to choose a different tile.
# To pick a tile from the face-up ones on the table, simply click that tile and place it, as described above.

Note: Once all but one player have chosen a tile, the remaining player will see '''ALL''' remaining tiles in the deck in the "Tiles Available on the Table" section and they can choose any one of those 5 tiles. (It's always 5 tiles for the remaining player.)

At any point during the game, you can pre-place your hidden tile by clicking it and placing it in your grid the same way you place tiles from the deck or table. Your hidden tile will be shown slightly transparent in your grid so you know that this is it. You can remove the tile (to place it somewhere else) by clicking the button in "The Hidden Tile" section at the top. On the 9th round at the latest, you will be prompted to place your hidden tile on the remaining spot in the 3x3 grid. If you did before, you can simply click "Confirm" in the status bar (if you're happy with your placement) or adjust the placement by rotating the tile.

Once all players have done so, the game will be over and the winner will be declared.

BgaAutofit

2025-07-30T09:11:53Z

Firgon: /* Using with TypeScript */

{{Studio_Framework_Navigation}}

'''[https://x.boardgamearena.net/data/game-libs/bga-autofit/1.x/demo/index.html Demo] [https://x.boardgamearena.net/data/game-libs/bga-autofit/1.x/docs/index.html Doc]'''

== Overview ==
'''bga-autofit''' is a javascript component that you can use in your game interface to make text fit some fixed-size boxes.

The main usage is to make translated text on game cards fix the dedicated space of the card image.

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

At the end of your game setup:
<pre>
BgaAutofit.init();
</pre>

On any HTML element with fixed size that contain text to be fitted into:
<pre>
<div class="my-class-for-fixed-size bga-autofit">${text}</div>
</pre>'''Note:''' If you add a bga-autofit div after the end of the setup, it wil work too! The component use a MutationObserver to detect new elements with this class, and apply the same autofit. Make sure you only call <code>BgaAutoFit.init();</code> once!

== 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-autofit/1.x/dist/bga-autofit.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: BgaAutofit is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock",
getLibUrl('bga-autofit', '1.x'),
],
function (dojo, declare, gamegui, counter, stock, BgaAutofit) {
(window as any).BgaAutofit = BgaAutofit; //trick
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.0''': Initial version

[[Category:Studio]]

BgaAutofit

2025-07-30T09:10:46Z

Firgon: /* Using with TypeScript */

{{Studio_Framework_Navigation}}

'''[https://x.boardgamearena.net/data/game-libs/bga-autofit/1.x/demo/index.html Demo] [https://x.boardgamearena.net/data/game-libs/bga-autofit/1.x/docs/index.html Doc]'''

== Overview ==
'''bga-autofit''' is a javascript component that you can use in your game interface to make text fit some fixed-size boxes.

The main usage is to make translated text on game cards fix the dedicated space of the card image.

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

At the end of your game setup:
<pre>
BgaAutofit.init();
</pre>

On any HTML element with fixed size that contain text to be fitted into:
<pre>
<div class="my-class-for-fixed-size bga-autofit">${text}</div>
</pre>'''Note:''' If you add a bga-autofit div after the end of the setup, it wil work too! The component use a MutationObserver to detect new elements with this class, and apply the same autofit. Make sure you only call <code>BgaAutoFit.init();</code> once!

== 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-autofit/1.x/dist/bga-autofit.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: BgaAutofit is not defined" error) :
<pre>
define([
"dojo",
"dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock",
getLibUrl('bga-autofit', '1.0.0'),
],
function (dojo, declare, gamegui, counter, stock, BgaAutofit) {
(window as any).BgaAutofit = BgaAutofit;
return declare("bgagame.reforest", ebg.core.gamegui, new Reforest());
});
</pre>

== Changelog ==
'''1.0.0''': Initial version

[[Category:Studio]]

Gamehelpforestshuffledartmoor

2025-07-01T12:52:25Z

Firgon: Created page with " ==Overview== In ''Forest Shuffle: Dartmoor'', you create a habitat for flora and fauna to thrive. Plant trees and shrubs, discover moor landscapes, and synergize your cards to earn the most points before winter. ==Turn Actions== Choose between one of two options: #'''Draw two cards''' from the clearing and/or deck and add them to your hand. Your hand limit is 10 cards. You can't take the draw action if you already have 10 cards. If you have 9 cards, you may only draw 1..."

==Overview==
In ''Forest Shuffle: Dartmoor'', you create a habitat for flora and fauna to thrive. Plant trees and shrubs, discover moor landscapes, and synergize your cards to earn the most points before winter.
==Turn Actions==
Choose between one of two options:
#'''Draw two cards''' from the clearing and/or deck and add them to your hand. Your hand limit is 10 cards. You can't take the draw action if you already have 10 cards. If you have 9 cards, you may only draw 1 card.
#'''Play one card from your hand''': pay its cost by discarding cards from your hand, then place the chosen card in the forest and carry out its effect. If your discards cause there to be 10 or more cards in the clearing, all cards in the clearing are removed at the end of the turn.
==Cards==
There are 5 types of cards: Trees and Shrubs, Moors, Forest Dwellers, and Winter.

'''TREE''' and '''SHRUB CARDS''' depict a single tree/shrub. To plant one in the forest, simply pay its cost. The cost amount shown in the brown rectangle at the top left of the card. To pay it, place a number of cards from your hand into the clearing equal to the cost.

Trees and shrubs provide a slot on each side (top, bottom, left, right) for you to add forest dwellers. Only 1 forest dweller per slot, unless a card says otherwise.

Each time you play a TREE, a card from the deck is added to the Clearing. '''<u>This DOES NOT apply to shrubs.</u>'''

'''MOOR CARDS''' depict a moor landscape and are placed sideways in your display after you pay their cost.

Moors provide two slots at the top and two slots at the bottom for forest dweller cards.

Some moors have permanent effects that you can use from your next turn on, e.g., some let you draw a card every time you play a certain type of card.

Other moors have scoring effects that apply at game end.

'''FOREST DWELLER CARDS''' are split. They depict two creatures on them, but only ONE of them may be played. These are the animals and plants that you can add to the forest.

To play a forest dweller, select an empty slot on a tree, shrub, or moor for the desired half of the card, then discard cards from your hand into the clearing equal to the cost. Note that moors only accept cards that are split into a top and bottom half.

Once a forest dweller is slotted onto a tree, shrub, or moor, the other half of the card is now hidden. Only the effects of the visible forest dweller may trigger.

Note that some cards give you a special bonus effect when you pay for them if ALL of the cards you discard bear the matching leaf symbol. On split cards, only one half of the card must bear the symbol.

When you have drawn the top 2/3rds of the deck the first '''WINTER CARD''' will be revealed. The other two WINTER CARDS were previously shuffled into the remainder of the deck and serve as a random end timer. When the 3rd winter card is drawn, the game ends immediately! You may not finish your turn.
==Game End==
Total the points of all visible cards in your forests, plus one point per card you hid in your cave (if any). None of their effects trigger.

The player with the most points wins!

Options and preferences: gameoptions.json, gamepreferences.json

2025-03-19T21:56:29Z

Firgon: /* Accessing User Preferences on the server */

{{Studio_Framework_Navigation}}

In <code>gameoptions.json</code>, you can define your game options (i.e. game variants).

In <code>gamepreferences.json</code>, you can define user preferences.

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

'''IMPORTANT:''' after edits to these files, you have to go to the control panel and press "Reload game options configuration" on Studio for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for player count, which is automatically handled). For example, whether to include ''The River'' in Carcassonne.
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, whether or not to prompt for action, whether or not auto-opt in in some actions, etc.

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in <code>gameoptions.json</code> as an object:

{
"100": { "name": "Game Setup", ... },
"101": { "name": "Draft", ... }
}

Each key corresponds to the option id, and each value is that option definition, which is described below.

'''Note:''' the file must be valid [https://www.json.org/ JSON]. That is, trailing commas and comments are not allowed. However you can use still standard json hack to add a field like "$comment": "Here we go"

'''Note 2:''' the key in json file must be a string type, even its correspond to a number in other places (such as php, or other references in same json).

'''$this->tableOptions->get(int $optionId): int'''

To get the value of a table option from the Game class, using the JSON key.

To access json data (the metadata only) can use
$game_options = $this->getTableOptions();
=== Details of game options format ===

The following are the values of the option definition object:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. This is automatically marked for translation.
* '''values''' - '''mandatory'''. The map representing possible values of this option. The key of the map is possible value of this option, its a number but has to be string in json. The value is an object descring it.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. This is automatically marked for translation.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected. Note: if there is no description, this should be omitted.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of options.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - (array of conditions) - checks the conditions before displaying the option for selection. All (or any) conditions must be true for the option to be displayed. All or any depends on value of displayconditionoperand
Supported display condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' condition ensures at most this many players
** ''otheroption'' condition ensures another option is set to given values.
** ''otheroptionisnot'' condition ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - (map from value to conditions array) - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game.
Supported start condition types:
** ''minplayers'' condition ensures at least this many players (an array of values is not supported here)
** ''maxplayers'' condition ensures at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example. <span style="background: #FFCDD2; color: #B71C1C; padding: 2px;">But this should never be used -- see the warning below</span>
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#level|below]] for more informations.

Common (reserved) options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
**0 = Normal
**1 = Training
**2 = Arena
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile
**[0, 1, 2] - realtime (technically <10 realtime but you cannot define range in php)
**values >=10 - turn based (currently 10..21)
**Note there are two similar values, 9 = realtime "no time limit with friends only" vs. 20 = turn-based "no time limit with friends only"

'''Example:'''
<pre>
{
"100": {
"name": "Game Variant",
"values": {
"1": {
"name": "Learning",
"firstgameonly": true,
"tmdisplay": "Learning"
},
"2": {
"name": "Base",
},
"3": {
"name": "Extended",
"nobeginner": true,
"beta": true,
"tmdisplay": "Extended"
}
},
"default": 2
},
"101": {
"name": "Draft variant",
"values": {
"1": {
"name": "No draft"
},
"2": {
"name": "Draft",
"tmdisplay": "Draft",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 2, 3 ]
},
{
"type": "otheroption",
"id": 201,
"value": 1
}
],
"startcondition": {
"1": [],
"2": [
{
"type": "maxplayers",
"value": 3,
"message": "Draft option is available for 3 players maximum."
}
]
}
},
"102": {
"name": "Takeovers",
"values": {
"2": {
"name": "No takeover"
},
"1": {
"name": "Allow takeovers",
"tmdisplay": "Takeovers",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 3 ]
}
],
"startcondition": {
"2": [],
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "Rebel vs Imperium Takeover Scenario is available for 2 players only."
}
]
}
}
}
</pre>

'''Example of option that condition on ELO off:'''
{
"100": {
"name": "Learning Game (No Research)",
"values": {
"1": {
"name": "Off",
"tmdisplay": ""
},
"2": {
"name": "On",
"tmdisplay": "Learning Game"
}
},
"startcondition": {
"2": {
"type": "otheroption",
"id": 201,
"value": 1,
"message": "Learning variant available only in friendly mode"
}
}
}
}
'''Example of condition that is only available for REALTIME game mode:'''
<pre>
"displaycondition": [
{ "type": "otheroption", "id": 200, "value": [0, 1, 2] }
],
</pre>

'''Example of using condition on your own option:'''
<pre>
{
"102": {
"name": "Scenarios",
"values": {
"1": {
"name": "Off",
"nobeginner": false
},
"2": {
"name": "On",
"tmdisplay": "Scenarios",
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroptionisnot",
"id": 100,
"value": 1
}
],
"notdisplayedmessage": "Scenarios variant is not available if Learning variant is chosen"
}
}

</pre>

'''Example of handling solo vs multiplayer options:'''<pre>
{
"100": {
"name": "Board setup",
"values": {
"1": {
"name": "Mirror setup",
"description": "The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.",
"tmdisplay": "Mirror setup"
},
"2": {
"name": "Random setup",
"description": "Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.",
"tmdisplay": "Random setup"
}
},
"displaycondition": [
{
"type": "minplayers",
"value": [
2,
3,
4
]
}
]
},
"102": {
"name": "Solo difficulty",
"values": [
{
"name": "Banana-apprentice",
"description": "Do not remove any seed before starting the game.",
"tmdisplay": "Banana-apprentice"
},
{
"name": "Pear to the Throne",
"description": "Remove 1 seed before starting the game.",
"tmdisplay": "Pear to the Throne"
}
],
"displaycondition": [
{
"type": "maxplayers",
"value": 1
}
]
}
}

</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

The other difference is displaycondition affect option itself, while startcondition affect specific values selected

==== gamestartonly ====

<div style="padding: 1em; background: #FFCDD2; color: #B71C1C">
<b>WARNING:</b> [https://studio.boardgamearena.com/bug?id=104 See studio bug #104]. You should <b>NEVER</b> use <code>gamestartonly</code>! Otherwise, you allow players to (unknowingly!) create a turn-based table with impossible options that can never start. Players receive no indication that the option combination they selected is invalid until the last player joins the table (hours or days later) and the game attempts to auto-start. The table won't start because of the <code>startcondition</code>, and the table options cannot be changed because it's a turn-based table, so the table must be abandoned. This is a horrible user experience. Please don't subject players to this.
</div>

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
{
"100": {
"name": "Option name",
"values": [],
"startcondition": {
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "This option is available for 2 players only.",
"gamestartonly": true
}
]
}
}
}
</pre>

==== level ====
Note: At this moment this only has an impact in fancy lobby mode; The presentation of level or checkboxes is not available via normal table creation UI (such as in studio, or when you click Play button in control panel).<pre>
{
"100": {
"name": "Option name",
"values": [...],
"level": "major"
}
}
</pre>

* '''base''' is the default value (you don't need to specify it).
* '''major''' denotes a major option, which will always be displayed on top, and with a specific UI.
* '''additional''' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each value, from the [[Game metadata manager]] (in the "Major Variants" section). Note: this cannot be tested from Studio as there is not studio-only Game metadata manager, to see Major Variants option - the game has to be deployed at least as alpha.
* the major option can have more than 2 values (there will then be an arrow to slide to the other values, carousel-like)
* the naming of major variant values should be concise and the values should have descriptive text (not just "enabled" or "disabled")
** 👍 Option name "Expansion", option values "Base game", "Bigger is Better" => Displayed as ''"Expansion: Base game"'' or ''"Expansion: Bigger is Better"''
** 👎 Option name "Bigger is Better", option values "Enabled", "Disabled => Displayed as ''"Bigger is Better: Enabled"'' or ''"Bigger is Better: Disabled"''

About additional options:
* Please set each option that concerns small details in this category: Advanced players will find this option anyway, and it will simplify the interface of the page of your game.

[[File:Option-levels.png|800px|Option levels]]

==== option presentation ====

An option WILL be displayed as a '''Checkbox''' instead of a selector if certain conditions are met:

* option has only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

The "default" value still has to be specified, and can be "on" or "off" (it's actually just a difference in display).

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu (and also at the bottom on the page in the Options tab).
"Display game logs" and "Display tooltips" are baked-in by default, but you can extend this list as below.

The preference json slightly resembles options, but these are conceptually different. The numbers comes from a different space and do not correspond or conflict with options,
i.e. preference 100 has nothing to do with option 100. You can use range 100-199 with gaps.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
{
"100": {
"name": "Colorblind Support",
"needReload": true,
"values": {
"1": {
"name": "None",
"cssPref": "colorblind_off"
},
"2": {
"name": "Numbers",
"cssPref": "colorblind_on"
},
"3": {
"name": "Shapes",
"cssPref": "colorblind_shapes"
}
},
"default": 1
}
}
</pre>

There is two ways to check/apply this. In javascript

if (this.getGameUserPreference(100) == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref is specified, it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: you also need to set needReload to true for that class change to be effective.

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

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. This string is marked for translation.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The map of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. This string is marked for translation.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes and updating preference from code ===
The BGA framework offers read/write and callback for user preference changes. See [[Game interface logic: yourgamename.js#User preferences]]

=== Accessing User Preferences on the server ===
PHP has an object called '''$this->userPreferences''', and you simply have to use its method get ('''get($playerId, $prefId): ?$int''') to know the preference value of a specific player :
<pre>
if ($this->userPreferences->get($playerId, $prefId) == $prefValue) {
....
}
</pre>See : [[Main game logic: Game.php#User preferences]]

== Translations ==
Note that any name or description values in these JSON files are automatically added to the translation system.

== Migration ==
Previously, options and preferences were specified in a single <code>gameoptions.inc.php</code> file.

BGA has switched to a JSON format to make parsing easier on the server-side, and to avoid a reliance on PHP for static config.

The PHP format will continue to work for ''existing'' games, and although preferred, there is no need to migrate unless you want to. However, newly created games must use the new format.

'''Note''': once a game has been committed with a <code>gameoptions.json</code> file, however, it is not possible to go back without admin intervention.

If you want to migrate:

Simple method:
* Go to studio and press Reload game options configuration
* It will dump json on the log window - you can take this, format it and save into 2 files (if you have both). For gamepreference.json remove option "200" - this is default common option, it should not be in your file.

Manual method:
* Remove all calls to <code>totranslate()</code>, and replace with the plain string
* Remove any references to BGA's PHP constants, such as GAMESTATE_RATING_MODE, and replace with the plain value (in this case, 201)
* You can populate <code>gameoptions.json</code> with the result of <code>json_encode($game_options, JSON_PRETTY_PRINT)</code>
* You can populate <code>gamepreferences.json</code> with the result of <code>json_encode($game_preferences, JSON_PRETTY_PRINT)</code>
* If you include gameoptions.inc.php directly, to read the values, then replace those calls with <code>$this->getTableOptions()</code> or <code>$this->getTablePreferences()</code> as appropriate which return arrays parsed from the JSON files
This message was posted to the developer Discord channel:<blockquote>'''Game options change (Optional!)'''

<code>gameoptions.inc.php</code> is now considered legacy, and <code>gameoptions.json</code> and <code>gamepreferences.json</code> are recommended for new projects:

* The wiki and the template project have been updated: [[Options and preferences: gameoptions.json, gamepreferences.json#User Preferences|https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json]]
* Any questions/problems can come to me, or can be asked here.
* The format of the json files matches the format of the old php files

We realise there are some drawbacks (sorry!):

* No comments in the JSON file, meaning you have to check the wiki for examples
* No PHP constants in the JSON file, meaning magic numbers

However, we hope it's good for BGA because:

* Simpler to parse (for robots and humans)
* Easier to check for errors (we could perhaps use an XSLT one day)
* No need to run game-specific PHP code on the metasite

'''NOTE''': Switching is totally optional, and the legacy files will still work for existing projects, and for those who know about them. </blockquote>
[[Category:Studio]]

Options and preferences: gameoptions.json, gamepreferences.json

2025-03-19T21:53:03Z

Firgon:

{{Studio_Framework_Navigation}}

In <code>gameoptions.json</code>, you can define your game options (i.e. game variants).

In <code>gamepreferences.json</code>, you can define user preferences.

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

'''IMPORTANT:''' after edits to these files, you have to go to the control panel and press "Reload game options configuration" on Studio for your changes '''to take effect'''.

Make sure you understand difference between options and preferences:
* Game options - something usually in the rule book defined as "variant" (except for player count, which is automatically handled). For example, whether to include ''The River'' in Carcassonne.
* User preferences - personal choices of each player only visible to that specific player - i.e. layout, whether or not to prompt for action, whether or not auto-opt in in some actions, etc.

__TOC__

== Game Options ==

Game options are selected by the table creator and usually correspond to game variants, for example if the game includes expansions or certain special rules.

These variants are defined in <code>gameoptions.json</code> as an object:

{
"100": { "name": "Game Setup", ... },
"101": { "name": "Draft", ... }
}

Each key corresponds to the option id, and each value is that option definition, which is described below.

'''Note:''' the file must be valid [https://www.json.org/ JSON]. That is, trailing commas and comments are not allowed. However you can use still standard json hack to add a field like "$comment": "Here we go"

'''Note 2:''' the key in json file must be a string type, even its correspond to a number in other places (such as php, or other references in same json).

'''$this->tableOptions->get(int $optionId): int'''

To get the value of a table option from the Game class, using the JSON key.

To access json data (the metadata only) can use
$game_options = $this->getTableOptions();
=== Details of game options format ===

The following are the values of the option definition object:
* '''name''' - '''mandatory'''. The name of the option visible for table creator. This is automatically marked for translation.
* '''values''' - '''mandatory'''. The map representing possible values of this option. The key of the map is possible value of this option, its a number but has to be string in json. The value is an object descring it.
** '''name''' - '''mandatory'''. String representation of the numeric value visible to table creator. This is automatically marked for translation.
** '''description''' - String description of this value to use when the name of the option is not self-explanatory. Displayed at the table under the option when this value is selected. Note: if there is no description, this should be omitted.
** '''tmdisplay''' - String representation of the option visible in the table description in the lobby. Usually if a variant values are On and Off (default), the tmdisplay would be same as description name when On, and nothing (empty string) when Off. ('''Warning''': due to some caching, a change in tmdisplay may not be effective immediately in the studio, even after forcing a reload of options.) '''Pro Tip:''' You can use this as a pre-game communication by adding fake options that just do nothing in the game but make it easier to find other player wanted the same game configuration (see the crew deep sea for example).
** '''nobeginner''' - Set to true if not recommended for beginners
** '''firstgameonly''' - Set to true if this option is recommended only for the first game (discovery option)
** '''beta''' - Set to true to indicate that this option is in "beta" development stage (there will be a warning for players starting the game)
** '''alpha''' - Set to true to indicate that this option is in "alpha" development stage (there will be a warning, and starting the game will be allowed only in training mode except for the developer)
** '''premium''' - Option can be only used by premium members
* '''default''' - indicates the default value to use for this option (optional, if not present the first value listed is the default)
* '''displaycondition''' - (array of conditions) - checks the conditions before displaying the option for selection. All (or any) conditions must be true for the option to be displayed. All or any depends on value of displayconditionoperand
Supported display condition types:
** ''minplayers'' condition ensures at least this many players (Note: if your game works with a disjoint interval of player counts, you can supply an array of valid counts instead of a single value)
** ''maxplayers'' condition ensures at most this many players
** ''otheroption'' condition ensures another option is set to given values.
** ''otheroptionisnot'' condition ensure another option is NOT set to this given values
* '''displayconditionoperand''' - can be 'and' (this is the default) or 'or'. Allows to change the behaviour to display the option if one of the conditions is true instead of all of them.
* '''startcondition''' - (map from value to conditions array) - checks the conditions (on options VALUES) before starting the game. All conditions must be true for the game to start, otherwise players will get a red error message when attempting to begin the game.
Supported start condition types:
** ''minplayers'' condition ensures at least this many players (an array of values is not supported here)
** ''maxplayers'' condition ensures at most this many players
** ''otheroption'' conditions ensure another option is set to this given values. That works the same as in '''displaycondition'''.
** ''otheroptionisnot'' conditions ensure another option is NOT set to this given value. That works the same as in '''displaycondition'''.
*: For all these condition types, a ''gamestartonly'' boolean option can be added, if you have options that are exclusive. Setting this boolean to ''true'' will defer the evaluation of the startcondition to the game creation, instead of preventing the player to select options that are exclusive at all. See [[#gamestartonly|below]] for an example. <span style="background: #FFCDD2; color: #B71C1C; padding: 2px;">But this should never be used -- see the warning below</span>
* '''notdisplayedmessage''' - if option is not suppose to be visible because of displaycondition but this is set, the text will be visible instead of combo drop down
* '''level''' - what kind of option it is: ''base'', ''major'', or ''additional''. See [[#level|below]] for more informations.

Common (reserved) options for all tables (reserved range 200-299):
*201 (const GAMESTATE_RATING_MODE) - ELO OFF (aka Training mode),
**0 = Normal
**1 = Training
**2 = Arena
*200 (const GAMESTATE_CLOCK_MODE) - game speed profile
**[0, 1, 2] - realtime (technically <10 realtime but you cannot define range in php)
**values >=10 - turn based (currently 10..21)
**Note there are two similar values, 9 = realtime "no time limit with friends only" vs. 20 = turn-based "no time limit with friends only"

'''Example:'''
<pre>
{
"100": {
"name": "Game Variant",
"values": {
"1": {
"name": "Learning",
"firstgameonly": true,
"tmdisplay": "Learning"
},
"2": {
"name": "Base",
},
"3": {
"name": "Extended",
"nobeginner": true,
"beta": true,
"tmdisplay": "Extended"
}
},
"default": 2
},
"101": {
"name": "Draft variant",
"values": {
"1": {
"name": "No draft"
},
"2": {
"name": "Draft",
"tmdisplay": "Draft",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 2, 3 ]
},
{
"type": "otheroption",
"id": 201,
"value": 1
}
],
"startcondition": {
"1": [],
"2": [
{
"type": "maxplayers",
"value": 3,
"message": "Draft option is available for 3 players maximum."
}
]
}
},
"102": {
"name": "Takeovers",
"values": {
"2": {
"name": "No takeover"
},
"1": {
"name": "Allow takeovers",
"tmdisplay": "Takeovers",
"premium": true,
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroption",
"id": 100,
"value": [ 3 ]
}
],
"startcondition": {
"2": [],
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "Rebel vs Imperium Takeover Scenario is available for 2 players only."
}
]
}
}
}
</pre>

'''Example of option that condition on ELO off:'''
{
"100": {
"name": "Learning Game (No Research)",
"values": {
"1": {
"name": "Off",
"tmdisplay": ""
},
"2": {
"name": "On",
"tmdisplay": "Learning Game"
}
},
"startcondition": {
"2": {
"type": "otheroption",
"id": 201,
"value": 1,
"message": "Learning variant available only in friendly mode"
}
}
}
}
'''Example of condition that is only available for REALTIME game mode:'''
<pre>
"displaycondition": [
{ "type": "otheroption", "id": 200, "value": [0, 1, 2] }
],
</pre>

'''Example of using condition on your own option:'''
<pre>
{
"102": {
"name": "Scenarios",
"values": {
"1": {
"name": "Off",
"nobeginner": false
},
"2": {
"name": "On",
"tmdisplay": "Scenarios",
"nobeginner": true
}
},
"displaycondition": [
{
"type": "otheroptionisnot",
"id": 100,
"value": 1
}
],
"notdisplayedmessage": "Scenarios variant is not available if Learning variant is chosen"
}
}

</pre>

'''Example of handling solo vs multiplayer options:'''<pre>
{
"100": {
"name": "Board setup",
"values": {
"1": {
"name": "Mirror setup",
"description": "The starting player shuffles their 6 Farm Cards and randomly lays a card face up in each of the round spaces of their Fruit Island Board. The other players then lay their cards in exactly the same way, copying the order of the starting player.",
"tmdisplay": "Mirror setup"
},
"2": {
"name": "Random setup",
"description": "Instead of every player copying the same card configuration as the starting player, every player shuffles their Farm Cards and lays down the cards randomly on their Fruit Island Board.",
"tmdisplay": "Random setup"
}
},
"displaycondition": [
{
"type": "minplayers",
"value": [
2,
3,
4
]
}
]
},
"102": {
"name": "Solo difficulty",
"values": [
{
"name": "Banana-apprentice",
"description": "Do not remove any seed before starting the game.",
"tmdisplay": "Banana-apprentice"
},
{
"name": "Pear to the Throne",
"description": "Remove 1 seed before starting the game.",
"tmdisplay": "Pear to the Throne"
}
],
"displaycondition": [
{
"type": "maxplayers",
"value": 1
}
]
}
}

</pre>

==== displaycondition vs startcondition ====

<code>displaycondition</code> should be used when an option should not be present in the list under certain conditions.

For example, displaying the option which is consistent with the player count.

* 2 player maps: A B C D
* 3 player maps: E F G H
* 4 player maps: I J K L

<code>startcondition</code> should be used when a specific combination of option values is invalid, but the option itself still makes sense to show.

For example:

* Player 1 faction: A, B, C, D, E, F, G
* Player 2 faction: A, B, C, D, E, F, G
* startcondition: both players can't be the same faction

These options should both be displayed at all times, but there are some invalid configurations.

The other difference is displaycondition affect option itself, while startcondition affect specific values selected

==== gamestartonly ====

<div style="padding: 1em; background: #FFCDD2; color: #B71C1C">
<b>WARNING:</b> [https://studio.boardgamearena.com/bug?id=104 See studio bug #104]. You should <b>NEVER</b> use <code>gamestartonly</code>! Otherwise, you allow players to (unknowingly!) create a turn-based table with impossible options that can never start. Players receive no indication that the option combination they selected is invalid until the last player joins the table (hours or days later) and the game attempts to auto-start. The table won't start because of the <code>startcondition</code>, and the table options cannot be changed because it's a turn-based table, so the table must be abandoned. This is a horrible user experience. Please don't subject players to this.
</div>

On the table configuration page, it won't let you select a combination which is invalid according to <code>startcondition</code>. Doing so will show a red warning, and will revert the option to the previous value. This means you could end up in a situation where you can't easily change between certain options (requiring you to set or unset options in a specific order).

The consequence of the <code>gamestartonly</code> flag is that the player _can_ select an invalid combination. However, when clicking "Start", an invalid combination will produce an error.

Probably the easiest way to see what the difference is is with an example.

With a _Clans of Caledonia_ table:
* set to training mode
* set player count to 1
* try setting "Clan Auction" to one of the "On" options
* try starting the game, there's an error! Ie. <code>"gamestartonly" => true</code>

Then, with a _Sushi Go Party!_ table:
* set number of players to 7
* try setting "Sushi Go! / Sushi Go Party!" to "Sushi Go!"
* you can't set the option! Ie. <code>"gamestartonly" => false</code>

In code:

<pre>
{
"100": {
"name": "Option name",
"values": [],
"startcondition": {
"1": [
{
"type": "maxplayers",
"value": 2,
"message": "This option is available for 2 players only.",
"gamestartonly": true
}
]
}
}
}
</pre>

==== level ====
Note: At this moment this only has an impact in fancy lobby mode; The presentation of level or checkboxes is not available via normal table creation UI (such as in studio, or when you click Play button in control panel).<pre>
{
"100": {
"name": "Option name",
"values": [...],
"level": "major"
}
}
</pre>

* '''base''' is the default value (you don't need to specify it).
* '''major''' denotes a major option, which will always be displayed on top, and with a specific UI.
* '''additional''' means this option will not be displayed by default, to unclutter the option panel.

About major options:
* a game can only have '''1 major option''', and of course, it must be a important game changer.
* the pictures will default to the standard Game Box, and can be set independently for each value, from the [[Game metadata manager]] (in the "Major Variants" section). Note: this cannot be tested from Studio as there is not studio-only Game metadata manager, to see Major Variants option - the game has to be deployed at least as alpha.
* the major option can have more than 2 values (there will then be an arrow to slide to the other values, carousel-like)
* the naming of major variant values should be concise and the values should have descriptive text (not just "enabled" or "disabled")
** 👍 Option name "Expansion", option values "Base game", "Bigger is Better" => Displayed as ''"Expansion: Base game"'' or ''"Expansion: Bigger is Better"''
** 👎 Option name "Bigger is Better", option values "Enabled", "Disabled => Displayed as ''"Bigger is Better: Enabled"'' or ''"Bigger is Better: Disabled"''

About additional options:
* Please set each option that concerns small details in this category: Advanced players will find this option anyway, and it will simplify the interface of the page of your game.

[[File:Option-levels.png|800px|Option levels]]

==== option presentation ====

An option WILL be displayed as a '''Checkbox''' instead of a selector if certain conditions are met:

* option has only '''2 values'''
* values are either (case insensitive):
** ''yes'' and ''no''
** ''on'' and ''off''
** ''enabled'' and ''disabled''

The "default" value still has to be specified, and can be "on" or "off" (it's actually just a difference in display).

[[File:Option-display.png|800px|Example of checkbox display]]

== User Preferences ==

User preferences is something cosmetic about the game interface which however can create user wars, so you can satisfy all users
by giving them individual preferences. You should use this only if it significantly improves the interface for a large proportion of users.
These preferences appear in the three-line hamburger menu in the top corner of the bga menu (and also at the bottom on the page in the Options tab).
"Display game logs" and "Display tooltips" are baked-in by default, but you can extend this list as below.

The preference json slightly resembles options, but these are conceptually different. The numbers comes from a different space and do not correspond or conflict with options,
i.e. preference 100 has nothing to do with option 100. You can use range 100-199 with gaps.

[[File:century_preferences_menu.PNG|400px|The user preferences menu for the game Century]]

<blockquote>
''These preferences are a good place to put accessibility options - as Century did for its Colorblind Support.''
</blockquote>

<pre>
{
"100": {
"name": "Colorblind Support",
"needReload": true,
"values": {
"1": {
"name": "None",
"cssPref": "colorblind_off"
},
"2": {
"name": "Numbers",
"cssPref": "colorblind_on"
},
"3": {
"name": "Shapes",
"cssPref": "colorblind_shapes"
}
},
"default": 1
}
}
</pre>

There is two ways to check/apply this. In javascript

if (this.getGameUserPreference(100) == 2) ...

This checks if preferences 100 has selected value 2.

Second, if cssPref is specified, it will be applied to the '''<html>''' tag. So you can use different css styling for the preference. Note: you also need to set needReload to true for that class change to be effective.

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

The following are the parameters of preferences description array:
* '''name''' - '''mandatory'''. The name of the preference. This string is marked for translation.
* '''needReload''' - If set to true, the game interface will auto-reload after a change of the preference.
* '''values''' - '''mandatory'''. The map of values with additional parameters per value.
** '''name''' - '''mandatory'''. String representation of the numeric value. This string is marked for translation.
** '''cssPref''' - CSS class to add to the '''<html>''' tag. Currently it is added or removed only after a reload (see needReload).
* '''default''' - Indicates the default value to use for this preference (optional, if not present the first value listed is the default).

=== Listening for preference changes and updating preference from code ===
The BGA framework offers read/write and callback for user preference changes. See [[Game interface logic: yourgamename.js#User preferences]]

=== Accessing User Preferences on the server ===
PHP has an object called '''$this->userPreferences''', and you simply have to use its method get ('''get($playerId, $prefId): ?$int''') to know the preference value of a specific player :
<pre>
if ($this->userPreferences->get($playerId, $prefId) == $prefValue) {
....
}
</pre>

== Translations ==
Note that any name or description values in these JSON files are automatically added to the translation system.

== Migration ==
Previously, options and preferences were specified in a single <code>gameoptions.inc.php</code> file.

BGA has switched to a JSON format to make parsing easier on the server-side, and to avoid a reliance on PHP for static config.

The PHP format will continue to work for ''existing'' games, and although preferred, there is no need to migrate unless you want to. However, newly created games must use the new format.

'''Note''': once a game has been committed with a <code>gameoptions.json</code> file, however, it is not possible to go back without admin intervention.

If you want to migrate:

Simple method:
* Go to studio and press Reload game options configuration
* It will dump json on the log window - you can take this, format it and save into 2 files (if you have both). For gamepreference.json remove option "200" - this is default common option, it should not be in your file.

Manual method:
* Remove all calls to <code>totranslate()</code>, and replace with the plain string
* Remove any references to BGA's PHP constants, such as GAMESTATE_RATING_MODE, and replace with the plain value (in this case, 201)
* You can populate <code>gameoptions.json</code> with the result of <code>json_encode($game_options, JSON_PRETTY_PRINT)</code>
* You can populate <code>gamepreferences.json</code> with the result of <code>json_encode($game_preferences, JSON_PRETTY_PRINT)</code>
* If you include gameoptions.inc.php directly, to read the values, then replace those calls with <code>$this->getTableOptions()</code> or <code>$this->getTablePreferences()</code> as appropriate which return arrays parsed from the JSON files
This message was posted to the developer Discord channel:<blockquote>'''Game options change (Optional!)'''

<code>gameoptions.inc.php</code> is now considered legacy, and <code>gameoptions.json</code> and <code>gamepreferences.json</code> are recommended for new projects:

* The wiki and the template project have been updated: [[Options and preferences: gameoptions.json, gamepreferences.json#User Preferences|https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json]]
* Any questions/problems can come to me, or can be asked here.
* The format of the json files matches the format of the old php files

We realise there are some drawbacks (sorry!):

* No comments in the JSON file, meaning you have to check the wiki for examples
* No PHP constants in the JSON file, meaning magic numbers

However, we hope it's good for BGA because:

* Simpler to parse (for robots and humans)
* Easier to check for errors (we could perhaps use an XSLT one day)
* No need to run game-specific PHP code on the metasite

'''NOTE''': Switching is totally optional, and the legacy files will still work for existing projects, and for those who know about them. </blockquote>
[[Category:Studio]]

Bugsclarification forestshuffle

2025-02-25T10:03:32Z

Firgon: /* Bonuses are not Bonus */

Bugsclarification forestshuffle

2025-02-25T10:03:10Z

Firgon:

== Please do not post bug report if "all bonuses don't work" (and sometimes, even if "one bonus doesn't work"). ==

==== Bonuses are not Bonus ====

You probably need to ckeck in the rules the difference between "Effect" (which is always triggered when you pay to place a card) and "Bonus" (which is triggered only if you pay with and only with matching cards).

Bonus and effect are NEVER triggered if you place a card freely thanks to the effect (or the bonus) of an other card.

==== Shrubs are not Trees ====
Another one of the main reasons for "fake bug report" is a confusion between SHRUB and TREE. All cards that refer to "tree" doesn't work with "shrub" (ants, mushrooms, fat dormouse...)

Gamehelpelpasogwt

2025-02-04T09:44:55Z

Firgon: Created page with "El Paso at the end of the 19th century: five railroad companies have connected the Sun City to their network and made it a major hub for the cattle trade. Take on the role of ranchers of that time and bring your best cattle to El Paso to earn money and victory points. Hire more cowboys, builders, and engineers to get closer to your goals. '''Central Display''' The central display at the top features: * The map with various buildings and empty spaces and a circular tra..."

El Paso at the end of the 19th century: five railroad companies have connected the Sun City to their network and made it a major hub for the cattle trade. Take on the role of ranchers of that time and bring your best cattle to El Paso to earn money and victory points. Hire more cowboys, builders, and engineers to get closer to your goals.

'''Central Display'''

The central display at the top features:

* The map with various buildings and empty spaces and a circular trail connecting those, appearing as a dashed line. In the center, there are trading posts with numbers above them and bonuses shown below them, as well as the orange Simmental cattle cards, with a counter how many are left.
* Above the map, you see four train cards with 2-3 actions that can be accessed via the Train action on building F.
* Next to the train, you see the stack of bonus tiles (with a bell icon) and three face-up tiles beside it, as well as the stack of objective tiles (with a horn icon) and, also, three face-up tiles beside it. These can be gained via the Train action on building F.
* To the right of the map, there is the building display, featuring the six types of buildings; each building has a counter showing how many are left. For details on the building cost, click the question mark icon. Buildings can be built on building E.
* Below the buildings, there is the cattle market, featuring the four types of cattle, also showing how many of each type are left. Note the question mark icon that tells you how much each cattle card costs. Cattle can be acquired on building D.
* Last, but not least, below the cattle market, you see the four types of workers and how many of each type are left. These can be hired on building B.

'''Personal Display'''

Your personal play area features:

* At the top, your draw pile, showing how many cards it contains, and your hand of cattle cards (four at the start). As the game progresses, your discard pile will be shown to the right of your hand.
* Below that, on the left, you see your player board featuring 4 auxiliary actions on the left, of which 4 spaces are covered with a disc; in the middle, you see three bonuses you can unlock; and, on the right, you see your certificate track, which shows how many certificates you will be able to spend in El Paso (see El Paso action).
* Finally, to the right of your player board, you see how many workers of each type you have at your disposal. Note that workers have bonuses printed at the top that you can use at any time on your turn (you will see a button in the status bar reminding you of that).

The player panel in the side bar shows:

* With live scoring enabled, your score below your username.
* Below that, your cash, your herder’s range, the number of permanent certificates, the value on your certificate track, and how many exchange tokens you have.
* Any objective tiles you have, see Setup and Train action.

'''Setup'''

As part of setup, in reverse play order, players pick one of the face-up objective tiles, which will be placed in your player panel in the side bar. A little icon will show which objectives you meet (for now, you will see an X for the first one you take).

'''Your Turn'''

Your turn comprises three phases in this order: movement, actions, and cleanup. At any point during your turn, you may discard workers from your play area for their printed bonus or use exchange tokens to improve your hand. Note the buttons on the right of the status bar informing you of these options.

'''Movement'''

On your first turn, simply pick any starting building except El Paso (B-G). Later, you may pick any building in clockwise order within your herder’s range, which is 3 at the start (see player panel in the side bar). Empty spaces do not count. If the trail forks, the game will consider the more advantageous option.

'''Actions'''

Carry out the actions of the building you chose during movement. You may always choose to take an auxiliary action instead of the building actions. If you land on an opponent’s building (see Construct a Building below for details), you can only take an auxiliary action.

'''Auxiliary Actions'''

The left side of your player board features 4 auxiliary actions: two are available from the start and can be improved, the other two need to be unlocked first. Some buildings allow you to take an auxiliary action as part of their effect (cogwheel icon).

The four auxiliary actions on the left of your player board, from top to bottom, are:

* Gain $1. If unlocked, gain $3 instead.
* Gain 1 certificate on your certificate track (max. 4).
* Exchange 1 card (same as using an exchange token, see there). If unlocked, you may exchange a second time.
* Trash 1 card from hand (i.e., remove it from play permanently). Unlocking this action costs $3.

'''Building Actions'''

These are some of the common building actions. Note that all these actions are optional and can be performed in any order. If in doubt or if an action is not listed here, check the tooltip or printed appendix.

* Discard Cattle for Money (B, D, and E): Discard the depicted cattle card to gain $2. Even if you have more of that cattle in hand, you can only discard one per action.
* Hire Workers (B):
** Pay $5 and pick a worker type from the central display; the worker will be immediately placed with your other workers.
** If you choose a wild worker (showing all three types), you must pay an additional $4.
** You can hire a second worker for an additional $8, but you must choose a different one than the first.
** You must pay $5 and $8 only on building B—other buildings and effects (e.g., trading post 9) may offer this action at no cost (except when choosing a wild worker—they always cost an additional $4).
** Each worker is worth 2 or 3 VP, as printed on the card.

* Buy Cattle (D):
** Pick a cattle from the cattle market and pay the indicated cost—from left to right, cattle cost $2/$4/$6/$8 and you must discard 1/2/3/4 cowboys (and/or wild workers) from your worker area.
** New cattle will be placed in your discard pile; you can only buy one cattle per action, even if you have more money and cowboys.
** Cattle are worth varying numbers of VP, as printed on the card.

* Construct a Building (E):
** Pick a building from the central display and pay the indicated cost—an amount of money and you must discard a number of builders (and/or wild workers) from your worker area.
** Then choose an empty space along the trail and pay the additional cost printed on the space, if any.
** If you already have a building on the map, you may upgrade it to a more valuable one by paying the difference between the two. The new building will then replace the old one and the old one will become available for building once again. When upgrading a building, you don’t have to pay the cost printed on the space again.
** You can build any building you can afford, but each player may only have at most 2 buildings on the map. Once you have 2 buildings, you can only upgrade them.
** Each building is worth a number of VP, as printed on the building.

* Use the Train (F):
** Pick a train card and pay the cost printed on the card—up to $8 and you must discard a number of engineers (and/or wild workers) from your worker area.
** Carry out the effect of the chosen train. When gaining an objective or bonus tile, you may take a face-up one or draw one from the respective stack.
** Objective tiles score at game end if you meet their condition. Every component in the game can only be assigned to one objective; for building requirements, you “spend” that many workers paid for buildings, not the building itself (i.e., you may complete more than two of those objectives).
** Bonus tiles provide a one-time bonus or a permanent effect. Among the permanent effects are the permanent certificate (with an infinity symbol) and the ability to count duplicate cattle cards at El Paso (see that action for details).
* Other building actions include: taking an auxiliary action (cogwheel symbol); gaining money or certificates; gaining exchange tokens (sometimes at a cost), cattle, or bonus/objective tiles; moving your herder along the trail to take another action.

'''El Paso Actions'''

When moving your herder, you can never move past El Paso. In El Paso, you must carry out the following actions in this order:

# You gain $5 and a Simmental cattle card that is placed on your discard pile. If the Simmental cattle pile on the map is empty, the first player to visit El Paso will place their herder on that space, gaining 2 VP during scoring; this will trigger the end of the game, with every other player taking one more action. Any later arrivals at El Paso do not place their herder on that space.
# The game will reveal your hand to everyone else and compute your breeding value, i.e., add up the numbers at the top of the cattle cards in your hand; each type of cattle will only contribute once, i.e., duplicates are ignored unless you have the appropriate bonus tile.
# The game will also add any permanent certificates you have (with an infinity symbol) and ask you how many of the certificates on your certificate track you’d like to add. Note that you may also discard builders from your worker area to purchase additional certificates, as per that worker’s printed bonus action.
# Once you confirm the total, you must choose a trading post on the map with the same or a lower value and a disc from your player board, which will be placed on that space. If that space has a bonus action, you will now take it. Note that you may have at most one disc per space, except spaces 0, 12, and 16. Discs of other players don’t matter. To remove a disc from the middle of your player board, you must pick a trading post of value 10 or more. Spaces 10 and up are worth VP at game end.
# Finally, your hand is discarded.

'''Cleanup'''

At the end of your turn, the game will draw up to your hand limit, which is 4 at the start. Any cards you did not use this turn will remain in your hand.

'''Scoring'''

See El Paso Actions, bullet point 1 for how the game ends. After each other player has had their final turn, players will score:

* 1 VP per $5—on your final turn, you will have the option
* VP from building tiles on the map
* VP from trading posts with your discs—each disc counts
* VP from cattle + 2 VP if your herder is on the Simmental space
* VP from workers
* VP from bonus tiles

* VP from your objective tiles—the game determines automatically the best outcome if you have competing tiles. Each component can only attribute to one objective tile; for building objectives, the total of workers spent on buildings is considered, not the buildings themselves. You don’t lose VP for failed objectives.

Gamehelpsirocelotscave

2025-01-31T14:59:41Z

Firgon: Created page with "In <b>Sir Ocelot's Cave</b>, Sir Ocelot and Professor Penguin explore a newly discovered cave system, competing for the precious gemstones found inside. To locate and collect gemstones, you will be using your tools — compass, lamp, and pickaxe — and your trusty companion’s good instincts. The deeper you get into the cave, the more valuable treasure you will find! In the end, the player with the most valuable collection of gemstones wins the game!<br> <b>How to pla..."

In <b>Sir Ocelot's Cave</b>, Sir Ocelot and Professor Penguin explore a newly discovered cave system, competing for
the precious gemstones found inside. To locate and collect gemstones, you will be using
your tools — compass, lamp, and pickaxe — and your trusty companion’s good instincts. The
deeper you get into the cave, the more valuable treasure you will find! In the end, the
player with the most valuable collection of gemstones wins the game!<br>

<b>How to play:</b> <br>

Players alternate taking turns until the game ends. You must go through the following steps in this order:<br>

<b>1. Move your companion</b> (optional)
Starting with the first cave (blue level), you can assign your trusty companion to any empty space or one containing a (1-point) rock crystal. If placed on a (1-point) rock crystal, this is yours.
Once inside a cave, you only can move your companion forward to the next cave level. You may move your companion only <b>once per turn.</b> <br>

NOTE: If you not feel like placing your companion in step 1., proceed with steps 2. to 3. until you want to start your turn by placing it. <br><br>

<b>2. Place a token </b>(mandatory)
Regardless if you placed or moved your companion yet, you MUST place exactly one token:
- either a tool on an empty circular space on the perimeter of a cave
- or - if you have not already - the companion in side the (blue level) cave<br>

Your goal is to place the token such that you can collect gemstones. <b>Be sure to check all visual axis after placing a token IRL.</b>
Here on boardgamerarena.com, the implementation will do this for you. <br>

You may place tools freely on the perimeter of any cave if the space is still vacant.
you are not required to start at level 1. Note that tools are double-sided, showing different tools on both sides.<br>

<b>3. Collect gemstones </b> (optional)
After placing a token, check if you can collect any gemstones:
to collect a gemstone, it must be "seen" from three different sides <b>by three different tools</b>.
One of the tools may be your trusty <B<companion</b>. It serves as a wild tool for collection gemstones,
i.e. it can replace a missing tool for YOU. <br>

Note: Your companion does not block the view for your opponent, but it will only serve you to collect.<br>

The game ends when you both run out of tokens to place. The player with the most valuable collection wins.<br>

<b>What to collect:</b> <br>

<b>Gemstones:</b> score points as shown on the token<br>
<b>Geodes: </b>are innocent looking rocks that need to be opened. When you collect a geode, immediately draw an <b>amethyst</b> from the corresponding bag (matching the color of the cave); the geode will be discarded. Amethysts are worth varying amounts of points. Their value is kept hidden until the end of the game. <br>
<b>Celestites:</b> This mysterious type of gemstone is only available in level-1-cave and comes in three shapes: <b>a sun, a crescent moon and a star</b>. Whenever you collect a set of <b>all three shapes</b>, immediately draw an amethyst from the blue bag. Unlike geodes, you get to keep the celestites.<br><br>

<b>Have fun exploring Sir Ocelot's Cave!</b>

Bugsclarification treos

2024-07-29T07:08:52Z

Firgon:

=== Routes ===
We have done a lot of testing on all the routes in this modular map. There should be no more bugs, but it can happen though. If you think you found a bug (because you can't play where you want for example), we ask you to report the bug with a mandatory screenshot (including the current Event Card, your movement card, the map)
Thank you very much !

Bugsclarification treos

2024-07-29T07:08:17Z

Firgon: Created page with "# Routes # We have done a lot of testing on all the routes in this modular map. There should be no more bugs, but it can happen though. If you think you found a bug (because you can't play where you want for example), we ask you to report the bug with a mandatory screenshot (including the current Event Card, your movement card, the map) Thank you very much !"

# Routes #

We have done a lot of testing on all the routes in this modular map. There should be no more bugs, but it can happen though. If you think you found a bug (because you can't play where you want for example), we ask you to report the bug with a mandatory screenshot (including the current Event Card, your movement card, the map)
Thank you very much !

Gamehelptreos

2024-06-27T09:17:30Z

Firgon: Created page with "Welcome on Treos !! Head out and explore the world: complete quests and side quests to collect enough gold faster than the others. The first player to collect 20 gold wins the game. == Sunrise : Planning == Each player draws 5 cards from their deck and assigns them face down : One on the bid space : the higher the card number on the bottom left of the card you place there, the earlier you will move during this round. Three on the 3 different day turns: considering the..."

Welcome on Treos !!

Head out and explore the world: complete quests and side quests to collect enough gold faster than the others.
The first player to collect 20 gold wins the game.

== Sunrise : Planning ==
Each player draws 5 cards from their deck and assigns them face down :
One on the bid space : the higher the card number on the bottom left of the card you place there, the earlier you will move during this round.
Three on the 3 different day turns: considering the movement options on the cards they place there.
The last card may be replaced on top of their card deck or discarded.

Players also place an intrigue marker face down on each of the 3 movement cards (NB: on this bga adaptation, you just have to choose a space for the "move highwayman token")

== Morning, Midday, Evening : movement ==
According to their turn order markers, each player takes one turn : reveal the movement card and the intrigue marker and then move accordingly their pawn and (if a move highwayman token has been revealed) one highwayman.

Reaching new places :
=== Town===
Complete a quest, take a new quest card (if you have a free space for it),
=== Fort===
Get the fort's weapon, if you don't already have it (triggers character-specific power)
=== Inn===
Get a side quest
=== Secret Place===
Reveal the power of the secret place : get a movement card, get a side quest, open a Portal
=== Portal===
Free move to another portal

== Sundown : clean-up ==
All players discard their cards into their respective discard pile.
An Event is revealed, providing a special rule for the next turn.

Gamehelpnirds

2024-06-27T06:56:26Z

Firgon:

Welcome to Nirds VS Gnomes !

It's a cooperative game, all players fight together against Gnomes. All players have (usually) two gnomes in front of them but they can attack any gnome on the table. On the other hand, at the end of each round, the Gnomes will attack only their own player. They usually cause player to lose lives. Each player starts with 3 lives, if your life counter falls to zero, you die, all players lose. At the end of each round, new gnomes arrive; if the gnome deck is empty, you win.

== Trading phase ==
Unless a gnome prevents you from trading, all players may trade their dice freely. On this BGA adaptation, you have to send a request to the player who has a die you want, and this player must accept (except in turn-based games where the response can be automatic). At this phase, using the same trading system, the players also decide who will be the first player. You can place your dice on cards or "lock dice", this doesn't really affect the gameplay, but indicates to other players that you don't want to trade locked dice.

Once everyone has passed, it's Action phase !

== Action phase ==
Using your Attack cards (green), you can roll matching die (or dice) to try to knock out gnomes before the end of the round. In this BGA adaptation, you need to place dice on the Attack card before activating it.
You can also spend your unused dice to recruit new nirds and build your army up !

== Gnome phase ==
All remaining gnomes (if any) attack their respective player, causing them to lose lives.
If a player has no remaining lives, the game ends and the players lose. If not, all players receive new gnomes to have 2 gnomes in front of them again. And a new round begins.

== Tactic cards (orange) ==
As they knock out Gnomes, the players will receive tactics cards. Tactics cards can (usually) be played at any time (even outside of your turn, even if you have passed) and they will give you extra power (i.e. Violin Concerto will knock out all Gnomes with 2 lives or less)

Gamehelpnirds

2024-06-27T06:55:33Z

Firgon: add tactic cards hint

Welcome to Nirds VS Gnomes !

It's a cooperative game, all players fight together against Gnomes. All players have (usually) two gnomes in front of them but they can attack any gnome on the table. On the other hand, at the end of each round, the Gnomes will attack only their own player. They usually cause player to lose lives. Each player starts with 3 lives, if your life counter falls to zero, you die, all players lose. At the end of each round, new gnomes arrive; if the gnome deck is empty, you win.

== Trading phase ==
Unless a gnome prevents you from trading, all players may trade their dice freely. On this BGA adaptation, you have to send a request to the player who has a die you want, and this player must accept (except in turn-based games where the response can be automatic). At this phase, using the same trading system, the players also decide who will be the first player. You can place your dice on cards or "lock dice", this doesn't really affect the gameplay, but indicates to other players that you don't want to trade locked dice.

Once everyone has passed, it's Action phase !

== Action phase ==
Using your Attack cards (green), you can roll matching die (or dice) to try to knock out gnomes before the end of the round. In this BGA adaptation, you need to place dice on the Attack card before activating it.
You can also spend your unused dice to recruit new nirds and build your army up !

== Gnome phase ==
All remaining gnomes (if any) attack their respective player, causing them to lose lives.
If a player has no remaining lives, the game ends and the players lose. If not, all players receive new gnomes to have 2 gnomes in front of them again. And a new round begins.

=== Tactic cards (orange) ===
As they knock out Gnomes, the players will receive tactics cards. Tactics cards can (usually) be played at any time (even outside of your turn, even if you have passed) and they will give you extra power (i.e. Violin Concerto will knock out all Gnomes with 2 lives or less)

Gamehelpnirds

2024-06-27T06:44:42Z

Firgon: Created page with "Welcome to Nirds VS Gnomes ! It's a cooperative game, all players fight together against Gnomes. All players have (usually) two gnomes in front of them but they can attack any gnome on the table. On the other hand, at the end of each round, the Gnomes will attack only their own player. They usually cause player to lose lives. Each player starts with 3 lives, if your life counter falls to zero, you die, all players lose. At the end of each round, new gnomes arrive; if th..."

Bugsclarification forestshuffle

2024-06-15T11:39:31Z

Firgon: creation

Please do not post bug report if "all bonuses don't work" or even if "one bonus doesn't work".

You probably need to ckeck in the rules the difference between "Effect" (which is always triggered when you pay to place a card) and "Bonus" (which is triggered only if you pay with and only with matching cards).

Bonus and effect are NEVER triggered if you place a card freely thanks to the effect (or the bonus) of an other card.