Board Game Arena - User contributions [en]

Gamehelpharmonies

2026-01-14T09:31:25Z

Mizutismask: re add the note about spirit points that was removed and explain it more

== Overview ==

Your goal is to earn the most points by building landscapes and habitats for Animals. Which landscapes and habitats are built using colored tokens in certain arrangements. The more arrangements you have, the more points you can earn.

Tokens can be one of five colors. There are 23 blue tokens (representing water), 23 grey tokens (representing mountains), 21 brown tokens (representing woody trees), 19 green tokens (representing foliage or treetops), 19 yellow tokens (representing fields) and 15 red tokens (representing buildings).

Animals are represented by Animal cards. Each Animal card indicates the habitat pattern you must form within your landscape.

Nature's Spirit Cards can be added to the game and provide additional scoring conditions. When integrated into the game, choose between 2 randomly dealt spirit cards before taking your first turn. Refer to the rule indicated on the card to determine its value in points.

== Turns ==

There are 3 possible actions to take. One is mandatory, two are optional. They can be done in any order.

'''Mandatory action - Take and place tokens:''' Choose one set of 3 tokens (out of 5 sets). Place each of the 3 tokens on your board according to the following requirements:

- The token cannot be placed underneath another token.

- The token cannot be placed on top of a spirit cube.

- The token must be either on an empty space or on top of 1-2 previously placed tokens (see diagram).

[[File:Harmonies.png]]

'''Optional action - Take an Animal card:''' The card will be placed in one of 4 available slots. You can only take 1 card per turn.

Each card displays the pattern/arrangement to make to score points, the spirit cubes to earn for making the pattern, and the number of points you can earn for each spirit cube. When all the cubes are used, the card is discarded and you can take a new one.

'''Optional action - Place an Animal cube'''. If you have placed a valid pattern on your board, you can place a spirit cube where indicated on its Animal card.

At the end of a turn, the central board of tokens is refilled and the Animal cards are replaced so there are 5.

== End of Game ==

The game ends when either A) there are no tokens left to refill the central board or B) a player has 2 or fewer empty spaces on their board. At that point, the round ends so that all players have completed the same number of turns.

=== Scoring ===

==== Animal Cards ====
Each player scores points according to the number of points indicated in the topmost space without an Animal cube. A card with all its cubes scores 0.

==== Landscape ====
Each player scores points according to the standard patterns for certain landscape features (colors).
{|class="wikitable" style="max-width:50rem;text-align:center;" border="2"
!Token
!Formation
!Scoring
|-
! style="background:#6e790f;color:#fff" | Tree
|1 green token placed on top of 0/1/2 brown tokens
|The scores corresponding are 1/3/7 pts.
|-
! style="background:#858983;color:#fff" | Mountain
|A stack made of 1/2/3 gray tokens
|Only mountains adjacent to other mountains score: each mountain scores 1/3/7 pts
|-
! style="background:#deae09;color:#fff" | Field
|2+ yellow tokens
|Each 2+ contiguous yellow tokens group you get 5 pts.
|-
! style="background:#b82521;color:#fff" | Building
|1 red token on top of a red, brown, or gray token
|Each Building scores 5 pts if surrounded by at least 3 tokens of different colors (only consider the top of each adjacent place).
|-
! style="background:#197984;color:#fff" | Water ''(Side A)''
|Blue tokens
|Score for your longest continuous chain of blue tokens. Choose any two blue tokens and count how many blue tokens connect them by the '''shortest''' path (inclusive of the two selected tokens at both ends of the chain). Score 2/5/8/11/15 pts for a chain of 2/3/4/5/6 blue tokens + 4 pts for every additional token in the chain.
Making '''loops''' is not recommended since according to this shortest rule your river length will be only half of its tokens +1.
|-
! style="background:#197984;color:#fff" | Water ''(Side B)''
|Areas divided by blue tokens
|Each island that is separated from each other by blue tokens gives you 5 pts.
|}

== Spirit Cards ==
If playing with Spirit cards, the following changes to the game are made.

Each player chooses 1 of 2 Spirit cards. This card counts toward your 4-card limit and is given a Nature's Spirit cube. These follow the same rules as Animal cards, but have different requirements, such as points for the number of landscapes or groups of connected landscapes of a certain pattern.

At the end of the game, points are scored for Spirit cards just like Animal cards.
'''''NOTE:''' Nature’s Spirit cards are Animal cards, so points from a Nature’s Spirit card are scored just like Animal cards (in the card column), and are in addition to all other basic points scored elsewhere. (The spirit card score is highlighted in the animal cards column. It has the color of the spirit cube)''

Gamehelpinsidejob

2025-06-12T13:49:03Z

Mizutismask: /* Core Concepts */ add intels explanation

===Overview===

If you are an Insider, try to collect a set amount of Intel without being caught by the other players, if you are an Agent then try to get through a certain number of Tricks with special conditions met

===Core Concepts===

The start player plays a single card as a lead suit

The followers must play to Suit if possible, but otherwise can play any card

The Insider may play any card EVEN if they have a suit card

The player who played the highest value in the lead Suit wins the trick

However, each Mission will determine a Trump suit, if a player plays a Trump then they win instead of the Lead Suit, if multiple play Trump then the highest Trump wins

==== Intels ====
If you have at least one intel token, you may wager intel. To do that, you place an intel token on your card after playing into the trick according to the rules. You therefore have to follow suit (if you can) and then wager intel.

'''For the purposes of the active mission and for determining the winner of a trick, a card with an intel token on it is considered the trump suit.'''

===Turn===

The start player first draws 2 Mission cards privately, selecting one to play and the other to discard in secret

The central area of a Mission dictates what must be done to win the mission, the lower area shows the Trump suit

After the Mission is selected, the start player commences the trick

Whoever wins the trick, gains 1 Intel

If the mission Succeeded, retain it as a completed mission card

If the mission Failed, return it to the box as a failure

Before moving on to a new trick, check whether either side has won

If a player collects enough Intel required for the Insider to win but is NOT the insider, they flip their role card over to show they are an Agent (If playing with it, this also stops that player from using Wagers)

===Game Ends===

In a 3/4/5 player game

The Agents win if they complete 9/7/6 Missions

The Insider wins if they obtain 6/5/4 Intel

If neither of these occur by the end of the final trick (2/2/1 cards remaining in hand), the group votes on who the Insider is, if they are correct then Agents win, if incorrect then the Insider wins (you cannot vote for yourself, nor can you vote for someone whose role has been revealed via an effect)

If both win conditions occur in the same round, the Insider wins

===Wagers and Special Roles and Risky===

Once you feel comfortable, you can introduce Wagers &/or Special Roles &/or Risky

Wagers cannot be taken by the start player or anyone with a revealed role

To Wager, place an Intel token on your played card, this makes it the Trump suit regardless of what it actually is

Whoever wins the trick will gain all Intel Wagered

If there is a tie, because both the real trump card and the Wagered card share the same value, the card which was played later in the round wins

Special Roles require a 4 or 5 player count

All Special Roles in a given game are known before dealing them secretly

If you use the Professional then you do NOT use the normal Insider

It is generally recommended to only have one or two special roles, the rest being normal Agents/insider

Risky introduces four Missions which lean towards aiding the Insider and are shuffled into the regular deck

==Special Cards, Details==
{{pill|This section needs a proper translation. Please help by providing one. Remove this notice once the translation is complete. 09 June 2025|firebrick}}

French translation included in case of ambiguity.

===Agent with a Microphone (Agent sur écoute)===
Objective: You win if the agents win.
Special rule: You must reveal your role to the others as soon as you know it's the Agent with a Microphone. If at any point you have more than one suitcase in hand, the Infiltrator immediately wins the game, and all agents lose.

===Paranoid Agent===
Objective: You win if the agents win.
Special rule: When you vote, you can vote against two different people. If your role has been revealed during the game because you have collected the indicated number of suitcases, you can vote twice against the same person.

===Agent at full risk (Agent tous risques)===
Objective: You win if the agents win.
Special Rule: Before starting the game, shuffle the four Risky Mission cards into the mission deck. All players must apply this rule, even those without the role of Agent at Risk: when choosing a mission, if one of the cards is a Risky Mission, you are required to choose it; if there are two Risky Missions, you may choose one of them. Additionally, if your role is revealed during the game due to having obtained the indicated number of briefcases, all agents, including the Agent at Risk, win the game.

===The Decoy (Le leurre)===
Objective: You only win if you receive the majority of votes in the voting phase.
Special Rule: If you win, all other players lose. If the Infiltrator and the Decoy receive the same number of votes, they both win the game.

===The Accomplice===
First, reveal your character to the other players. Then, you must look at another player's card. This player is now your accomplice.
Objective: You only win if your accomplice wins. You cannot lay down or collect briefcases. If you win a trick, your accomplice loses a briefcase. You also cannot vote.

===Tim Shady===
Objective: You only win if the player to your right loses.
Special Rule: If your card is revealed during the game due to collecting the required briefcases, immediately draw a briefcase from the player to your right. Furthermore, once your role is revealed, you cannot vote.

===Sleeping Agent===
Objective: You win only if these two circumstances occur simultaneously. Your role is not revealed, and the agents win.
Special Rule: If your role is revealed during the game, after collecting the indicated number of briefcases, you switch sides. From that moment on, you only win if the Infiltrator wins. Therefore, from the moment the Sleeping Agent is revealed, they can no longer vote.

===No-Professor (No-Professor), replacing the Infiltrator.===
Objective: You win if your card is not revealed or if all other cards are revealed. Therefore, it's not about collecting briefcases, but rather avoiding them so that your card isn't revealed.
Special rule: Players reveal their cards when they obtain:
* 4 briefcases with 4 players;
* 3 briefcases with 5 players.
Players whose card is revealed cannot vote.
You are the Infiltrator, so you may not play the suit led. If your card is revealed, you immediately lose the game.

Gamehelpwizardscup

2025-05-22T12:47:38Z

Mizutismask: /* Gameplay */ Element chart added

== Background ==

The '''Wizards Cup''' is a magical tournament for wizards from all walks of life. You, as the great ruler, will be taking part in these festivities by assembling a team of 6 exceptional wizards from your realm and determining the sequence in which they will engage with the rival team. Once you have set this up, all you can do is observe your wizards fight the duels. Forge a formidable team to win this once-in-a-century tournament and demonstrate the might of your kingdom across the land!

== Gameplay ==
[[File:HelpWhite.png|thumb|Look at the arrows to know what element beats another]]
1. Before the game begins, each player receives a set of 18 cards, each player randomly draw 1 to display.

2. Each player then chooses 5 cards from the 17 cards left in the set, combined with the one displayed, together into a '''deck'''.

3. Each player selects 5 of the 6 cards in his deck and arranges them in the order in which they will be played. The unselected 6th card is the '''Waiting Card'''.

4. Once both players are ready, start '''the duel'''. Each player reveals the first card from his deck and places it in the '''Duel zone'''.

Wizards can win or lose their duel according to 3 criteria, in this order:

A. Their '''Magic Power'''

B. Their associated '''Element'''

C. Their '''Value'''

At the end of the duel, the losing Wizard moves into the owner's discard pile. The winning Wizard card (if any) '''remains in place'''.

Each player with no Wizard in the Duel zone draws the top card from his deck and begins a new duel.

Duels continue in this way until one of the players can no longer play a Wizard card into the Duel zone, at which time his opponent '''wins the round'''.

In rare cases, both players simultaneously cannot play a wizard card from either deck, in which case both win the round.

If a player has received 2 '''Cup Tokens''', go to '''end of the game'''. Otherwise, '''prepare for a new round'''.

==== Prepare for a new round ====

Each player has the option to go through the remaining 12 cards in his set. He may swap one of the cards in his deck for one of these 12 cards. Once both players have finish this preparation process, a new round begins at step 3 (each player selects 5 of the 6 cards in his deck, etc.).

==== End of the Game ====

The player with 2 '''Cup Tokens''' wins. If both players receive their second '''Cup Tokens''' at the same time, the player with the lowest total value of the 6 cards in his current deck wins the game.

File:HelpWhite.png

2025-05-22T12:45:37Z

Mizutismask:

Elements relationships

BGA Studio Cookbook

2025-05-22T12:37:51Z

Mizutismask: not recommending adding false player panels

This page is a cookbook of design and implementation recipes for BGA Studio framework.
For tooling and usage recipes see [[Tools and tips of BGA Studio]].
If you have your own recipes feel free to edit this page.

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

==== Create pieces dynamically (using template) ====

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Note: this method is recommended by BGA guildlines

Declared js template with variables in .tpl file, like this
<pre>
<script type="text/javascript">
// Javascript HTML templates
var jstpl_ipiece = '<div class="${type} ${type}_${color} inlineblock" aria-label="${name}" title="${name}"></div>';
</script>
</pre>

Use it like this in .js file
div = this.format_block('jstpl_ipiece', {
type : 'meeple',
color : 'ff0000',
name : 'Bob',
});

Then you do whatever you need to do with that div, this one specifically design to go to log entries, because it has embedded title (otherwise its a picture only) and no id.

Note: you could have place this variable in js itself, but keeping it in .tpl allows you to have your js code be free of HTML. Normally it never happens but
it is good to strive for it.
Note: you can also use string concatenation, its less readable. You can also use dojo dom object creation api's but its brutally verbose and its more unreadable.

==== Create pieces dynamically (using string concatenation) ====

'''Ingredients:''' ggg.js

<pre>
div = "<div class='meeple_"+color+"'></div>";
</pre>

or modern way

<pre>
div = `<div class='meeple_${color}'></div>`;
</pre>

==== Create all pieces statically ====

'''Ingredients:''' ggg_ggg.tpl, ggg.css, ggg.view.php (optional)

* Create ALL game pieces in html template (.tpl)
* ALL pieces should have unique id, and it should be meaningful, i.e. meeple_red_1
* Do not use inline styling
* Id of player's specific pieces should use some sort of 'color' identification, since player id cannot be used in static layout, you can use english color name, hex 6 char value, or color "number" (1,2,3...)
* Pieces should have separated class for its color, type, etc, so it can be easily styled in groups. In example below you now can style all meeples, all red meeples or all red tokens, or all "first" meeples

ggg.tpl:
<pre>
<div id="home_red" class="home_red home">
<div id="meeple_red_1" class="meeple red n1"></div>
<div id="meeple_red_2" class="meeple red n2"></div>
</div>
</pre>

ggg.css:

<pre>
.meeple {
width: 32px;
height: 39px;
background-image: url(img/78_64_stand_meeples.png);
background-size: 352px;
}

.meeple.red {
background-position: 30% 0%;
}
</pre>

* There should be straight forward mapping between server id and js id (or 1:1)
* You place objects in different zones of the layout, and setup css to take care of layout

<pre>
.home .meeple{
display: inline-block;
}
</pre>
* If you need to have a temporary object that look like original you can use dojo.clone (and change id to some temp id)
* If there is lots of repetition or zone grid you can use template generator, but inject style declaration in css instead of inline style for flexibility

Note:
* If you use this model you cannot use premade js components such as Stock and Zone
* You have to use alternative methods of animation (slightly altered) since default method will leave object with inline style attributes which you don't need

==== Use player color in template ====

NOTE: view.php is deprecated, its best to generate html from .js

'''Ingredients:''' ggg_ggg.tpl, ggg.view.php

.view.php:
<pre>
function build_page($viewArgs) {
// Get players & players number
$players = $this->game->loadPlayersBasicInfos();
$players_nbr = count($players);
/**
* ********* Place your code below: ***********
*/

// Set PCOLOR to the current player color hex
$cplayer = $this->getCurrentPlayerId();
if (array_key_exists($cplayer, $players)) { // may be not set if spectator
$player_color = $players [$cplayer] ['player_color'];
} else {
$player_color = 'ffffff'; // spectator
}
$this->tpl ['PCOLOR'] = $player_color;
</pre>

=== Status bar ===

==== Changing state prompt ====

State prompt is message displayed for player which usually comes from state description.
Sometimes you want to change it without changing state (one way is change state but locally, see client states above).

Simple way just change the html
<pre>
setMainTitle: function(text) {
$('pagemaintitletext').innerHTML = text;
},
// usage
onMeeple: function(event) {
//...
this.setMainTitle(_('You must select where meeple is going'));
},
</pre>

This however will not work with parameters and will not draw You in color, if you want this its more sophisticated:

<pre>
setDescriptionOnMyTurn : function(text) {
this.gamedatas.gamestate.descriptionmyturn = text;
var tpl = dojo.clone(this.gamedatas.gamestate.args);
if (tpl === null) {
tpl = {};
}
var title = "";
if (this.isCurrentPlayerActive() && text !== null) {
tpl.you = this.divYou();
}
title = this.format_string_recursive(text, tpl);

if (!title) {
this.setMainTitle(" ");
} else {
this.setMainTitle(title);
}
},
</pre>

Note: this method uses '''setMainTitle''' defined above and '''divYou''' defined in another section of this wiki.

=== Animation ===

==== Attach to new parent without destroying the object ====

BGA function attachToNewParent for some reason destroys the original, if you want similar function that does not you can use this
ggg.js

<pre>
/**
* This method will attach mobile to a new_parent without destroying, unlike original attachToNewParent which destroys mobile and
* all its connectors (onClick, etc)
*/
attachToNewParentNoDestroy: function (mobile_in, new_parent_in, relation, place_position) {

const mobile = $(mobile_in);
const new_parent = $(new_parent_in);

var src = dojo.position(mobile);
if (place_position)
mobile.style.position = place_position;
dojo.place(mobile, new_parent, relation);
mobile.offsetTop;//force re-flow
var tgt = dojo.position(mobile);
var box = dojo.marginBox(mobile);
var cbox = dojo.contentBox(mobile);
var left = box.l + src.x - tgt.x;
var top = box.t + src.y - tgt.y;

mobile.style.position = "absolute";
mobile.style.left = left + "px";
mobile.style.top = top + "px";
box.l += box.w - cbox.w;
box.t += box.h - cbox.h;
mobile.offsetTop;//force re-flow
return box;
},
</pre>

==== Animation on oversurface ====
If you use non-absolute position for your game elements (i.e you use layouts) - you cannot really use BGA animation functions. After years of fidding with different options I use
techique which I call animation on oversurface that works when parents use different zoom, rotation, etc

* You need another layer on top of everything - oversurface
* We create copy of the object on oversurface - to move
* We move the real object on final position - but make it invisible for now
* We move the phantom to final position applying required zoom and rotation (using css animation), then destroy it
* When animation is done we make original object visible in new position

The code is bit complex it can be found here

https://codepen.io/VictoriaLa/pen/gORvdJo

Game using it: century, ultimaterailroads

==== Scroll element into view ====
Ingredients: game.js

This function will scroll given node (div) into view and respect replays and archive mode

<pre>
scrollIntoViewAfter: function (node, delay) {
if (this.instantaneousMode || this.inSetup) {
return;
}
if (typeof g_replayFrom != "undefined") {
$(node).scrollIntoView();
return;
}
if (!delay) delay = 0;
setTimeout(() => {
$(node).scrollIntoView({ behavior: "smooth", block: "center" });
}, delay);
},
</pre>

=== Logs ===

==== Inject icon images in the log ====

Here is an example of what was done for Terra Mystica which is simple and straightforward:

<pre>
//Define the proper message
$message = clienttranslate('${player_name} gets ${power_income} via Structures');
if ($price > 0) {
$this->DbQuery("UPDATE player SET player_score = player_score - $price WHERE player_id = $player_id");
$message = clienttranslate('${player_name} pays ${vp_price} and gets ${power_income} via Structures');
}

// Notify
$this->notify->all( "powerViaStructures", $message, array(
'i18n' => array( ),
'player_id' => $player_id,
'player_name' => $this->getUniqueValueFromDb( "SELECT player_name FROM player WHERE player_id = $player_id" ),
'power_tokens' => $power_tokens,
'vp_price' => $this->getLogsVPAmount($price),
'power_income' => $this->getLogsPowerAmount($power_income),
'newScore' => $this->getUniqueValueFromDb( "SELECT player_score FROM player WHERE player_id = $player_id" ),
'counters' => $this->getGameCounters(null),
) );
</pre>

With some functions to have the needed html added inside the substitution variable, such as:

<pre>
function getLogsPowerAmount( $amount ) {
return "<div class='tmlogs_icon' title='Power'><div class='power_amount'>$amount</div></div>";
}
</pre>
Note: injecting html from php is not ideal but easy, if you want more clean solution, use method below but it is a lot more sophisticated.

==== Inject images and styled html in the log ====

{{InfoBox|title=Warning — Translation|maxWidth=500|color=#c00|body='''In order to prevent interference with the translation process, keep in mind that you must only apply modifications to the args object, and not try to substitute the keys (the <code>${player_name}</code> parts of your string) in the log string.'''}}

So you want nice pictures in the game log. What do you do? The first idea that comes to mind is to send html from php in notifications (see method above).

This is a bad idea for many reasons:

* It's bad architecture. ui elements leak into the server, and now you have to manage the ui in multiple places.
* If you decided to change something in the ui in future version, replay logs for old games and tutorials may not work, since they use stored notifications.
* Log previews for old games become unreadable. (This is the log state before you enter the game replay, which is useful for troubleshooting and game analysis.)
* It's more data to transfer and store in the db.
* It's a nightmare for translators.

So what else can you do? You can use client side log injection to intercept log arguments (which come from the server) and replace them with html on the client side. Here are three different method you can use to achieve this.

===== Override <code>this.format_string_recursive()</code> method =====

'''Ingredients:''' ggg.js, ggg.game.php

I use this recipe for '''client side log injection''' to intercept log arguments (which come from the server) and replace them with html on the client side.

[[File:clientloginjection.png|left]]

ggg.js

<pre>

/** Override this function to inject html into log items. This is a built-in BGA method. */

/* @Override */
format_string_recursive : function format_string_recursive(log, args) {
try {
if (log && args && !args.processed) {
args.processed = true;

// list of special keys we want to replace with images
var keys = ['place_name','token_name'];

for ( var i in keys) {
var key = keys[i];
key in args && args[key] = this.getTokenDiv(key, args);

}
}
} catch (e) {
console.error(log,args,"Exception thrown", e.stack);
}
return this.inherited({callee: format_string_recursive}, arguments);
},
</pre>

'''Important:''' In the ''format_string_recursive'' method, the 'args' parameter will only contain arguments passed to it from the notify method in ggg.game.php (see below).

The 'log' parameter is the actual string that is inserted into the logs. You can perform additional js string manipulation on it.

<pre>
getTokenDiv : function(key, args) {
// ... implement whatever html you want here, example from sharedcode.js
var token_id = args[key];
var item_type = getPart(token_id,0);
var logid = "log" + (this.globalid++) + "_" + token_id;
switch (item_type) {
case 'wcube':
var tokenDiv = this.format_block('jstpl_resource_log', {
"id" : logid,
"type" : "wcube",
"color" : getPart(token_id,1),
});
return tokenDiv;

case 'meeple':
if ($(token_id)) {
var clone = dojo.clone($(token_id));

dojo.attr(clone, "id", logid);
this.stripPosition(clone);
dojo.addClass(clone, "logitem");
return clone.outerHTML;
}
break;

default:
break;
}

return "'" + this.clienttranslate_string(this.getTokenName(token_id)) + "'";
},
getTokenName : function(key) {
return this.gamedatas.token_types[key].name; // get name for the key, from static table for example
},
</pre>

Note that in this case the server simply injects token_id as a name, and the client substitutes it for the translated name or the picture.

ggg.game.php:

$this->notify->all('playerLog', clienttranslate('Game moves ${token_name}'), ['token_name'=>$token_id]);

'''Important:''' As noted above, only arguments actually passed by this method are available to the args parameter received in the client-side ''format_string_recursive'' method.

Sometimes it is the case that you want to pass arguments that are not actually included in the output message. For example, suppose we have a method like this:

$this->notify->all('tokenPlaced', clienttranslate('Player placed ${token_name}'), array(
'token_name' => $token_id,
'zone_played' => $zone);

This will output "Player placed ${token_name}" in the log, and if we subscribe to a notification method activated by the "tokenPlaced" event in the client-side code, that method can make use of the 'zone_played' argument.

Now if you want to make some really cool things with game log, most probably you would need more arguments than are included in log message. The problem with that,
it will work at first, but if you reload game using F5 or when the game loads in turn based mode, you will loose your additional parameters, why? Because when game reloads it does not actually send same notifications, it sends special "hitstorical_log" notification where all parameters not listed in the message are removed. In example above, field zone_played would be removed from historical log as it is not included in message of the notification. You can till preserve specific arguments in historical log by adding special field preserve to notification arguments like this:

<pre>
$this->notify->all('tokenPlaced', clienttranslate('Player placed ${token_name}'), array(
'token_name' => $token_id,
'zone_played' => $zone,
'preserve' => [ 'zone_played' ]
);
</pre>

Now you can use zone_played in format_string_recursive even in historical logs.

===== Use <code>:formatFunction</code> option provided by <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

The above method will work in most of the cases, but if you use dotted keys such as <code>${card.name}</code> (which is supported by the framework, for private state args), the key won't be substituted because the <code>key in arg</code> test will fail. If so you need to rely either on this way, or the one after.

'''WARNING:''' using this method on an already advanced project will require you to go through all your notifications to change keys !

Under the hood, the '''this.format_string_recursive()''' function calls the '''dojo.string.substitute''' method which substitutes <code>${keys}</code> with the value provided. If you take a look at the [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] and [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] you can notice that the key can be suffixed with a colon (<code>:</code>) followed by a function name. This will allow you to specify directly in the substitution string which keys need HTML injection.

First of all, you need to define your formatting function in the ggg.js file:
<pre>
[[ggg.js]]
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
}
}
</pre>

Obviously you need to define the appropriate templates in the ggg_ggg.tpl file:
<pre>
[[ggg_ggg.tpl]]
let jstpl_HTMLLogElement1 = '<div class="log-element log-element-1-${value}"></div>';
let jstpl_HTMLLogElement2 = '<div class="log-element log-element-2-${value}"></div>';
...
</pre>
And the appropriate classes in ggg.css.

Then you need to add the <code>dojo/aspect</code> module at the top of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And you also need to add the following code in your <code>contructor</code> method in the ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){

// ... skipped code ...
let gameObject = this; //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) { //This allows you to modify the arguments of the dojo.string.substitute method before they're actually passed to it
return [template, map, transform, gameObject];
});

Now you're all set to inject HTML in your logs. To actually achieve this, you must specify the function name with the key like so:

<nowiki>[[ggg.game.php]]</nowiki>
$this->notify->all("notificationName", clienttranslate("This log message contains ${plainTextArgument} and the following will receive HTML injection: ${html_injected_argument1:getTokenDiv}"), [
"plainTextArgument" => "some plain text here",
"html_injected_argument1" => "some value used by getTokenDiv",
]);

You're not limited writing only one function, you can write as many functions as you like, and have them each inject a specific type of HTML. You just need to specify the relevant function name after the column in the substitution key.

===== Use <code>transform</code> argument of <code>dojo.string.substitute</code> =====

'''Ingredients:''' ggg.js, ggg.game.php, ggg_ggg.tpl, ggg.css

This method is also relying on the use of <code>dojo.string.substitute</code> by the framework, and will use the <code>transform</code> argument, which, accordting to [https://github.com/dojo/dojo/blob/c3ceb017cfa25b703f5662dc83d1c8aae9bc5d81/string.js#L163 source code] and [https://dojotoolkit.org/reference-guide/1.7/dojo/string.html#substitute documentation] will be run on all the messages going through dojo.string.substitute.

'''WARNING:''' This method will be applied to all strings that go through dojo.string.substitute. As such you must take extra care not to substitute keys that may be used by the framework (i.e. ${id}). In order to do so, a good practise would be to prefix all keys that need substitution with a trigram of the game name.

Since all the keys will be fed to the tranform function, by default, it must return the value, substituted or not per your needs. You can define the function like this in the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
getTokenDiv : function(value, key) {
//This is only an example implementation, you need to write your own.
//The method should return HTML code
switch (key) {
case 'html_injected_argument1':
return this.format_block('jstpl_HTMLLogElement1',{value: value});
case 'html_injected_argument2':
return this.format_block('jstpl_HTMLLogElement2',{value: value});
...
default:
return value; //Needed otherwise regular strings won't appear since since the value isn't returned by the function
}
}

The templates must be defined in the ggg_ggg.tpl file and the corresponding CSS classes in the ggg.css file.

You need to add the following code at the beginning of the ggg.js file:

<nowiki>[[ggg.js]]</nowiki>
define([
"dojo", "dojo/_base/declare",
'''<span style="color:green;">"dojo/aspect",</span> //MUST BE IN THIRD POSITION''' (see [[#Including your own JavaScript module (II)|below]])
"ebg/core/gamegui",
"ebg/counter",
], function (dojo, declare, <span style="color:green;">'''aspect'''</span>) {
...

And the following code to the <code>constructor</code> method in ggg.js:

<nowiki>[[ggg.js]]</nowiki>
constructor: function(){
// ... skipped code ...
let transformFunction = dojo.hitch(this, "getTokenDiv"); //Needed as the this object in aspect.before will not refer to the game object in which the formatting function resides
aspect.before(dojo.string, "substitute", function(template, map, transform) {
if (undefined === transform) { //Check for a transform function presence, just in case
return [template, map, transformFunction];
}
});

Then you're all set for log injection, no need to change anything on the PHP side.

==== Processing logs on re-loading ====

You rarely need to process logs when reloading, but if you want to do something fancy you may have to do it after logs are loaded.
Logs are loaded asyncronously so you have to listen for logs to be fully loaded.
Unfortunately there is no direct way of doing it so this is the hack.

'''Hack alert''' - this extends undocumented function and may be broken when framework is updated

'''Ingredients:''' ggg.js

<pre>
/*
* [Undocumented] Override BGA framework functions to call onLoadingLogsComplete when loading is done
@Override
*/
setLoader: function(image_progress, logs_progress) {
this.inherited(arguments); // required, this is "super()" call, do not remove
//console.log("loader", image_progress, logs_progress)
if (!this.isLoadingLogsComplete && logs_progress >= 100) {
this.isLoadingLogsComplete = true; // this is to prevent from calling this more then once
this.onLoadingLogsComplete();
}
},

onLoadingLogsComplete: function() {
console.log('Loading logs complete');
// do something here
},
</pre>

=== Player Panel ===

==== Inserting non-player panel ====
'''This should be avoided. The new guideline is to avoid it in new games and remove it from old games.'''

'''Ingredients:''' ggg.js, ggg_ggg.tpl

If you want to insert non-player panel on the right side (for example to hold extra preferences, zooming controls, etc)

this can go pretty much anywhere in template it will be moved later

ggg_ggg.tpl:
<pre>
<div class='player_board_config' id="player_board_config">

<button id="zoom-out" class=" fa fa-search-minus fa-2x config-control"></button>
<button id="zoom-in" class=" fa fa-search-plus fa-2x config-control"></button>
<button id="show-settings" class="fa fa-cog fa-2x config-control "></button>
</div>
</pre>

some hackery required in js

ggg.js:
<pre>
/* @Override */
updatePlayerOrdering() {
this.inherited(arguments);
dojo.place('player_board_config', 'player_boards', 'first');
},
</pre>

=== Images and Icons ===

==== Accessing images from js ====

'''Ingredients:''' ggg.js

<pre>
// your game resources

var my_img = '<img src="'+g_gamethemeurl+'img/cards.jpg"/>';

// shared resources
var my_help_img = "<img class='imgtext' src='" + g_themeurl + "img/layout/help_click.png' alt='action' /> <span class='tooltiptext'>" +
text + "</span>";
</pre>

==== High-Definition Graphics ====

Some users will have screens which can display text and images at a greater resolution than the usual 72 dpi, e.g. the "Retina" screens on the 5k iMac, all iPads, and high-DPI screens on laptops from many manufacturers. If you can get art assets at this size, they will make your game look extra beautiful. You ''could'' just use large graphics and scale them down, but that would increase the download time and bandwidth for users who can't display them. Instead, a good way is to prepare a separate graphics file at exactly twice the size you would use otherwise, and add "@2x" at the end of the filename, e.g. if pieces.png is 240x320, then pieces@2x.png is 480x640.

There are two changes required in order to use the separate graphics files. First in your css, where you use a file, add a media query which overrides the original definition and uses the bigger version on devices which can display them. Ensuring that the "background-size" attribute is set means that the size of the displayed object doesn't change, but only is drawn at the improved dot pitch.
<pre>
.piece {
position: absolute;
background-image: url('img/pieces.png');
background-size:240px 320px;
z-index: 10;
}
@media (-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)
{
.piece {
background-image: url('img/pieces@2x.png');
}
}
</pre>

Secondly, in your setup function in javascript, you must ensure than only the appropriate one version of the file gets pre-loaded (otherwise you more than waste the bandwidth saved by maintaining the standard-resolution file). Note that the media query is the same in both cases:
<pre>
var isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
if (window.matchMedia(isRetina).matches)
{
this.dontPreloadImage( 'pieces.png' );
this.dontPreloadImage( 'board.jpg' );
}
else
{
this.dontPreloadImage( 'pieces@2x.png' );
this.dontPreloadImage( 'board@2x.jpg' );
}
</pre>

==== Using CSS to create different colors of game pieces if you have only white piece ====

<pre>
background-color: #${color};
background-blend-mode: multiply;
background-image: url( 'img/mypiece.png');
mask: url('img/mypiece.png');
-webkit-mask: url('img/mypiece.png');
</pre>

where ${color} - is color you want

Note: piece has to be white (shades of gray). Sprite can be used too, just add add background-position as usual.

==== Accessing player avatar URLs ====

<pre>
getPlayerAvatar(playerId) {
let avatarURL = '';

if (null != $('avatar_' + playerId)) {
let smallAvatarURL = dojo.attr('avatar_' + playerId, 'src');
avatarURL = smallAvatarURL.replace('_32.', '_184.');
}
else {
avatarURL = 'https://x.boardgamearena.net/data/data/avatar/default_184.jpg';
}

return avatarURL;
},
</pre>

Note: This gets avatar URLs at 184x184 resolution. You can also use 92, 50, and 32 depending on which resolution you want.

==== Adding Image buttons ====

Its pretty trivial but just in case you need a working function:

ggg.js:
<pre>
addImageActionButton: function (id, div_html, handler) { // div_html is string not node
this.addActionButton(id, div_html, handler, '', false, 'gray');
dojo.style(id, "border", "none"); // remove ugly border
dojo.addClass(id, "bgaimagebutton"); // add css class to do more styling
return $(id); // return node for chaining
},

</pre>
Example of usage:
<pre>
this.addImageActionButton('button_coin',"<div class='coin'></div>", ()=>{ alert('Ha!'); });
</pre>

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

Sometime game elements use specific fonts of text, if you want to match it up you can load some specific font (IMPORTANT: from some '''free font''' source. See notes below).

[[File:Dragonline_font.png]]

.css
<pre>
/* latin-ext */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: 400;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/2Dy1Unur1HJoklbsg4iPJ_Y6323mHUZFJMgTvxaG2iE.woff2) format('woff2');
unicode-range: U+0100-024F, U+1E00-1EFF, U+20A0-20AB, U+20AD-20CF, U+2C60-2C7F, U+A720-A7FF;
}
/* latin */
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(https://fonts.gstatic.com/s/qwigley/v6/gThgNuQB0o5ITpgpLi4Zpw.woff2) format('woff2');
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2212, U+2215, U+E0FF, U+EFFD, U+F000;
}
@font-face {
font-family: 'Qwigley';
font-style: normal;
font-weight: normal;
src: local('Qwigley'), local('Qwigley-Regular'), url(http://ff.static.1001fonts.net/q/w/qwigley.regular.ttf) format('ttf');
}

.zone_title {
display: inline-block;
position: absolute;
font: italic 32px/32px "Qwigley", cursive;
height: 32px;
width: auto;
}
</pre>

'''NB:''' if you need to include a font that's not available online, an extra action will be needed from an admin. Please include the font file(s) in your img directory, and mention it to admins when requesting your game to be moved to alpha. '''Please remember that the font has to be free, and include a .txt with all appropriate license information about the font.'''
You can look for free fonts (for example) on https://fonts.google.com or https://www.fontsquirrel.com/)

'''Content Security Policy'''

BGA runs a Content Security Policy which will limit the origins from which you can load external fonts, in order to prevent license abuse.

The CSP is a whitelist of allowed origins. To see the list, view the response headers of any page on Studio, and look for the "Content-Security-Policy" header.

You will specifically want to check for the font-src token within these headers, and limit any external fonts to these sources.

'''This list is subject to change''' but as of the time of writing, the only acceptabled external sites are use.typekit.net and fonts.gstatic.com.

=== Scale to fit for big boards ===

'''Ingredients:''' ggg_ggg.tpl, ggg.js

Lets say you have huge game board, and lets say you want it to be 1400px wide. Besides the board there will be side bar which is 240 and trim.
My display is 1920 wide so it fits, but there is big chance other people won't have that width. What do you do?

You have to decide:
* If board does not fit you want scale whole thing down, the best way is probably use viewport (see https://en.doc.boardgamearena.com/Your_game_mobile_version)
* You can leave the board as is and make sure it is scrollable horizonatally
* You add custom scale just for the board (can add user controls - and hook to transform: scale())

I tried to auto-scale but this just does work, too many variables - browser zoom, 3d mode, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming...
Here is scaling functing for custom user scaling

ggg_ggg.tpl:
<pre>
<div id="thething" class="thething">
... everything else you declare ...
</div>
</pre>

ggg.js:
<pre>
onZoomPlus: function() {
this.setZoom(this.zoom + 0.1);
},
onZoomMinus: function() {
this.setZoom(this.zoom - 0.1);
},

setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
var inner = document.getElementById("thething");

if (zoom == 1) {
inner.style.removeProperty("transform");
inner.style.removeProperty("width");
} else {
inner.style.transform = "scale(" + zoom + ")";
inner.style.transformOrigin = "0 0";
inner.style.width = 100 / zoom + "%";
}
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
this.onScreenWidthChange();
},
</pre>

=== Dynamic tooltips ===

If you really need a dynamic tooltip you can use this technique. (Only use it if the static tooltips provided by the BGA framework are not sufficient.)

new dijit.Tooltip({
connectId: ["divItemId"],
getContent: function(matchedNode){
return "... calculated ...";
}
});

This is an out-of-the-box djit.Tooltip. It has a ''getContent'' method which is called dynamically.

The string returned by getContent() becomes the innerHTML of the tooltip, so it can be anything. In this example matchedNode is a dojo node representing dom object with id of "divItemId" but there are more parameters which I am not posting here which allows more sophisticated subnode queries (i.e. you can attach tooltip to all nodes with class or whatever).

[https://dojotoolkit.org/reference-guide/1.10/dijit/Tooltip.html dijit.Tooltip]

It's not part of the BGA API so use at your own risk.

=== Rendering text with players color and proper background ===

'''Ingredients:''' ggg.js

<pre>
/* Implementation of proper colored You with background in case of white or light colors */

divYou: function() {
var color = this.gamedatas.players[this.player_id].color;
var color_bg = "";
if (this.gamedatas.players[this.player_id] && this.gamedatas.players[this.player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[this.player_id].color_back + ";";
}
var you = "<span style=\"font-weight:bold;color:#" + color + ";" + color_bg + "\">" + __("lang_mainsite", "You") + "</span>";
return you;
},

/* Implementation of proper colored player name with background in case of white or light colors */

divColoredPlayer: function(player_id) {
var color = this.gamedatas.players[player_id].color;
var color_bg = "";
if (this.gamedatas.players[player_id] && this.gamedatas.players[player_id].color_back) {
color_bg = "background-color:#" + this.gamedatas.players[player_id].color_back + ";";
}
var div = "<span style=\"color:#" + color + ";" + color_bg + "\">" + this.gamedatas.players[player_id].name + "</span>";
return div;
},
</pre>

=== Cool realistic shadow effect with CSS ===

==== Rectangles and circles ====

It is often nice to have a drop shadow around tiles and tokens, to separate them from the table visually. It is very easy to add a shadow to rectangular elements, just add this to your css:

<pre>
.xxx-tile {
box-shadow: 3px 3px 3px #000000a0;
}
</pre>

box-shadow obeys '''border-radius''' of the element, so it will look good for rounded rectangles, and hence also circles (if border-radius is set appropriately).

box-shadow also supports various other parameters and can be used to achieve effects such as glowing, borders, inner shadows etc. If you need to animate a box-shadow, you may be able to get better performance (avoiding redraws) if you attach the shadow to another element (possibly an ::after pseudo-element) and change only the '''opacity''' of that element.

==== Irregular Shapes ====

If you wish to make a shadow effect for game pieces that are not a rectangle, but your game pieces are drawn from rectangles in a PNG image, you can apply the shadow to the piece using any art package and save it inside the image. This usually will yield the best performance. Remember to account for the size of the shadow when you lay out images in the sprite sheet.

However that sometimes will not be an option, for example if the image needs to be rotated while the shadow remains offset in the same direction. In this case, one option is to not use box-shadow but use filter, which is supported by recent major browsers. This way, you can use the alpha channel of your element to drop a shadow. This even work for transparent backgrounds, so that if you are using the "CSS-sprite" method, it will work!

For instance:

<pre>
.xxx-token {
filter: drop-shadow(0px 0px 1px #000000);
}
</pre>

Beware that some browsers still do not always draw drop-shadow correctly. In particular, Safari frequently leaves bits of shadow behind when objects move around the screen. In Chrome, shadows sometimes flicker badly if another element is animating close by. Some of these correctness issues can be solved by adding '''isolation: isolate; will-change: filter;''' to affected elements, but this significantly affects redraw performance.

Beware of performance issues - particularly on Safari (MacOS, iPhone and iPad). Keep in mind that drop-shadow are very GPU intensive. This becomes noticeable once you have about 40 components with drop-shadow filter. If that is your case, you can quite easily implement a user preference to disable shadows for users on slower machines:

gameoptions.inc.php
<pre>
100 => array(
'name' => totranslate('Shadows'),
'needReload' => true, // after user changes this preference game interface would auto-reload
'values' => array(
1 => array( 'name' => totranslate( 'Enabled' ), 'cssPref' => '' ),
2 => array( 'name' => totranslate( 'Disabled' ), 'cssPref' => 'no-shadow' )
)
),
</pre>

[game].css
<pre>
.no-shadow * {
filter: none !important;
}
</pre>For Safari, it is usually better to simply disable drop-shadow completely: [[Game interface stylesheet: yourgamename.css#Warning: using drop-shadow]].

==== Shadows with clip-path ====

For some reason, a shadow will not work together with clip-path on one element. To use both clip-path (when for example using .svg to cut out cardboard components from your .jpg spritesheet) and drop-shadow, you need to wrap the element into another one, and apply drop-shadow to the outer one, and clip-path to the inner one.

<pre>
<div class='my-token-wrap'>
<div class='my-token'>
</div>
</div>
</pre>
<pre>
.my-token-wrap {
filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
clip-path: url(#my-token-path);
}
</pre>

=== Using the CSS classes from the state machine ===

If you need to hide or show stuff depending on the state of your game, you can of course use javascript, but CSS is hand enough for that. The #overall-content element does change class depending on the game state. For instance, if you are in state ''playerTurn'', it will have the class ''gamestate_playerTurn''.

So now, if you want to show the discard pile only during player turns, you may use:

<pre>
#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }
</pre>

This can be used if you want to change sizing of elements, position, layout or visual appearance.

== Game Model and Database design ==

=== Database for The euro game ===
Lets say we have a game with workers, dice, tokens, board, resources, money and vp. Workers and dice can be placed in various zones on the board, and you can get resources, money, tokens and vp in your home zone. Also tokens can be flipped or not flipped.

[[File:Madeira board.png]]

Now lets try to map it, we have
* (meeple,zone)
* (die, zone, sideup)
* (resource cube/money token/vp token,player home zone)
* (token, player home zone, flip state)
We can notice that resource and money are uncountable, and don't need to be track individually so we can replace our mapping to
* (resource type/money,player home zone, count)
And vp stored already for us in player table, so we can remove it from that list.

Now when we get to encode it we can see that everything can be encoded as (object,zone,state) form, where object and zone is string and state is integer. The resource mapping is slightly different semantically so you can go with two table, or counting using same table with state been used as count for resources.

So the piece mapping for non-grid based games can be in most case represented by (string: token_key, string: token_location, int: token_state), example of such database schema can be found here: [https://github.com/elaskavaia/bga-sharedcode/blob/master/dbmodel.sql dbmodel.sql] and class implementing access to it here [https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php table.game.php].

Variant 1: Minimalistic

CREATE TABLE IF NOT EXISTS `token` (
`token_key` varchar(32) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_red_1
|home_red
|0
|-
|dice_black_2
|board_guard
|1
|-
|dice_green_1
|board_action_mayor
|3
|-
|bread
|home_red
|5
|}

Now how we represent resource counters such as bread?
Using same table from we simply add special counter token for bread and use state to indicate the count. Note to keep first column unique we have to add player identification for that counter, i.e. ff0000 is red player.

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|bread_ff0000
|tableau_ff0000
|5
|}

See php module for this table here https://github.com/elaskavaia/bga-sharedcode/blob/master/modules/tokens.php

Variant 2: Additional resource table, resource count for each player id

CREATE TABLE IF NOT EXISTS `resource` (
`player_id` int(10) unsigned NOT NULL,
`resource_key` varchar(32) NOT NULL,
`resource_count` int(10) signed NOT NULL,
PRIMARY KEY (`player_id`,`resource_key`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

ALTER TABLE resource ADD CONSTRAINT fk_player_id FOREIGN KEY (player_id) REFERENCES player(player_id);

{| class="wikitable"
|+resource
! player_id
! resource_key
! resource_count
|-
|123456
|bread
|5
|}

Variant 3: More normalised

This version is similar to "card" table from hearts tutorial, you can also use exact cards database schema and Deck implementation for most purposes (even you not dealing with cards).

CREATE TABLE IF NOT EXISTS `token` (
`token_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`token_type` varchar(16) NOT NULL,
`token_arg` int(11) NOT NULL,
`token_location` varchar(32) NOT NULL,
`token_state` int(10),
PRIMARY KEY (`token_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

{| class="wikitable"
|+token
! token_id
! token_type
! token_arg
! token_location
! token_state
|-
|22
|meeple
|123456
|home_123456
|0
|-
|23
|dice
|2
|board_guard
|1
|-
|26
|dice
|1
|board_action_mayor
|3
|-
|49
|bread
|0
|home_123456
|5
|}

Advantages of this would be is a bit more straightforward to do some queries in db, disadvantage its hard to read (as you can compare with previous example, you
cannot just look at say, ah I know what it means). Another questionable advantage is it allows you to do id randomisation, so it hard to do crafted queries to
cheat, the down side of that you cannot understand it either, and handcraft db states for debugging or testing.

=== Database for The card game ===

Lets say you have a standard card game, player have hidden cards in hand, you can draw card from draw deck, play card on tableau and discard to discard pile.
We have to design database for such game.

In real word to "save" the game we take a picture a play area, save cards from it, then put away draw deck, discard and hand of each player separately and mark it, also we will record current scoring (if any) and who's turn was it.

* Framework handles state machine transition, so you don't have to worry about database design for that (i.e. who's turn it is, what phase of the game we are at, you still have to design it but part of state machine step)
* Also framework supports basic player information, color, order around the table, basic scoring, etc, so you don't have to worry about it either
* The only thing you need in our database is state of the "board", which is "where each pieces is, and in what state", or (position,rotation) pair.

Lets see what we have for that:
* The card state is very simple, its usually "face up/face down", "tapped/untapped", "right side up/up side down"
* As position go we never need real coordinates x,y,z. We need to know what "zone" card was, and depending on the zone it may sometimes need an extra "z" or "x" as card order. The zone position usually static or irrelevant.
* So our model is: we have cards, which have some attributes, at any given point in time they belong to a "zone", and can also have order and state
* Now for mapping we should consider what information changes and what information is static, later is always candidate for material file
* For dynamic information we should try to reduce amount of fields we need
** we need at least a field for card, so its one
** we need to know what zone cards belong to, its 2
** and we have possibly few other fields, if you look closely at you game you may find out that most of the zone only need one attribute at a time, i.e. draw pile always have cards face down, hand always face up, also for hand and discard order does not matter at all (but for draw it does matter). So in majority of cases we can get away with one single extra integer field representing state or order
* In real database both card and zone will be integers as primary keys referring to additional tables, but in our case its total overkill, so they can be strings as easily

Variant 1: Minimalistic

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_key` varchar(32) unsigned NOT NULL,
`card_location` varchar(32) NOT NULL,
`card_state` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Variant 2: More normalised

This version supported by Deck php class, so unless you want to rewrite db access layer go with this one

<pre>
CREATE TABLE IF NOT EXISTS `card` (
`card_id` int(10) unsigned NOT NULL AUTO_INCREMENT,
`card_type` varchar(16) NOT NULL,
`card_type_arg` int(11) NOT NULL,
`card_location` varchar(16) NOT NULL,
`card_location_arg` int(11) NOT NULL,
PRIMARY KEY (`card_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 AUTO_INCREMENT=1 ;
</pre>

Note: if you using this schema, some zones/locations have special semantic. The 'hand' location is actually multiple locations - one per player, but player id is encoded as card_location_arg. If 'hand' in your game is ordered, visible or can have some other card states, you cannot use hand location (replacement is hand_<player_id> or hand_<color_id>)

== Game Elements ==

=== Resource ===

A game resource, such as "wood," is usually infinite and represented by a count allocated to a specific player or supply.

If a resource can be placed on location, use the "Meeple" model described below.

For a working example, you can check out: [https://codepen.io/VictoriaLa/pen/emYgLzR CodePen Example] (ui only).

==== Representation in Database ====
In a minimalistic "tokens" database, it would look like this (e.g., the red player has 3 wood):

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|wood_ff0000
|
|3
|-
|wood_supply
|
|40
|}

The second row you need to store the resource in the supply (if it's counted).

If you don't like this solution can use bga_globals table for this or create your own resource table.

Its not recommened to extend player table to store this information.

==== Representation in Material File (material.inc.php) ====
In the material file, you can define some information about resources. For instance, you can specify that it's of type "resource" and call it "Wood" in English, along with a tooltip:
<pre>
$this->token_types = [
...
'wood' => [
'name' => clienttranslate('Wood'),
'tooltip' => clienttranslate('Game resource used for building houses'),
'type' => 'resource',
'max' => 40
]
];
</pre>

==== HTML Representation ====
In HTML, this would look something like this within the player panel. Using the data attribute instead of a CDATA value is much more flexible:
<pre>
<div id="wood_ff0000" class="resource wood" data-value="3"></div>
</pre>

==== JavaScript Handling ====
When you get the object from the server, one of the tokens will be sent in the array like this:
<pre>
token = {
key: 'wood_ff0000',
location: '-',
state: '3'
}
</pre>

You can create a corresponding `<div>` in the `setup()` method of `game.js` as follows:
<pre>
const playerColor = token.key.split('_')[1];
const resType = token.key.split('_')[0];
const tokenInfo = this.gamedatas.token_types[resType]; // token_types is the structure from the material file sent to the client
const div = `<div id="${token.key}" class="${resType} ${tokenInfo.type} ${token.key}" data-value="${token.state}"></div>`;

if (playerColor != 'supply') {
document.querySelector(`#player_board_${this.getPlayerIdByColor(playerColor)} > .player-board-game-specific-content`).insertAdjacentHTML('beforeend',div);
this.addTooltip(token.key, _(tokenInfo.name) + " " + _(tokenInfo.tooltip), "");
}
</pre>

When you receive an update notification (assuming you get the same "token" object), you can simply update the `data-value`:
<pre>
document.querySelector(`#${token.key}`).dataset.value = token.state;
</pre>

To display the resource in the game log, you can format it like this:
<pre>
Player gains <div class="resource wood" data-value="1"></div>
</pre>
For more on injecting icon images in the log, see: [[BGA_Studio_Cookbook#Inject_icon_images_in_the_log]]

==== Graphic Representation (.css) ====
To properly display the resource image, it is preferable to use an image sprite that includes all resources,
usually it will be .png as these objects have shape.
This how will .css look like with horizontal sprite image:

<pre>
.resource {
background-image: url(https://en.doc.boardgamearena.com/images/d/d3/Cubes.png);
background-repeat: no-repeat;
background-size: cover; /* auto-scale */
aspect-ratio: 1/1; /* that will keep heigh in sync */
width: 32px; /* default size, specific location should override */
}

.wood {
/* Since the sprite is a horizontal row of 11 cubes and 9 is the brown cube position */
background-position: calc(100% / (11 - 1) * 9) 0%;
}
</pre>

To show a text overlay with the resource value, you can use the following CSS:
<pre>
.resource[data-value]:after {
content: attr(data-value);
width: 100%;
height: 100%;
position: absolute;
font-size: xx-large;
text-align: center;
text-shadow: 2px 0 2px #fff, 0 -2px 2px #fff, 0 2px 2px #fff, -2px 0 2px #fff;
}
</pre>

This solution is fully scalable — you only need to specify the size where you want it displayed.
For example:
<pre>
.player_board_content > .resource {
width: 40px;
position: relative;
}
</pre>

Note: if you have that board that tracks the resource on resource tracker - you can show this IN ADDITION of showing resource on player panel.

==== Selection and Actions ====
It is best to put buttons with resource images on the status bar, rather than having the player click on the player panel.

For animation:
* Can use move animation to animate resourced gained or played from the board location to the player panel
* Can use "vapor" animation to show resource gained from the board

=== Meeple ===

A meeple is a game piece, typically representing a "worker," depicted as a human-shaped figure in a specific color assigned to a player.

The key distinction between meeples and traditional resources is that meeples are placed on locations and can exist
in at least two states — standing or lying down.

This concept also applies to similar pieces like "houses," "animeeples," "ships," and others.

==== Representation in Database ====
In a simplified "tokens" database, it might be represented like this
(e.g., the red player's first meeple is on action spot 1, while the white meeple remains in supply):

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|meeple_ff0000_1
|actionspot_1
|1
|-
|meeple_ffffff_1
|supply
|0
|}

==== Representation in Material File (material.inc.php) ====

Here we define some properties, for example name can be used in notification and as tooltip, type can be used to create the div by
javascript, 'create' - can be used by server to create 8 meeples of this type in database and set location to 'supply_ff0000'

<pre>
$this->token_types = [
...
'meeple_ff0000' => [
'name' => clienttranslate('Red Worker'),
'type' => 'meeple meeple_ff0000',
'create' => 8,
'location' => 'supply_ff0000'
]
];
</pre>

==== HTML Representation ====
In HTML, this would look something like this.
<pre>
<div id="meeple_ff0000_1" class="meeple meeple_ff0000" data-state="1"></div>
</pre>

==== JavaScript Handling ====
When you get the object from the server, each meeple object will be similar to this:
<pre>
meeple = {
key: 'meeple_ff0000_1',
location: 'actionslot_1',
state: '1'
}
</pre>

You can create a corresponding `<div>` in the `setup()` method of `game.js` as follows:
<pre>
const playerColor = token.key.split('_')[1];
const resType = token.key.split('_')[0];
const tokenInfo = this.gamedatas.token_types[resType]; // token_types is the structure from the material file sent to the client
const div = `<div id="${token.key}" class="${tokenInfo.type} ${token.key}" data-state="${token.state}"></div>`;

$(token.location).insertAdjacentHTML('beforeend',div);
this.addTooltip(token.key, _(tokenInfo.name) + " " + _(tokenInfo.tooltip), "");
$(token.key).addEventListener('onclick',(ev)=>this.onMeepleClick(ev));

</pre>

When you receive an update notification (assuming you get the same "token" object), you either create it if not exists or animate:
<pre>
if ($(token.key)) {
// exists
$(token.key).dataset.state = token.state; // update state
this.moveToken(token.key, token.location); // animate to new location (custom functon), see [[BGA_Studio_Cookbook#Animation]]
} else {
// crate meeple using code in previous section
}

</pre>

==== Graphic Representation (.css) ====

Use same sprite technique from Resource section above.

When placed on the board it will look good with shadow, but its not recommended on mobile

filter: drop-shadow(black 5px 5px 5px);

To represent "laying down" meeple, you have to use a different sprite image, which you will apply based on data attribute

<pre>
.meeple[data-state="1"] {
background-image: url(...);
}
</pre>

You can also rotate you div, but it will look lame.
Other options include changing its shading, adding overlay (i.e. sad face) and so on.

==== Selection and Actions ====
To show user that meeple is active it best to use drop-shadow as image as non-square, however this may be very slow.
For simplier case use box shadow.

<pre>
.active_slot {
filter: drop-shadow(0px 0px 10px blue);
cursor: pointer;
}

/* draw a circle around game element for selection */
.active_slot_simple:after {
content: " ";
width: 110%;
top: -5%;
left: -5%;
aspect-ratio: 1/1;
position: absolute;
border-radius: 50%;
box-shadow: 0px 0px 4px 3px #64b4ff;
}

</pre>

See code example at https://codepen.io/VictoriaLa/pen/emYgLzR

When a meeple is gained from the supply, you can display a meeple icon on the status bar button
instead of showing the supply on the board.

=== Dice ===
The 2D dice can use similar handing as meeple but it has 6 states instead of 2.

IMPORTANT: Never roll dice using javascript. All dice rolling must be done using bga_rand() function in php.

==== Representation in Database ====
In a simplified "tokens" database, it might be represented like this

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|die_black
|actionspot_1
|1
|-
|die_red
|supply
|6
|}

==== Representation in Material File (material.inc.php) ====

Similar to resource and meeple above

==== HTML Representation ====

<pre>
<div id="die_black" class="die" data-state="1"></div>
</pre>

==== JavaScript Handling (.js) ====
See meeple section

==== Graphic Representation (.css) ====
For dice we would usually use N x 6 sprite, and since the sides are square - the .jpg format is better (it is smaller then png)

<pre>
.die {
background-image: url(https://en.doc.boardgamearena.com/images/c/c5/64_64_dice.jpg);
background-size: 600%;
background-repeat: no-repeat;
aspect-ratio: 1/1;
width: 64px;
border-radius: 5%; /* looks better with rounded corders */
}
.die[data-state="3"] {
background-position: calc(100% / 5 * 2) 0%;
}
</pre>

The 3D dice a bit tricker to create but its feasible, see https://codepen.io/VictoriaLa/pen/QWBBbwz for an example.

Also multiple examples on N-sided dice can be found on [[BGA_Code_Sharing]]

==== Selection and Actions ====
Since it is a square its a lot easier to make a square selection highlight

<pre>
.die.active_slot {
box-shadow: 0px 0px 4px 4px blue;
}
</pre>

=== Card ===

Cards are the most complex game resource, they can be located in various zones, stacked, tapped, put face down and can have arbitrary complete abilities.
If you have square tiles - it can be treated the same as cards.

==== Representation in Database ====

In a simplified "tokens" database, it might be represented like this

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|card_project_123
|tableau_ff0000
|1
|-
|card_corp_p1
|deck_corp
|6
|}

Means project card is player red tableau and state 1 means it has been used for example,
and second card of corproration file in in deck at position 6 from the top.

When duplcates are in play you need to add extra unique disambigator in the key.

Usually cards will have numeric id associated with type, but it this number is per expansition, so leave the space for expansion identifier in there also.

Another option use [[Deck]] component.

==== Representation in Material ====

All the card properties which do not change during the game can be put in material file (or its alternative)

This is example from terraforming mars
<pre>
'card_main_81' => [ //
'location' => 'deck_main',
'create' => 'single',
'num' => 81,
'name' => clienttranslate('Ganymede Colony'),
't' => 1,
'r' => "city('Ganymede Colony')",
'cost' => 20,
'tags' => 'Space City Jovian',
'vp' => 'tagJovian',
'deck' => 'Basic',
'text' => clienttranslate('Place a city tile ON THE RESERVED AREA [for Ganymede Colony].'),
'text_vp' => clienttranslate('1 VP per Jovian tag you have.'),
],
</pre>

==== HTML Representation ====

There is 2 main options:
* Use exact cards images in english
* Use cards images WITHOUT text

The 3d option is completely redo the graphic layout that game designed did already, but I won't go there

The first option is very simple and similar to other resources and meeple

<pre>
<div id="card_project_123" class="card card_project card_project_123" data-state="1"></div>
</pre>

The second option means you can add translated text instead
<pre>
<div id="card_project_123" class="card card_project card_project_123" data-state="1" data-cost="22">
<div class="card_name">Ganymede Colony</div>
<div class="card_text">Place a city tile ON THE RESERVED AREA [for Ganymede Colony].</div>
<div class="card_cost"></div>
</div>
</pre>

In the example above card_cost is also rendered as this can change during the game (even printed value is the same),
it would be rendered using data-cost attribute.

Instead of using class you can also use state even if it is static

<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>

Note: to make flip animation you effectively need to make a "3d" card and provide both faces with separate graphics,
which makes more complex div. See examples at https://thoun.github.io/bga-cards/demo/index.html

Note: you can also use [[Stock]] component that handles html, js, css, layout and selection at the same time. If do that skip sections below.

==== JavaScript Handling (.js) ====
You will get the server data which looks like this

<pre>
card = {
key: 'card_project_123',
location: 'tableau_ff0000',
state: '1'
}
</pre>

<pre>
createCard(token: Token) {
// token_types is the structure from the material file sent to the client
const tokenInfo = this.gamedatas.token_types[token.key];
const div = `
<div id="${token.key}" class="${tokenInfo.type} ${token.key}" data-state="${token.state}">
<div class="card_name">${_(tokenInfo.name)}</div>
<div class="card_text">${_(tokenInfo.text)}</div>
</div>`;

$(token.location).insertAdjacentHTML('beforeend',div);
this.addTooltipHtml(token.key, this.getTooptipHtmlForToken(token));
$(token.key).addEventListener("onclick", (ev) => this.onCardClick(ev));
}
</pre>

When you receive an update notification (assuming you get the same "token" object), you either create it if not exists or animate:
<pre>
if ($(token.key)) {
// exists
$(token.key).dataset.state = token.state; // update state
$(token.key).dataset.cost = token.cost; // update cost (discounted cost)
this.moveCard(token.key, token.location); // animate to new location (custom functon), see [[BGA_Studio_Cookbook#Animation]]
} else {
this.createCard(token);
}
</pre>

==== Graphic Representation (.css) ====

For this html
<pre>
<div id="game" class="classic_deck">
<div id="hand" class="hand">
<div id="card_H_10" class="card" data-suit='H' data-rank="10"> </div>
<div id="card_C_K" class="card" data-suit='C' data-rank="K"> </div>
</div>
</div>
</pre>

This is example css using sprite image of playing cards
<pre>
.card {
background-image: url('https://x.boardgamearena.net/data/others/cards/FULLREZ_CARDS_ORIGINAL_NORMAL.jpg'); /* don't do full url in your game, copy this file inside img folder */

background-size: 1500% auto; /* this mean size of background is 15 times bigger than size of card, because its sprite */
border-radius: 5%;
width: 10em;
height: 13.5em;
box-shadow: 0.1em 0.1em 0.2em 0.1em #555;
}

.card[data-rank="10"] { /* 10 is column number 10 - 2 because we start from 0 and first card is sprite is 2. The multiplier is (15 - 1) is because we have 15 columns. -1 is because % in CSS is weird like that. */
background-position-x: calc(100% / (15 - 1) * (10 - 2));
}
.card[data-rank="K"] { /* King will be number 13 in rank */
background-position-x: calc(100% / (15 - 1) * (13 - 2));
}
.card[data-suit="H"] { /* Hears row position is 1 (because we count from 0). Multiplier (4 - 1) is because we have 4 rows and -1 is because % in CSS is weird like that. */
background-position-y: calc(100% / (4 - 1) * (1));
}
.card[data-suit="C"] { /* Clubs row position is 2 */
background-position-y: calc(100% / (4 - 1) * (2));
}
</pre>
See code at https://codepen.io/VictoriaLa/pen/mdMzRxa

==== Selection and Actions ====

Since it is a square its a lot easier to make a square selection highlight

<pre>
.card.active_slot {
box-shadow: 0px 0px 4px 4px blue;
}
</pre>

==== Card Layouts ====
There are two options - you use [[Stock]] component or don't, see [[Anti-Stock]] for details on how to do your own layouts.

This is comprehensive example of various card layouts and animations
https://thoun.github.io/bga-cards/demo/index.html

=== Hex Tiles ===
From data perspective hex tiles exactly the same as cards.
From visualization there is a small trick.

CSS:
<pre>
.hex {
width: var(--hex-width);
aspect-ratio: 1 / 1.1193;
border-radius: 30%;
background-color: yellow; /* this is just for demo, use proper .png file for this */
clip-path: polygon(50% 0, 100% 25%, 100% 75%, 50% 100%, 0% 75%, 0% 25%);
}

.hex.active_slot_simple {
background-color: rgba(86, 207, 110, 0.4);
}
.hex.active_slot {
filter: drop-shadow(0px 0px 10px blue);
}
</pre>

=== Tetris Tiles ===
You can use clip-path for actual shape and svg path for outline
See example at https://codepen.io/VictoriaLa/pen/OJmoZGw

=== Track ===

Tracker can be represented as "resource" in database - in this case its just number, or similar to "meeple" in which case
the location will have the "number" associated with position on track

In a simplified "tokens" database, it might be represented like this

{| class="wikitable"
|+token
! token_key
! token_location
! token_state
|-
|tracker_o
|scale_o_1
|0
|-
|tracker_t
|scale_t_10
|0
|}

The tracker location in this case may have some properties in material file, for example to trigger game effect when we land on this spot

<pre>
'scale_t' => [
'index_start' => 0,
'max' => 20,
'value_start' => -30,
'value_step' => 2,
'slot_type' => 'slot slot_t'
],
'scale_t_10' => [
'r' => 'ocean',
'param' => 't',
'tooltp' => clienttranslate('Place an ocean'),
'value' => 0
],
</pre>

The track in this case can be generated as series of slots (create in js)
<pre>
for(let i=trackInfo.index_start,value = trackInfo.value_start;i<trackInfo.index_start+trackInfo.max;i++,value+=trackInfo.value_step) {
$(trackInfo.key).insertAdjacentHTML('beforeend',`<div id="${trackInfo.key}_${i}" class="${trackInfo.slot_type} data-value=${value}"></div>`);
this.addTooltip(`${trackInfo.key}_${i}`, _(tokenInfo.tooltip), "");
}
</pre>

Then use regular move animation to move tracker into position on track.

== Code Organization ==

=== Including your own JavaScript module ===
'''Ingredients:''' ggg.js, modules/ggg_other.js

* Create ggg_other.js in modules/ folder and sync
<pre>
define([
"dojo", "dojo/_base/declare"
], function( dojo, declare )
{
return declare("bgagame.other", null, { // null here if we don't want to inherit from anything
constructor: function(){},
mystuff: function(){},
});

});

</pre>
* Modify ggg.js to include it

define([ "dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter",
g_gamethemeurl + "modules/ggg_other.js" // load my own module!!!
], function(dojo,
declare) {

use it

foo = new bgagame.other();

=== Including your own JavaScript module (II) ===

* Create ggg_other.js in modules/ folder and sync

define([], function () {
return "value";
});

* Modify ggg.js to include it

define([
"dojo",
"dojo/_base/declare",
"bgagame/modules/ggg_other",
"ebg/core/gamegui",
"ebg/counter"
], function(dojo, declare, other) {

});

This is maybe a little bit more the idea of the AMD Loader than the first option, although the first option should work as well.

A little explanation to this:
The define function loads all the modules listed in the array and calls the following function with these loaded modules as parameters.
By putting your module at the third position in the array it is passed as the third parameter to the function. Be aware that the modules are resolved by position only, not by name. So you can load the module '''ggg_other''' and pass it as a parameter with the name '''other'''. '''gamegui''' and '''counter''' are passed in as well, but when the parameters are not defined they are just skipped. Because these modules put their content into the global scope it does not matter and you can use them from there.

In the example above the string "value" is passed for the parameter '''other''', but the function in your module can return whatever you want. It can be an object, an array, something you declared with dojo.declare, you can return even functions.
Your module can load other modules. Just put them in the array at the beginning and pass them as parameters to your function.
The advantage of passing the values as parameter is that you do not need to put these values in the global scope, so they can't be collisions with values defined in other scripts or the BGA Framework.

The dojo toolkit provides good documentation to all of its components, the complete documentation for the AMD-Loader is here:
https://dojotoolkit.org/documentation/tutorials/1.10/modules/index.html It should be still correct, even as it seems to be only for version 1.10

=== Including your own PHP module ===
'''Ingredients:''' ggg.game.php, modules/ggg_other.php

* Create ggg_other.php in modules/ folder and sync
* Modify ggg.game.php to include it

require_once ('modules/ggg_other.php');

=== Creating a test class to run PHP locally ===

'''Ingredients:''' ggg.game.php, stubs
For this you need stubs of other method you can use this for example
https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

Create another php files, i.e ggg_test.php
<pre>
<?php
define("APP_GAMEMODULE_PATH", "misc/"); // include path to stubs, which defines "table.game.php" and other classes
require_once ('eminentdomaine.game.php');

class MyGameTest1 extends MyGame { // this is your game class defined in ggg.game.php
function __construct() {
parent::__construct();
include '../material.inc.php';// this is how this normally included, from constructor
}

// override/stub methods here that access db and stuff
function getGameStateValue($var) {
if ($var == 'round')
return 3;
return 0;
}
}
$x = new MyGameTest1(); // instantiate your class
$p = $x->getGameProgression(); // call one of the methods to test
if ($p != 50)
echo "Test1: FAILED";
else
echo "Test1: PASSED";

</pre>

Run from command line like
php8.2 ggg_test.php

If you do it this way - you can also use local php debugger (i.e. integrated with IDE or command line).

=== Avoiding code in dojo declare style ===
Dojo class declarations are rather bizzare and do not work with most IDEs.
If you want to write in plain JS with classes, you can stub all the dojo define/declare stuff
and hook your class into that, so the classes are outside of this mess.

NOTE: this technique is for experienced developers, do not try it if you do not understand
the consequences.

This is complete example of game .js class
<pre>
// Testla is game name is has to be changed
class Testla {
constructor(game) {
console.log('game constructor');
this.game = game;
this.varfoo = new MyFoo(); // this example of class from custom module
}

setup(gamedatas) {
console.log("Starting game setup", this.varfoo);
this.gamedatas = gamedatas;
this.dojo.create("div", { class: 'whiteblock', innerHTML: _("hello") }, 'thething');
console.log("Ending game setup");
};
onEnteringState(stateName, args) {
console.log('onEnteringState : ' + stateName, args);
this.game.addActionButton('b1',_('Click Me'), (e)=>this.onButtonClick(e));
};
onLeavingState(stateName) {
console.log('onLeavingState : ' + stateName, args);
};
onUpdateActionButtons(stateName, args) {
console.log('onUpdateActionButtons : ' + stateName, args);
};
onButtonClick(event) {
console.log('onButtonClick',event);
};
};

define([
"dojo", "dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
g_gamethemeurl + '/modules/foo.js' // custom module if needed
],
function(dojo, declare) {
// testla is game name is has to be changed
return declare("bgagame.testla", ebg.core.gamegui, {
constructor: function() {
this.xapp = new Testla(this);
this.xapp.dojo = dojo;
},
setup: function(gamedatas) {
this.xapp.setup(gamedatas);
},
onEnteringState: function(stateName, args) {
this.xapp.onEnteringState(stateName, args?.args);
},
onLeavingState: function(stateName) {
this.xapp.onLeavingState(stateName, args);
},
onUpdateActionButtons: function(stateName, args) {
this.xapp.onUpdateActionButtons(stateName, args);
},
});
});

</pre>

=== More readable JS: onEnteringState ===

If you have a lot of states in onEnteringState or onUpdateActionButtons and friends - it becomes rather wild, you can do this trick to call some methods dynamically.

<pre>

onEnteringState: function(stateName, args) {
console.log('Entering state: ' + stateName, args);

// Call appropriate method
var methodName = "onEnteringState_" + stateName;
if (this[methodName] !== undefined) {
console.log('Calling ' + methodName, args.args);
this[methodName](args.args);
}
},

onEnteringState_playerTurn: function(args) { // this is args directly, not args.args
// process
},

onEnteringState_playerSomethingElse: function(args) {
// process
},

</pre>

Note: since its ignores the undefined functions you don't have define function for each state, but on the other hand you cannot make typos.
Same applies to onUpdateActionButtons except you pass 'args' to method, not args.args, and for onLeavingState where you don't pass anything.

=== Frameworks and Preprocessors ===

* [[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
* [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
* [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner

=== PHP Migration ===

'''Ingredients:''' */php, modules/*.php

BGA recently migrated to from 7.4 to 8.2.
New php has new rules and deprecations.

There is a tool that can help you do the migration automation, which is php module called rector https://getrector.com/.
Below is the recipe that converts variables in strings like ${var} (which is deprecated) to {$var}.

1. Install the module
composer global require --dev rector/rector
2. Go to your project directory, commit your code first before this!

3. Create a rector.php file on top level with the following content:
<pre>
<?php

use Rector\Config\RectorConfig;
use Rector\Php82\Rector\Encapsed\VariableInStringInterpolationFixerRector;

return RectorConfig::configure()
->withPaths([
__DIR__
])
// A. whole set
//->withPreparedSets(typeDeclarations: true)
// B. or few rules
->withRules([
VariableInStringInterpolationFixerRector::class
]);
</pre>
4. Dry run (mine is on linux, not sure where global install on windows)
~/.config/composer/vendor/bin/rector process --dry-run

5. If happy re-run without --dry-run

6. Can remove rector.php now (or can do different rules)

== Backend ==

=== Assigning Player Order ===
Normally when game starts there is "natural" player order assigned randomly.

If you want to deliberatly assign player order at the start of the game (for example, in a game with teams options), you can do so by retrieving the initialization-only player attribute '''player_table_order''' and using it to assign values to '''player_no''' (which is normally assigned at the start of a game in the order in which players come to the table). (See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql#The_player_table Game database model] for more details.)

<div style="padding: 1em; background: #FFCDD2; color: #B71C1C">
<b>WARNING:</b> To prevent unfair advantage (e.g. collusion), the random order must be the default option and <b>non-random options should be limited to friendly mode.</b>
</div>

'''Example:'''
<pre>
// Retrieve inital player order ([0=>playerId1, 1=>playerId2, ...])
$playerInitialOrder = [];
foreach ($players as $playerId => $player) {
$playerInitialOrder[$player['player_table_order']] = $playerId;
}
ksort($playerInitialOrder);
$playerInitialOrder = array_flip(array_values($playerInitialOrder));

// Player order based on 'playerTeams' option
$playerOrder = [0, 1, 2, 3];
switch ($this->getGameStateValue('playerTeams')) {
case $this->TEAM_1_2:
$playerOrder = [0, 2, 1, 3];
break;
case $this->TEAM_1_4:
$playerOrder = [0, 1, 3, 2];
break;
case $this->TEAM_RANDOM:
shuffle($playerOrder);
break;
default:
case $this->TEAM_1_3:
// Default order
break;
}

// Create players
// Note: if you added some extra field on "player" table in the database (dbmodel.sql), you can initialize it there.
$sql =
'INSERT INTO player (player_id, player_color, player_canal, player_name, player_avatar, player_no) VALUES ';
$values = [];

foreach ($players as $playerId => $player) {
$color = array_shift($default_colors);
$values[] =
"('" .
$playerId .
"','$color','" .
$player['player_canal'] .
"','" .
addslashes($player['player_name']) .
"','" .
addslashes($player['player_avatar']) .
"','" .
$playerOrder[$playerInitialOrder[$playerId]] .
"')";
}
$sql .= implode(',', $values);
$this->DbQuery($sql);
$this->reattributeColorsBasedOnPreferences(
$players,
$gameinfos['player_colors']
);
$this->reloadPlayersBasicInfos();
</pre>

=== Send different notifications to active player vs everybody else ===

'''Ingredients:''' ggg.js

Hack alert. This is a hack. We were hoping for proper solution by bga framework.

This will allow you to send notification with two message one for specific player and one for everybody else including spectators.
Note that this does not split the data - all data must be shared.

Add this to .js file (if you already overriding it merge obviously)
<pre>
/** @Override */
format_string_recursive: function(log, args) {
if (typeof args.log_others != 'undefined' && typeof args.player_id != 'undefined' && this.player_id != args.player_id)
log = args.log_others;
return this.inherited(arguments); // you must call this to call super
},
</pre>

Example of usage (from eminentdomain)
<pre>
$this->notify->all('tokenMoved',
clienttranslate('${player_name} adds +2 Colonies to ${place_name}'), // notification with show for player with player_id
['player_id'=>$player_id, // this is mandatory
'log_others'=>clienttranslate('${player_name} adds +2 Colonies to an unknown planet'), // notification will show for others
...
]);
</pre>

=== Send transient notifications without incrementing move ID ===

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

Use this if you need to send some transient notification that should not create a new move ID. The notification should be idempotent -- it should have no practical effect on the game state and would be '''safe to drop''' (e.g., it would not matter if a player never received this notification). For example, in a co-op game you want all players to see a real-time preview of some action, before the active player commits their turn.

Doing this mainly affects the instant replay & archive modes. During replay, the BGA framework automatically inserts a 1.5-second pause between each "move". With this hack, your transient notifications are not considered to be a "move", so no pause gets added.

; In ggg.php
<pre>
$this->not_a_move_notification = true; // note: do not increase the move counter
$this->notify->all('cardsPreview', '', $args);
</pre>

Note: you cannot have code that send notification or even changes state after this, and you cannot reset this variable back either because it only takes effect when you exit action handling function

== Assorted Stuff ==

=== Out-of-turn actions: Un-pass ===

'''Ingredients:''' ggg.js, ggg.game.php, ggg.action.php, states.inc.php

In multiplayer game sometimes players passes but than they think more and want to un-Pass and redo their choice.
To re-active a player who passes some trickery required.

Define a special action that does that and hook it up.

In states.inc.php add an action to multipleactiveplayer state to "unpass", lets call it "actionCancel"

In ggg.action.php add action hook
public function actionCancel() {
$this->setAjaxMode();
$this->game->actionCancel();
$this->ajaxResponse();
}

In ggg.game.php add action handler
function actionCancel() {
$this->gamestate->checkPossibleAction('actionCancel');
$this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
}

Finally to call this in client ggg.js you would do something like:
<pre>
onUpdateActionButtons: function(stateName, args) {
if (this.isCurrentPlayerActive()) {
// ...
} else if (!this.isSpectator) { // player is NOT active but not spectator
switch (stateName) {
case 'playerTurnMultiPlayerState':
this.addActionButton('button_unpass', _('Oh no!'), 'onUnpass');
break;
}
}
}

onUnpass: function(e) {
this.bgaPerformAction("actionCancel", null, { checkAction: false }); // no checkAction!
}
</pre>
Although be careful that if the turn comes back to the player while he is about to click cancel, the action buttons will be updated and the player will misclick which can be quite frustrating. To avoid this, move the cancel button to another position, like to the left of pagemaintitletext:
dojo.place('button_unpass', 'pagemaintitletext', 'before');
Being out of the generalactions div, it won't be automatically destroyed like normal buttons, so you'll have to handle that yourself in onLeavingState. You might also want to change the button color to red (blue buttons for active player only, red buttons also for inactive players?)

Note: same technique can be used to do other out-of-turn actions, such as re-arranging cards in hand, exchanging resources, etc (i.e. if permitted by rules, such as "at any time player can...")

=== Multi Step Interactions: Select Worker/Place Worker - Using Selection ===

'''Ingredients:''' ggg.js

Simple way to implement something like that without extra states is to use "selection" mechanism. When user click on worker add some sort of class into that element i.e. 'selected' (which also have to have some indication by css i.e. outline).

Than user can click on placement zone, you can use dojo.query for "selected" element and use it along with zone id to send data to server. If proper worker is not selected yet can give a error message using this.showMessage(...) function.

Extra code required to properly cleanup selection between states.
Also when you do that sometimes you want to change the state prompt, see below 'Change state prompt'

=== Multi Step Interactions: Select Worker/Place Worker - Using Client States ===

'''Ingredients:''' ggg.js

I don't think its documented feature but there is a way to do client-only states, which is absolutely wonderful for few reasons
* When player interaction is two step process, such as select worker, place worker, or place worker, pick one of two resources of your choice
* When multi-step process can result of impossible situation and has to be undone (by rules)
* When multi-step process is triggered from multiple states (such as you can do same thing as activated card action, pass action or main action)

So lets do Select Worker/Place Worker

Define your server state as usual, i.e. playerMainTurn -> "You must pick up a worker".
Now define a client state, we only need "name" and "descriptionmyturn", lets say "client_playerPicksLocation". Always prefix names of client state with "client_" to avoid confusion. Now we have to do the following:
* Have a handler for onUpdateActionButtons for playerMainTurn to activate all possible workers he can pick
* When player clicks workers, remember the worker in one of the members of the main class, I usually use one called this.clientStateArgs.
* Transition to new client state
onWorker: function(e) {
var id = event.currentTarget.id;
dojo.stopEvent(event);
... // do validity checks
this.clientStateArgs.worker_id = id;
this.setClientState("client_playerPicksLocation", {
descriptionmyturn : _("${you} must select location"),
});
}
* Have a handler for onUpdateActionButtons for client_playerPicksLocation to activate all possible locations this worker can go AND add Cancel button (see below)
* Have a location handler which will eventually send a server request, using stored this.clientStateArgs.worker_id as worker id
* The cancel button should call a method to restore server state, also if you doing it for more than one state you can add this universally using this.on_client_state check

if (this.isCurrentPlayerActive()) {
if (this.on_client_state && !$('button_cancel')) {
this.addActionButton('button_cancel', _('Cancel'), dojo.hitch(this, function() {
this.restoreServerGameState();
}));
}
}
Note: usually I call my own function call this.cancelLocalStateEffects() which will do more stuff first then call restoreServerGameState(), same function is usually needs to be called when server request has failed (i.e. invalid move)

Note: If you need more than 2 steps, you may have to do client side animation to reflect the new state, which gets trickier because you have to undo that also on cancellation.

Code is available here [https://github.com/elaskavaia/bga-sharedcode/blob/master/sharedcode.js sharedcode.js] (its using playerTurnPlayCubes and client_selectCubeLocation).

=== Action Stack - Using Client States ===

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access.

Examples:
* Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
* Ultimate Railroads - action taking game where effects can be executed in any order
* Lewis and Clark - card game where actions executed as queue

There is two ways of implementing it - on the server or the client.
For the server see article below.
The requirement for client side stack implementation is - all action can be undone, which means
* No dice rolls
* No card drawn
* No other players interaction

No snippets are here, as this will be too complex but basically flow is:
* You have a action/effect stack (queue/list) as js object attached to "this", i.e. this.unprocessed_actions
* When player plays a card, worker, etc, you read the effect of that card from the material file (client copy), and place into stack
* Then we call dispatch method which pulls the next action from the stack and change client state accordinly, i.e. this.setClientState("client_playerGainsCubes")
* When players acts on it - the action is removed from the stack and added to "server action arguments" list, this is another object which be used to send ajax call, i.e. this.clientStateArgs
* If nothing left in stack we can submit the ajax call assembling parameters from collected arguments (that can include action name)
* This method allows cheap undo - by restoring server state you will wipe out all user actions (but if you need intermediate aninmation you have to handle it yourself)

Code can be found in Ultimate Railroads game (but it is random access list - so it a bit complex) and Lewis and Clark (complexity - user can always deny part of any effect)

=== Action Stack - Using Server States ===

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response. The "top" can be choice of multiple actions, in this case player has to chose one before resolving the effect.
* Player state knows about the stack and pulls arguments (argX) from the effect arguments of the db
* Player action should clear up the top effect, and can possibly add more effects, then switch to "dispatcher" state again
* If stack is empty, dispatcher can either pick next player itself or use another game state which responsible for picking next player

Code can be found in Tapestry and Terraforming Mars.
=== Custom error/exception handling in JavaScript ===

; In ggg.php
Throw \BgaUserException with some easy-to-identify prefix such as "!!!" and a custom error code. DO NOT TRANSLATE this message text. The exception will rollback database transaction and cancel all changes (including any notifications).
<pre>
function foo(bool $didConfirm = false): void
{
// do processing for the user's move
// afterwards, you determine this move will end the game
// so you want to rollback the transaction and require the user to confirm the move first

if ($gameIsEnding && !$didConfirm) {
throw new \BgaUserException('!!!endGameConfirm', 9001);
}
}
</pre>

; In ggg.js
Override framework function showMessage to suppress the red banner message and gamelog message when you detect the "!!!" prefix
<pre>
/* @Override */
showMessage: function (msg, type) {
if (type == "error" && msg && msg.startsWith("!!!")) {
return; // suppress red banner and gamelog message
}
this.inherited(arguments);
},
</pre>

Deal with the error in your callback:
<pre>
fooAction: function (didConfirm) {
var data = {
foo: "bar",
didConfirm: !!didConfirm,
};
this.bgaPerformAction("fooAction", data).catch((error, errorMsg) => {
if (error && errorMsg == "!!!endGameConfirm") {
// your custom error handling goes here
// for example, show a confirmation dialog and repeat the action with additional param
this.confirmationDialog(
_("Doing the foo action now will end the game"),
() => this.fooAction(true)
);
}
});
},
</pre>

For custom global error handling, you could modify ajaxcallwrapper:
<pre>
ajaxcallwrapper: function (action, args, handler) {
if (!args) args = {};
args.lock = true;
args.version = this.gamedatas.version;
if (this.checkAction(action)) {
this.bgaPerformAction(
action,
args
).catch((error, errorMsg, errorCode) => {
if (error && errorMsg == "!!!checkVersion") {
this.infoDialog(
_("A new version of this game is now available"),
_("Reload Required"),
() => {
window.location.reload();
},
true
);
} else {
if (handler) handler(error, errorMsg, errorCode);
}
}
);
}
},
</pre>

=== Force players to refresh after new deploy ===

When you deploy a new version of your game, the PHP backend code is immediately updated but the JavaScript/HTML/CSS frontend code *does not update* for active players until they manually refresh the page (F5) in their browser. Obviously this is not ideal. In the best case, real-time tables don't see your shiny new enhancements. In the worst case, your old JS code isn't compatible with your new PHP code and the game breaks in strange ways (any bug reports filed will be false positives and unable to reproduce). To avoid any problems, you should force all players to immediately reload the page following a new deploy.

By throwing a "visible" exception (simplest solution), you'll get something like this which instructs the user to reload:

[[File:Force-refresh.png|950x950px]]

Or, if you combine this technique with the above custom error handling technique, you could do something a bit nicer. You could show a dialog box and automatically refresh the page when the user clicks "OK":

[[File:Reload-required.png|500x500px]]
; In ggg.php
Transmit the server version number in <code>getAllDatas()</code>.
<pre>
protected function getAllDatas(): array
{
$players = $this->getCollectionFromDb("SELECT player_id id, player_score score FROM player");
return [
'players' => $players,
'version' => intval($this->gamestate->table_globals[300]), // <-- ADD HERE
...
];
}
</pre>

Create a helper function to fail if the client and server versions mismatch. Note the version check uses <code>!=</code> instead of <code><</code> so it can support rollback to a previous deploy as well. ;-)
<pre>
public function checkVersion(int $clientVersion): void
{
if ($clientVersion != intval($this->gamestate->table_globals[300])) {
// Simplest way is to throw a "visible" exception
// It's ugly but comes with a "click here" link to refresh
throw new BgaVisibleSystemException($this->_("A new version of this game is now available. Please reload the page (F5)."));

// For something prettier, throw a "user" exception and handle in JS
// (see BGA cookbook section above on custom error handling)
throw new \BgaUserException('!!!checkVersion');
}
}
</pre>
; In ggg.action.php
Create a helper function for actions:
<pre>
private function checkVersion()
{
$clientVersion = (int) $this->getArg('version', AT_int, false);
$this->game->checkVersion($clientVersion);
}
</pre>

Call <code>$this->checkVersion()</code> at the top of <b>every action function</b>, immediately after <code>$this->setAjaxMode()</code>:
<pre>
public function move()
{
$this->setAjaxMode();
$this->checkVersion(); // <-- ADD HERE
...
$this->ajaxResponse();
}
</pre>

; In ggg.js
Transmit the version (from gamedatas) as a parameter with every ajax call. For example, if you're already using a wrapper function for every ajax call, add it like this:
<pre>
ajaxcallwrapper: function (action, args) {
if (!args) args = {};
args.version = this.gamedatas.version; // <-- ADD HERE
this.bgaPerformAction(action, args);
},
</pre>

=== Disable / lock table creation for new deploy ===

If you are deploying a major new game version, especially if it involves upgrading production game databases, you may have a lot of angry players if you break their tables. Depending on your changes, you may be able to restore the previous version and fix the tables easily.

However, if a new deploy turns out bad and players created turn-based tables while it was live, it may be quite difficult to fix those tables, since they were created from a bad deploy.

The solution? You can announce in your game group that you are locking table creation, and then in your new version, add an impossible startcondition to an existing option.
Note: This only makes sense if you have a few games running in real time mode in the time of deployment, otherwise it won't achieve much, unless you wait at least a day for other turn based games to break (or not)

Here is an example of an option with only 2 values (if you don't have options at all you have to create a fake option to use this method, if you have more values - you have to list them all):

; In gameoptions.json
<pre>
"startcondition": {
"0": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ],
"1": [ { "type": "minplayers", "value": 32, "message": "Maintenance in progress. Table creation is disabled." } ]
},
</pre>
; In gameoptions.inc.php (older method if you have it in php)
<pre>
// TODO NEXT remove after testing deploy to upgrade, here 0 and 1 - replace with values of your option!
'startcondition' => [
0 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
1 => [ [ 'type' => 'minplayers', 'value' => 32, 'message' => totranslate('Maintenance in progress. Table creation is disabled.') ] ],
],
</pre>

* Be sure to click "Reload game options configuration" after making this change, then test in studio (test that you cannot create any table)
* Deploy to production
* Now, when a player attempts to create a new table, they will see a red error bar with your "Maintenance in progress" message.
* Wait for screaming (if you have real times games in progress waiting 15 min probably ok, if you have only turn based games, probably a day)
* Once you confirm the new deploy looks good, you can revert the change in gameoptions.inc.php and do another deploy.

=== Local Storage ===

There is not much you can store in localStorage (https://developer.mozilla.org/docs/Web/API/Window/localStorage), since most stuff should be stored either in game db or in user prefrences,
but some stuff makes sense to store there, for example "zoom" level (if you use custom zooming). This setting really affect this specific host and specific browser, setting it localStorage makes most sense.

game.js
<pre>
setup: function (gamedatas) {
let zoom = localStorage.getItem(`${this.game_name}_zoom`);
this.setZoom(zoom);
...
},
</pre>
In this case setZoom is custom function to actually set it.
When zoom changed, for example when some buttons pressed, store current value (but sanitize it so it never so bad that game cannot be viewed

<pre>
setZoom: function (zoom) {
zoom = parseInt(zoom) || 0;
if (zoom === 0 || zoom < 0.1 || zoom > 10) {
zoom = 1;
}
this.zoom = zoom;
localStorage.setItem(`${this.game_name}_zoom`, "" + this.zoom);
... do actual zooming stuff
},
</pre>

=== Capture client JavaScript errors in the "unexpected error" log ===

PHP (backend) errors are recorded in the "unexpected error" log, but JavaScript (frontend) errors are only available in the browser itself. This means you have no visibility about things that go wrong in the client... unless you make clients report their errors to the server.

; In actions.php:
<pre>
public function jsError()
{
$this->setAjaxMode(false);
$this->game->jsError($_POST['userAgent'], $_POST['msg']);
$this->ajaxResponse();
}
</pre>

; In game.php:
<pre>
public function jsError($userAgent, $msg): void
{
$this->error("JavaScript error from User-Agent: $userAgent\n$msg // ");
}
</pre>

; In game.js:
<pre>
define(["dojo", "dojo/_base/declare", "ebg/core/gamegui", "ebg/counter"], function (dojo, declare) {
const uniqJsError = {};
...

return declare("bgagame.nowboarding", ebg.core.gamegui, {
...
/* @Override */
onScriptError(msg) {
if (!uniqJsError[msg]) {
uniqJsError[msg] = true;
console.error("⛔ Reporting JavaScript error", msg);
this.ajaxcall(
"/" + this.game_name + "/" + this.game_name + "/jsError.html",
{
msg,
userAgent: navigator.userAgent,
},
this,
() => {},
() => {},
"post"
);
}
this.inherited(arguments);
},
</pre>

== Algorithms ==

=== Generate permutations in lexicographic order ===

Use this when you have an array like [1, 2, 3, 4] and need to loop over some/all 24 permutations of possible ordering. This type of [https://www.php.net/manual/en/language.generators.syntax.php generator function] computes each possibility one at a time, making it vastly more efficient than either a normal iteration or recursive function that produce all possibilities up front.

<pre>
function generatePermutations(array $array): Generator
{
// https://en.wikipedia.org/wiki/Permutation#Generation_in_lexicographic_order
// Sort the array and this is the first permutation
sort($array);
yield $array;

$count = count($array);
do {
// Find the largest index k where a[k] < a[k + 1]
// End when no such index exists
$found = false;
for ($k = $count - 2; $k >= 0; $k--) {
$kvalue = $array[$k];
$knext = $array[$k + 1];
if ($kvalue < $knext) {
// Find the largest index l greater than k where a[k] < a[l]
for ($l = $count - 1; $l > $k; $l--) {
$lvalue = $array[$l];
if ($kvalue < $lvalue) {
// Swap a[k] and a[l]
[$array[$k], $array[$l]] = [$array[$l], $array[$k]];

// Reverse the sequence from a[k + 1] up to and including the final element
$reverse = array_reverse(array_slice($array, $k + 1));
array_splice($array, $k + 1, $count, $reverse);
yield $array;

// Restart with the new array to find the next permutation
$found = true;
break 2;
}
}
}
}
} while ($found);
}
</pre>

Usage:
<pre>
$cash = [4, 1, 2, 3, 4];
foreach ($this->generatePermutations($cash) as $p) {
// your code here to evaluate permutation $p
// first iteration: $p = [1, 2, 3, 4, 4]
// last (60th) iteration: $p = [4, 4, 3, 2, 1]
// break from loop once you achieve your goal
}
</pre>

[[Category:Studio]]

Gamehelpharmonies

2025-01-22T09:01:32Z

Mizutismask: clarify side A water count with loops

== Overview ==

Your goal is to earn the most points and win the game by building landscapes and creating habitats for your animals.

There are 23 blue tokens, 23 grey, 21 brown, 19 green, 19 yellow and 15 red.

Nature's Spirit Cards can be added to the game and provide additional scoring conditions. When integrated into the game, choose between 2 randomly dealt spirit cards before taking your first turn. The Spirit Card scoring conditions are described on the card.

== On your turn ==

In the order of your choosing:

You must choose a set of 3 tokens on the central board and place them onto your board with the following rules:

- It can always be placed on an empty space.

- It can be placed on top of 1 or 2 previously placed tokens to create trees, buildings or mountains (see diagram below).

- It cannot be placed underneath other tokens or on top of a cube.

[[File:Harmonies.png]]

Then you may take an animal card. The card will be placed on top of your board in one of the 4-card slots.

Each animal card has its habitat pattern. You may place a cube from the animal card to fulfill the pattern on the corresponding token. You cannot place more than one cube to a token. You may place unlimited cubes according to the patterns available to you.

Once the final cube on an animal card has been placed, it will no longer count against your 4-card limit.

== End of the game ==

When there are no tokens left to refill the central board or any player has 2 or fewer empty spaces on their board, finish the round and calculate points.
{|class="wikitable" style="max-width:50rem;text-align:center;" border="2"
!Token
!Formation
!Scoring
|-
! style="background:#6e790f;color:#fff" | Tree
|1 green token placed on top of 0/1/2 brown tokens
|The scores corresponding are 1/3/7 pts.
|-
! style="background:#858983;color:#fff" | Mountain
|A stack made of 1/2/3 gray tokens
|The scores corresponding are 1/3/7 pts. (Only mountains adjacent to another mountain score.)
|-
! style="background:#deae09;color:#fff" | Field
|2+ yellow tokens
|Each 2+ contiguous yellow tokens group you get 5 pts.
|-
! style="background:#b82521;color:#fff" | Building
|1 red token on top of another token
|Each Building scores 5 pts if surrounded by at least 3 tokens of different colors (only consider the top of each adjacent place).
|-
! style="background:#197984;color:#fff" | Water ''(Side A)''
|Blue tokens
|Score for your longest continuous chain of blue tokens. Choose any two blue tokens and count how many blue tokens connect them by the '''shortest''' path (inclusive of the two selected tokens at both ends of the chain). Score 2/5/8/11/15 pts for a chain of 2/3/4/5/6 blue tokens + 4 pts for every additional token in the chain.
Making '''loops''' is not recommended since according to this shortest rule your river length will be only half of its tokens +1.
|-
! style="background:#197984;color:#fff" | Water ''(Side B)''
|Areas divided by blue tokens
|Each island that is separated from each other by blue tokens gives you 5 pts.
|}

'''Animal cards:''' For each animal card you will score the number indicated in the topmost space without a cube. (If a card still has all of its cubes, it scores zero.)

Gamehelpjustdesserts

2024-10-29T15:46:57Z

Mizutismask:

[[Category:Card games]]
==Objective==

Satisfy customers with your desserts to collect enough customers and win the game.

==Setup==

* Each player starts with 3 desserts of their own (not visible to other players).
* 3 guests visible to all players are at the centre of the table (top of the screen on BGA).

==On Your Turn==

* Draw a dessert and draw a guest to the centre of the table

==== Note ====

* If the last '''dessert''' has been drawn, then the discard pile will be reshuffled into the draw pile.
* If the last '''guest''' has been drawn, then all cards '''below''' the top of the discard pile will be reshuffled into the draw pile.

=== Actions ===

Choose 1 of 3 available actions:

==== Satisfy Customers ====

* Discard dessert cards to fully satisfy all of a guest's cravings without giving them anything that they refuse, then move that guest in front of you.
* If you use their favourite, draw a dessert.
* You can serve at most 2 customers.
* To serve a guest:
*# Select one or more desserts that fully satisfy the customer and click on the cards.
*# Select the customer you are serving.
*# Select ''serve guest''.

==== Go back to the Kitchen ====

* Draw a dessert.

==== Dump your Tray ====

* Discard any number of desserts and draw the same number back.
* If there are any guests with duplicate suits at the end of a turn, remove guests until there is at most 1 of each suit remaining.
* The most recently departed guest can also be served.

==Winning==

* You win if you have three guests of the same suit or five guests of all different suits.
* If no one achieved victory when all guests are served (including the face-up guests, not just an empty draw pile), everyone scores 1 for each guest and 1 for each pair of matching guest. The highest score wins.
* In case of a tie, whoever has the most desserts remaining wins.

==Variants==

===Poaching and Blocking===

* Once per turn, you may attempt to poach (steal) a customer from another player.
* You may attempt to poach a customer by satisfying them.
* That player can block by re-satisfying them.
* If you poach with a favourite, it can only be blocked by another favourite.
* If you are blocked, you take back all the cards you played.
* A player whose guest is stolen draws a dessert. If any favourites are served, the players draw a card for each favourite they played.

===Opening a Buffet===

* This is a fourth turn option.
* To open a buffet, you need to play 4 single-flavoured cards.
* If a buffet is opened, all opponents need to put a guest of their choice back to the middle.
* Then, you draw 3 cards and can serve a guest.

===Expansions===

* The expansions are Just Coffee and Better with Bacon.
* They provide 6 new desserts and 4 new customers each.
* Each pack also introduces a new flavor and a new suit.
* To select these expansions, you must have a premium membership.

== Solo ==

=== Objective ===
Satisfy as many Guests as possible before the Desserts are all gone!

=== How to Play ===
Follow the '''standard rules''' for the way a Guest is satisfied by discarding one or more Dessert cards. When you satisfy someone, add a new Guest to the hungry lineup. You also draw an extra Dessert card immediately if you give a Guest their Favorite thing.

'''Discarding Desserts''': When you’ve satisfied as many of the Guests as you can (or wish to) with the Dessert cards you have, discard 3 (or all of your cards if you have 3 or fewer). After discarding, draw again until you have 5 Dessert cards.

=== The Kitchen is Closing ===
When the Dessert card draw pile is almost gone, you will get all of the remaining Dessert cards into your hand at once. Specifically, if the number of cards remaining is 4 or fewer, after you’ve drawn back to 5, add the rest of the Dessert card deck to your hand.

=== How to Win ===
Your score is the number of Guests you have left unsatisfied when the kitchen closes (i.e. the Dessert deck runs out). The lower your score, the better. A score of 3 or less is a very good score. The ultimate victory is to satisfy everyone!

=== Remaining Guests Rank ===
0 You take the CAKE!

1-3 You did BERRY well!

4-6 That should be PUDDING a smile on your face

7-9 DONUT worry, you can try again!

10+ It’s a SHERBET you’ll do better next time!

Bugsclarification harmonies

2024-09-18T07:01:23Z

Mizutismask:

== River points are incorrect ==
Water point scoring is different on each side of the board. Which side are you using ?

=== Side A : river length ===
Count the number of tokens from one end of the river to the other by the '''SHORTEST''' path, not the longest. If you think the score is wrong, take the beginning and the end of you best river, and count again how you can go from one to the other by the shortest path. Then score 2/5/8/11/15 for a chain of 2/3/4/5/6 blue tokens + 4 points for every additional token in the chain.

=== Side B : zones delimited by blue tokens ===
Each space or group of spaces separated from each other by blue tokens forms an Island. You score 5 points for each island. You always have at least 1 island, even if you don’t create any separation using blue tokens

== Spirit card points are incorrect ==
Whatever kind of points spirits give, they are never counted in the first column, that is reserved for basic points. As shown in the scoring sheet, spirit points are in the second column, with the white cube, written in white, to indicate that this is the spirit score
https://snipboard.io/wETG47.jpg

== I can only see the top token of each pile with Firefox ==
This is due to the option layout.css.has-selector.enabled not being enabled by default before version 129. The best solution is to update firefox.
If you can’t update your firefox, activate this option following this method:
stackoverflow.com/questions/73936048/how-do-you-enable-has-selector-on-firefox

Bugsclarification harmonies

2024-09-18T06:37:49Z

Mizutismask:

== River points are incorrect ==
Water point scoring is different on each side of the board. Which side are you using ?

=== Side A : river length ===
Count the number of tokens from one end of the river to the other by the '''SHORTEST''' path, not the longest. If you think the score is wrong, take the beginning and the end of you best river, and count again how you can go from one to the other by the shortest path. Then score 2/5/8/11/15 for a chain of 2/3/4/5/6 blue tokens + 4 points for every additional token in the chain.

=== Side B : zones delimited by blue tokens ===
Each space or group of spaces separated from each other by blue tokens forms an Island. You score 5 points for each island. You always have at least 1 island, even if you don’t create any separation using blue tokens

== Spirit card points are incorrect ==
Whatever kind of points spirits give, they are never counted in the first column, that is reserved for basic points. As shows in the scoring sheet, spirit points are in the second column, with the white cube, written in white, to indicate that this is the spirit score
https://snipboard.io/wETG47.jpg

== I can only see the top token of each pile with Firefox ==
This is due to the option layout.css.has-selector.enabled not being enabled by default before version 129. The best solution is to update firefox.
If you can’t update your firefox, activate this option following this method:
stackoverflow.com/questions/73936048/how-do-you-enable-has-selector-on-firefox

Bugsclarification harmonies

2024-09-18T04:42:02Z

Mizutismask:

== River points are incorrect ==
Water point scoring is different on each side of the board. Which side are you using ?

=== Side A : river length ===
Count the number of tokens from one end of the river to the other by the '''SHORTEST''' path, not the longest. If you think the score is wrong, take the beginning and the end of you best river, and count again how you can go from one to the other by the shortest path. Then score 2/5/8/11/15 for a chain of 2/3/4/5/6 blue tokens + 4 points for every additional token in the chain.

=== Side B : zones delimited by blue tokens ===
Each space or group of spaces separated from each other by blue tokens forms an Island. You score 5 points for each island. You always have at least 1 island, even if you don’t create any separation using blue tokens

== I can only see the top token of each pile with Firefox ==
This is due to the option layout.css.has-selector.enabled not being enabled by default before version 129. The best solution is to update firefox.
If you can’t update your firefox, activate this option following this method:
stackoverflow.com/questions/73936048/how-do-you-enable-has-selector-on-firefox

Bugsclarification harmonies

2024-08-30T08:55:39Z

Mizutismask: format

Bugsclarification harmonies

2024-08-30T08:54:53Z

Mizutismask: Created page with "=== River points are incorrect === Water point scoring is different on each side of the board. Which side are you using ? == Side A : river length == Count the number of tokens from one end of the river to the other by the SHORTEST path, not the longest. If you think the score is wrong, take the beginning and the end of you best river, and count again how you can go from one to the other by the shortest path. Then score 2/5/8/11/15 for a chain of 2/3/4/5/6 blue tokens..."

=== River points are incorrect ===

Water point scoring is different on each side of the board. Which side are you using ?

== Side A : river length ==

Count the number of tokens from one end of the river to the other by the SHORTEST path, not the longest. If you think the score is wrong, take the beginning and the end of you best river, and count again how you can go from one to the other by the shortest path. Then score 2/5/8/11/15 for a chain of 2/3/4/5/6 blue tokens + 4 points for every additional token in the chain.

== Side B : zones delimited by blue tokens ==

Each space or group of spaces separated from each other by blue tokens forms an Island. You score 5 points for each island. You always have at least 1 island, even if you don’t create any separation using blue tokens

Gamehelpharmonies

2024-08-30T08:46:28Z

Mizutismask: Precision on how water points are calculated on side A

== Overview ==

Your goal is to earn the most points and win the game by building landscapes and creating habitats for your animals.

== On your turn ==

You must choose a set of 3 tokens on the central board and place them onto your board with the following rules:

- It can always be placed on an empty space.

- It can be placed on top of 1 or 2 previously placed tokens to create trees, buildings or mountains (as shown in the rules).

- It cannot be placed underneath other tokens or on top of a cube.

Then you may take an animal card. The card will be placed on top of your board in one of the 4-card slots.

Each animal card has its habitat pattern. You may place a cube from the animal card to fulfill the pattern on the corresponding token. You cannot place more than one cube to a token.

Once the final cube on an animal card has been placed, it will no longer count against your 4-card limit.

== End of the game ==

When there are no tokens left to refill the central board or any player has 2 or fewer empty spaces on their board, finish the round and calculate points.

Trees: A tree is formed by 1 green tokens placed on top of 0/1/2 brown tokens. The scores corresponding are 1/3/7.

Mountains: Only mountains adjacent to another mountain score, for stack made of 1/2/3 gray token, they score 1/3/7.

Fields: Each 2+ contiguous yellow tokens group you get 5 pts.

Building: A building (red token) on top of another token may score 5 if surrounded by at least 3 tokens of different colors (only consider the top of each adjacent place).

[[File:Harmonies.png]]

Water in side A: Count the number of tokens from one end of the river to the other by the '''SHORTEST''' path. Score 2/5/8/11/15 for a chain of 2/3/4/5/6 blue tokens + 4 points for every additional token in the chain.

Water in side B: Each island that is separated from each other by blue tokens gives you 5 pts.

Animal cards: For each animal card you will score the number indicated in the topmost space without a cube.

Bugsclarification nimalia

2024-08-01T07:41:57Z

Mizutismask: Created page with "== Red goals scoring == === I did not get my points while I was second === There a second reward only for 3 or 4 player games, as mentioned on the goal cards === Pandas and gorillas did not give me the right amount of points === Remember that the scoring of this card is the sum of the two categories, you can get 5 points for gorillas and -5 points for pandas, so the total amount is 0 and that’s normal === Crocodiles and flamingoes did not give me the right amoun..."

== Red goals scoring ==

=== I did not get my points while I was second ===

There a second reward only for 3 or 4 player games, as mentioned on the goal cards

=== Pandas and gorillas did not give me the right amount of points ===

Remember that the scoring of this card is the sum of the two categories, you can get 5 points for gorillas and -5 points for pandas, so the total amount is 0 and that’s normal

=== Crocodiles and flamingoes did not give me the right amount of points ===

Same as the previous point, remember that the scoring of this card is the sum of the two categories. Except here, you get 5 points for having LESS flamingoes than the other players

Gamehelpnimalia

2024-02-28T13:39:00Z

Mizutismask: Created page with "The game lasts 5 rounds, and each round comprises 3 phases: * Build Your Reserve * Calculate Your Points * Finish the Round == 1 BUILD YOUR RESERVE == At the beginning of each round, each player draws 3 Animal cards. Then, you simultaneously place one of these cards in front of you, to create and modify your reserve. Next, you pass the 2 remaining cards to your left neighbor (in rounds 1, 3, and 5) or your right neighbor (in rounds 2 and 4). Repeat this procedure with..."

The game lasts 5 rounds, and each round comprises 3 phases:
* Build Your Reserve
* Calculate Your Points
* Finish the Round

== 1 BUILD YOUR RESERVE ==
At the beginning of each round, each player draws 3 Animal cards.
Then, you simultaneously place one of these cards in front of you, to create and modify your reserve.

Next, you pass the 2 remaining cards to your left neighbor (in rounds 1, 3, and 5) or your right neighbor (in rounds 2 and 4).
Repeat this procedure with the 2 cards you just received from your neighbor, and then place the final card.

When you modify your reserve, you must respect the following rules:
* Each card you place must cover at least one space of your existing reserve (this does not apply to the very first card you place).
* The entirety of your reserve must fit within a 6-space×6-space area.
* You are not allowed to tuck a card under cards already in your reserve.

== 2 CALCULATE YOUR POINTS ==
After placing all three cards, everyone scores their
points by moving their tokens on the score track.
You score points according to the different objective
cards that are in effect this round (as indicated by
the Round card).
* Round 1: the blue and green cards.
* Round 2: the green and yellow cards.
* Round 3: the blue and red cards.
* Round 4: the green, yellow and red cards.
* Round 5: the blue, red and yellow cards.

If there is a tie on a red objective, all of the tied players receive (or lose) the points!
'''If the tie is for 1st place, 2nd place is not awarded.'''

== 3 FINISH THE ROUND ==
If this was not the 5th round, advance the Round Counter
token to the number of the next round, and start a new
round. Don’t forget to flip the round Counter token to know
in which direction you should pass your cards this round.
Otherwise, this is the end of the game (see other side).

= END OF THE GAME =
At the end of the 5th round, the player with the most points wins. '''If it’s a tie, the tied player with the most animals of the same type in their reserve wins.'''

Gamehelpexpeditions

2023-05-21T06:53:46Z

Mizutismask: Major update : rules adapted to this edition of the game, and cohesive with the french original version

==Setup==
Every player get 3 tickets and some destinations (12 cards if less than 4 players, 9 otherwise). Six additional destination cards are drawn face up for all players.
==Reveal 4 destinations per player ==
Before starting the game, each player must place a token of their color on the board corresponding to one of their destinations in hand. This is to be done 4 times until all the tokens are placed. These must be placed at least 3 paths from the wind rose.
==Gameplay==
'''On his turn, a player must play an expedition arrow of the color of his choice.''' Either by starting from the wind rose if it is the first, or by continuing the expedition already started.

* If he reaches a '''green destination''', the player who owns the card (if there is one) has '''achieved one of his objectives'''. If it is a common destination, the player places the card in front of him and a new one from the draw pile replaces it.
* If he reaches a '''blue destination''', he '''replays a new arrow from any expedition'''.
* If he reaches a '''red destination''', the player '''wins a ticket'''.
* If a player makes a '''loop''' with an expedition, '''he benefits from the effect of his destination AND replays an arrow of the same color''' starting '''from any point''' of this expedition.

'''On his turn, when he wishes, a player can play up to 2 tickets.'''

A ticket allows you to:

* either '''replay''' an arrow from any expedition
* either '''remove the last arrow''' from an expedition and apply the effect of the destination that was upstream
* or '''exchange one of his cards''' with another of two from the draw pile.

==End of game==
The game ends '''when a player has reached all his destinations'''. Players play again, up to the first player (so everyone has the same number of turns).

A game also stops if all arrows have been played.
==Scoring ==
*each reached destination => 1 point
*each card still in hand at the end => -1 point
*each token taken back => 1 point
*each token still on the board at the end => -1 point
The player with the '''most points wins'''. In the event of a '''tie''', the player with the '''most tickets''' is awarded.
==Additional notes==
An expedition cannot return to itself directly ('''no round trip on the same path'''). But several expeditions of '''different colors can follow the same path'''.

Finally, the Earth is round, the red dots at the edge of the board are one and the same destination point (at the same height only).

Practical debugging

2022-06-05T17:51:40Z

Mizutismask: /* Fully automated version (working on 05/06/2922) */

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

__TOC__

== Tools ==

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

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

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

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

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

== General tip for debugging ==

=== Save & Restore ===

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

You can save up to 3 different states.

=== Refresh ===

If something does not seems to work properly even you "fixed it", it may be refresh issue. Not all files born equal. Some require a lot more steps to get into the game.

See https://en.doc.boardgamearena.com/Studio_file_reference for information on how to "refresh" each files.

== Debugging my game when it cannot start ==

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

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
However errors and logs generated by setupNewGame not always (almost never) there, so see Debug setupNewGame session.
More cases of why game can't start are described on the [[Troubleshooting]] page.

== Debugging an issue with the waiting screen ==

BGA displays a waiting screen during a few seconds inviting free players to become premium when they are playing a lot.

This waiting screen should not in principle impact your game, but in some cases it might.

To test the waiting screen on the studio, you can set the desired duration by adding the get parameter studioLockingDuration with the number of seconds for the lock screen to be displayed. For example to have a 10 seconds waiting screen when you launch a game on the studio:
https://studio.boardgamearena.com?studioLockingDuration=10

Then you can just set it back to zero in the same way with https://studio.boardgamearena.com?studioLockingDuration=0 (or restart your browser to clear the session value).

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

=== Add traces to your code ===

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

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

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

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

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

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

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

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

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

'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method described below in this case (seciton "Debugging setupNewGame").

=== Call php functions from chat ===

This is best feature ever, you can call individual function in your game.php from chat window, see details
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat

=== Dump data and die ===

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

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

Example:
<pre>

// (...my code to debug)

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

// (...my code to debug)

</pre>

Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.
<pre>
echo "<pre>";
var_dump( $my_variable );
echo "</pre>";
</pre>

=== Debug at home ===

If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

To run php locally you need to wrap it into test or something, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

=== Debugging setupNewGame ===

This is separate section because tracing method do not work in this function.
Recommended way to debug it
* leave setupNewGame exactly as in template (inlcuding setting up player table and activating first player), and add a single call at the end
$this->initTables();
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.

Remember that this function cannot send notification or query active or current player. If you need to get player data use $this->loadPlayersBasicInfos().

function initTables() {
try {
$players = $this->loadPlayersBasicInfos();
// ... code the function
} catch ( Exception $e ) {
// logging does not actually work in game init :(
// but if you calling from php chat it will work
$this->error("Fatal error while creating game");
$this->dump('err', $e);
}
}

Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio).

The same problem exists if you game state immediately follow starting state (problem of debugging it without the logs), in this case create a dummy player state in which player just press OK that will transition
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.

Instead of calling initTables directly you can call helper function instead from chat window which will also reset the client, i.e.
function debug_initTables() {
$this->deleteAllTables(); // this suppose to delete/reset all data - you have to implement this function
$this->initTables();
$newGameDatas = $this->getAllTableDatas(); // this is framework function
$this->notifyPlayer($this->getActivePlayerId(), 'resetInterfaceWithAllDatas', '', $newGameDatas); // this is notification to reset all data
$this->notifyAllPlayers("message",'setup called',[]);
}

=== Debugging endOfGame ===

Debugging end of game is hard if game ends! Make sure it does not end, then you can restore to previous state using saved states.
In php file:

$this->processEndOfGame();
if ($this->getBgaEnvironment() == 'studio')
$this->gamestate->nextState('debuglast'); // debug end
else
$this->gamestate->nextState('last'); // real end

You have to end a special user state in states file for debug in states file

<pre>
STATE_GAME_TURN_NEXT_PLAYER => array( // normal state
"name" => "gameTurnNextPlayer",
"description" => '',
"type" => "game",
"action" => "st_gameTurnNextPlayer",
"updateGameProgression" => true,
"transitions" => array(
"next" => STATE_PLAYER_TURN_ACTION,
"loopback" => STATE_GAME_TURN_NEXT_PLAYER,
"last" => STATE_END_GAME,
"debuglast" => STATE_PLAYER_GAME_END // for debugging on studio
),
),
// for debugging end of game
STATE_PLAYER_GAME_END => array(
"name" => "playerGameEnd",
"description" => clienttranslate('Game Over'),
"descriptionmyturn" => clienttranslate('Game Over'),
"type" => "activeplayer",
"args"=>"arg_playerTurnAction",
"possibleactions" => array( "end"),
"transitions" =>
array(
"next" => STATE_END_GAME,
"loopback"=> STATE_PLAYER_GAME_END)
),
</pre>

== Debugging my HTML/CSS layout ==

Example situations

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

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

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

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

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

When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console
<pre>
// this goes outside dojo class - before or after
function reloadCss() {
var links = document.getElementsByTagName("link");
for (var cl in links) {
var link = links[cl];
if (link.rel === "stylesheet" && link.href.includes("99999")) {
var index = link.href.indexOf("?timestamp=");
var href = link.href;
if (index >= 0) {
href = href.substring(0, index);
}

link.href = href + "?timestamp=" + Date.now();

console.log("reloading " + link.href);
}
}
}

</pre>

For mobile its also handy to have this as button (studio only), this goes to setup() function in js:
<pre>
// add reload Css debug button
var parent = document.querySelector('.debug_section');
if (parent) {
var butt = dojo.create('a', { class: 'bgabutton bgabutton_gray', innerHTML: "Reload CSS" }, parent);
dojo.connect(butt, 'onclick', () => reloadCss());
}
</pre>
=== Debugging Toolips CSS/Layout ===

To inspect tooltip you need to pin it so it does not disappear.
* Chrome tools:
** Open dev tools and switch to Source tab to engage with debugger
** Hover over you element until tooltip showing
** Press F8 - that stops the JS, so tooltip should freeze
** Now you can go to Elements tab and find your tooltip at the botton in dijitTooltip div
** Don't forget to resume it again to continue (F8 again or resume button)
* Other method: Open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.

=== Debugging my Javascript game interface logic ===

To debug javascript you just use embedded browser debugger, usually found in Source tab of dev tools (F12)

Modern browsers also allow you to put breakpoints in your js code. It is in source tab, but its a bit difficult to find (your code that is), see picture below on how to insert breakpoints.

[[File:Bga-debug.jpg]]

The easier method is to add breakpoint directly into your code and reload.

In Chrome, to add a breakpoint: add a line to your .js file

<pre>debugger; </pre>

Refresh the page F5, and make sure you have the Developer tools window open, press F12.
When the break-point is hit you can then step through your code and visualise variables, etc.

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

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

Note: See the Reversi tutorial for an example.

=== Add traces in your code ===

You can use the following:

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

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

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

'''alert( variable_to_inspect )'''

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

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

== Online format checkers ==
Copy and paste code for a quick code sanity check like the right number of brackets.

PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]

JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]

Checks for proper attributes values and browser's compatibility

CSS: http://jigsaw.w3.org/css-validator/

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).
* Click on the "Go to game database" button
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.
* Then you should be able to play with the same state of the game as when the report was created in production.
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).
*
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug()
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window

<pre>
public function LoadDebug()
{
// These are the id's from the BGAtable I need to debug.
$ids = [
86107517,
86872172,
85086097,
84380410,
11000525
];

// Id of the first player in BGA Studio
$sid = 2296755;

foreach ($ids as $id) {
// basic tables
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );

// 'other' game specific tables. example:
// tables specific to your schema that use player_ids
self::DbQuery("UPDATE card SET card_location_arg=$sid WHERE card_location_arg = $id" );

++$sid;
}
}
</pre>

=== Fully automated version===
Thanks to quietmint for [https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167 coming up] with that!
(updated and working on 05/06/2922)

; In ggg.php
<pre>
/*
* loadBug: in studio, type loadBug(20762) into the table chat to load a bug report from production
* client side JavaScript will fetch each URL below in sequence, then refresh the page
*/
public function loadBug($reportId)
{
$db = explode('_', self::getUniqueValueFromDB("SELECT SUBSTRING_INDEX(DATABASE(), '_', -2)"));
$game = $db[0];
$tableId = $db[1];
self::notifyAllPlayers('loadBug', "Trying to load <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a>", [
'urls' => [
// Emulates "load bug report" in control panel
"https://studio.boardgamearena.com/admin/studio/getSavedGameStateFromProduction.html?game=$game&report_id=$reportId&table_id=$tableId",

// Emulates "load 1" at this table
"https://studio.boardgamearena.com/table/table/loadSaveState.html?table=$tableId&state=1",

// Calls the function below to update SQL
"https://studio.boardgamearena.com/1/$game/$game/loadBugSQL.html?table=$tableId&report_id=$reportId",

// Emulates "clear PHP cache" in control panel
// Needed at the end because BGA is caching player info
"https://studio.boardgamearena.com/admin/studio/clearGameserverPhpCache.html?game=$game",
]
]);
}

/*
* loadBugSQL: in studio, this is one of the URLs triggered by loadBug() above
*/
public function loadBugSQL($reportId)
{
$studioPlayer = self::getCurrentPlayerId();
$players = self::getObjectListFromDb("SELECT player_id FROM player", true);

// Change for your game
// We are setting the current state to match the start of a player's turn if it's already game over
$sql = [
"UPDATE global SET global_value=2 WHERE global_id=1 AND global_value=99"
];
foreach ($players as $pId) {
// All games can keep this SQL
$sql[] = "UPDATE player SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE global SET global_value=$studioPlayer WHERE global_value=$pId";
$sql[] = "UPDATE stats SET stats_player_id=$studioPlayer WHERE stats_player_id=$pId";
$sql[] = "UPDATE gamelog SET gamelog_player=$studioPlayer WHERE gamelog_player=$pId";
$sql[] = "UPDATE gamelog SET gamelog_current_player=$studioPlayer WHERE gamelog_current_player=$pId";
$sql[] = "UPDATE gamelog SET gamelog_notification=REPLACE(gamelog_notification, $pId, $studioPlayer)";

// TODO Add game-specific SQL updates for the tables, everywhere players ids are used in your game
$sql[] = "UPDATE deck SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";
$sql[] = "UPDATE card SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";
$sql[] = "UPDATE piece SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE log SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE log SET action_arg=REPLACE(action_arg, $pId, $studioPlayer)";

// This could be improved, it assumes you had sequential studio accounts before loading
// e.g., quietmint0, quietmint1, quietmint2, etc. are at the table
$studioPlayer++;
}
$msg = <nowiki>"<b>Loaded <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a></b><hr><ul><li>" . implode(';</li><li>', $sql) . ';</li></ul>';</nowiki>
self::warn($msg);
self::notifyAllPlayers('message', $msg, []);

foreach ($sql as $q) {
self::DbQuery($q);
}
self::reloadPlayersBasicInfos();
$this->gamestate->reloadState();
}
</pre>

; In ggg.action.php
<pre>
public function loadBugSQL() {
self::setAjaxMode();
$reportId = (int) self::getArg('report_id', AT_int, true);
$this->game->loadBugSQL($reportId);
self::ajaxResponse();
}
</pre>

; In ggg.js
<pre>
// Load production bug report handler
const self = this; // save the `this` context in a variable
dojo.subscribe("loadBug", this, function loadBug(n) {
function fetchNextUrl() {
var url = n.args.urls.shift();
console.log("Fetching URL", url, "...");
// all the calls have to be made with ajaxcall in order to add the csrf token, otherwise you'll get "Invalid session information for this action. Please try reloading the page or logging in again"
self.ajaxcall(url,
{
lock: true,
},
self,
function (success) {
console.log("=> Success ", success);

if (n.args.urls.length > 1) {
fetchNextUrl();
}
else if (n.args.urls.length > 0) {
//except the last one, clearing php cache
url = n.args.urls.shift();
dojo.xhrGet({
url: url,
load: function (success) {
console.log("Success for URL", url, success);
console.log("Done, reloading page");
window.location.reload();
},
handleAs: "text",
error: function (error) {
console.log("Error while loading : ", error);
}
});
}
}
,
function (error) {
if (error)
console.log("=> Error ", error);
}
);
}
console.log("Notif: load bug", n.args);
fetchNextUrl();
});
</pre>

== Studio environment ==

Some developers have requested a method allowing to know which environment the module is running on. While in general, your code should be the same on all environments so that the validation process makes sense, this may allow for example to display some helpers for testing during development while being sure that they'll never show up outside of the studio.

From your <gamename>.game.php file you can use:

<pre>if ($this->getBgaEnvironment() == 'studio') { ... }</pre>

Or if needed from your <gamename>.view.php file:

<pre>if ($this->game->getBgaEnvironment() == 'studio') { ... }</pre>

[[Category:Studio]]

Practical debugging

2022-06-05T17:49:29Z

Mizutismask: /* Fully automated version */

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

__TOC__

== Tools ==

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

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

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

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

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

== General tip for debugging ==

=== Save & Restore ===

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

You can save up to 3 different states.

=== Refresh ===

If something does not seems to work properly even you "fixed it", it may be refresh issue. Not all files born equal. Some require a lot more steps to get into the game.

See https://en.doc.boardgamearena.com/Studio_file_reference for information on how to "refresh" each files.

== Debugging my game when it cannot start ==

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

If the error is not explicitly displayed when you click on "Express start", you should check the "Gameserver error log" as per [[Studio logs]].
However errors and logs generated by setupNewGame not always (almost never) there, so see Debug setupNewGame session.
More cases of why game can't start are described on the [[Troubleshooting]] page.

== Debugging an issue with the waiting screen ==

BGA displays a waiting screen during a few seconds inviting free players to become premium when they are playing a lot.

This waiting screen should not in principle impact your game, but in some cases it might.

To test the waiting screen on the studio, you can set the desired duration by adding the get parameter studioLockingDuration with the number of seconds for the lock screen to be displayed. For example to have a 10 seconds waiting screen when you launch a game on the studio:
https://studio.boardgamearena.com?studioLockingDuration=10

Then you can just set it back to zero in the same way with https://studio.boardgamearena.com?studioLockingDuration=0 (or restart your browser to clear the session value).

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

=== Add traces to your code ===

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

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

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

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

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

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

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

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

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

'''WARNING''': tracing does not work in constructor, setupNewGame and game states immediately following starting state (not sure why). Use other method described below in this case (seciton "Debugging setupNewGame").

=== Call php functions from chat ===

This is best feature ever, you can call individual function in your game.php from chat window, see details
at https://en.doc.boardgamearena.com/Tools_and_tips_of_BGA_Studio#Run_PHP_functions_from_the_chat

=== Dump data and die ===

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

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

Example:
<pre>

// (...my code to debug)

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

// (...my code to debug)

</pre>

Now since this text will be returned back to client it will usually choke on this, but you can actually see it better if you wrap it some html, i.e.
<pre>
echo "<pre>";
var_dump( $my_variable );
echo "</pre>";
</pre>

=== Debug at home ===

If you develop some complex logic it is better sometimes to stub all external calls and debug it locally using command line or IDE debugger for php.
You can get some basic stubs here https://github.com/elaskavaia/bga-sharedcode/raw/master/misc/module/table/table.game.php

To run php locally you need to wrap it into test or something, see example https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Creating_a_test_class_to_run_PHP_locally

=== Debugging setupNewGame ===

This is separate section because tracing method do not work in this function.
Recommended way to debug it
* leave setupNewGame exactly as in template (inlcuding setting up player table and activating first player), and add a single call at the end
$this->initTables();
This will be your own function which you will be changing, so you don't touch setupNewGame anymore.

Remember that this function cannot send notification or query active or current player. If you need to get player data use $this->loadPlayersBasicInfos().

function initTables() {
try {
$players = $this->loadPlayersBasicInfos();
// ... code the function
} catch ( Exception $e ) {
// logging does not actually work in game init :(
// but if you calling from php chat it will work
$this->error("Fatal error while creating game");
$this->dump('err', $e);
}
}

Create a code for this function, and if it does not work run it from the chat window of the just created game (i.e. 'initTables()' without quotes). That way you can see debug output!
The only trick is you have to clear all your tables in the begging so when you run it multiple times your db does not puke.
If your game does not start at all - do not even call it from setupNewGame, comment it out and only call from chat window until it works.
Don't forget you can also look at tables in db using php-admin tool (link at the bottom of the game table in studio).

The same problem exists if you game state immediately follow starting state (problem of debugging it without the logs), in this case create a dummy player state in which player just press OK that will transition
to you game state, after you done debugging it remove the state and shortcut the transition to your game state.

Instead of calling initTables directly you can call helper function instead from chat window which will also reset the client, i.e.
function debug_initTables() {
$this->deleteAllTables(); // this suppose to delete/reset all data - you have to implement this function
$this->initTables();
$newGameDatas = $this->getAllTableDatas(); // this is framework function
$this->notifyPlayer($this->getActivePlayerId(), 'resetInterfaceWithAllDatas', '', $newGameDatas); // this is notification to reset all data
$this->notifyAllPlayers("message",'setup called',[]);
}

=== Debugging endOfGame ===

Debugging end of game is hard if game ends! Make sure it does not end, then you can restore to previous state using saved states.
In php file:

$this->processEndOfGame();
if ($this->getBgaEnvironment() == 'studio')
$this->gamestate->nextState('debuglast'); // debug end
else
$this->gamestate->nextState('last'); // real end

You have to end a special user state in states file for debug in states file

<pre>
STATE_GAME_TURN_NEXT_PLAYER => array( // normal state
"name" => "gameTurnNextPlayer",
"description" => '',
"type" => "game",
"action" => "st_gameTurnNextPlayer",
"updateGameProgression" => true,
"transitions" => array(
"next" => STATE_PLAYER_TURN_ACTION,
"loopback" => STATE_GAME_TURN_NEXT_PLAYER,
"last" => STATE_END_GAME,
"debuglast" => STATE_PLAYER_GAME_END // for debugging on studio
),
),
// for debugging end of game
STATE_PLAYER_GAME_END => array(
"name" => "playerGameEnd",
"description" => clienttranslate('Game Over'),
"descriptionmyturn" => clienttranslate('Game Over'),
"type" => "activeplayer",
"args"=>"arg_playerTurnAction",
"possibleactions" => array( "end"),
"transitions" =>
array(
"next" => STATE_END_GAME,
"loopback"=> STATE_PLAYER_GAME_END)
),
</pre>

== Debugging my HTML/CSS layout ==

Example situations

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

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

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

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

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

When changing css you have to force reload (Ctrl+R). But it also reloads all images which is long, if you want it faster you can define this function in js file, and call it from Browser js console
<pre>
// this goes outside dojo class - before or after
function reloadCss() {
var links = document.getElementsByTagName("link");
for (var cl in links) {
var link = links[cl];
if (link.rel === "stylesheet" && link.href.includes("99999")) {
var index = link.href.indexOf("?timestamp=");
var href = link.href;
if (index >= 0) {
href = href.substring(0, index);
}

link.href = href + "?timestamp=" + Date.now();

console.log("reloading " + link.href);
}
}
}

</pre>

For mobile its also handy to have this as button (studio only), this goes to setup() function in js:
<pre>
// add reload Css debug button
var parent = document.querySelector('.debug_section');
if (parent) {
var butt = dojo.create('a', { class: 'bgabutton bgabutton_gray', innerHTML: "Reload CSS" }, parent);
dojo.connect(butt, 'onclick', () => reloadCss());
}
</pre>
=== Debugging Toolips CSS/Layout ===

To inspect tooltip you need to pin it so it does not disappear.
* Chrome tools:
** Open dev tools and switch to Source tab to engage with debugger
** Hover over you element until tooltip showing
** Press F8 - that stops the JS, so tooltip should freeze
** Now you can go to Elements tab and find your tooltip at the botton in dijitTooltip div
** Don't forget to resume it again to continue (F8 again or resume button)
* Other method: Open the console (dev tools) large enough window, hover to make the tooltip appear and alt + tab to focus the console that will cover the tooltip. That way the onmouseout will never be triggered.

=== Debugging my Javascript game interface logic ===

To debug javascript you just use embedded browser debugger, usually found in Source tab of dev tools (F12)

Modern browsers also allow you to put breakpoints in your js code. It is in source tab, but its a bit difficult to find (your code that is), see picture below on how to insert breakpoints.

[[File:Bga-debug.jpg]]

The easier method is to add breakpoint directly into your code and reload.

In Chrome, to add a breakpoint: add a line to your .js file

<pre>debugger; </pre>

Refresh the page F5, and make sure you have the Developer tools window open, press F12.
When the break-point is hit you can then step through your code and visualise variables, etc.

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

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

Note: See the Reversi tutorial for an example.

=== Add traces in your code ===

You can use the following:

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

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

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

'''alert( variable_to_inspect )'''

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

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

== Online format checkers ==
Copy and paste code for a quick code sanity check like the right number of brackets.

PHP: [https://phpcodechecker.com/ https://phpcodechecker.com/]

JS: [http://esprima.org/demo/validate.html http://esprima.org/demo/validate.html]

Checks for proper attributes values and browser's compatibility

CSS: http://jigsaw.w3.org/css-validator/

== Some frequent errors ==

See [[Troubleshooting]].

== Get the database matching a bug report ==

When a player creates a bug report in production, a snapshot of the game database is taken. You can get access to this snapshot from the studio by following the steps below:
* Create a table in the studio with the same game and number of players as the table for which the report has been written. Launch this table.
* Open another tab on the studio and go to "Manage game" page for your project (you have to be admin for this project)
* In the "Errors in production" section, fill up the fields "Bug report ID" (this is the ID of the bug report in production) and "Studio table ID" (this is the ID of the table you created above) then click the "⇨ Load bug report state into this table save slot #1" button.
* If the snapshot is correctly retrieved, you see a "Done!" message.
* Go back to the tab with your studio table and click "Load 1".
* The page refreshes automatically and is broken. This is normal, as the player ids from the snapshot are the player ids of the production, not those of the studio. We'll need to update them.
** '''Important note:''' if you see a "Done!" message but clicking "Load 1" doesn't bring any change, it's that the snapshot is unfortunately not available (most likely because the bug report was declared too long after the game ended and the database had already been garbage collected to reclaim space).
* Click on the "Go to game database" button
* For each table using player_ids, you'll need to update the player_ids from the production to use the player_ids from the studio. You can see the player_ids from the table page before entering the game by hovering over the player names.
* Tables to update:
** player
** global (value with ID 2 is the active player)
** stats
** tables specific to your schema that use player_ids
* If your changes to player_ids are not taken into account, it may be a cache problem: use the "Clear PHP cache" button on your "Manage game" page.
* Then you should be able to play with the same state of the game as when the report was created in production.
* If the game has ended, you can place it again in the game state you want to debug by setting the value with ID 1 in the global table to the appropriate state value, and the value with ID 2 to the player you want active).
*
* Below is an example php function you may want to make. You can call this function from the chat window: LoadDebug()
* change instances of 2308257, and 2308258 to you own BGA Studio logins YourLogin0 and YourLogin1
* change $id0 and $id1 to the player_ids from the table you want to debug, and have recently imported.
* Before you load Slot1, open a second tab with the table, because after loading the slot, that tab will be unusable. In the second tab you can call LoadDebug() in the chat window

<pre>
public function LoadDebug()
{
// These are the id's from the BGAtable I need to debug.
$ids = [
86107517,
86872172,
85086097,
84380410,
11000525
];

// Id of the first player in BGA Studio
$sid = 2296755;

foreach ($ids as $id) {
// basic tables
self::DbQuery("UPDATE player SET player_id=$sid WHERE player_id = $id" );
self::DbQuery("UPDATE global SET global_value=$sid WHERE global_value = $id" );
self::DbQuery("UPDATE stats SET stats_player_id=$sid WHERE stats_player_id = $id" );

// 'other' game specific tables. example:
// tables specific to your schema that use player_ids
self::DbQuery("UPDATE card SET card_location_arg=$sid WHERE card_location_arg = $id" );

++$sid;
}
}
</pre>

=== Fully automated version (working on 05/06/2922)===
Thanks to quietmint for [https://boardgamearena.com/forum/viewtopic.php?f=12&t=16454#p63167 coming up] with that!

; In ggg.php
<pre>
/*
* loadBug: in studio, type loadBug(20762) into the table chat to load a bug report from production
* client side JavaScript will fetch each URL below in sequence, then refresh the page
*/
public function loadBug($reportId)
{
$db = explode('_', self::getUniqueValueFromDB("SELECT SUBSTRING_INDEX(DATABASE(), '_', -2)"));
$game = $db[0];
$tableId = $db[1];
self::notifyAllPlayers('loadBug', "Trying to load <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a>", [
'urls' => [
// Emulates "load bug report" in control panel
"https://studio.boardgamearena.com/admin/studio/getSavedGameStateFromProduction.html?game=$game&report_id=$reportId&table_id=$tableId",

// Emulates "load 1" at this table
"https://studio.boardgamearena.com/table/table/loadSaveState.html?table=$tableId&state=1",

// Calls the function below to update SQL
"https://studio.boardgamearena.com/1/$game/$game/loadBugSQL.html?table=$tableId&report_id=$reportId",

// Emulates "clear PHP cache" in control panel
// Needed at the end because BGA is caching player info
"https://studio.boardgamearena.com/admin/studio/clearGameserverPhpCache.html?game=$game",
]
]);
}

/*
* loadBugSQL: in studio, this is one of the URLs triggered by loadBug() above
*/
public function loadBugSQL($reportId)
{
$studioPlayer = self::getCurrentPlayerId();
$players = self::getObjectListFromDb("SELECT player_id FROM player", true);

// Change for your game
// We are setting the current state to match the start of a player's turn if it's already game over
$sql = [
"UPDATE global SET global_value=2 WHERE global_id=1 AND global_value=99"
];
foreach ($players as $pId) {
// All games can keep this SQL
$sql[] = "UPDATE player SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE global SET global_value=$studioPlayer WHERE global_value=$pId";
$sql[] = "UPDATE stats SET stats_player_id=$studioPlayer WHERE stats_player_id=$pId";
$sql[] = "UPDATE gamelog SET gamelog_player=$studioPlayer WHERE gamelog_player=$pId";
$sql[] = "UPDATE gamelog SET gamelog_current_player=$studioPlayer WHERE gamelog_current_player=$pId";
$sql[] = "UPDATE gamelog SET gamelog_notification=REPLACE(gamelog_notification, $pId, $studioPlayer)";

// TODO Add game-specific SQL updates for the tables, everywhere players ids are used in your game
$sql[] = "UPDATE deck SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";
$sql[] = "UPDATE card SET card_location_arg=$studioPlayer WHERE card_location_arg=$pId";
$sql[] = "UPDATE piece SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE log SET player_id=$studioPlayer WHERE player_id=$pId";
$sql[] = "UPDATE log SET action_arg=REPLACE(action_arg, $pId, $studioPlayer)";

// This could be improved, it assumes you had sequential studio accounts before loading
// e.g., quietmint0, quietmint1, quietmint2, etc. are at the table
$studioPlayer++;
}
$msg = <nowiki>"<b>Loaded <a href='https://boardgamearena.com/bug?id=$reportId' target='_blank'>bug report $reportId</a></b><hr><ul><li>" . implode(';</li><li>', $sql) . ';</li></ul>';</nowiki>
self::warn($msg);
self::notifyAllPlayers('message', $msg, []);

foreach ($sql as $q) {
self::DbQuery($q);
}
self::reloadPlayersBasicInfos();
$this->gamestate->reloadState();
}
</pre>

; In ggg.action.php
<pre>
public function loadBugSQL() {
self::setAjaxMode();
$reportId = (int) self::getArg('report_id', AT_int, true);
$this->game->loadBugSQL($reportId);
self::ajaxResponse();
}
</pre>

; In ggg.js
<pre>
// Load production bug report handler
const self = this; // save the `this` context in a variable
dojo.subscribe("loadBug", this, function loadBug(n) {
function fetchNextUrl() {
var url = n.args.urls.shift();
console.log("Fetching URL", url, "...");
// all the calls have to be made with ajaxcall in order to add the csrf token, otherwise you'll get "Invalid session information for this action. Please try reloading the page or logging in again"
self.ajaxcall(url,
{
lock: true,
},
self,
function (success) {
console.log("=> Success ", success);

if (n.args.urls.length > 1) {
fetchNextUrl();
}
else if (n.args.urls.length > 0) {
//except the last one, clearing php cache
url = n.args.urls.shift();
dojo.xhrGet({
url: url,
load: function (success) {
console.log("Success for URL", url, success);
console.log("Done, reloading page");
window.location.reload();
},
handleAs: "text",
error: function (error) {
console.log("Error while loading : ", error);
}
});
}
}
,
function (error) {
if (error)
console.log("=> Error ", error);
}
);
}
console.log("Notif: load bug", n.args);
fetchNextUrl();
});
</pre>

== Studio environment ==

Some developers have requested a method allowing to know which environment the module is running on. While in general, your code should be the same on all environments so that the validation process makes sense, this may allow for example to display some helpers for testing during development while being sure that they'll never show up outside of the studio.

From your <gamename>.game.php file you can use:

<pre>if ($this->getBgaEnvironment() == 'studio') { ... }</pre>

Or if needed from your <gamename>.view.php file:

<pre>if ($this->game->getBgaEnvironment() == 'studio') { ... }</pre>

[[Category:Studio]]

Gamehelpdobble

2021-12-19T17:25:06Z

Mizutismask:

==The Tower==
'''Object of the Game: To collect the most cards'''

*Each player has 1 card. The remaining cards go faceup in the middle of the table to form the draw pile.
*Simultaneously, players flip their cards faceup and try to '''spot the 1 symbol that appears on both the center card and their own card'''. Then the center card goes faceup on top of your flipped card to form a personal pile. Now use the new top card on your personal pile to find a match with the new center card. Continue playing until the draw pile runs out of cards.

==The well==
'''Object of the Game: To be the first player to get rid of all their cards'''

*There is 1 card faceup in the middle of the table. The remaining cards facedown are dealt as evenly as possible among all the players.
*Simultaneously, players flip their entire draw piles over so they are faceup. If you are the first player to '''spot the matching symbol on both your top card and the center card''', place your card on top of the center pile; it immediately becomes the new center card. Use the new card revealed on your personal pile to find a match with the center card. Continue playing until 1 player runs out of cards.

==Hot Potato (several rounds)==
'''Object of the Game: To have the fewest cards after all the rounds have been played.''' This is accomplished by getting rid of your cards each round.

*Each player has 1 card. Remaining cards are set aside
*If you '''spot a matching symbol between your card and another player’s card''', place your card faceup on top of the other player’s card. If you have 2 or more cards in your hand, look only at your top card for a match. When you spot it, give all your cards to the other player with the match. Continue playing until 1 player has all the cards. That player loses the round and places the cards in front of them. A new round starts.

==The Poisoned Gift==
'''Object of the Game: To have the fewest cards'''

*Each player has 1 card. Remaining cards are faceup in the middle of the table to form the draw pile.
*Players '''look for a match between the center card and any other player’s card'''. If you spot a match, take the center card and place it on top of the other player’s card on which you found the match. This is the “poisoned gift” because you give an unwanted card to an opponent. The revealed card on the draw pile becomes the new card that players use to find a match. Continue playing until the draw pile runs out of cards.

==Triplet==
'''Object of the Game: To collect the most cards'''

*All the cards are facedown in a pile. The first 9 cards goes faceup on the table
*Simultaneously, players '''try to find a matching symbol on any 3 cards'''. The same symbol must be present on all 3 cards to make a matching set. As soon as you find a matching set, take the 3 cards showing the matching symbol. Those 3 cards are replaced with 3 new ones. The game ends when there are fewer than 9 cards left and no more matching sets of 3 cards.

Gamehelpdobble

2021-12-19T17:23:28Z

Mizutismask: /* Triplet */

==The Tower==
'''Object of the Game: To collect the most cards'''

*Each player has 1 card. The remaining cards go faceup in the middle of the table to form the draw pile.
*Simultaneously, players flip their cards faceup and try to spot the 1 symbol that appears on both the center card and their own card. Then the center card goes faceup on top of your flipped card to form a personal pile. Now use the new top card on your personal pile to find a match with the new center card. Continue playing until the draw pile runs out of cards.

==The well==
'''Object of the Game: To be the first player to get rid of all their cards'''

*There is 1 card faceup in the middle of the table. The remaining cards facedown are dealt as evenly as possible among all the players.
*Simultaneously, players flip their entire draw piles over so they are faceup. If you are the first player to spot the matching symbol on both your top card and the center card, place your card on top of the center pile; it immediately becomes the new center card. Use the new card revealed on your personal pile to find a match with the center card. Continue playing until 1 player runs out of cards.

==Hot Potato (several rounds)==
'''Object of the Game: To have the fewest cards after all the rounds have been played.''' This is accomplished by getting rid of your cards each round.

*Each player has 1 card. Remaining cards are set aside
*If you spot a matching symbol between your card and another player’s card, place your card faceup on top of the other player’s card. If you have 2 or more cards in your hand, look only at your top card for a match. When you spot it, give all your cards to the other player with the match. Continue playing until 1 player has all the cards. That player loses the round and places the cards in front of them. A new round starts.

==The Poisoned Gift==
'''Object of the Game: To have the fewest cards'''

*Each player has 1 card. Remaining cards are faceup in the middle of the table to form the draw pile.
*Players look for a match between the center card and any other player’s card. If you spot a match, take the center card and place it on top of the other player’s card on which you found the match. This is the “poisoned gift” because you give an unwanted card to an opponent. The revealed card on the draw pile becomes the new card that players use to find a match. Continue playing until the draw pile runs out of cards.

==Triplet==
'''Object of the Game: To collect the most cards'''

*All the cards are facedown in a pile. The first 9 cards goes faceup on the table
*Simultaneously, players try to find a matching symbol on any 3 cards. The same symbol must be present on all 3 cards to make a matching set. As soon as you find a matching set, take the 3 cards showing the matching symbol. Those 3 cards are replaced with 3 new ones. The game ends when there are fewer than 9 cards left and no more matching sets of 3 cards.

Gamehelpdobble

2021-12-19T17:22:54Z

Mizutismask:

==The Tower==
'''Object of the Game: To collect the most cards'''

*Each player has 1 card. The remaining cards go faceup in the middle of the table to form the draw pile.
*Simultaneously, players flip their cards faceup and try to spot the 1 symbol that appears on both the center card and their own card. Then the center card goes faceup on top of your flipped card to form a personal pile. Now use the new top card on your personal pile to find a match with the new center card. Continue playing until the draw pile runs out of cards.

==The well==
'''Object of the Game: To be the first player to get rid of all their cards'''

*There is 1 card faceup in the middle of the table. The remaining cards facedown are dealt as evenly as possible among all the players.
*Simultaneously, players flip their entire draw piles over so they are faceup. If you are the first player to spot the matching symbol on both your top card and the center card, place your card on top of the center pile; it immediately becomes the new center card. Use the new card revealed on your personal pile to find a match with the center card. Continue playing until 1 player runs out of cards.

==Hot Potato (several rounds)==
'''Object of the Game: To have the fewest cards after all the rounds have been played.''' This is accomplished by getting rid of your cards each round.

*Each player has 1 card. Remaining cards are set aside
*If you spot a matching symbol between your card and another player’s card, place your card faceup on top of the other player’s card. If you have 2 or more cards in your hand, look only at your top card for a match. When you spot it, give all your cards to the other player with the match. Continue playing until 1 player has all the cards. That player loses the round and places the cards in front of them. A new round starts.

==The Poisoned Gift==
'''Object of the Game: To have the fewest cards'''

*Each player has 1 card. Remaining cards are faceup in the middle of the table to form the draw pile.
*Players look for a match between the center card and any other player’s card. If you spot a match, take the center card and place it on top of the other player’s card on which you found the match. This is the “poisoned gift” because you give an unwanted card to an opponent. The revealed card on the draw pile becomes the new card that players use to find a match. Continue playing until the draw pile runs out of cards.

==Triplet==
'''Object of the Game: To collect the most cards'''

*All the cards are facedown in a pile. The first 9 cards goes faceup on the table
*Simultaneously, players try to find a matching symbol on any 3 cards. The same symbol must be present on all 3 cards to make a matching set. As soon as you find a matching set, take the 3 cards
showing the matching symbol. Those 3 cards are replaced with 3 new ones. The game ends when there are fewer than 9 cards left and no more matching sets of 3 cards.

Gamehelpdobble

2021-12-19T17:16:51Z

Mizutismask: Created page with "==The Tower== *Object of the Game: To collect the most cards *Each player has 1 card. The remaining cards go faceup in the middle of the table to form the draw pile. *Simulta..."

==The Tower==
*Object of the Game: To collect the most cards

*Each player has 1 card. The remaining cards go faceup in the middle of the table to form the draw pile.
*Simultaneously, players flip their cards faceup and try to spot the 1 symbol that appears on both the center card and their own card. Then the center card goes faceup on top of your flipped card to form a personal pile. Now use the new top card on your personal pile to find a match with the new center card. Continue playing until the draw pile runs out of cards.

==The well==
*Object of the Game: To be the first player to get rid of all their cards

*There is 1 card faceup in the middle of the table. The remaining cards facedown are dealt as evenly as possible among all the players.
*Simultaneously, players flip their entire draw piles over so they are faceup. If you are the first player to spot the matching symbol on both your top card and the center card, place your card on top of the center pile; it immediately becomes the new center card. Use the new card revealed on your personal pile to find a match with the center card. Continue playing until 1 player runs out of cards.

==Hot Potato (several rounds)==
*Object of the Game: To have the fewest cards after all the rounds have been played. This is accomplished by getting rid of your cards each round.

*Each player has 1 card. Remaining cards are set aside
*If you spot a matching symbol between your card and another player’s card, place your card faceup on top of the other player’s card. If you have 2 or more cards in your hand, look only at your top card for a match. When you spot it, give all your cards to the other player with the match. Continue playing until 1 player has all the cards. That player loses the round and places the cards in front of them. A new round starts.

==The Poisoned Gift==
*Object of the Game: To have the fewest cards

*Each player has 1 card. Remaining cards are faceup in the middle of the table to form the draw pile.
*Players look for a match between the center card and any other player’s card. If you spot a match, take the center card and place it on top of the other player’s card on which you found the match. This is the “poisoned gift” because you give an unwanted card to an opponent. The revealed card on the draw pile becomes the new card that players use to find a match. Continue playing until the draw pile runs out of cards.

==Triplet==
*Object of the Game: To collect the most cards

*All the cards are facedown in a pile. The first 9 cards goes faceup on the table
*Simultaneously, players try to find a matching symbol on any 3 cards. The same symbol must be present on all 3 cards to make a matching set. As soon as you find a matching set, take the 3 cards showing the matching symbol. Those 3 cards are replaced with 3 new ones. The game ends when there are fewer than 9 cards left and no more matching sets of 3 cards.

BGA Code Sharing

2021-01-15T07:46:18Z

Mizutismask: /* Projects hosted not in studio */

{{Studio_Framework_Navigation}}

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

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
|}

== Projects on studio ==

Links to studio project which owner wish share as read only.
Project owner please add you project here, dev nickname and short description if you would like to share it.
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.

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

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

BGA Code Sharing

2020-10-02T09:55:26Z

Mizutismask:

{{Studio_Framework_Navigation}}

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

== Projects hosted not in studio ==

See the table a link and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] tag on github.

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
! GAME
! CODE LINK
! DEVELOPER
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|}

== Projects on studio ==

Links to studio project which owner wish share as read only.
Project owner please add you project here, dev nickname and short description if you would like to share it.
For the projects below any developer can add themselves to a project as read-only from http://en.studio.boardgamearena.com/#!projects page.

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

== Other useful resources ==

* Archive of tutorial projects https://www.dropbox.com/s/rsd5r4v49xudpp0/Studio.zip?dl=0
** Note: Hearts project is corrupted there, use Hearts tutorial project above
* Website with bunch of textures and sounds http://www.grsites.com/archive/textures/
* Shrink images without loss of quality https://tinypng.com/ or http://www.iloveimg.com/ (recommended by Gregory Isabelli)
* CSS shapes https://css-tricks.com/examples/ShapesOfCSS/
* PDF Scraper - extract images - http://www.extractpdf.com/
* BoardGameArena Workbench - set of tools to help test and deploy BGA projects - https://github.com/danielholmes/bga-workbench