BGA Studio Migration Guide

under construction

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

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

📌 This symbol: information about migration, if you want to migrate an old game to the most recent ways

Structural changes

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

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

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

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

When building the game with this file you will see deprecation warning.

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

Move and refactor, see section Namespaced game class

<gamename>.action.php => remove

See section Autowire game actions

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

See section Removal of view and template

material.inc.php => optional

See section #Material

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

See section #States

<gamename>.js

File still there but massive API changes, see bottom sections

PHP migration

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

New projects are generated using the strict mode

📌

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

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

User preferences

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

📌

• If you had a custom function called setupPreferences() reading the <select> values, you can now use onGameUserPreferenceChanged instead.
• If you had a copy of the user preferences on a DB table, it's not needed anymore. Remove all support of writing to this table. Replace access to this table with

       $pref = (int) $this->userPreferences->get($playerId, $prefCode);

Instant cssPref on user preferences

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

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

Game options

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

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

📌

• Remove declaration of game options from "initGameStateLabels"
• Instead of using $this->getGameStateValue or $this->gamestate->table_globals use

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

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

Namespaced game class

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

Main game logic: Game.php#Creating other classes

📌 The class file should be moved to modules/php/Game.php and start with this adapted part:

namespace Bga\Games\YourGameName;

class Game extends \Bga\GameFramework\Table { ... }

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

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

The material.inc.php to have be moved (see below)

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

• notifyAllPlayers
• notifyPlayer
• mysql_fetch_assoc
• Table (class access without namespace)
• isMutiactiveState (misspelled version)
• ...

Material

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

Autowire game actions

Simplify the action calls by removing <gamename>.action.php file

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

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

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

Notifications

Functions notifyAllPlayers and notifyPlayer from main game.php are deprecated

📌 Replace notifyAllPlayers by $this->notify->all() and notifyPlayer by $this->notify->player()

Notification Decorators

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

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

Notification args consistency

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

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

[
 'roundNumber' => $roundNumber, // number, to update the round counter
 'round_number' => $roundNumber, // number that will be transformed to string by bgaFormatText, when shown in bold in the logs
]

📌 Do not duplicate the value, as the notif_ handler will now get unmutated args

Deprecated getGameName

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

📌 Delete the getGameName function in the Game PHP file.

Legacy

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

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

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

Any Globals

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

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

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

Server Counters

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

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

📌 Replace setting player_score/player_score_aux using db queries with use of $this->playerScore and $this->playerScoreAux. Remove the notifications, or part of notifications, updating the scoreCtrl counter (if you had some custom notification you may still need them).

Updated Zombie Mode documentation and recommendations

We now recommend making the zombie player playing randomly, instead of passing as a default. A new "Zombie Mode level" field has been added to the Game Metadata Manager, to indicated the Zombie Mode you implemented in your game.

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

IDE Support

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

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

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

View and template files: deprecated

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

📌 The DOM should be built on the JS side to remove the view/template files, so it can be complicated for old projects using them intensively. It would look like this:

this.getGameAreaElement().insertAdjacentHTML('beforeend', `
  <span>${_('My translated text')}</span><div id="player-tables"></div>
`);
 

See more in #Access template elements

Forbid access to global BGA variables and direct DB access on action/view files

If you did not remove action and view files, you cannot longer use some stuff in them, such $g_user global and db access functions.

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

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

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

States

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

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

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

If still using states.php

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

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

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

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

Deprecation of ajaxcall

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

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

📌 Replace combination of checkAction/ajaxcall by bgaPerformAction. Beware of the options (3rd param) if it was an ajaxcall without checkAction.

Access template elements

New functions getPlayerPanelElement(player_id) and this.getGameAreaElement()

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

📌 Code like dojo.place(html, player_board_${player.id}); would be replaced by this.getGameAreaElement().insertAdjacentHTML('beforeend', html);

Easier notification setup

Notifications can now be automatically scanned and called without needing to register them one by one. They'll handle Promises, so they end synchronously when the Promise resolves.

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

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

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

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

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

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

Status bar manipulation

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

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

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

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

Dojo usage

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

📌 Replace dojo by vanilla JS where possible

examples are coming...

Sound loading

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

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

📌 Replace template loading of sounds and global function playSound

Formatting of log message using bgaFormatText

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

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

Future support of dark mode

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

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

Automata player panel

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

📌 Replace manually created automata player panel with this new function

New JS libraries

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

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