BGA Studio Cookbook - Revision history

Thoun at 10:14, 15 October 2026

2026-10-15T10:14:54Z

← Older revision		Revision as of 12:14, 15 October 2026
Line 1,767:		Line 1,767:
	).catch((error, errorMsg, errorCode) => {		).catch((error, errorMsg, errorCode) => {
	if (error && errorMsg == "!!!checkVersion") {		if (error && errorMsg == "!!!checkVersion") {
	this.~~infoDialog~~(		this.bga.dialogs.info(
	_("A new version of this game is now available"),		_("A new version of this game is now available"),
	_("Reload Required"),		_("Reload Required")
	() => window.location.reload(),		).then(() => window.location.reload());
	);
	} else {		} else {
	if (handler) handler(error, errorMsg, errorCode);		if (handler) handler(error, errorMsg, errorCode);

Quietmint: /* Force players to refresh after new deploy */

2026-10-09T14:00:47Z

Force players to refresh after new deploy

← Older revision		Revision as of 16:00, 9 October 2026
Line 1,811:		Line 1,811:
	{		{
	if ($clientVersion != $this->bga->tableOptions->getGameVersion())) {		if ($clientVersion != $this->bga->tableOptions->getGameVersion())) {
	// ~~Simplest way is to throw a "visible" exception~~		// Throw an empty "user" exception and handle in JS
	~~// It's ugly but comes with a "click here" link to refresh~~		throw new UserException(new NotificationMessage('', ['checkVersion' => true]));
	~~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');
	}		}
	}		}
Line 1,835:		Line 1,830:
	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:		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>		<pre>
	performActionWrapper~~: function~~ (action, args, options) {		performActionWrapper(action, args, options) {
	if (!args) args = {};		if (!args) args = {};
	args.version = this.gamedatas.version; ~~// <-- ADD HERE~~		args.version = this.gamedatas.version;
	this.bga.actions.performAction(action, args, options);		return this.bga.actions.performAction(action, args, options).catch((error) => {
	},		if (error?.args?.checkVersion) {
			this.bga.dialogs.multipleChoice(_("A new version of this game is now available"), [_("Reload Required")]).then(() => window.location.reload());
			} else {
			reject(error);
			}
			});
			}
	</pre>		</pre>

Thoun: /* Custom error/exception handling in JavaScript */

2026-10-09T13:11:08Z

Custom error/exception handling in JavaScript

← Older revision		Revision as of 15:11, 9 October 2026
Line 1,770:		Line 1,770:
	_("A new version of this game is now available"),		_("A new version of this game is now available"),
	_("Reload Required"),		_("Reload Required"),
	() => {		() => window.location.reload(),
	window.location.reload();
	},
	~~true~~
	);		);
	} else {		} else {

Quietmint: /* Force players to refresh after new deploy */

2026-10-03T14:21:45Z

Force players to refresh after new deploy

← Older revision		Revision as of 16:21, 3 October 2026
Line 1,838:		Line 1,838:
	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:		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>		<pre>
	performActionWrapper: function (action, args) {		performActionWrapper: function (action, args, options) {
	if (!args) args = {};		if (!args) args = {};
	args.version = this.gamedatas.version; // <-- ADD HERE		args.version = this.gamedatas.version; // <-- ADD HERE
	this.bga.actions.performAction(action, args);		this.bga.actions.performAction(action, args, options);
	},		},
	</pre>		</pre>

Thoun: /* Force players to refresh after new deploy */

2026-09-28T14:07:45Z

Force players to refresh after new deploy

← Older revision		Revision as of 16:07, 28 September 2026
Line 1,803:		Line 1,803:
	return [		return [
	'players' => $players,		'players' => $players,
	'version' => ~~intval(~~$this->~~gamestate~~->~~table_globals[300]~~), // <-- ADD HERE		'version' => $this->bga->tableOptions->getGameVersion(), // <-- ADD HERE
	...		...
	];		];
Line 1,813:		Line 1,813:
	public function checkVersion(int $clientVersion): void		public function checkVersion(int $clientVersion): void
	{		{
	if ($clientVersion != ~~intval(~~$this->~~gamestate~~->~~table_globals[300]~~)) {		if ($clientVersion != $this->bga->tableOptions->getGameVersion())) {
	// Simplest way is to throw a "visible" exception		// Simplest way is to throw a "visible" exception
	// It's ugly but comes with a "click here" link to refresh		// It's ugly but comes with a "click here" link to refresh
Line 1,838:		Line 1,838:
	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:		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>		<pre>
	~~ajaxcallwrapper~~: function (action, args) {		performActionWrapper: function (action, args) {
	if (!args) args = {};		if (!args) args = {};
	args.version = this.gamedatas.version; // <-- ADD HERE		args.version = this.gamedatas.version; // <-- ADD HERE
	this.~~bgaPerformAction~~(action, args);		this.bga.actions.performAction(action, args);
	},		},
	</pre>		</pre>

Thoun: /* Images and Icons */

2026-09-08T13:40:30Z

Images and Icons

← Older revision		Revision as of 15:40, 8 September 2026
Line 477:		Line 477:

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

	~~====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~~
	~~return this.statusBar.addActionButton(div_html, handler, { id });~~
	},

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

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

Thoun: /* Adding Image buttons */

2026-09-08T13:39:58Z

Adding Image buttons

← Older revision		Revision as of 15:39, 8 September 2026
Line 485:		Line 485:
	<pre>		<pre>
	addImageActionButton: function (id, div_html, handler) { // div_html is string not node		addImageActionButton: function (id, div_html, handler) { // div_html is string not node
	this.statusBar.addActionButton(div_html, handler, { id });		return this.statusBar.addActionButton(div_html, handler, { id });
	~~dojo.addClass(id, "bgaimagebutton"); // add css class to do more styling~~
	~~return $(id); // return node for chaining~~
	},		},

Thoun: /* High-Definition Graphics */

2026-09-08T13:39:06Z

High-Definition Graphics

← Older revision		Revision as of 15:39, 8 September 2026
Line 456:		Line 456:
	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:		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>		<pre>
	~~var~~ isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";		const isRetina = "(-webkit-min-device-pixel-ratio: 2), (min-device-pixel-ratio: 2), (min-resolution: 192dpi)";
	if (window.matchMedia(isRetina).matches)		if (window.matchMedia(isRetina).matches) {
	{		this.bga.images.dontPreloadImages(['pieces.png', 'board.jpg'];
	this.~~dontPreloadImage~~( 'pieces.png' );		} else {
	~~this.dontPreloadImage(~~ 'board.jpg' );		this.bga.images.dontPreloadImages(['pieces@2x.png', 'board@2x.jpg']);
	}
	else
	{
	this.~~dontPreloadImage~~( 'pieces@2x.png' );
	~~this.dontPreloadImage(~~ 'board@2x.jpg' );
	}		}
	</pre>		</pre>

Thoun: /* Animation */

2026-09-08T13:37:34Z

Animation

← Older revision		Revision as of 15:37, 8 September 2026
Line 68:		Line 68:

	=== Animation ===		=== 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 ====		==== Scroll element into view ====

Thoun: /* Avoiding code in dojo declare style */

2026-07-27T12:08:04Z

Avoiding code in dojo declare style

← Older revision		Revision as of 14:08, 27 July 2026
Line 1,533:		Line 1,533:

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

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

	=== Frameworks and Preprocessors===		=== Frameworks and Preprocessors===