BGA Studio Cookbook

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.

Visual Effects, Layout and Animation

DOM manipulations

Create pieces dynamically (using string concatenation)

Ingredients: ggg.js

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

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:

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

ggg.css:

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

.meeple.red {
	background-position: 30% 0%;
}

• 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

.home .meeple{
   display: inline-block;
}

• 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

Animation

Scroll element into view

Ingredients: game.js

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

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

Logs

Inject images and styled html in the log

Warning — Translation

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 ${player_name} parts of your string) in the log string.

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

This is a bad idea for many reasons:

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

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

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

ggg.js

 

        /** Declare this function to inject html into log items. */

        bgaFormatText : function(log, args) {
            try {
                if (log && args && !args.processed) {
                    args.processed = true;
                    

                    // list of special keys we want to replace with images
                    const keys = ['place_name','token_name'];
                    
                  
                    for (let i in keys) {
                        const key = keys[i];
                        if (args[key]) args[key] = this.getTokenDiv(key, args);                            

                    }
                }
            } catch (e) {
                console.error(log,args,"Exception thrown", e.stack);
            }
            return { log, args };
        },

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

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

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

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

Game.php:

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

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

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

          $this->bga->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:

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

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

Use :formatFunction option provided by dojo.string.substitute

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 ${card.name} (which is supported by the framework, for private state args), the key won't be substituted because the key in arg 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 ${keys} with the value provided. If you take a look at the documentation and source code you can notice that the key can be suffixed with a colon (:) 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:

[[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});
                ...
            }
       }

Obviously you need to define the appropriate templates in the ggg_ggg.tpl file:

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

And the appropriate classes in ggg.css.

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

[[ggg.js]]
define([
    "dojo", "dojo/_base/declare",
    "dojo/aspect",                 //MUST BE IN THIRD POSITION (see below)
    "ebg/core/gamegui",
    "ebg/counter",
], function (dojo, declare, aspect) {
...

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

[[ggg.js]]
        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:

[[ggg.game.php]]
$this->bga->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 transform argument of dojo.string.substitute

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

This method is also relying on the use of dojo.string.substitute by the framework, and will use the transform argument, which, accordting to source code and 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:

[[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});
                ...
                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:

[[ggg.js]]
define([
    "dojo", "dojo/_base/declare",
    "dojo/aspect",                 //MUST BE IN THIRD POSITION (see below)
    "ebg/core/gamegui",
    "ebg/counter",
], function (dojo, declare, aspect) {
...

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

[[ggg.js]]
        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

			/*
  			* [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
			},

Overriding format_string_recursive to inject HTML into log, including adding tooltips to log

Ingredients: ggg.js

I'm using cards as an example but this will work with any type of resource or game element. The first step is to override format_string_recursive. You can find info about this in this excellent guide. We will replace the return line from the guide with this:

return this.logInject(text);

The purpose of logInject() is to catch pre-coded text from your notifications, siphon out the meaningful info so that you can manipulate it on the front end, and then replace that pre-coded text in the log with whatever html you desire, as well as adding a tooltip to the element you're injecting. Here is a simplified version of logInject():

logInject: function (log_entry) {
    const card_regex = /\[\w+-*\w* *\w*\(\d+\)\]/g;    // this will catch a card name in the log formatted like so: [card_name(card_type_arg)] -You may need to adjust the regex to catch your card names
    const cards_to_replace = log_entry.matchAll(card_regex);
    for (let card of cards_to_replace) {
        const match = card[0];
        const left_parenthesis = match.indexOf('(');
        const card_type_arg = match.slice(left_parenthesis+1, match.length-2);
        const card_span = this.getHTMLForLog(card_type_arg, 'card');
        log_entry = log_entry.replace(match, card_span);
    }
    return log_entry;
}

getHTMLForLog() takes the card_type_arg and uses it to create the <span> to be injected into the log that you can then attach a tooltip to:

getHTMLForLog: function (item, type) {   // in this example, item refers to the card_type_arg
    switch(type) {
        case 'card':
            this.log_span_num++; // adds a unique num to the span id so that duplicate card names in the log have unique ids
            const card_name = this.gamedatas['cards'][item]['description'];  // or wherever you store your translated card name
            const item_type = 'card_tt';
            return `<span id="${this.log_span_num}_item_${item}" class="${item_type} item_tooltip">${card_name}</span>`;
    }
}

If you only want to add some HTML to your log and don't care about the tooltips, you can remove the item_tooltip class from the above and stop here. If you want tooltips, you'll need a function to add them:

addTooltipsToLog: function() {
    const item_elements = dojo.query('.item_tooltip:not(.tt_processed)');
    Array.from(item_elements).forEach(ele => {
        const ele_id = ele.id;
        ele.classList.add('tt_processed');  // prevents tooltips being re-added to previous log entries
        if (ele.classList.contains('card_tt')) {
            const card_type_arg = ele_id.slice(-3).replace(/^\D+/g, '');  // extracts the card_type_arg from the span id
            this.cardTooltip(ele_id, card_type_arg)
        }
    });
}

cardTooltip() is just however you want to create and add your tooltip. Mine is below:

cardTooltip: function (ele, card_type_arg) {
    const card = this.gamedatas.cards[card_type_arg];
    const bg_pos = card['x_y'];
    const skill = dojo.string.substitute("${skill}", { skill: card['skill'] });
    const description = dojo.string.substitute("${description}", { description: card['description'] });
    const html = `<div style="margin-bottom: 5px; display: inline;"><strong>${description}</strong></div>
                  <span style="font-size: 10px; margin-left: 5px;">${skill}</span>
                  <div class="asset asset_tt" style="background-position: -${bg_pos[0]}% -${bg_pos[1]}%; margin-bottom: 5px;"></div>`;
    this.addTooltipHTML(ele, html, 1000);
}

And finally, you need to connect addTooltipsToLog. Using the new promise-based notifications you can supply the `onEnd` param like

this.bgaSetupPromiseNotifications({ onEnd: this.addTooltipsToLog.bind(this) });

Or, if you're not using them, you can attach to the notifqueue so it is called whenever the log is updated like

dojo.connect(this.notifqueue, 'addToLog', () => {
    this.addTooltipsToLog();
});

You can expand this to cover multiple types of tooltips. For example, I have it set up for cards: formatted in log as [card_name(card_type_arg)], hexes: formatted as {pitch_name(pitch_type_arg)}, objectives: formatted as ==objective_name(objective_type_arg)==, etc.

Images and Icons

Accessing images from js

Ingredients: Game.js

 
     const my_img = `<img src="${this.bga.images.getImgUrl('cards.jpg')}"/>`;

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 [email protected] 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.

.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/[email protected]');
    }
}

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:

            const isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
            if (window.matchMedia(isRetina).matches) {
                this.bga.images.dontPreloadImages(['pieces.png', 'board.jpg'];
            } else {
                this.bga.images.dontPreloadImages(['[email protected]', '[email protected]']);
            }

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

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

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 and mask-size to match background-size.

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, viewport, custom bga scaling, devicePixelRatio - all create some impossible coctail of zooming... Here is scaling functing for custom user scaling

ggg_ggg.tpl:

   <div id="thething" class="thething">
            ... everything else you declare ...
   </div>

ggg.js:

    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();
    },

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

dijit.Tooltip

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

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:

.xxx-tile {
    box-shadow: 3px 3px 3px #000000a0;
}

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:

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

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

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' )
			)
	),

[game].css

.no-shadow * {
	filter: none !important; 
} 

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.

<div class='my-token-wrap'>
  <div class='my-token'>
  </div>
</div>

.my-token-wrap {
    filter: drop-shadow(0px 0px 1px #000000);
}
.my-token-wrap .my-token {
    clip-path: url(#my-token-path);
}

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:

#discard_pile { display: none }
.gamestate_playerTurn #discard_pile { display: block }

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.

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: dbmodel.sql and class implementing access to it here 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;

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.

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

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;

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

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 ;

Variant 2: More normalised

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

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 ;

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

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:

$this->token_types = [
  ...
  'wood' => [
     'name' => clienttranslate('Wood'),
     'tooltip' => clienttranslate('Game resource used for building houses'),
     'type' => 'resource',
     'max' => 40
  ]
];

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:

<div id="wood_ff0000" class="resource wood" data-value="3"></div>

JavaScript Handling

When you get the object from the server, one of the tokens will be sent in the array like this:

token = {
  key: 'wood_ff0000',
  location: '-',
  state: '3'
}

You can create a corresponding `

` in the `setup()` method of `game.js` as follows:

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), "");
}

When you receive an update notification (assuming you get the same "token" object), you can simply update the `data-value`:

document.querySelector(`#${token.key}`).dataset.value = token.state;

To display the resource in the game log, you can format it like this:

Player gains <div class="resource wood" data-value="1"></div>

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:

.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%;
}

To show a text overlay with the resource value, you can use the following CSS:

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

This solution is fully scalable — you only need to specify the size where you want it displayed. For example:

.player_board_content > .resource {
  width: 40px;
  position: relative;
}

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

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'

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

HTML Representation

In HTML, this would look something like this.

<div id="meeple_ff0000_1" class="meeple meeple_ff0000" data-state="1"></div>

JavaScript Handling

When you get the object from the server, each meeple object will be similar to this:

meeple = {
  key: 'meeple_ff0000_1',
  location: 'actionslot_1',
  state: '1'
}

You can create a corresponding `

` in the `setup()` method of `game.js` as follows:

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

When you receive an update notification (assuming you get the same "token" object), you either create it if not exists or animate:

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
}

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

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

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.

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

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

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

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

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)

.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%;
}

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

.die.active_slot  {
  box-shadow: 0px 0px 4px 4px blue;
}

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

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

 '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.'),
],

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

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

The second option means you can add translated text instead

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

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

Note: to make flip animation you effectively need to make a "3d" card and provide both faces with separate graphics, which makes more complex div. See examples at BgaCards.

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

JavaScript Handling (.js)

You will get the server data which looks like this

card = {
  key: 'card_project_123',
  location: 'tableau_ff0000',
  state: '1'
}

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

When you receive an update notification (assuming you get the same "token" object), you either create it if not exists or animate:

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

Graphic Representation (.css)

For this html

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

This is example css using sprite image of playing cards

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

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

.card.active_slot  {
  box-shadow: 0px 0px 4px 4px blue;
}

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:

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

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

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

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

The track in this case can be generated as series of slots (create in js)

    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), "");
    }

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

Code Organization

Creating a test class to run PHP locally

See https://en.doc.boardgamearena.com/Testing_by_developer#PHP

Frameworks and Preprocessors

• Using Typescript and Scss - How to auto-build Typescript and SCSS files to make your code cleaner
• Using Vue - work-in-progress guide on using the modern framework Vue.js to create a game

PHP Migration

Ingredients: */php, modules/*.php

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

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

1. Install the module

composer global require --dev rector/rector

2. Go to your project directory, commit your code first before this!

3. Create a rector.php file on top level with the following content:

<?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
    ]);

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 Game database model for more details.)

WARNING: To prevent unfair advantage (e.g. collusion), the random order must be the default option and non-random options should be limited to friendly mode.

Example:

                // 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();

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 ggg.game.php add action handler

   function actCancel() {
       $this->gamestate->setPlayersMultiactive(array ($this->getCurrentPlayerId() ), 'error', false);
   }

Finally to call this in client ggg.js you would do something like:

 onUpdateActionButtons:  function(stateName, args) {
   if (this.bga.players.isCurrentPlayerActive()) { 
     // ...
   } else if (!this.bga.players.isCurrentPlayerSpectator()) { // player is NOT active but not spectator
       switch (stateName) {
          case 'playerTurnMultiPlayerState':
		this.bga.statusBar.addActionButton(_('Oh no!'), () => this.bgaPerformAction("actCancel", null, { checkAction: false }), { color: 'secondary' });
		break;
	}
   }
 }

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

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

In ggg.js

Override framework function showMessage to suppress the red banner message and gamelog message when you detect the "!!!" prefix

    /* @Override */
    showMessage: function (msg, type) {
      if (type == "error" && msg && msg.startsWith("!!!")) {
        return; // suppress red banner and gamelog message
      }
      this.inherited(arguments);
    },

Deal with the error in your callback:

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

For custom global error handling, you could modify ajaxcallwrapper:

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

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:

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

In ggg.php

Transmit the server version number in getAllDatas().

    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
            ...
        ];
    }

Create a helper function to fail if the client and server versions mismatch. Note the version check uses != instead of < so it can support rollback to a previous deploy as well. ;-)

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

Every action requires a parameter int $version and a call to $this->checkVersion() as the first line. The version check should happen before anything else, even before checking if the action is allowed (since possible actions could change between versions). If you are using auto-wired "act" action functions, modify each to start like this:

    #[CheckAction(false)]
    public function actXxx(int $version, ...) {
        $this->checkVersion($version);
        $this->checkAction('actXxx'); // or $this->gamestate->checkPossibleAction('actXxx');
        ...
    }

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:

  ajaxcallwrapper: function (action, args) {
    if (!args) args = {};
    args.version = this.gamedatas.version; // <-- ADD HERE
    this.bgaPerformAction(action, args);
  },

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

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

In gameoptions.inc.php (older method if you have it in php)

// 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.') ] ],
],

• 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

   setup: function (gamedatas) {
        let zoom = localStorage.getItem(`${this.game_name}_zoom`);
        this.setZoom(zoom);
...
   },

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

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

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

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

Usage:

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