Board Game Arena - User contributions [en]

BGA-ts-template Tutorials

2024-04-12T13:58:59Z

NevinAF: NevinAF moved page BGA-ts-template Tutorials to BGA Type Safe Template: Tutorials: Cleaner and more clear

#REDIRECT [[BGA Type Safe Template: Tutorials]]

BGA Type Safe Template: Tutorials

2024-04-12T13:58:59Z

NevinAF: NevinAF moved page BGA-ts-template Tutorials to BGA Type Safe Template: Tutorials: Cleaner and more clear

''This page was generated from [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md BGA TS Template: README.md]. It is recommended to view this document from the source file. All links will redirect to source documentation, and images will only be included via link.''

<span id="ts-template-tutorials"></span>
= TS Template: Tutorials =

[https://github.com/NevinAF/bga-ts-template?tab=readme-ov-file#board-game-arena-type-safe-template ''BGA Type Safe Template'']

All tutorials are beginner friendly and are designed to help you get started with the BGA Type Safe Template. Each tutorial will link to this page for the first four steps which are shared for any project you are working.

<span id="tutorial-list"></span>
== Tutorial List ==

# [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/reversi.md Reversi]: A two player turn-based, perfect knowledge strategy game. Great starting point, meant for learning the purpose of each file and quickly getting a game up and running. Less good for learning internal components and framework.

<span id="step-0---development-environment-setup"></span>
== Step 0 - Development Environment Setup ==

No matter what you are doing, the first step is to always prepare your development tools. There are many different ways to set up your development environment, and many different tools to choose from.

Board Game Arena requires some sort of [https://en.wikipedia.org/wiki/SSH_File_Transfer_Protocol SFTP client], but that’s about it. Adding on to that, the Type Safe Template requires [https://nodejs.org/en/ Node.js] to initialize and build the project. Everything else is up to the developer or team.

<blockquote>'''S'''ecure '''F'''ile '''T'''ransfer '''P'''rotocol (SFTP) essentially describes how to upload and download files from a network drive, not that different from Google Drive or Dropbox.
</blockquote>
The official BGA team recommends [https://code.visualstudio.com/ Visual Studio Code] and a specific set of extensions for development. Based on this, the following steps are a quick guide for anyone who is starting from scratch or unsure of what to do.

<blockquote>This is labeled as step 0 because it only ever needs to be down once. If you already have these tools installed and set up, you can skip this step.
</blockquote>
<span id="recommended-tools"></span>
=== Recommended Tools ===

# '''[https://code.visualstudio.com/ Visual Studio Code]''': A code editor with a wide range of extensions and features. Using VS Code will provide automatic code completion, syntax highlighting, and many other features that make development easier. Download [https://code.visualstudio.com/download VS Code here.]
# '''[https://nodejs.org/en/download/ Node.js]''': A JavaScript runtime which is used to initialize and build source files to

<blockquote>A node version manager is also recommended for managing multiple versions of node.
</blockquote>
<ol start="3" style="list-style-type: decimal;">
<li><p>'''[https://docs.npmjs.com/about-npm Node Package Manager (npm)]''': A package manager for JavaScript. This will be used to automatically install and manage the dependencies,including the BGA Type Safe Template.</p>
<p>Once you have node.js installed, you can install npm by simply running the following in the terminal:</p>
<pre lang="bash">npm install -g npm</pre></li>
<li><p>'''[https://marketplace.visualstudio.com/items?itemName=nevinfoster.bga-extension-pack BGA Extension Pack]''': A collection of VS Code extensions that are useful for BGA development. This includes syntax highlighting for BGA files, a BGA icon theme, and more.</p></li>
<li><p>(optional) '''[https://git-scm.com/downloads Git]''': One of the most populate version control systems. This is used to track changes to your code and collaborate easily with others. Nearly all BGA developers use [https://github.com GitHub] to share their code, which is built on top of Git.</p></li></ol>

<table>
<tr>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/download_vscode.gif
</td>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/download_nodejs.png
</td>
</tr>
<tr>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/download_npm.gif
</td>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/download_git.png
</td>
</tr>
</table>
<span id="step-1---create-a-new-project"></span>
== Step 1 - Create a New Project ==

<ol style="list-style-type: decimal;">
<li><p>Go to [https://studio.boardgamearena.com studio.boardgamearena.com] and login. Then navigate to your [https://studio.boardgamearena.com/studio manage games] page:</p>
<ul>
<li>Click on your profile icon on the top right of any page.</li>
<li>Click on the Control Panel button on the top right. This is only visible if you are on a developer account.</li>
<li>Click on the Manage Games button on the left side of the page.</li></ul>

<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/bga_create_new_project.gif</p>
</p></li>
<li><p>'''Create new project'''. You only need to fill out the name of the game, usually something like <code><UserName>Tutorial<Game></code> for a first project.</p></li></ol>

<blockquote>This should always be in upper camel case (Pascal Case) with no spaces or special characters. This is because the project name is used in the URL of the game, and the URL is case sensitive.
</blockquote>
<ol start="3" style="list-style-type: decimal;">
<li><p>'''Create a local folder''' for the project files. Something like <code>C:\Users\<UserName>\Documents\BGA\<project-name></code> is a good place to start.</p></li>
<li><p>'''Use SFTP client to download the project files''' to the folder you just created. If you are using the recommended tools for development, you can do the following:</p>
<ol style="list-style-type: lower-alpha;">
<li><p>'''Open the new folder in VS Code'''. You can open VS Code and use the <code>File > Open Folder</code> to open the specific folder you created.</p></li>
<li><p>'''Run the [[command:sftp.config|SFTP: Config]] command'''. You can do this by pressing <code>Ctrl+Shift+P</code> (or <code>F1</code>) to open the command palette, then typing <code>SFTP: Config</code> and pressing enter.</p></li>
<li><p>'''Paste the following''' into the created <code>.vscode/sftp.json</code> file, then update the username, password, and remotePath fields with your own information. The username and password will have been emailed when signing up for a developer account::</p></li></ol>

<pre lang="json">{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "___YourUsername___",
"password": "___yourpassword_hexstring___",
"remotePath": "/___lowercaseprojectname___/",
"ignore": [
".vscode",
".git",
".idea",
".gitignore",
".DS_Store",
"node_modules",
"package-lock.json",
"yarn.lock",
"nmp-debug.log",
"yarn-error.log",
"source/client/build"
]
}</pre>
<ol start="4" style="list-style-type: lower-alpha;">
<li>'''Run the [[command:sftp.sync.remoteToLocal|SFTP: Sync Remote -> Local]]''' command. This will download all initial files from the BGA server to your local folder.</li></ol>
</li></ol>

<p align="center" width="50%">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/bga_starting_files.png
</p>
<blockquote>When viewing files in VS Code, the php files will have errors because the shared codes in not yet linked. This will be resolved in the next step.
</blockquote>
<ol start="5" style="list-style-type: decimal;">
<li><p>'''Run the game''' to make sure everything is working correctly. You can run tests filled with your developer accounts by using <code>Express Start</code> when setting up to play a game.</p>
<ul>
<li>Navigate to the <code>Manage Games</code> page as described in step 1.1.</li>
<li>Click on any games in your list of games.</li>
<li>Click on <code>Play</code> from within the list of options on one of your game’s versions.</li>
<li>Click on <code>Create A Table</code>.</li>
<li>Click on <code>Express Start</code>.</li></ul>
</li></ol>

<table>
<tr>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/bga_test_game.gif
</td>
<td>
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/bga_open_dev_player.png
</td>
</tr>
</table>
<blockquote>You can play as any of the connected developer accounts by clicking on the red <code>></code> next to any of the players’ names.
</blockquote>
<span id="step-2---initialize-the-bga-type-safe-template"></span>
== Step 2 - Initialize the BGA Type Safe Template ==

# '''Create a <code>package.json</code> file''', and fill it with the following contents:

<pre lang="json">{
"scripts": {
"init": "npm install bga-ts-template && npx bga-init YourGameName \"developers\" source --typescript --scss --vscode-extension-pack --php-8.2 --gameinfos.jsonc --gameoptions.jsonc --gamepreferences.jsonc --stats.jsonc --gamestates.jsonc",
"build": "npx bga-build",
"watch": "npx bga-build --watch"
}
}</pre>
<ol start="2" style="list-style-type: decimal;">
<li><p>'''Change the <code>YourGameName</code> and <code>developers</code> arguments''' to fit your project. You can also change any of the other arguments to fit your needs. See the [https://github.com/NevinAF/bga-ts-template/blob/main/README.md#configurations BGA Type Safe Template: Configurations] for more information.</p></li>
<li><p>'''Run the <code>init</code> script'''. This can be done using a terminal on the project directory, or in VS Code by hovering over the <code>scripts: "init"</code> line in the <code>package.json</code> file. You can see more information about the package.json scripts at [https://github.com/NevinAF/bga-ts-template/blob/main/README.md#package-scripts BGA Type Safe Template: Package Scripts].</p></li></ol>

<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/package_json_run_script.gif
</p>
<ol start="4" style="list-style-type: decimal;">
<li><p>'''View your files.''' You should now only have a trhee error among all of your files.</p>
<ul>
<li>One issue in <code>yourgamename.game.php</code> file, usually on line 75, and is a syntax error caused by a minor bug in the starting files.</li></ul>

<table align="center">
<tr>
<td>
<pre lang="php">// Error: Expected type 'null|array'. Found 'string'
$sql .= implode( $values, ',' ); </pre>
</td>
<td>
<pre lang="php">// Fixed!
$sql .= implode( ',', $values ); </pre>
</td>
</tr>
</table>
<ul>
<li>Two issues in <code>yourgamename.action.php</code>, one for each player action. This is a type error stating that your main game code does not have the player action functions defined (which is true!). This will be fixed later when adding player actions.</li></ul>

<table align="center">
<tr>
<td>
<pre lang="php">public function playCard()
{
self::setAjaxMode();

/** @var int $card_id */
$card_id = self::getArg('card_id', AT_int, true);

$this->game->playCard( $card_id ); // Error: Undefined method
self::ajaxResponse();
}</pre>
</td>
<td>
<pre lang="php">public function pass()
{
self::setAjaxMode();

$this->game->pass( ); // Error: Undefined method
self::ajaxResponse();
}</pre>
</td>
</tr>
</table></li>
<li><p>Sync your local files to the BGA server. When using VS Code SFTP extension, '''run the [[command:sftp.sync.localToRemote|SFTP: Sync Local -> Remote]] command'''. ''This is only needed the first time you upload, or if you change files when VS code is not running (ie, the extension is not active).''</p></li>
<li><p>'''Run the game in the BGA studio'''. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-1---create-a-new-project step 1.5] for more information on how to do this.</p></li>
<li><p>'''Hard Refresh the client page'''. You should ALWAYS do a hard refresh when making changes, otherwise you will likely be using old cached files.</p>
<ul>
<li>''Windows'': Chrome, Firefox, or Edge => Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>.</li>
<li>''Mac'': Chrome or Firefox => Press <code>Cmd+Shift+R</code>. Safari => Press <code>Cmd+Option+E</code>.</li></ul>
</li></ol>

<blockquote>There are no differences, but running the game makes sure that everything is working correctly.
</blockquote>
<span id="step-3---game-information-metadata"></span>
== Step 3 - Game Information + Metadata ==

A good portion of this information is optional, but it is always good practice to fill out as much as possible for all projects.

# '''Update <code>shared/gameinfos.jsonc</code>'''. The [https://en.doc.boardgamearena.com/Game_meta-information:_gameinfos.inc.php Game Infos] contains all meta-information for the game such as the full name and number of players. Each value in the file has hover-able tooltips for more information and will show error if there are any validation issues.
# '''Run <code>npm run build</code>'''. This will convert your json to the <code>gameinfos.inc.php</code> file which is used by the BGA server. See the [https://github.com/NevinAF/bga-ts-template/blob/main/README.md#package-scripts BGA Type Safe Template: Package Scripts] for more information.

<blockquote>You can also run <code>npm run watch</code> to automatically build any files whenever they are changed.
</blockquote>
<ol start="3" style="list-style-type: decimal;">
<li>Go to the manage game page for your game and '''select Reload game informations'''. This must be clicked whenever the <code>gameinfos</code> file is updated.</li></ol>

<blockquote>The manage game page for a game can always be found by going to the <code>Manage Games</code> page from [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-1---create-a-new-project Step 1.1], then clicking on the game you want to manage.
</blockquote>
<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/game_configuration.png
</p>
<ol start="4" style="list-style-type: decimal;">
<li>From the same location in step 3.3, click on <code>Manage metadata images</code> to edit all visual/informational metadata of the game. See the [https://en.doc.boardgamearena.com/Game_metadata_manager Game Metadata Manager] wiki page for more information.</li></ol>

After steps 3.3 and 3.4, your can view your game’s <code>game page</code> verify that you see the corrected information.

Setting up BGA Development environment using VSCode

2024-04-12T13:55:37Z

NevinAF: Fixed redirect on bga type safe template

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==

* Download and install vscode from https://code.visualstudio.com
* Download and install php (7.4) command line interface (for local tests and debugging)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===
The IntelliSense for JavaScript code is to '''use the [[BGA Type Safe Template]]'''. It offers a much cleaner initial file, clearer workflow, and nearly complete type and autofill support for whatever you may need.

<table>
<tr>
<td>[[File:Stripped base Typescript file.png|alt=Starting TS file with comments/template code removed|thumb|696x696px|Starting TS file with comments/template code removed]]</td>
<td>[[File:Typescript autofill.gif|alt=Typescript Autocomplete using BGA Type Safe Template|thumb|542x542px|Typescript Autocomplete using BGA Type Safe Template]] </td>
</tr>
</table>

If this does not interest you, you can also revert to the old ways of getting better intellisense:

- Because of dojo style class/method declarations most IDE won't be able to index main JavaScript file properly (i.e. go to definition of function and such).
If you manage to get it working in VS code, let us know how.

- There is a way to re-structure code to avoid using this style, but this is not for beginners. Do not use this on your first game!
https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Avoiding_code_in_dojo_declare_style

- There is also a complete example of a "dojo-less" project, it also includes a (incomplete) typescript definition file (.d.ts) for auto-completion of js BGA interfaces
https://github.com/elaskavaia/bga-dojoless

===PHP Intellisense===

If you don't do anything PHP will complain about undefined symbols from BGA framework (as well as from the material file).
To solve the warning about framework issues, you need a stubs for the BGA APIs:

*git clone git@github.com:elaskavaia/bga-sharedcode.git (you can also get and unzip it from the GitHub page)
** if that doesn't work, try git clone <nowiki>https://github.com/elaskavaia/bga-sharedcode.git</nowiki>
**you can do this in a terminal from VS Code - Terminal menu -> New Terminal
*add reference (include path) to bga-sharedcode/misc using settings of PHP extension, see example below

If you're using the Intelephense plugin, add this to global user settings (modify the path obviously)

"intelephense.environment.includePaths": [
"/home/victoria/git/bga-sharedcode/misc/"
],

To solve the warning about the material file class members

Option 1)
If you don't have too many class members you can define them, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/victoria/php-composer
composer require --dev phpunit/phpunit ^9

Then add this path (e.x. /home/victoria/php-composer) to include paths as above

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store"
],
"syncOption": {
"skipCreate": false, # syncs new files
"delete": true # syncs deleted files
}
}
</pre>

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.

=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.19.1",
"prettier": "^2.7.1"
},
"prettier": {
"braceStyle": "1tbs"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>

[[Category:Studio]]

Using Typescript and Scss

2024-04-12T13:53:23Z

NevinAF: Fixed redirect on bga type safe template

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

== BGA Type Safe Template ==
If you are interested in all of the BGA Framework being typed for you, '''check out the [[BGA Type Safe Template]]'''. It will let you set up full typescript support and more with the fewest, easy-to-follow steps.
[[File:Typescript autofill.gif|alt=Typescript Autocomplete|center|thumb|734x734px|Typescript Autocomplete using BGA Type Safe Template]]'''The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.'''

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''

{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "tsc",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "tsc --watch",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"sass": "^1.32.6",
"typescript": "^4.1.3"
}
}

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

For Typescript compilation we also need to set up a <code>tsconfig.json</code> on the root folder.

'''tsconfig.json'''

{
"rootDir": ".",
"compilerOptions": {
"target": "es5",
"module": "none",
"lib": ["dom", "esnext"],
"sourceMap": false,
"typeRoots": ["src/types", "./types", "./node_modules/@types"],
"outFile": "YourGameName.js"
},
"files": [
"src/GameBody.ts",
"src/define.ts"
]
}

Note: it only works now with es5

If you want to split your code onto multiple files, just add them in the file list (order is important for dependencies, new subpart should go on top of the list). No need to import classes or types from one file to another. In fact, you can't with this configuration.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look [https://github.com/thoun/bga-ts-example here] for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/GameBody.ts'''

<pre>
// @ts-ignore
GameGui = (function () { // this hack required so we fake extend GameGui
function GameGui() {}
return GameGui;
})();

// Note: it does not really extend it in es6 way, you cannot call super you have to use dojo way
class GameBody extends GameGui {
constructor() {}

public setup(gamedatas: any) {
this.setupNotifications();
}
public onEnteringState(stateName: string, args: any) {}
public onLeavingState(stateName: string) {}
public onUpdateActionButtons(stateName: string, args: any) {}
public setupNotifications() {}
}
</pre>

To plug the class with BGA framework, we'll also create another file:

'''src/define.ts'''

define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock"
],
function (dojo, declare) {
return declare("bgagame.yourgamename", ebg.core.gamegui, new GameBody());
});
Copy <code>bgagame.yourgamename</code> from original JS to avoid name mistakes with letter case.

If you try to compile it you will be missing definitions of bunch of methods and variables for that we will add special ts type definition file .d.ts, this is not a complete version but you can get more complete from git projects below

'''src/types/bga-framework.d.ts'''
<pre>

declare var gameui: GameGui;
declare var g_replayFrom: number | undefined;
declare var g_gamethemeurl: string;
declare var g_themeurl: string;
declare var g_archive_mode: string;
declare function _(str: string): string;

declare const define;
declare const ebg;

declare class GameGui {
page_is_unloading: any;
game_name: string;
instantaneousMode: any;
player_id: string;
interface_min_width: number;
gamedatas: any;

isCurrentPlayerActive(): boolean;
addActionButton(id: string, label: string, callback: (event?: any) => void);
checkAction(action: any);
ajaxcall(url: string, args: object, bind: GameGui, resultHandler: (result: any) => void, allHandler: any);

setup(gamedatas: any): void;
onEnteringState(stateName: string, args: any): void;
onLeavingState(stateName: string ): void;
onUpdateActionButtons(stateName: string, args: any): void;
setupNotifications(): void;

onScriptError(msg: string, url?: string, linenumber?:number);
inherited(args: any);
}

</pre>

Above is barebone definition of gameui interface, you can find more complete one here
https://github.com/elaskavaia/bga-dojoless/blob/main/src/types/bga-framework.d.ts

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.
Original content same as original .css, i.e

@import url(../../../css/csslayer.css);

Your SCSS code can be splitted in multiple files, for example :

'''yourgamename.scss'''
@import 'gametable';

/* some classes */

'''_gametable.scss'''
/* _gametable related classes */

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continiously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup stanard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

=== Hint ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To add code completion on framework, dojo, stock, ... you'll need more type definition files. Feel free to copy them from [https://github.com/thoun/bga-ts-example this repo] and reference them at the top of files array, even before your subpart files.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless
* https://github.com/NevinAF/bga-ts-template

[[Category:Studio]]

BGA Studio Cookbook

2024-04-12T13:51:25Z

NevinAF: Fixed redirect on bga type safe template

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

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

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

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

Note: this method is recommended by BGA guildlines

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

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

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

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

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

'''Ingredients:''' ggg.js

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

or modern way

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

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

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

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

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

ggg.css:

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

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

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

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

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

=== Animation ===

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

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

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

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

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

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

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

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

The code is bit complex it can be found here

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

Game using it: century, ultimaterailroads

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

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

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

=== Logs ===

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

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

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

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

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

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

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

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

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

This is a bad idea for many reasons:

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

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

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

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

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

[[File:clientloginjection.png|left]]

ggg.js

<pre>

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

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

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

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

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

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

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

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

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

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

default:
break;
}

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

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

ggg.game.php:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

=== Player Panel ===

==== Inserting non-player panel ====

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

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

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

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

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

some hackery required in js

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

=== Images and Icons ===

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

'''Ingredients:''' ggg.js

<pre>
// your game resources

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

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

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

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

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

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

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

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

where ${color} - is color you want

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

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

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

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

return avatarURL;
},
</pre>

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

==== Adding Image buttons ====

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

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

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

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

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

[[File:Dragonline_font.png]]

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

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

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

===== Content Security Policy =====

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

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

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

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

=== Use player color in template ===

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

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

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

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

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

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

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

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

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

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

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

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

=== Dynamic tooltips ===

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

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

==== Rectangles and circles ====

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

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

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

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

==== Irregular Shapes ====

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

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

For instance:

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

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

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

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

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

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

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

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

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

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

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

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

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

== Game Model and Database design ==

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

[[File:Madeira board.png]]

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

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

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

Variant 1: Minimalistic

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

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

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

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

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

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

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

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

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

Variant 3: More normalised

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

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

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

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

=== Database for The card game ===

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

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

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

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

Variant 1: Minimalistic

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

Variant 2: More normalised

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

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

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

== Code Organization ==

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

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

});

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

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

use it

foo = new bgagame.other();

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

* Create ggg_other.js in modules/ folder and sync

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

* Modify ggg.js to include it

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

});

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

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

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

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

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

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

require_once ('modules/ggg_other.php');

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

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

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

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

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

</pre>

Run from command line like
php7 ggg_test.php

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

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

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

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

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

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

</pre>

=== More readable JS: onEnteringState ===

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

<pre>

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

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

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

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

</pre>

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

=== Frameworks and Preprocessors ===

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

== Assorted Stuff ==

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

'''Ingredients:''' ggg.js

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

So lets do Select Worker/Place Worker

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

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

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

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

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

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access
Examples:
* Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
* Ultimate Railroads - action taking game where effects can be executed in any order
* Lewis and Clark - card game where actions executed as queue

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

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

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

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

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response
* 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.

=== Changing state prompt ===

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

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

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

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

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

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

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

=== Ajax Call wrapper ===
'''Ingredients:''' ggg.js

The current ajaxcall is super vebose and prone to errors, I suggest using a helper function. It does a lot of stuff you must do anyways.
Most beginner mistakes come from missing part of this code (which is understandstandable - this is a huge snippet to clone every time).

<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = {}; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server
if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, it has optional param "is_error" - you rarely need it
}
},
</pre>

Usage:
<pre>
this.ajaxcallwrapper('pass'); // no args
this.ajaxcallwrapper('playCard', {card: card_id}); // with args
this.ajaxcallwrapper('playCard', {card: card_id}, (is_error)=>{if (!is_error) dojo.query(".selected").removeClass('selected');}) // with handler that cleans up 'selected' class on success
</pre>

Note: this always will lock interface and always check for action, you can modify this method to do it optionally, i.e replace 'args.lock = true;' in the code above with this
if (args.lock!==false) args.lock = true; else delete args.lock; // it does not work with false value - it has to be removed

=== Custom error/exception handling in JavaScript ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Local Storage ===

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

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

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

== Algorithms ==

=== Generate permutations in lexicographic order ===

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

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

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

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

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

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

[[Category:Studio]]

Tutorial reversi

2024-04-12T13:49:49Z

NevinAF: Fixed redirect on bga type safe template

'''Check out an update version''' of the [[BGA Type Safe Template: Reversi|Reversi Tutorial]] which uses the [[BGA Type Safe Template]]. {{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

== Create your first game ==

''Note: you should already have created a project following instructions in [[First_steps_with_BGA_Studio#Create_a_new_game_project|Create a new game project]]. While you will find a '''reversi''' directory in your SFTP folder, do not use it for this tutorial. Instead, use the project you have created as an (empty) starting point.''

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 1. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games. If you choose to start with 2 players, you should see two names on the right: testdude0 and testdude1. To switch between them, press the red arrow button near their names; it will open another tab. This way you don't need to login and logout from multiple accounts.)
* Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

End the game by clicking on the game options icon on the top right, and then on "Express Stop".

== Editing the game information (Optional) ==

This step is optional and will fix the warnings on the project page (missing BGG_ID and presentation).

==== Edits to fix Errors ====
* Edit your local copy of the gameinfos.inc.php file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 37.
** Add <code>1,</code> to the players array - that's around line 41.
** Change the presentation array content - that's around line 134. Uncomment one line and change the text. Remove the final comma if you keep only one line!
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

===== Not working? =====
Some changes will require bypassing the cache. It is often worth doing a hard refresh to make sure the

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

Let's start with the board. This will give you a good idea of how things will look and where tokens should go.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we chose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg filesare lighter than png, so they are faster to load. Later, we are going to use PNGs for tokens because they allow for transparency.

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>reversi_reversi.tpl</code> to add a <code>div</code> for your board.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame_mygame.tpl</code>). The file names in your project will be different than shown in this tutorial, replacing <code>reversi</code> with your project name. Be sure that any code (other than comments) that references <code>reversi</code> is changed to your actual project name.

<pre>
<div id="board">
</div>
</pre>

* edit your <code>reversi.css</code> file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

'''Important: refresh your page.''' Here's your board:[[File:reversi1.jpg]]

If the board does not appear, refresh the page (always do this when you update the CSS file), and check the image filename. Remember file names are case sensitive!

==== Code the Grid ====
Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for the white and black tokens.

===== Make a Square Template =====
The board is 8 squares by 8 squares. This means we need 64 squares. To avoid writing 64 individual <code>div</code> elements on our template, we are going to use the "block" feature.

Let's modify our template (the <code>.tpl</code> file) like this:

<pre>
<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>

</div>
</pre>

As you can see, we created a "square" block, with 4 variable elements: <code>X</code>, <code>Y</code>, <code>LEFT</code>, and <code>TOP</code>. We are going to use this block 64 times during page load.

===== Use Square Template to Build Grid =====
Let's do it in our <code>reversi.view.php</code> file, inside the <code>build_page</code> function:

Note that "reversi_reversi" is the name of the game and if you named your differently you will have to change that when you copy and paste. Example "testreversi_testreversi".

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

Note: as you can see, squares in our <code>board.jpg</code> files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

===== Style Those Squares =====
Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* <code>background-color: red;</code> is used for testing. This allows us to see the invisible elements. (You could instead do something like <code>border: 1px solid orange;</code>. have fun and be creative)

Let's refresh and check our (beautiful) squares:

[[File:reversi2.jpg]]

Now that you know the squares are there, you can remove the test line <code>background-color: red;</code> from your <code>.square</code> class in the CSS stylesheet.

===== Not Working? =====
If the styled squares do not appear, inspect and check your css (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css).

If your changes are not there try clearing your cache. Remember, you can bybass cache

== The Tokens ==

Now, our board is ready for some tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

=== Build the Token ===
There are quite a few steps before the tokens will appear. You may be used to testing after every change, but that won't work well here. The token will '''not''' show until you have add a div to the tpl, styles to the css, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

==== HTML in the .tpl file ====
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>


<div id="tokens">
</div>
</div>
</pre>

Note: <code>tokens</code> is plural. This div will be used to hold the token divs. Shortly, we will use javascript to add individual tokens to the board.

==== Add Token to img directory ====
Here's a new piece of art with the tokens. We need transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory.

Important Fun Fact: we are using ONE file for both tokens. It is really important to use a minimum number of graphic files for your game. This is called the "CSS sprite" technique, because it makes the game load faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

==== Style the Tokens in .css file ====
<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we could apply the classes "token" and "tokencolor_ffffff" to a div element and we'd got a white token.

Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.

==== Build Token JS Template in .tpl file ====
Now, let's make the first token appear on our board. Tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (<code>reversi_reversi.tpl</code>), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named <code>jstpl_token</code> with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (braces <code>{}</code>) and JS template variables (dollar and braces <code>${}</code>).

==== Add Token Utility Method in .js file ====
Now, let's create a method in our Javascript code (in the <code>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section //// Utility methods:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();
},
</pre>

===== Utility Method Explanation =====
* with <code>dojo.place</code> and <code>this.format_block</code> methods, we create a HTML piece of code and insert it as a new child of <code>tokens</code> div element.
* with BGA <code>this.placeOnObject</code> method, we place this element over the panel of some player.
* Immediately after, using BGA <code>this.slideToObject</code> method, we make the token slide to the <code>square</code> element, its final destination.
* <code>'overall_player_board_'+player</code> refers to the div element that contains each player's information and avatar. By initially placing the token here, it gives the effect that the player's avatar is throwing the token onto the board.

Note: don't forget to call the <code>play()</code>, otherwise the token will remain at its original location.

Note: during this process, the parent of the new token HTML element will stay <code>tokens</code>. <code>placeOnObject</code> and <code>slideToObject</code> methods are ''only'' moving the position of elements on screen, and they are ''not'' modifying the HTML tree.

==== Set Token Colors in setupNewGame in .game.php file ====
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Note: A few lines below, you may have to remove the line <code>self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );</code>

=== Test the Token ===
Now, to test if everything works fine

==== addTokenOnBoard() in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under <code>// TODO: Set up your game interface here</code> add
this.addTokenOnBoard( 2, 2, this.player_id );
Now restart the game.

''Note: if the page fails to load with a <code>Javascript error: n is null</code> message, make sure you have added the "tokens" div in your template as instructed above.''

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now. To design the database model of our game, you will need to access the database. You won't need to do anything in database UI, yet.

=== Accessing the Database ===
To access the database, start a game, then click "Go to game database" link at the bottom of our game, to access the database directly with a PhpMyAdmin instance.

After the first time you've acess the database, you could skip opening a game and instead, go to https://studio.boardgamearena.com/db/ . Your PhpMyAdmin username/password is in your welcome email.

'''Note''': do not remove existing tables

=== Create Table in .sql file ===
Now, you are able to create the table(s) you need for your game, and report every SQL command used in your <code>dbmodel.sql</code> file.

The database model of Reversi is short: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Add the above SQL to <code>dbmodel.sql</code>. Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL.

=== Test the Table ===
Now, a new database with a <code>board</code> table will be created each time we start a Reversi game. This is why after modifying our <code>dbmodel.sql</code> it's a good time to stop your current game & start a new game.

Start a new game and verify a table is created.

== Setup the initial game position ==

'''Note''': From now on, you must launch the game with '''two players''' to get two <code>player_id</code>s within the database. Otherwise, the game will crash.

The <code>setupNewGame</code> method of our <code>reversi.game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

=== Initialize the Board in .game.php file ===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
self::DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

* We create one table entry for each square, with a <code>NULL</code> value which means "empty square"
* On 4 of the squares, we place an initial token.

After this, we set <code>activeNextPlayer</code> to make the first player active at the beginning of the game (this line is already present in the default code template).

If you didn't do it earlier, you need to remove the call to <code>self::reattributeColorsBasedOnPreferences()</code> in <code>SetupNewGame()</code>. If you don't, player color preferences will try (and fail) to override the two colors supported here.

=== Show the Initial Token Setup ===
Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our <code>getAllDatas()</code> PHP method. <code>getAllDatas()</code> is called during each page reload.

In the <code>getAllDatas()</code> method, after <code>// TODO: Gather all information about current game situation (visible by player $current_player_id)</code>, add the following lines:

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

Next, you may need to modify the query that gets player information to also get the player's colors. This is in the variable <code>$sql</code>, above the lines you just inserted in <code>getAllDatas()</code>. Below is what the line will look like. Notice how we've added <code>player_color color</code> to the sql query.

<pre>
$sql = "SELECT player_id id, player_score score, player_color color FROM player ";
</pre>

We are using the BGA framework's <code>getObjectListFromDB()</code> that formats the result of this SQL query in a PHP array with x, y and player attributes. We add it to the result associative array with the key <code>board</code>.

Last, we process this array client side. Let's place a token on the board for each array item. We'll do this in our Javascript <code>setup</code> method under <code>// TODO: Set up your game interface here, according to "gamedatas"</code>.

This will result in a removal or edit of the previously added line <code>this.addTokenOnBoard(2, 2, this.player_id);</code>

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addTokenOnBoard( square.x, square.y, square.player );
}
}
</pre>

The <code>board</code> entry created in <code>getAllDatas()</code> is used here as <code>gamedatas.board</code>

=== Test the Game Start ===
Reload... and here we are:

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

== The game state machine ==

Stop your game, again. You're about to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's relatively simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

=== Build your States ===
And here's our <code>states.inc.php</code>, according to this diagram:

<pre>
$machinestates = array(

1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 10 )
),

10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

Now, in <code>reversi.game.php</code> let's create the methods that are declared in this game states description file:
* <code>argPlayerTurn</code>: referenced in the <code>args</code> property of the <code>playerTurn</code> state; this is the name of the method to call to retrieve arguments for this gamestate. Arguments are sent to the client side to be used on <code>onEnteringState</code> or to set arguments in the gamestate description.
* <code>stNextPlayer</code>: referenced in the <code>action</code> property of the <code>nextPlayer</code> state; this is the name of the method to call when this game state become the current game state.

=== Test Your States ===
... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state <code>playerTurn</code> right after the initial setup. That's why the status bar contains the description of <code>playerTurn</code> state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

We will use the <code>getPossibleMoves</code> PHP method to:
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* Check if the player has the right to play in the spot they choose

<blockquote>
Example of getPossibleMoves here https://gist.github.com/leocaseiro/a8bc2851bd0caddd06685b5035937d15
</blockquote>

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a <code>getTurnedOverDiscs(x,y)</code> method that returns coordinates of discs that would be turned over if a token would be played at <code>x</code>,<code>y</code>.
* Loop through all free squares of the board and call the <code>getTurnedOverDiscs</code> method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Making a database query is slow! Please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of <code>getPossibleMoves</code>, and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of <code>reversi.game.php</code>. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

== Display allowed moves ==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a <code>argPlayerTurn</code> method in <code>reversi.game.php</code>. This method is called on the server each time we enter into <code>playerTurn</code> game state, and its result is transferred automatically to the client-side:

<pre>
function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We use the <code>getPossibleMoves</code> method we just developed.

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method (in the <code>reversi.js</code> file, under "Game & client states"). This lets us use the data returned by the method above on the client side.

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

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we enter into <code>playerTurn</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>
Here's what this does. At first, it removes all <code>possibleMove</code> classes currently applied with the very useful combination of <code>dojo.query</code> and <code>removeClass</code> method.

Then it loops through all possible moves our PHP <code>updatePossibleMoves</code> function created for us, and adds the <code>possibleMove</code> class to each corresponding square.

Finally, it uses the BGA framework <code>addTooltipToClass</code> method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

To see the possible moves we need to create a CSS class (<code>possibleMove</code>) that can be applied to a <code>square</code> element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a <code>possibleMove</code> square, send the move to the server.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the token position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
dojo.stopEvent( evt );

// Get the clicked square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

Warning: Make sure to replace <code>reversi</code> in line <code>this.ajaxcall( "/reversi/reversi/playDisc.html", {</code> with the name of your project. E.g. <code>"/yourgamename/yourgamename/playDisc.html"</code>

What we do here is:
* We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
* We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
* We check that <code>playDisc</code> action is possible, according to current game state (see <code>possibleactions</code> entry in our <code>playerTurn</code> game state defined above). This check is important to avoid issues if a player double clicks on a square.
* Finally, we make a call to the server using BGA <code>ajaxcall</code> method with argument x and y.

Now, we have to manage this <code>playDisc</code> action on the server side. At first, we introduce a <code>playDisc</code> entry point in our <code>reversi.action.php</code>:

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding <code>playDisc</code> method in our game logic (<code>reversi.game.php</code>).

Now, let's have a look of this <code>playDisc</code> method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

<pre>
// Now, check if this is a possible move
$board = self::getBoard();
$player_id = self::getActivePlayerId();
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

self::DbQuery( $sql );

</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
self::DbQuery( $sql );

// Statistics
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
self::incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
self::incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
self::incStat( 1, 'discPlayedOnCenter', $player_id );

</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

<pre>
// Notify
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

self::notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications (<code>playDisc</code>, <code>turnOverDiscs</code> and <code>newScores</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new BgaSystemException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine (<code>playDisc</code> is the name of a transition in the <code>playerTurn</code> game state description above which leads to state 11 which is <code>nextPlayer</code>).

To make the statistics work, we have to initialize them in <code>stats.json</code>:

<pre>
{
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
</pre>

A last thing to do on the server side is to activate the next player when we enter the <code>nextPlayer</code> game state (in the <code>reversi.game.php</code> file, under "Game state reactions"):

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = self::getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = self::getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( self::getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}

}
</pre>

Now, when we play a token, the rules are checked and the token appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appear automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our <code>setupNotifications</code> method in <code>reversi.js</code>, we register 2 methods for the 2 notifications we created at the previous step (<code>playDisc</code> and <code>turnOverDiscs</code>):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
dojo.subscribe( 'newScores', this, "notif_newScores" );
this.notifqueue.setSynchronous( 'newScores', 500 );
</pre>

As you can see, we associate each of our 3 notifications with a method prefixed with <code>notif_</code>. We also define these notifications as "synchronous", with a duration in millisecond. It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Update the player scores
* (wait 500ms)

The 2nd parameter in <code>dojo.subscribe</code> call (this) is the <code>context</code>, and will be passed in as a parameter to the specified method.

Let's have a look now on the <code>playDisc</code> notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handles the <code>turnOverDiscs</code> notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Make these discs blink and set them to the specified color
for( var i in notif.args.turnedOver )
{
var token = notif.args.turnedOver[ i ];

// Make the token blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeOut( {
node: 'token_'+token.x+'_'+token.y,
onEnd: function( node ) {

// Remove any color class
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'tokencolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>notif.args.turnedOver</code> (see previous paragraph). We loop through all these discs, and create a complex animation using <code>dojo.Animation</code> for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with <code>play()</code>.

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

[[Category:Studio]]

BGA-ts-template Reversi

2024-04-12T13:48:12Z

NevinAF: NevinAF moved page BGA-ts-template Reversi to BGA Type Safe Template: Reversi: Cleaner and more clear

#REDIRECT [[BGA Type Safe Template: Reversi]]

BGA Type Safe Template: Reversi

2024-04-12T13:48:12Z

NevinAF: NevinAF moved page BGA-ts-template Reversi to BGA Type Safe Template: Reversi: Cleaner and more clear

''This page was generated from [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/reversi.md BGA TS Template: Reversi.md]. It is recommended to view this document from the source file. All links will redirect to source documentation, and images will only be included via link.''

<span id="ts-template-reversi-tutorial"></span>
= TS Template: Reversi Tutorial =

[https://github.com/NevinAF/bga-ts-template?tab=readme-ov-file#board-game-arena-type-safe-template ''BGA Type Safe Template'']

'''Project Files:''' [[BGA-TS-Template-Reversi]]

This page is a beginner friendly tutorial which mimics the official [https://en.doc.boardgamearena.com/Tutorial_reversi Tutorial Reversi] page, but is more approachable and uses the BGA Type Safe Template. If you are not a new Board Game Arena developer, you may want to follow along with the [https://github.com/NevinAF/bga-ts-template?tab=readme-ov-file#getting-started BGA Type Safe Template: Getting Started] guide for a more concise overview of the template.

<blockquote>All steps are recorded as a git branch so you can track the exact changes that were made, and view the project files from any point in the tutorial.
</blockquote>
<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/reversi_steps_branches.gif<br>
</p>
<span id="steps-0-1-2-3"></span>
== Steps 0, 1, 2, 3 ==

Go to [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md TS Template: Tutorial] for the first four steps of the tutorial. The first four steps for any project are the same. To avoid redundancy, they are not repeated here.

<span id="step-3.5---from-here-on-out"></span>
== Step 3.5 - From here on out ==

At this point, your are ready to start developing your game. You can choose to follow any of the tutorials or guides on the [https://en.doc.boardgamearena.com/Main_Page BGA Studio Documentation] to continue.

From this point in the tutorial and on:

* It will be assumed that files are built and synced before running the game in the BGA studio.
* It will be assumed that you do a hard refresh of the client page after making changes.
* It will be assumed that you are using all of the default settings for initializing the typescript template. Adjustments can be made as needed and all sections have links to original file documentation for reference.
* Most steps will have specific instructions, but you can always adjust at your own discretion.

''Make sure the following game information is set for Reversi:''

<pre lang="json">// gameinfos.jsonc
{
"players": [ 2 ],
"bgg_id": 2389,
"player_colors": [ "cbcbcb", "363636" ],
"favorite_colors_support": false
}</pre>
<span id="step-4---game-board"></span>
== Step 4 - Game Board ==

# Download the following board image for Reversi, and place it in the <code>img</code> folder of your project. It should be named <code>board.jpg</code> to match the SCSS background-image in the next step.

<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/board.jpg
</p>
<ol start="2" style="list-style-type: decimal;">
<li><p>Add the board to the DOM by adding the following Smarty template code to the <code>yourgamename_yourgamename.tpl</code> file:</p>
<pre lang="html"><div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>

</div></pre>
<blockquote><p>The <code></code> and <code></code> are Smarty template tags that let you programmatically generate HTML as you will use in a following step. See [https://en.doc.boardgamearena.com/Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl X_X.tpl] for more information about the template file for BGA games.</p></blockquote></li>
<li><p>Add the following SCSS to the <code>yourgamename.scss</code> file to style the board:</p>
<pre lang="scss">#board {
// Setup Image
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
// Center the board
margin: auto;
left: 0; top: 0; right: 0; bottom: 0;
// Tokens and squares are absolutely placed relative to the board
position: relative;
}

.square {
// Size of a square
width: 62px;
height: 62px;
// Position relative to the board, not affected by other elements.
position: absolute;
// Placeholder for validating the positions.
background-color: red;
}</pre>
<blockquote><p>See [https://en.doc.boardgamearena.com/Game_interface_stylesheet:_yourgamename.css X.css] for more information about the style sheet for BGA games.</p></blockquote>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step4-3.png<br> <i>Reloading the game (with a hard refresh).</i></p>
</p></li>
<li><p>Add the following code to the <code>yourgamename.view.php</code> file.</p>
<pre lang="php">// function build_page( $viewArgs ) {
// ...
/*********** Place your code below: ************/

// States that we should start inserting at the 'square' block
// <yourgamename>_<yourgamename> should be replaced with your game name: tstemplatereversi_tstemplatereversi
$this->page->begin_block( "<yourgamename>_<yourgamename>", "square" );

$hor_scale = 64.8; // Constant for square width
$ver_scale = 64.4; // Constant for square height
for( $x=1; $x<=8; $x++ ) // Loop the 8 columns..
{
for( $y=1; $y<=8; $y++ ) // Loop the 8 rows..
{
// Inserts the code found at the square block based on the variables.
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}</pre>
<blockquote><p>See [https://en.doc.boardgamearena.com/Game_layout:_view_and_template:_yourgamename.view.php_and_yourgamename_yourgamename.tpl X.view.php] for more information about the view file for BGA games.</p></blockquote>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step4-4.png<br> <i>Reloading the game (with a hard refresh).</i></p>
</p></li></ol>

<span id="step-5---the-tokens"></span>
== Step 5 - The Tokens ==

<ol style="list-style-type: decimal;">
<li><p>Add the following token image to the <code>img</code> folder of your project. It should be named <code>tokens.png</code> to match the SCSS background-image in the next step.</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/tokens.png</p>
</p></li>
<li><p>Add a template variable to the <code>yourgamename_yourgamename.tpl</code> file to represent the tokens:</p>
<pre lang="html"><div id="board"> ... </div>

<script type="text/javascript">

var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';

</script></pre>
<blockquote><p>Note that this does not have any information that needs to be populated by the server, so this could be directly defined in the TypeScript file.</p></blockquote></li>
<li><p>Add the following SCSS to the <code>yourgamename.scss</code> file to style the tokens:</p>
<pre lang="scss">// Same as square, but matching the token size/image.
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
}
// For clarity, but doesn't actually do anything.
.tokencolor_cbcbcb { background-position: 0px 0px; }
// Translate the background the exact size of the white token, so the black one shows instead.
.tokencolor_363636 { background-position: -56px 0px; }</pre></li>
<li><p>Add a TypeScript function to the <code>yourgamename.ts</code> file to place the tokens on the board. You can hover over any function/property in the TypeScript file to see the documentation and usage.</p>
<pre lang="typescript">///////////////////////////////////////////////////
//// Utility methods

/** Adds a token matching the given player to the board at the specified location. */
addTokenOnBoard( x: number, y: number, player_id: number )
{
let player = this.gamedatas.players[ player_id ];
if (!player)
throw new Error( 'Unknown player id: ' + player_id );

dojo.place( this.format_block( 'jstpl_token', {
x_y: `${x}_${y}`,
color: player.color
} ) , 'board' );

this.placeOnObject( `token_${x}_${y}`, `overall_player_board_${player_id}` );
this.slideToObject( `token_${x}_${y}`, `square_${x}_${y}` ).play();
}</pre>
<blockquote><p>See [https://en.doc.boardgamearena.com/Game_interface_logic:_yourgamename.js X.js] for more information about the script file for BGA games.</p></blockquote></li>
<li><p>For a placeholder, test your tokens by manually placing some in the setup function. you can also remove the boilerplate code.:</p>
<pre lang="typescript">///////////////////////////////////////////////////
//// Game setup

setup(gamedatas: Gamedatas): void
{
console.log( "Starting game setup" );

this.addTokenOnBoard( 2, 2, this.player_id );
this.addTokenOnBoard( 6, 3, this.player_id );

this.setupNotifications(); // <-- Keep this line
}</pre>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step5-4.png<br> <i>Reloading the game (with a hard refresh).</i></p>
</p></li></ol>

<span id="step-6---the-database-and-initial-setup"></span>
== Step 6 - The Database and Initial Setup ==

<ol style="list-style-type: decimal;">
<li><p>Create a database for your board in the <code>dbmodel.sql</code> file:</p>
<pre lang="sql">CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;</pre>
<p>Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL. You can quit and restart your game to see if the file is correct.</p>
<blockquote><p>See [https://en.doc.boardgamearena.com/Game_database_model:_dbmodel.sql dbmodel.sql] for more information about the database file for BGA games.</p></blockquote></li>
<li><p>Setup the board in your <code>yourgamename.game.php</code> file. This is initializing the data in the database and setting the four discs in the center of the board:</p>
<pre lang="php">protected function setupNewGame( $players, $options = array() )
{
//...
$sql .= implode( ',', $values );
self::DbQuery( $sql );
// self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );
self::reloadPlayersBasicInfos();

/************ Start the game initialization *****/
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $whiteplayer_id, $blackplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
// Initial positions of white player
if( ($x==4 && $y==4) || ($x==5 && $y==5) )
$token_value = "'$whiteplayer_id'";
// Initial positions of black player
else if( ($x==4 && $y==5) || ($x==5 && $y==4) )
$token_value = "'$blackplayer_id'";
// Not a starting position
else
$token_value = "NULL";
$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
self::DbQuery( $sql );
//...
}</pre></li>
<li><p>Now we need to send the board information to the client whenever the page is reloaded. In your <code>yourgamename.game.php</code> file, add the following code to the <code>getAllDatas</code> function:</p>
<pre lang="php">protected function getAllDatas()
{
//...
$sql = "SELECT board_x x, board_y y, board_player player
FROM board WHERE board_player IS NOT NULL";
$result['board'] = self::getObjectListFromDB( $sql );
//...
}</pre></li>
<li><p>Add the board data to the <code>Gamedatas</code> interface in the <code>yourgamename.d.ts</code> file:</p>
<pre lang="typescript">interface Gamedatas {
board: { x: number, y: number, player: number }[];
}</pre></li>
<li><p>Add the following to the <code>yourgamename.ts</code> file place the discs at the start of a page load:</p>
<pre lang="typescript">setup(gamedatas: Gamedatas): void
{
console.log( "Starting game setup" );

// Place the tokens on the board
for( let i in gamedatas.board )
{
let square = gamedatas.board[i];

if( square?.player ) // If square is defined and has a player
this.addTokenOnBoard( square.x, square.y, square.player );
}

this.setupNotifications(); // <-- Keep this line
}</pre>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step6-5.png<br> <i>Reloading the game (with a hard refresh).</i></p>
</p></li></ol>

<span id="step-7---game-states"></span>
== Step 7 - Game States ==

<ol style="list-style-type: decimal;">
<li><p>Replace the gamestates.jsonc file with the following:</p>
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/gamestates.schema.json",

// The initial state. Please do not modify.
"1": {
"name": "gameSetup",
"description": "",
"type": "manager",
"action": "stGameSetup",
"transitions": { "": 10 }
},

"10": {
"name": "playerTurn",
"description": "${actplayer} must play a disc",
"descriptionmyturn": "${you} must play a disc",
"type": "activeplayer",
"args": "argPlayerTurn",
"argsType": {
"possibleMoves": "boolean[][]"
},
"possibleactions": {
"playDisc": [
{ "name": "x", "type": "AT_int" },
{ "name": "y", "type": "AT_int" }
]
},
"transitions": {
"playDisc": 11,
"zombiePass": 11
}
},

"11": {
"name": "nextPlayer",
"type": "game",
"action": "stNextPlayer",
"updateGameProgression": true,
"transitions": {
"nextTurn": 10,
"cantPlay": 11,
"endGame": 99
}
},

// Final state.
// Please do not modify (and do not overload action/args methods}.
"99": {
"name": "gameEnd",
"description": "End of game",
"type": "manager",
"action": "stGameEnd",
"args": "argGameEnd",
"argsType": "object"
}
}</pre>
<p>There is a lot of information in this file. Most information can be found in the hover-over tooltips, but the [https://en.doc.boardgamearena.com/Your_game_state_machine:_states.inc.php Game States] page has more information about the concepts.</p>
<blockquote><p>This will automatically be converted to <code>gamestates.inc.php</code>, <code>yourgamename.action.php</code>, and <code>build/gamestates.d.ts</code> when you run <code>npm run build</code>.</p></blockquote></li>
<li><p>Add placeholder functions to remove <code>Undefined method</code> errors. Add the following to your <code>yourgamename.action.php</code> file. Note that this replaces the large section of comments in the file describing the player actions, state arguments, and state actions.</p>
<pre lang="php">// Player actions
function playDisc( int $x, int $y ) {
/* TODO */
}

// Game state arguments
function argPlayerTurn() {
/* TODO */
}

// Game state actions
function stNextPlayer() {
/* TODO */
}</pre></li>
<li><p>Fix the <code>dummmy</code> state errors in your <code>yourgamename.ts</code> file. These are added as a placeholder and now cause issues because there is no gamestate with the name <code>dummmy</code>:</p>
<pre lang="typescript">onEnteringState(stateName: GameStateName, args: CurrentStateArgs): void
{
console.log( 'Entering state: ' + stateName );
}

onLeavingState(stateName: GameStateName): void
{
console.log( 'Leaving state: ' + stateName );
}

onUpdateActionButtons(stateName: GameStateName, args: AnyGameStateArgs | null): void
{
console.log( 'onUpdateActionButtons: ' + stateName, args );
}</pre></li></ol>

<blockquote>You should no longer have any type issues in any of your files.
</blockquote>
When you reload your game (this will cause current games to fail), your should see the banner change to <code>{actplayer} must play a disc</code> or <code>You must play a disc</code>. This will be the only visible change in the game at this point.

<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step7-3.png<br> <i>Reloading the game (with a hard refresh).</i>
</p>
<span id="step-8---game-rules-and-possible-moves"></span>
== Step 8 - Game Rules and Possible Moves ==

There are a couple of variations on the rules for Reversi, but the most common is with <code>outflanking rules</code>. You can see the official rules at [https://www.worldothello.org/about/about-othello/othello-rules/official-rules/ World Othello]. There rules have been implemented with the following utility functions.

<ol style="list-style-type: decimal;">
<li><p>Copy these functions into your <code>yourgamename.game.php</code> file:</p>
<pre lang="php">// Get the complete board with a double associative array
function getBoard()
{
$sql = "SELECT board_x x, board_y y, board_player player FROM board";
return self::getDoubleKeyCollectionFromDB( $sql, true );
}

// Get the list of possible moves (x => y => true)
function getPossibleMoves( $player_id )
{
$result = array();

$board = self::getBoard();

for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$returned = self::getTurnedOverDiscs( $x, $y, $player_id, $board );
if( count( $returned ) == 0 )
{
// No discs returned => not a possible move
}
else
{
// Okay => set this coordinate to "true"
if( ! isset( $result[$x] ) )
$result[$x] = array();

$result[$x][$y] = true;
}
}
}

return $result;
}

// Get the list of returned disc when "player" we play at this place ("x", "y"),
// or a void array if no disc is returned (invalid move)
function getTurnedOverDiscs( $x, $y, $player, $board )
{
$turnedOverDiscs = array();

if( $board[ $x ][ $y ] === null ) // If there is already a disc on this place, this can't be a valid move
{
// For each directions...
$directions = array(
array( -1,-1 ), array( -1,0 ), array( -1, 1 ), array( 0, -1),
array( 0,1 ), array( 1,-1), array( 1,0 ), array( 1, 1 )
);

foreach( $directions as $direction )
{
// Starting from the square we want to place a disc...
$current_x = $x;
$current_y = $y;
$bContinue = true;
$mayBeTurnedOver = array();

while( $bContinue )
{
// Go to the next square in this direction
$current_x += $direction[0];
$current_y += $direction[1];

if( $current_x<1 || $current_x>8 || $current_y<1 || $current_y>8 )
$bContinue = false; // Out of the board => stop here for this direction
else if( $board[ $current_x ][ $current_y ] === null )
$bContinue = false; // An empty square => stop here for this direction
else if( $board[ $current_x ][ $current_y ] != $player )
{
// There is a disc from our opponent on this square
// => add it to the list of the "may be turned over", and continue on this direction
$mayBeTurnedOver[] = array( 'x' => $current_x, 'y' => $current_y );
}
else if( $board[ $current_x ][ $current_y ] == $player )
{
// This is one of our disc

if( count( $mayBeTurnedOver ) == 0 )
{
// There is no disc to be turned over between our 2 discs => stop here for this direction
$bContinue = false;
}
else
{
// We found some disc to be turned over between our 2 discs
// => add them to the result and stop here for this direction
$turnedOverDiscs = array_merge( $turnedOverDiscs, $mayBeTurnedOver );
$bContinue = false;
}
}
}
}
}

return $turnedOverDiscs;
}</pre></li>
<li><p>Add the list of possible moves to the <code>argPlayerTurn</code> function in your <code>yourgamename.action.php</code> file:</p>
<pre lang="php">function argPlayerTurn()
{
$possibleMoves = self::getPossibleMoves( self::getActivePlayerId() );
return array(
'possibleMoves' => $possibleMoves
);
}</pre></li>
<li><p>Add a css class to represent the possible moves in your <code>yourgamename.scss</code> file:</p>
<pre lang="scss">.possibleMove {
background-color: rgba(255, 255, 255, 0.15);
cursor: pointer;
transition: 100ms;
}

.possibleMove:hover {
background-color: rgba(255, 255, 255, 0.3);
}</pre></li>
<li><p>Add the possible moves to the board when entering a new state by adding the following to your <code>yourgamename.ts</code> file:</p>
<pre lang="typescript">// Utility methods

/** Removes the 'possibleMove' class from all elements. */
clearPossibleMoves() {
document.querySelectorAll('.possibleMove').forEach(element => {
element.classList.remove('possibleMove');
});
}

/** Updates the squares on the board matching the possible moves. */
updatePossibleMoves( possibleMoves: boolean[][] )
{
this.clearPossibleMoves();

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
let square = $(`square_${x}_${y}`);
if( !square )
throw new Error( `Unknown square element: ${x}_${y}. Make sure the board grid was set up correctly in the tpl file.` );
square.classList.add('possibleMove');
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
}

// Game & client states

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

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args!.possibleMoves );
break;
}
}</pre>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step8-4.png<br> <i>Reloading the game (with a hard refresh).</i></p>
</p></li></ol>

The game is still not playable, but you can now see the possible moves for the first turn.

<span id="step-9---player-actions"></span>
== Step 9 - Player Actions ==

<ol style="list-style-type: decimal;">
<li><p>Fill in the <code>playDisc</code> function in your <code>yourgamename.action.php</code> file:</p>
<pre lang="php">function playDisc( int $x, int $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );

// Now, check if this is a possible move
$board = self::getBoard();
$player_id = self::getActivePlayerId();
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) <= 0 )
throw new BgaSystemException( "Impossible move" );

// This move is possible!

// Let's place a disc at x,y and return all "$returned" discs to the active player
$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";
foreach( $turnedOverDiscs as $turnedOver )
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
$sql .= "('$x','$y') ) ";

self::DbQuery( $sql );

// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
self::DbQuery( $sql );

// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}</pre></li>
<li><p>Fill in the <code>stNextPlayer</code> function in your <code>yourgamename.action.php</code> file:</p>
<pre lang="php">function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

// Check if both player has at least 1 discs, and if there are free squares to play
$sql = "SELECT board_player, COUNT( board_x ) FROM board
GROUP BY board_player";
$player_to_discs = self::getCollectionFromDb( $sql, true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = self::getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{
// This player can't play
// Can his opponent play ?
$opponent_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( self::getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}
}</pre></li>
<li><p>Connect an <code>onclick</code> function to all of the squares on the board:</p>
<p>```typescript setup(gamedatas: Gamedatas): void { // … dojo.query( ‘.square’ ).connect( ‘onclick’, this, ‘onPlayDisc’ ); // … }</p></li>
<li><p>Add the <code>onPlayDisc</code> function to your <code>yourgamename.ts</code> file:</p>
<pre lang="typescript">// Player's action

/** Called when a square is clicked, check if it is a possible move and send the action to the server. */
onPlayDisc( evt: Event )
{
// Stop this event propagation
evt.preventDefault();

if (!(evt.currentTarget instanceof HTMLElement))
throw new Error('evt.currentTarget is null! Make sure that this function is being connected to a DOM HTMLElement.');

// Check if this is a possible move
if( !evt.currentTarget.classList.contains('possibleMove') )
return;

// Check that this action is possible at this moment (shows error dialog if not possible)
if( !this.checkAction( 'playDisc' ) )
return;

// Get the clicked square x and y
// Note: square id format is "square_X_Y"
let [_square_, x, y] = evt.currentTarget.id.split('_');

this.ajaxcall( `/${this.game_name}/${this.game_name}/playDisc.html`, {
x, y, lock: true
}, this, function() {} );
}</pre></li></ol>

Now you should be able to play the game! However, you will need to reload the game after every move to force the board to update.

<span id="step-10---notifications"></span>
== Step 10 - Notifications ==

Notifications are used to inform players when something happens in the game. In our case, we only need to send one notification stating when the player has played a disc; however, it is often much more useful to send the notifications as a sequence of events so they can be automatically sequenced in the client. In this case, we will send three notifications:=, all of which can be sent from the player action function: - When a player plays a disc - When discs are converted because of a move - When the scores

<ol style="list-style-type: decimal;">
<li><p>Add the following to the <code>playDisc</code> function in your <code>yourgamename.action.php</code> file:</p>
<pre lang="php">function playDisc( int $x, int $y )
{
// ...

// Notify
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

self::notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );

// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}</pre></li>
<li><p>Add the notifications to your <code>NotifTypes</code> interface in the <code>yourgamename.d.ts</code> file:</p>
<pre lang="typescript">interface NotifTypes {
'playDisc': { x: number, y: number, player_id: number };
'turnOverDiscs': {
player_id: number,
turnedOver: { x: number, y: number }[]
},
'newScores': { scores: Record<number, number> };
}</pre></li>
<li><p>Add the following to your <code>yourgamename.ts</code> file to listen and handle the notifications:</p>
<pre lang="typescript">setupNotifications()
{
console.log( 'notifications subscriptions setup' );

dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1000 );
dojo.subscribe( 'newScores', this, "notif_newScores" );
this.notifqueue.setSynchronous( 'newScores', 500 );
}

notif_playDisc( notif: NotifAs<'playDisc'> )
{
this.clearPossibleMoves();
this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
}

notif_turnOverDiscs( notif: NotifAs<'turnOverDiscs'> )
{
// Change the color of the turned over discs
for( var i in notif.args.turnedOver )
{
let token_data = notif.args.turnedOver[ i ]!;
let token = $<HTMLElement>( `token_${token_data.x}_${token_data.y}` );

if (!token)
throw new Error( `Unknown token element: ${token_data.x}_${token_data.y}. Make sure the board grid was set up correctly in the tpl file.` );

token.classList.toggle('tokencolor_cbcbcb');
token.classList.toggle('tokencolor_363636');
}
}

notif_newScores( notif: NotifAs<'newScores'> )
{
for( var player_id in notif.args.scores )
{
let counter = this.scoreCtrl[ player_id ];
let newScore = notif.args.scores[ player_id ];
if (counter && newScore)
counter.toValue( newScore );
}
}</pre></li>
<li><p>(optional) Add a flipping animation to the token when the classes:</p>
<p>''yourgamename_yourgamename.tpl'' <code>html // Updated token template var jstpl_token = '<div class="token-container tokencolor_${color}" id="token_${x_y}"><div class="token-flip"><div class="token-white"></div><div class="token-black"></div></div></div>';</code></p>
<p>''yourgamename.scss'' ```scss .token-container { background-color: transparent; width: 56px; height: 56px; perspective: 250px; position: absolute; }</p>
<p>.token-flip { position: relative; width: 100%; height: 100%; text-align: center; transition: transform 1.2s; transform-style: preserve-3d; border-radius:50%; box-shadow: 0 4px 8px 0 rgba(0,0,0,0.25); }</p>
<p>.tokencolor_363636 > .token-flip { transform: rotateY(180deg); }</p>
<p>.token-white, .token-black { position: absolute; width: 100%; height: 100%; -webkit-backface-visibility: hidden; backface-visibility: hidden; background-image: url(“img/tokens.png”); }</p>
<p>.token-white { background-position: 0px 0px; }</p>
<p>.token-black { background-position: -56px 0px; transform: rotateY(180deg); } ```</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step10-4.gif</p>
</p></li></ol>

At this point, you now have a fully functional game that can be played on BGA. The following steps are to add flurishes and additional features to the game.

<span id="optional-step-11---statistics"></span>
== (optional) Step 11 - Statistics ==

Statistics are mostly optional and are a fun way to compare player strategies or how much they have played the game.

<ol style="list-style-type: decimal;">
<li><p>Replace the contents of <code>shared/stats.jsonc</code> with the following:</p>
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/stats.schema.json",
// All of these stats are tracked per player
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}</pre>
<blockquote><p>See [https://en.doc.boardgamearena.com/Game_statistics:_stats.json stats.json] for more information about the stats file for BGA games.</p></blockquote></li>
<li><p>Add the following to the <code>playDisc</code> function in your <code>yourgamename.action.php</code> file:</p>
<pre lang="php">function playDisc( int $x, int $y )
{
//...
// Update scores...

// Statistics
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
self::incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
self::incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
self::incStat( 1, 'discPlayedOnCenter', $player_id );

// Notify...
}</pre></li>
<li><p>Reload the statistics configuration on the manage game page. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-3---game-information--metadata Step 3.3] for more information.</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/game_configuration.png</p>
</p></li>
<li><p>Play a game and verify that your new statistics are visible at the end of the game:</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step11-3.png</p>
</p></li></ol>

<span id="optional-step-12---game-options"></span>
== (Optional) Step 12 - Game Options ==

Game options are a way for users to change game behavior or rules. As an example, we will be adding another rule variant called “Reversi Bombs” that flips all 8 adjacent discs when a disc is played.

<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/reversi_bombs_rules.png
</p>
<ol style="list-style-type: decimal;">
<li><p>Replace your gameoptions with the following in the <code>shared/gameoptions.jsonc</code> file:</p>
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/gameoptions.schema.json",

"100": {
"name": "Variant",
"values": {
// This is the current rule set we have implemented
"1": {
"name": "Standard",
"description": "Flip all outflanked discs."
},
"2": {
"name": "Reversi Bombs",
"description": "Flip all 8 adjacent discs."
}
}
}
}</pre>
<blockquote><p>See [https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json gameoptions.json] for more information about the options file for BGA games.</p></blockquote></li>
<li><p>Modify the <code>getTurnedOverDiscs</code> function in your <code>yourgamename.game.php</code> file to handle the new game option:</p>
<pre lang="php">function getTurnedOverDiscs( $x, $y, $player, $board )
{
//...

foreach( $directions as $direction )
{
// If game option '100' is set to 2 (reversi bombs)
if ($this->gamestate->table_globals[100] == 2)
{
$current_x = $x + $direction[0];
$current_y = $y + $direction[1];
if( $current_x<1 || $current_x>8 || $current_y<1 || $current_y>8 )
continue; // Out of the board => stop here for this direction

if ($board[ $current_x ][ $current_y ] !== null)
// push the disc to be turned over
$turnedOverDiscs[] = array( 'x' => $current_x, 'y' => $current_y );

continue; // Don't do standard game logic
}
// Standard...
}

//...
}</pre></li>
<li><p>Fix the <code>playDisc</code> function to flip all turned disc instead of setting them to the active player:</p>
<pre lang="php">// Let's place a disc at x,y and return all "$returned" discs to the active player
$other_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id'" );
$sql = "UPDATE board SET board_player = CASE WHEN board_player = '$player_id' THEN '$other_id' ELSE '$player_id' END WHERE (board_x, board_y) IN (";
foreach( $turnedOverDiscs as $turnedOver )
//...</pre></li>
<li><p>Reload the game options from within the game manager page. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-3---game-information--metadata Step 3.3] for more information.</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/game_configuration.png</p>
</p></li></ol>

<p align="center">
https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step12-4.gif
</p>
<span id="user-preferences"></span>
== User Preferences ==

User preferences is something cosmetic about the game interface which you want users to be able to controll. Reversi has a classic athstetic, but in this example, we will add a user preference to change the color of the board. This is not a great use case for user preferences, but it is a simple example.

<ol style="list-style-type: decimal;">
<li><p>Replace the contents of <code>shared/gamepreferences.jsonc</code> with the following:</p>
<pre lang="json">{
"$schema": "../../node_modules/bga-ts-template/schema/gamepreferences.schema.json",
"101": {
"name": "Game Style",
"needReload": true,
"values": {
"1": {
"name": "Classic",
"cssPref": "game_style_classic"
},
"2": {
"name": "Wooden",
// Then this is added to the page, we will override the image urls in the css.
"cssPref": "game_style_wooden"
}
},
"default": 1
}
}</pre>
<blockquote><p>See [https://en.doc.boardgamearena.com/Options_and_preferences:_gameoptions.json,_gamepreferences.json gamepreferences.json] for more information about the options file for BGA games.</p></blockquote></li>
<li><p>Download the following images and add them to your <code>img</code> folder. They should be named ‘wooden_board.jpg’ and ‘wooden_tokens.png’.</p>
<table align="center" width="50%">
<tr>
<td>
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/wooden_board.jpg</p>
</td>
<td>
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/assets/wooden_tokens.png</p>
</td>
</tr>
</table></li>
<li><p>Add the following to your <code>yourgamename.scss</code> file to change the board and token images:</p>
<pre lang="scss">// This overrides the #board + .token- images when the .game_style_wooden is automatically added to the page (by the user preference).
.game_style_wooden {
#board {
background-image: url('img/wooden_board.jpg');
}
.token-white, .token-black {
background-image: url('img/wooden_tokens.png');
}
}</pre></li>
<li><p>Refresh the game options in the game manager page. See [https://github.com/NevinAF/bga-ts-template/blob/main/docs/tutorials/index.md#step-3---game-information--metadata Step 3.3] for more information.</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/game_configuration.png</p>
</p></li>
<li><p>Reload the game and change the user preference to see the new board and token images:</p>
<p align="center">
<p>https://github.com/NevinAF/bga-ts-template/tree/main/docs/tutorials/img/reversi/step13-5.gif</p>
</p></li></ol>

Studio

2024-04-12T13:45:29Z

NevinAF: Fixed redirect on bga type safe template

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.

__TOC__

== What is Board Game Arena Studio? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptations using the Board Game Arena platform.

It is open to any gamer with software development skills :)

BGA Studio website: https://studio.boardgamearena.com

Original announcement on BGA forum: https://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game] (or [http://en.doc.boardgamearena.com/images/5/58/1-why-developing.pdf ‎Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena] (or [http://en.doc.boardgamearena.com/images/1/1e/2-8-steps-to-realize.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] (or [http://en.doc.boardgamearena.com/images/7/79/3-thebgaframework.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine] (or [http://en.doc.boardgamearena.com/images/9/98/4-gamestates.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] (or [http://en.doc.boardgamearena.com/images/7/76/5-guidelines.pdf ‎Download as PDF])

== How to join the BGA developer team? ==

Please see this page: [[How to join BGA developer team?]]

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.

After that, we strongly advise you to take one of these game creation tutorials:
* [[Tutorial reversi]] - an abstract strategy game played on an 8×8 uncheckered board for 2 players
* [[Tutorial gomoku]] - an abstract strategy game tic-tac-toe style for 2 players
* [[Tutorial hearts]] - a card game for 4 players

Then start editing files and see what happens! ;)

Once you're done with tutorials, you can start a real game (or join existing project)
* [[Create a game in BGA Studio: Complete Walkthrough]]

If you have any questions, please check out the [[Studio FAQ]] or [[Contact BGA Studio]].

To search wiki pages on studio enter this text in search bar:
"Category:Studio" white rabbit
That is if you want to search for white rabbit

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

This part of the documentation focuses on the development framework itself: functions and methods available to build your game.

[[Studio file reference|File structure of a BGA game]]

==== Game logic (Server side) ====

* [[Main game logic: yourgamename.game.php]]
* [[Your game state machine: states.inc.php]]
* [[Game database model: dbmodel.sql]]
* [[Players actions: yourgamename.action.php]]
* [[Game material description: material.inc.php]]
* [[Game statistics: stats.inc.php]]

==== Game interface (Client side) ====

* [[Game interface logic: yourgamename.js]]
* [[Game art: img directory]]
* [[Game interface stylesheet: yourgamename.css]]
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]
* [[Your game mobile version]]

==== Other components ====

* [[Translations]] (how to make your game translatable)
* [[Game options and preferences: gameoptions.inc.php]]
* [[Game meta-information: gameinfos.inc.php]]
* [[Game replay]]
* [[3D]]

=== BGA Studio game components reference ===

Game components are useful tools you can use in your game adaptations.

JS:

* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Anti-Stock]]:Code snippets in ValinaJS/HTML5 to do what stock does (that is if you cannot beat Stock into submission)

PHP:
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).

Reference for classes in game class hierarchy

* [[Table]]: a PHP class that you inherit from for the game php

=== BGA Studio user guide ===

This part of the documentation is a user guide for the BGA Studio online development environment.

Lifecycle

* [[BGA game Lifecycle]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Pre-release checklist]] - Go throught this list if you think you done development
* [[Post-release phase]]

Tools and Advice
* [[BGA Studio Guidelines]]
* [[Tutorials checklist]]
* [[I wish I knew this when I started]] - one liners on most common missed features, mistakes, etc with further doc references
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
** [[Setting up BGA Development environment using VSCode]]
** [[Practical debugging]] - Tips focused on debugging
** [[Testing by developer]]
** [[Studio logs]] - Instructions for log access
** [[Troubleshooting]] - Most common "I am really stuck" situations
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
** [[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
** [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
** [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner
** [[Bots and Artificial Intelligence]] - How to add AI/Bots to the game
* [[Studio FAQ]]

Sharing
* [[Common board game elements image resources]] - Dice, meeples, cubes, etc
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links

== Software Versions ==

Versions currently used by BGA framework:

* Dojo Toolkit 1.15
* PHP: 7.4 (8.2 on studio - choice in control panel, also see announcement on forum)
* SQL: MySQL 5.7
* JS/CSS/HTML: limited by what minimization tools support [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29]]
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/ (available as <code><nowiki><i class="fa fa-clock" /></nowiki></code>)
* Font Awesome: 6.4.0 https://fontawesome.com/v6/search?o=r&m=free (available as <code><nowiki><i class="fa6 fa6-clock" /></nowiki></code>)

=== PHP Extensions Used ===

The following PHP extensions are - as of May 8th, 2022 - in use in BGA Studio and available:

date, libxml, openssl, pcre, zlib, filter, hash, Reflection, SPL, session, standard, sodium, apache2handler, mysqlnd, PDO, xml, apcu, bz2, calendar, ctype, curl, dom, mbstring, FFI, fileinfo, ftp, gd, gettext, gmp, iconv, igbinary, json, exif, msgpack, mysqli, pdo_mysql, apc, posix, readline, shmop, SimpleXML, sockets, sysvmsg, sysvsem, sysvshm, tokenizer, v8js, xmlreader, xmlwriter, xsl, zip, Phar, memcached, Zend OPcache

== Other resources ==

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]

DISCORD chat server/room invite link https://discord.gg/YxEUacY if it does not work check this topic https://forum.boardgamearena.com/viewtopic.php?f=12&t=17403&hilit=discord

Developer BLOGS https://bga-devs.github.io/blog/

[[Contact BGA Studio]]

[[Category:Studio]]

BGA-ts-template

2024-04-12T13:43:23Z

NevinAF: NevinAF moved page BGA-ts-template to BGA Type Safe Template: Cleaner and more clear

#REDIRECT [[BGA Type Safe Template]]

BGA Studio Cookbook

2024-04-11T21:15:12Z

NevinAF: /* Frameworks and Preprocessors */

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

__TOC__

== Visual Effects, Layout and Animation ==

=== DOM manipulatons ===

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

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

Note: this method is recommended by BGA guildlines

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

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

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

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

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

'''Ingredients:''' ggg.js

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

or modern way

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

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

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

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

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

ggg.css:

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

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

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

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

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

=== Animation ===

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

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

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

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

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

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

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

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

The code is bit complex it can be found here

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

Game using it: century, ultimaterailroads

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

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

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

=== Logs ===

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

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

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

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

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

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

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

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

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

This is a bad idea for many reasons:

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

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

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

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

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

[[File:clientloginjection.png|left]]

ggg.js

<pre>

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

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

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

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

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

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

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

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

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

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

default:
break;
}

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

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

ggg.game.php:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

=== Player Panel ===

==== Inserting non-player panel ====

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

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

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

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

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

some hackery required in js

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

=== Images and Icons ===

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

'''Ingredients:''' ggg.js

<pre>
// your game resources

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

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

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

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

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

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

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

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

where ${color} - is color you want

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

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

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

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

return avatarURL;
},
</pre>

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

==== Adding Image buttons ====

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

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

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

=== Other Fluff ===

==== Use thematic fonts ====

'''Ingredients:''' ggg.css

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

[[File:Dragonline_font.png]]

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

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

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

===== Content Security Policy =====

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

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

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

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

=== Use player color in template ===

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

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

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

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

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

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

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

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

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

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

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

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

=== Dynamic tooltips ===

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

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

==== Rectangles and circles ====

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

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

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

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

==== Irregular Shapes ====

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

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

For instance:

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

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

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

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

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

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

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

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

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

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

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

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

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

== Game Model and Database design ==

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

[[File:Madeira board.png]]

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

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

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

Variant 1: Minimalistic

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

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

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

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

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

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

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

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

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

Variant 3: More normalised

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

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

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

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

=== Database for The card game ===

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

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

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

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

Variant 1: Minimalistic

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

Variant 2: More normalised

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

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

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

== Code Organization ==

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

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

});

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

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

use it

foo = new bgagame.other();

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

* Create ggg_other.js in modules/ folder and sync

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

* Modify ggg.js to include it

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

});

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

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

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

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

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

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

require_once ('modules/ggg_other.php');

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

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

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

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

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

</pre>

Run from command line like
php7 ggg_test.php

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

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

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

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

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

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

</pre>

=== More readable JS: onEnteringState ===

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

<pre>

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

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

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

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

</pre>

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

=== Frameworks and Preprocessors ===

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

== Assorted Stuff ==

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

'''Ingredients:''' ggg.js

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

So lets do Select Worker/Place Worker

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

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

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

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

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

Action stack required where game is very complex and use triggered effects that can "stack". It not always actual stack, it can be queue or random access
Examples:
* Magic the Gathering - classic card game where effects go on Stack, that allows to counter spell and counter spell of counter spell (not on bga - it just example of mechanics)
* Ultimate Railroads - action taking game where effects can be executed in any order
* Lewis and Clark - card game where actions executed as queue

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

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

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

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

See definition of Action Stack above.

To implement you usually need another db table that has the following fields: index of effect - which is used for sorted access, type - which is essense of the effect (i.e. collect resource), some extra arguments (i.e. resource type and resource count), and usually owner of the effect (i.e. player id)
The flow is:
* There is some initial player state, where player can play card for example
* Player main action - pushes the card effect on stack, which also can cause triggered effects which also go on stack
* After action processing is finished switch to game state which is "dispatcher"
* Dispatcher pulls the top effect (whatever definition of the top is), changes the active player and changes the state to appropriate player state to collect response
* 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.

=== Changing state prompt ===

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

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

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

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

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

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

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

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

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

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

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

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

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

'''Ingredients:''' ggg.js

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

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

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

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

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

'''Ingredients:''' ggg.php

Hack alert. This is a hack.

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

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

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

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

=== Ajax Call wrapper ===
'''Ingredients:''' ggg.js

The current ajaxcall is super vebose and prone to errors, I suggest using a helper function. It does a lot of stuff you must do anyways.
Most beginner mistakes come from missing part of this code (which is understandstandable - this is a huge snippet to clone every time).

<pre>
ajaxcallwrapper: function(action, args, handler) {
if (!args) args = {}; // this allows to skip args parameter for action which do not require them

args.lock = true; // this allows to avoid rapid action clicking which can cause race condition on server
if (this.checkAction(action)) { // this does all the proper check that player is active and action is declared
this.ajaxcall("/" + this.game_name + "/" + this.game_name + "/" + action + ".html", args, // this is mandatory fluff
this, (result) => { }, // success result handler is empty - it is never needed
handler); // this is real result handler - it called both on success and error, it has optional param "is_error" - you rarely need it
}
},
</pre>

Usage:
<pre>
this.ajaxcallwrapper('pass'); // no args
this.ajaxcallwrapper('playCard', {card: card_id}); // with args
this.ajaxcallwrapper('playCard', {card: card_id}, (is_error)=>{if (!is_error) dojo.query(".selected").removeClass('selected');}) // with handler that cleans up 'selected' class on success
</pre>

Note: this always will lock interface and always check for action, you can modify this method to do it optionally, i.e replace 'args.lock = true;' in the code above with this
if (args.lock!==false) args.lock = true; else delete args.lock; // it does not work with false value - it has to be removed

=== Custom error/exception handling in JavaScript ===

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

=== Local Storage ===

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

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

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

== Algorithms ==

=== Generate permutations in lexicographic order ===

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

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

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

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

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

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

[[Category:Studio]]

Studio

2024-04-11T20:49:41Z

NevinAF: Added the BGA Type safe template to the tips/tools

{{Studio_Framework_Navigation}}

[[File:Bga_studio_small.jpg]]

Note: Please DO NOT translate Studio Documentation, so that there can be one place where you can find the latest information available.

__TOC__

== What is Board Game Arena Studio? ==

'''Board Game Arena Studio''' is a platform to build online board game adaptations using the Board Game Arena platform.

It is open to any gamer with software development skills :)

BGA Studio website: https://studio.boardgamearena.com

Original announcement on BGA forum: https://forum.boardgamearena.com/viewtopic.php?f=10&t=1973

== Discover BGA Studio in 5 presentations ==

Why, how, what... to start discovering BGA Studio, we prepared 5 "powerpoint" presentations for you:

* [http://www.slideshare.net/boardgamearena/5-reasons-why-you-should-use-bga-studio-for-your-online-board-game 5 reasons why you should use BGA Studio for your online board game] (or [http://en.doc.boardgamearena.com/images/5/58/1-why-developing.pdf ‎Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-8-steps-to-create-a-board-game-on-board-game-arena The 8 steps to create a board game on Board Game Arena] (or [http://en.doc.boardgamearena.com/images/1/1e/2-8-steps-to-realize.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/the-bga-framework-at-a-glance The BGA Framework at a glance] (or [http://en.doc.boardgamearena.com/images/7/79/3-thebgaframework.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine] (or [http://en.doc.boardgamearena.com/images/9/98/4-gamestates.pdf Download as PDF])
* [http://www.slideshare.net/boardgamearena/bga-studio-guidelines BGA developers guidelines] (or [http://en.doc.boardgamearena.com/images/7/76/5-guidelines.pdf ‎Download as PDF])

== How to join the BGA developer team? ==

Please see this page: [[How to join BGA developer team?]]

== Great, I'm in! ... How should I start? ==

If you didn't already, check the presentations at the top of this page to get the basics.

Then, you should checkout the [[First steps with BGA Studio]] to make sure that runs fine.

After that, we strongly advise you to take one of these game creation tutorials:
* [[Tutorial reversi]] - an abstract strategy game played on an 8×8 uncheckered board for 2 players
* [[Tutorial gomoku]] - an abstract strategy game tic-tac-toe style for 2 players
* [[Tutorial hearts]] - a card game for 4 players

Then start editing files and see what happens! ;)

Once you're done with tutorials, you can start a real game (or join existing project)
* [[Create a game in BGA Studio: Complete Walkthrough]]

If you have any questions, please check out the [[Studio FAQ]] or [[Contact BGA Studio]].

To search wiki pages on studio enter this text in search bar:
"Category:Studio" white rabbit
That is if you want to search for white rabbit

== BGA Studio documentation ==

=== BGA Studio Framework reference ===

This part of the documentation focuses on the development framework itself: functions and methods available to build your game.

[[Studio file reference|File structure of a BGA game]]

==== Game logic (Server side) ====

* [[Main game logic: yourgamename.game.php]]
* [[Your game state machine: states.inc.php]]
* [[Game database model: dbmodel.sql]]
* [[Players actions: yourgamename.action.php]]
* [[Game material description: material.inc.php]]
* [[Game statistics: stats.inc.php]]

==== Game interface (Client side) ====

* [[Game interface logic: yourgamename.js]]
* [[Game art: img directory]]
* [[Game interface stylesheet: yourgamename.css]]
* [[Game layout: view and template: yourgamename.view.php and yourgamename_yourgamename.tpl]]
* [[Your game mobile version]]

==== Other components ====

* [[Translations]] (how to make your game translatable)
* [[Game options and preferences: gameoptions.inc.php]]
* [[Game meta-information: gameinfos.inc.php]]
* [[Game replay]]
* [[3D]]

=== BGA Studio game components reference ===

Game components are useful tools you can use in your game adaptations.

JS:

* [[Counter]]: a JS component to manage a counter that can increase/decrease (ex: player's score).
* [[Scrollmap]]: a JS component to manage a scrollable game area (useful when the game area can be infinite. Examples: Saboteur or Takenoko games).
* [[Stock]]: a JS component to manage and display a set of game elements displayed at a position.
* [[Zone]]: a JS component to manage a zone of the board where several game elements can come and leave, but should be well displayed together (See for example: token's places at Can't Stop).
* [[Draggable]]: a JS component to manage drag'n'drop actions.
* [[ExpandableSection]]: a JS component to manage a rectangular block of HTML than can be displayed/hidden.
* [[Anti-Stock]]:Code snippets in ValinaJS/HTML5 to do what stock does (that is if you cannot beat Stock into submission)

PHP:
* [[Deck]]: a PHP component to manage cards (deck, hands, picking cards, moving cards, shuffle deck, ...).

Reference for classes in game class hierarchy

* [[Table]]: a PHP class that you inherit from for the game php

=== BGA Studio user guide ===

This part of the documentation is a user guide for the BGA Studio online development environment.

Lifecycle

* [[BGA game Lifecycle]]
* [[Create a game in BGA Studio: Complete Walkthrough]]
* [[Pre-release checklist]] - Go throught this list if you think you done development
* [[Post-release phase]]

Tools and Advice
* [[BGA Studio Guidelines]]
* [[Tutorials checklist]]
* [[I wish I knew this when I started]] - one liners on most common missed features, mistakes, etc with further doc references
* [[Tools and tips of BGA Studio]] - Tips and instructions on setting up development environment
** [[Setting up BGA Development environment using VSCode]]
** [[Practical debugging]] - Tips focused on debugging
** [[Testing by developer]]
** [[Studio logs]] - Instructions for log access
** [[Troubleshooting]] - Most common "I am really stuck" situations
* [[BGA Studio Cookbook]] - Tips and instructions on using API's, libraries and frameworks
** [[BGA-ts-template|BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
** [[Using Vue]] - work-in-progress guide on using the modern framework Vue.js to create a game
** [[Using Typescript and Scss]] - How to auto-build Typescript and SCSS files to make your code cleaner
** [[Bots and Artificial Intelligence]] - How to add AI/Bots to the game
* [[Studio FAQ]]

Sharing
* [[Common board game elements image resources]] - Dice, meeples, cubes, etc
* [[BGA Code Sharing]] - Shared resources, projects on git hub, common code, other links

== Software Versions ==

Versions currently used by BGA framework:

* Dojo Toolkit 1.15
* PHP: 7.4 (8.2 on studio - choice in control panel, also see announcement on forum)
* SQL: MySQL 5.7
* JS/CSS/HTML: limited by what minimization tools support [[Game_interface_logic:_yourgamename.js#Javascript_minimization_.28after_July_2020.29]]
* Font Awesome: 4.7 https://fontawesome.com/v4.7/icons/ (available as <code><nowiki><i class="fa fa-clock" /></nowiki></code>)
* Font Awesome: 6.4.0 https://fontawesome.com/v6/search?o=r&m=free (available as <code><nowiki><i class="fa6 fa6-clock" /></nowiki></code>)

=== PHP Extensions Used ===

The following PHP extensions are - as of May 8th, 2022 - in use in BGA Studio and available:

date, libxml, openssl, pcre, zlib, filter, hash, Reflection, SPL, session, standard, sodium, apache2handler, mysqlnd, PDO, xml, apcu, bz2, calendar, ctype, curl, dom, mbstring, FFI, fileinfo, ftp, gd, gettext, gmp, iconv, igbinary, json, exif, msgpack, mysqli, pdo_mysql, apc, posix, readline, shmop, SimpleXML, sockets, sysvmsg, sysvsem, sysvshm, tokenizer, v8js, xmlreader, xmlwriter, xsl, zip, Phar, memcached, Zend OPcache

== Other resources ==

[http://forum.boardgamearena.com/viewforum.php?f=12 Development forum]

[https://studio.boardgamearena.com/bugs Bug tracking system FOR STUDIO issues and APIs]

DISCORD chat server/room invite link https://discord.gg/YxEUacY if it does not work check this topic https://forum.boardgamearena.com/viewtopic.php?f=12&t=17403&hilit=discord

Developer BLOGS https://bga-devs.github.io/blog/

[[Contact BGA Studio]]

[[Category:Studio]]

Tutorial reversi

2024-04-11T20:43:27Z

NevinAF: Added a redirect note to the top of the page leading to the type-safe template tutorial for reversi

'''Check out an update version''' of the Reversi Tutorial: [[BGA-ts-template Reversi]] which uses the [[BGA-ts-template|BGA Type Safe Template]]. {{Studio_Framework_Navigation}}

== Introduction ==

Using this tutorial, you can build a complete working game on the BGA environment: Reversi.

Before you read this tutorial, you must:
* Read the overall presentations of the BGA Framework ([[Studio|see here]]).
* Know the [http://en.wikipedia.org/wiki/Reversi#Rules rules of Reversi].
* Know the languages used on BGA: PHP, SQL, HTML, CSS, Javascript
* '''Setup your development environment''' [http://en.doc.boardgamearena.com/First_steps_with_BGA_Studio First Steps with BGA Studio]

== Create your first game ==

''Note: you should already have created a project following instructions in [[First_steps_with_BGA_Studio#Create_a_new_game_project|Create a new game project]]. While you will find a '''reversi''' directory in your SFTP folder, do not use it for this tutorial. Instead, use the project you have created as an (empty) starting point.''

With the initial skeleton of code provided in your project, you can already start a game from the BGA Studio:
* Go to your [https://studio.boardgamearena.com/controlpanel studio Control panel], then Manage games and select your initial project. ''Note: there are warnings displayed about a missing BGG_ID and presentation text. You can ignore that for now.''
* Click the Play link next to your project name. This will open the Play page and offer to create a new table for your project. ''Optional: click the Heart icon to add your project to your favorite games list.''
* On the Play page, on the top of the page, make sure that your settings are "Simple game", "Real time" and "Manual".
* Click "Create table" to create a table of your project.
* For now, we are going to work with one player only, so use the (-) button to set the number of players to 1. Most of the time it is simpler to proceed with only one player during the early phase of development of your game, as it's easy and fast to start/stop games. If you choose to start with 2 players, you should see two names on the right: testdude0 and testdude1. To switch between them, press the red arrow button near their names; it will open another tab. This way you don't need to login and logout from multiple accounts.)
* Reminder: Always use the "Express Start" button to start the game.

Thus, you can start a "Reversi" game, and arrive on a void, empty game. Yeah.

End the game by clicking on the game options icon on the top right, and then on "Express Stop".

== Editing the game information (Optional) ==

This step is optional and will fix the warnings on the project page (missing BGG_ID and presentation).

==== Edits to fix Errors ====
* Edit your local copy of the gameinfos.inc.php file:
** Change the <code>bgg_id</code> value from <code>0</code> to <code>2389</code> - that's around line 37.
** Add <code>1,</code> to the players array - that's around line 41.
** Change the presentation array content - that's around line 134. Uncomment one line and change the text. Remove the final comma if you keep only one line!
* Upload the <code>gameinfos.inc.php</code> file to the SFTP server (see [[First_steps_with_BGA_Studio#Connect_to_your_SFTP_folder|Connect to your SFTP folder]]).

==== Test your Edits ====
* Go back to your project page, and in the "Game Information" section, click "Reload game informations".
* Finally, refresh the project page in your browser (usually CTRL-F5).

===== Not working? =====
Some changes will require bypassing the cache. It is often worth doing a hard refresh to make sure the

Sometimes the cache will keep your changes from showing. Since this is a possibility, it will be useful to know how to bypass the cache. To do so you may manually clear cache or use a shortcut to refresh and ignore the cached version of the page. Here's how

====== Windows ======
Chrome, Firefox, or Edge: Press <code>Ctrl+F5</code> or <code>Shift+F5</code> or <code>Ctrl+Shift+R</code>

====== Mac ======
Chrome or Firefox: Press <code>Shift+Command+R</code>

Safari for Mac: Press <code>Command+Option+E</code> to empty the cache, then hold down Shift and click Reload in the toolbar

== Make it look like Reversi ==

Let's start with the board. This will give you a good idea of how things will look and where tokens should go.

Be careful designing the layout of your game: you must always keep in mind that players with a 1024px screen width must be able to play. Usually, it means that the width of the play area can be 750px (in the worst case).

For Reversi, it's useless to have a 750x750px board - much too big, so we chose this one which fit perfectly (536x528):

[[File:Board.jpg]]

Note that we are using a jpg file. Jpg filesare lighter than png, so they are faster to load. Later, we are going to use PNGs for tokens because they allow for transparency.

==== Add the board ====
use lowercase file names
* upload <code>board.jpg</code> in your <code>img/</code> directory.
* edit <code>reversi_reversi.tpl</code> to add a <code>div</code> for your board.

Note: If you are building this game by following the tutorial, you will have a different project name than <code>reversi</code> (i.e. <code>mygame_mygame.tpl</code>). The file names in your project will be different than shown in this tutorial, replacing <code>reversi</code> with your project name. Be sure that any code (other than comments) that references <code>reversi</code> is changed to your actual project name.

<pre>
<div id="board">
</div>
</pre>

* edit your <code>reversi.css</code> file to transform it into a visible board:

#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
}

'''Important: refresh your page.''' Here's your board:[[File:reversi1.jpg]]

If the board does not appear, refresh the page (always do this when you update the CSS file), and check the image filename. Remember file names are case sensitive!

==== Code the Grid ====
Now, we need to create some invisible HTML elements where squares are. These elements will be used as position references for the white and black tokens.

===== Make a Square Template =====
The board is 8 squares by 8 squares. This means we need 64 squares. To avoid writing 64 individual <code>div</code> elements on our template, we are going to use the "block" feature.

Let's modify our template (the <code>.tpl</code> file) like this:

<pre>
<div id="board">

<div id="square_{X}_{Y}" class="square" style="left: {LEFT}px; top: {TOP}px;"></div>

</div>
</pre>

As you can see, we created a "square" block, with 4 variable elements: <code>X</code>, <code>Y</code>, <code>LEFT</code>, and <code>TOP</code>. We are going to use this block 64 times during page load.

===== Use Square Template to Build Grid =====
Let's do it in our <code>reversi.view.php</code> file, inside the <code>build_page</code> function:

Note that "reversi_reversi" is the name of the game and if you named your differently you will have to change that when you copy and paste. Example "testreversi_testreversi".

<pre>
$this->page->begin_block( "reversi_reversi", "square" );

$hor_scale = 64.8;
$ver_scale = 64.4;
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$this->page->insert_block( "square", array(
'X' => $x,
'Y' => $y,
'LEFT' => round( ($x-1)*$hor_scale+10 ),
'TOP' => round( ($y-1)*$ver_scale+7 )
) );
}
}
</pre>

Note: as you can see, squares in our <code>board.jpg</code> files do not have an exact width/height in pixels, and that's the reason we are using floating point numbers here.

===== Style Those Squares =====
Now, to finish our work and check if everything works fine, we are going to style our square a little bit in our CSS stylesheet:

<pre>
#board {
width: 536px;
height: 528px;
background-image: url('img/board.jpg');
position: relative;
}

.square {
width: 62px;
height: 62px;
position: absolute;
background-color: red;
}
</pre>

Explanations:
* With "position: relative" on board, we ensure square elements are positioned relatively to board.
* <code>background-color: red;</code> is used for testing. This allows us to see the invisible elements. (You could instead do something like <code>border: 1px solid orange;</code>. have fun and be creative)

Let's refresh and check our (beautiful) squares:

[[File:reversi2.jpg]]

Now that you know the squares are there, you can remove the test line <code>background-color: red;</code> from your <code>.square</code> class in the CSS stylesheet.

===== Not Working? =====
If the styled squares do not appear, inspect and check your css (Chrome DevTools: Application > Frames > top > Stylesheets > reversi.css).

If your changes are not there try clearing your cache. Remember, you can bybass cache

== The Tokens ==

Now, our board is ready for some tokens!

[Note: Throughout this tutorial, sometimes "tokens" is used, and sometimes "discs" is used. They are often swapped if you're looking at code in the reversi example project.]

=== Build the Token ===
There are quite a few steps before the tokens will appear. You may be used to testing after every change, but that won't work well here. The token will '''not''' show until you have add a div to the tpl, styles to the css, js template to the tpl, utility method in the js, adjusted the php file, and added the token to the board in the js file.

==== HTML in the .tpl file ====
At first, we introduce a new 'div' element as a child of "board" to host all these tokens (in our template):

<pre>


<div id="tokens">
</div>
</div>
</pre>

Note: <code>tokens</code> is plural. This div will be used to hold the token divs. Shortly, we will use javascript to add individual tokens to the board.

==== Add Token to img directory ====
Here's a new piece of art with the tokens. We need transparency here so we are using a png file:

[[File:tokens.png]]

Upload this image file <code>tokens.png</code> in your <code>img/</code> directory.

Important Fun Fact: we are using ONE file for both tokens. It is really important to use a minimum number of graphic files for your game. This is called the "CSS sprite" technique, because it makes the game load faster and more reliable. [http://www.w3schools.com/css/css_image_sprites.asp Read more about CSS sprites].

==== Style the Tokens in .css file ====
<pre>
.token {
width: 56px;
height: 56px;
position: absolute;
background-image: url('img/tokens.png');
}
.tokencolor_ffffff { background-position: 0px 0px; }
.tokencolor_000000 { background-position: -56px 0px; }
</pre>

With this CSS code, we could apply the classes "token" and "tokencolor_ffffff" to a div element and we'd got a white token.

Note the "position: absolute" which allows us to position tokens on the board and make them "slide" to their positions.

==== Build Token JS Template in .tpl file ====
Now, let's make the first token appear on our board. Tokens are not visible at the beginning of the game: they appear dynamically during the game. For this reason, we are going to make them appear from our Javascript code, with a BGA Framework technique called "JS template".

In our template file (<code>reversi_reversi.tpl</code>), let's create the piece of HTML needed to display our token:

<pre>
<script type="text/javascript">

// Templates

var jstpl_token='<div class="token tokencolor_${color}" id="token_${x_y}"></div>';

</script>
</pre>

Note: we already created the "templates" section for you in the game skeleton.

As you can see, we defined a JS template named <code>jstpl_token</code> with a piece of HTML and two variables: the color of the token and its x/y coordinates. Note that the syntax of the argument is different for template block variables (braces <code>{}</code>) and JS template variables (dollar and braces <code>${}</code>).

==== Add Token Utility Method in .js file ====
Now, let's create a method in our Javascript code (in the <code>reversi.js</code> file) that will make a token appear on the board, using this template. Add under the section //// Utility methods:

<pre>
addTokenOnBoard: function( x, y, player )
{
dojo.place( this.format_block( 'jstpl_token', {
x_y: x+'_'+y,
color: this.gamedatas.players[ player ].color
} ) , 'tokens' );

this.placeOnObject( 'token_'+x+'_'+y, 'overall_player_board_'+player );
this.slideToObject( 'token_'+x+'_'+y, 'square_'+x+'_'+y ).play();
},
</pre>

===== Utility Method Explanation =====
* with <code>dojo.place</code> and <code>this.format_block</code> methods, we create a HTML piece of code and insert it as a new child of <code>tokens</code> div element.
* with BGA <code>this.placeOnObject</code> method, we place this element over the panel of some player.
* Immediately after, using BGA <code>this.slideToObject</code> method, we make the token slide to the <code>square</code> element, its final destination.
* <code>'overall_player_board_'+player</code> refers to the div element that contains each player's information and avatar. By initially placing the token here, it gives the effect that the player's avatar is throwing the token onto the board.

Note: don't forget to call the <code>play()</code>, otherwise the token will remain at its original location.

Note: during this process, the parent of the new token HTML element will stay <code>tokens</code>. <code>placeOnObject</code> and <code>slideToObject</code> methods are ''only'' moving the position of elements on screen, and they are ''not'' modifying the HTML tree.

==== Set Token Colors in setupNewGame in .game.php file ====
Before we can show a token, we need to set the player colors in the setupNewGame function in reversi.game.php:

Replace <code>$default_colors = $gameinfos['player_colors'];</code> with the following line:
<pre>
$default_colors = array( "ffffff", "000000" );
</pre>

Note: A few lines below, you may have to remove the line <code>self::reattributeColorsBasedOnPreferences( $players, $gameinfos['player_colors'] );</code>

=== Test the Token ===
Now, to test if everything works fine

==== addTokenOnBoard() in .js file to Test ====
In <code>reversi.js</code>, in <code>setup: function</code>, under <code>// TODO: Set up your game interface here</code> add
this.addTokenOnBoard( 2, 2, this.player_id );
Now restart the game.

''Note: if the page fails to load with a <code>Javascript error: n is null</code> message, make sure you have added the "tokens" div in your template as instructed above.''

A token should appear and slide immediately to its position, like this:

[[File:reversi3.jpg]]

== The database ==

We did most of the client-side programming, so let's have a look on the other side now. To design the database model of our game, you will need to access the database. You won't need to do anything in database UI, yet.

=== Accessing the Database ===
To access the database, start a game, then click "Go to game database" link at the bottom of our game, to access the database directly with a PhpMyAdmin instance.

After the first time you've acess the database, you could skip opening a game and instead, go to https://studio.boardgamearena.com/db/ . Your PhpMyAdmin username/password is in your welcome email.

'''Note''': do not remove existing tables

=== Create Table in .sql file ===
Now, you are able to create the table(s) you need for your game, and report every SQL command used in your <code>dbmodel.sql</code> file.

The database model of Reversi is short: just one table with the squares of the board.

<pre>
CREATE TABLE IF NOT EXISTS `board` (
`board_x` smallint(5) unsigned NOT NULL,
`board_y` smallint(5) unsigned NOT NULL,
`board_player` int(10) unsigned DEFAULT NULL,
PRIMARY KEY (`board_x`,`board_y`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;
</pre>

Add the above SQL to <code>dbmodel.sql</code>. Pay special attention to the backtick <code>`</code> character vs. the single quote <code>'</code> when working with SQL.

=== Test the Table ===
Now, a new database with a <code>board</code> table will be created each time we start a Reversi game. This is why after modifying our <code>dbmodel.sql</code> it's a good time to stop your current game & start a new game.

Start a new game and verify a table is created.

== Setup the initial game position ==

'''Note''': From now on, you must launch the game with '''two players''' to get two <code>player_id</code>s within the database. Otherwise, the game will crash.

The <code>setupNewGame</code> method of our <code>reversi.game.php</code> is called during initial setup. This initializes our data and places the starting tokens on the board. At the beginning of the game, there should be 4 tokens on the board.

=== Initialize the Board in .game.php file ===
Under <code>// TODO: setup the initial game situation here</code>, initialize the board<pre>
// Init the board
$sql = "INSERT INTO board (board_x,board_y,board_player) VALUES ";
$sql_values = array();
list( $blackplayer_id, $whiteplayer_id ) = array_keys( $players );
for( $x=1; $x<=8; $x++ )
{
for( $y=1; $y<=8; $y++ )
{
$token_value = "NULL";
if( ($x==4 && $y==4) || ($x==5 && $y==5) ) // Initial positions of white player
$token_value = "'$whiteplayer_id'";
else if( ($x==4 && $y==5) || ($x==5 && $y==4) ) // Initial positions of black player
$token_value = "'$blackplayer_id'";

$sql_values[] = "('$x','$y',$token_value)";
}
}
$sql .= implode( ',', $sql_values );
self::DbQuery( $sql );
</pre>

==== Board Initialization Explanation ====

* We create one table entry for each square, with a <code>NULL</code> value which means "empty square"
* On 4 of the squares, we place an initial token.

After this, we set <code>activeNextPlayer</code> to make the first player active at the beginning of the game (this line is already present in the default code template).

If you didn't do it earlier, you need to remove the call to <code>self::reattributeColorsBasedOnPreferences()</code> in <code>SetupNewGame()</code>. If you don't, player color preferences will try (and fail) to override the two colors supported here.

=== Show the Initial Token Setup ===
Now, we need to make these tokens appear on the client side. The first step is to return the token positions with our <code>getAllDatas()</code> PHP method. <code>getAllDatas()</code> is called during each page reload.

In the <code>getAllDatas()</code> method, after <code>// TODO: Gather all information about current game situation (visible by player $current_player_id)</code>, add the following lines:

<pre>
// Get reversi board token
$result['board'] = self::getObjectListFromDB( "SELECT board_x x, board_y y, board_player player
FROM board
WHERE board_player IS NOT NULL" );
</pre>

Next, you may need to modify the query that gets player information to also get the player's colors. This is in the variable <code>$sql</code>, above the lines you just inserted in <code>getAllDatas()</code>. Below is what the line will look like. Notice how we've added <code>player_color color</code> to the sql query.

<pre>
$sql = "SELECT player_id id, player_score score, player_color color FROM player ";
</pre>

We are using the BGA framework's <code>getObjectListFromDB()</code> that formats the result of this SQL query in a PHP array with x, y and player attributes. We add it to the result associative array with the key <code>board</code>.

Last, we process this array client side. Let's place a token on the board for each array item. We'll do this in our Javascript <code>setup</code> method under <code>// TODO: Set up your game interface here, according to "gamedatas"</code>.

This will result in a removal or edit of the previously added line <code>this.addTokenOnBoard(2, 2, this.player_id);</code>

<pre>
for( var i in gamedatas.board )
{
var square = gamedatas.board[i];

if( square.player !== null )
{
this.addTokenOnBoard( square.x, square.y, square.player );
}
}
</pre>

The <code>board</code> entry created in <code>getAllDatas()</code> is used here as <code>gamedatas.board</code>

=== Test the Game Start ===
Reload... and here we are:

[[File:reversi5.jpg]]

It starts to feel like Reversi here...

== The game state machine ==

Stop your game, again. You're about to start the core game logic.

You already read [http://www.slideshare.net/boardgamearena/bga-studio-focus-on-bga-game-state-machine Focus on BGA game state machine], so you know that this is the heart of your game logic. For reversi, it's relatively simple. Here's a diagram of our game state machine:

[[File:reversi6.jpg]]

=== Build your States ===
And here's our <code>states.inc.php</code>, according to this diagram:

<pre>
$machinestates = array(

1 => array(
"name" => "gameSetup",
"description" => clienttranslate("Game setup"),
"type" => "manager",
"action" => "stGameSetup",
"transitions" => array( "" => 10 )
),

10 => array(
"name" => "playerTurn",
"description" => clienttranslate('${actplayer} must play a disc'),
"descriptionmyturn" => clienttranslate('${you} must play a disc'),
"type" => "activeplayer",
"args" => "argPlayerTurn",
"possibleactions" => array( 'playDisc' ),
"transitions" => array( "playDisc" => 11, "zombiePass" => 11 )
),

11 => array(
"name" => "nextPlayer",
"type" => "game",
"action" => "stNextPlayer",
"updateGameProgression" => true,
"transitions" => array( "nextTurn" => 10, "cantPlay" => 11, "endGame" => 99 )
),

99 => array(
"name" => "gameEnd",
"description" => clienttranslate("End of game"),
"type" => "manager",
"action" => "stGameEnd",
"args" => "argGameEnd"
)

);
</pre>

Now, in <code>reversi.game.php</code> let's create the methods that are declared in this game states description file:
* <code>argPlayerTurn</code>: referenced in the <code>args</code> property of the <code>playerTurn</code> state; this is the name of the method to call to retrieve arguments for this gamestate. Arguments are sent to the client side to be used on <code>onEnteringState</code> or to set arguments in the gamestate description.
* <code>stNextPlayer</code>: referenced in the <code>action</code> property of the <code>nextPlayer</code> state; this is the name of the method to call when this game state become the current game state.

=== Test Your States ===
... and start a new Reversi game.

As you can see on the screen capture below, the BGA framework makes the game jump to our first game state <code>playerTurn</code> right after the initial setup. That's why the status bar contains the description of <code>playerTurn</code> state ("XXXX must play a disc"):

[[File:reversi7.jpg]]

== The rules ==

We will use the <code>getPossibleMoves</code> PHP method to:
* Indicate to the current player where she is allowed to play by returning a list of coordinates
* Check if the player has the right to play in the spot they choose

<blockquote>
Example of getPossibleMoves here https://gist.github.com/leocaseiro/a8bc2851bd0caddd06685b5035937d15
</blockquote>

This is pure PHP programming here, and there are no special things from the BGA framework that can be used. This is why we won't go into details here. The overall idea is:
* Create a <code>getTurnedOverDiscs(x,y)</code> method that returns coordinates of discs that would be turned over if a token would be played at <code>x</code>,<code>y</code>.
* Loop through all free squares of the board and call the <code>getTurnedOverDiscs</code> method on each of them. If at least 1 token is turned over, this is a valid move.

IMPORTANT: Making a database query is slow! Please don't load the entire game board with a SQL query multiple times. In our implementation, we load the entire board once at the beginning of <code>getPossibleMoves</code>, and then pass the board as an argument to all methods.

If you want to look into details, please look at the "utility method" sections of <code>reversi.game.php</code>. If building the tutorial yourself, copy the functions under "Utility functions" comment from the Reversi tutorial.

== Display allowed moves ==

Now we want to highlight the squares where the player can place a disc.

To do this, we add a <code>argPlayerTurn</code> method in <code>reversi.game.php</code>. This method is called on the server each time we enter into <code>playerTurn</code> game state, and its result is transferred automatically to the client-side:

<pre>
function argPlayerTurn()
{
return array(
'possibleMoves' => self::getPossibleMoves( self::getActivePlayerId() )
);
}
</pre>

We use the <code>getPossibleMoves</code> method we just developed.

Each time we enter into a new game state, we use the <code>onEnteringState</code> Javascript method (in the <code>reversi.js</code> file, under "Game & client states"). This lets us use the data returned by the method above on the client side.

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

switch( stateName )
{
case 'playerTurn':
this.updatePossibleMoves( args.args.possibleMoves );
break;
}
},
</pre>

So, when we enter into <code>playerTurn</code> game state, we call our <code>updatePossibleMoves</code> method (under the "Utility methods" section). This method looks like this:

<pre>
updatePossibleMoves: function( possibleMoves )
{
// Remove current possible moves
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

for( var x in possibleMoves )
{
for( var y in possibleMoves[ x ] )
{
// x,y is a possible move
dojo.addClass( 'square_'+x+'_'+y, 'possibleMove' );
}
}

this.addTooltipToClass( 'possibleMove', '', _('Place a disc here') );
},
</pre>
Here's what this does. At first, it removes all <code>possibleMove</code> classes currently applied with the very useful combination of <code>dojo.query</code> and <code>removeClass</code> method.

Then it loops through all possible moves our PHP <code>updatePossibleMoves</code> function created for us, and adds the <code>possibleMove</code> class to each corresponding square.

Finally, it uses the BGA framework <code>addTooltipToClass</code> method to associate a tooltip to all those highlighted squares so that players can understand their meaning.

To see the possible moves we need to create a CSS class (<code>possibleMove</code>) that can be applied to a <code>square</code> element to highlight it:
<pre>
.possibleMove {
background-color: white;
opacity: 0.2;
filter:alpha(opacity=20); /* For IE8 and earlier */
cursor: pointer;
}
</pre>

And here we are:

[[File:reversi8.jpg.jpg]]

== Let's play ==

From now, it's better to restart a game with 2 players, because we are going to implement a complete Reversi turn. The summary of what we are going to do is:
* When we click on a <code>possibleMove</code> square, send the move to the server.
* Server side, check the move is correct, apply Reversi rules and jump to next player.
* Client side, change the token position to reflect the move.

First we associate each click on a square to one of our methods using our Javascript <code>setup</code> method:

<pre>
dojo.query( '.square' ).connect( 'onclick', this, 'onPlayDisc' );
</pre>

Note the use of the "dojo.query" method to get all HTML elements with "square" class in just one function call. Now, our "onPlayDisc" method is called each time someone clicks on a square.

Here's our "onPlayDisc" method below:

<pre>
onPlayDisc: function( evt )
{
// Stop this event propagation
dojo.stopEvent( evt );

// Get the clicked square x and y
// Note: square id format is "square_X_Y"
var coords = evt.currentTarget.id.split('_');
var x = coords[1];
var y = coords[2];

if( ! dojo.hasClass( 'square_'+x+'_'+y, 'possibleMove' ) )
{
// This is not a possible move => the click does nothing
return ;
}

if( this.checkAction( 'playDisc' ) ) // Check that this action is possible at this moment
{
this.ajaxcall( "/reversi/reversi/playDisc.html", {
x:x,
y:y
}, this, function( result ) {} );
}
},
</pre>

Warning: Make sure to replace <code>reversi</code> in line <code>this.ajaxcall( "/reversi/reversi/playDisc.html", {</code> with the name of your project. E.g. <code>"/yourgamename/yourgamename/playDisc.html"</code>

What we do here is:
* We stop the propagation of the Javascript <code>onclick</code> event. Otherwise, it can lead to random behavior so it's always a good idea.
* We get the x/y coordinates of the square by using <code>evt.currentTarget.id</code>
* We check that clicked square has the <code>possibleMove</code> class, otherwise we know for sure that we can't play there.
* We check that <code>playDisc</code> action is possible, according to current game state (see <code>possibleactions</code> entry in our <code>playerTurn</code> game state defined above). This check is important to avoid issues if a player double clicks on a square.
* Finally, we make a call to the server using BGA <code>ajaxcall</code> method with argument x and y.

Now, we have to manage this <code>playDisc</code> action on the server side. At first, we introduce a <code>playDisc</code> entry point in our <code>reversi.action.php</code>:

<pre>
public function playDisc()
{
self::setAjaxMode();
$x = self::getArg( "x", AT_posint, true );
$y = self::getArg( "y", AT_posint, true );
$result = $this->game->playDisc( $x, $y );
self::ajaxResponse( );
}
</pre>

As you can see, we get the 2 arguments x and y from the javascript call, and call a corresponding <code>playDisc</code> method in our game logic (<code>reversi.game.php</code>).

Now, let's have a look of this <code>playDisc</code> method:

<pre>
function playDisc( $x, $y )
{
// Check that this player is active and that this action is possible at this moment
self::checkAction( 'playDisc' );
</pre>

... at first, we check that this action is possible according to current game state (see "possible action"). We already did it on client side, but it's important to do it on server side too (otherwise it would be possible to cheat).

<pre>
// Now, check if this is a possible move
$board = self::getBoard();
$player_id = self::getActivePlayerId();
$turnedOverDiscs = self::getTurnedOverDiscs( $x, $y, $player_id, $board );

if( count( $turnedOverDiscs ) > 0 )
{
// This move is possible!
</pre>

...now, we are using the <code>getTurnedOverDiscs</code> method again to check that this move is possible.

<pre>
// Let's place a disc at x,y and return all "$returned" discs to the active player

$sql = "UPDATE board SET board_player='$player_id'
WHERE ( board_x, board_y) IN ( ";

foreach( $turnedOverDiscs as $turnedOver )
{
$sql .= "('".$turnedOver['x']."','".$turnedOver['y']."'),";
}
$sql .= "('$x','$y') ) ";

self::DbQuery( $sql );

</pre>

... we update the database to change the color of all turned over disc + the disc we just placed.

<pre>
// Update scores according to the number of disc on board
$sql = "UPDATE player
SET player_score = (
SELECT COUNT( board_x ) FROM board WHERE board_player=player_id
)";
self::DbQuery( $sql );

// Statistics
self::incStat( count( $turnedOverDiscs ), "turnedOver", $player_id );
if( ($x==1 && $y==1) || ($x==8 && $y==1) || ($x==1 && $y==8) || ($x==8 && $y==8) )
self::incStat( 1, 'discPlayedOnCorner', $player_id );
else if( $x==1 || $x==8 || $y==1 || $y==8 )
self::incStat( 1, 'discPlayedOnBorder', $player_id );
else if( $x>=3 && $x<=6 && $y>=3 && $y<=6 )
self::incStat( 1, 'discPlayedOnCenter', $player_id );

</pre>

... now, we update both player score by counting all disc, and we manage game statistics.

<pre>
// Notify
self::notifyAllPlayers( "playDisc", clienttranslate( '${player_name} plays a disc and turns over ${returned_nbr} disc(s)' ), array(
'player_id' => $player_id,
'player_name' => self::getActivePlayerName(),
'returned_nbr' => count( $turnedOverDiscs ),
'x' => $x,
'y' => $y
) );

self::notifyAllPlayers( "turnOverDiscs", '', array(
'player_id' => $player_id,
'turnedOver' => $turnedOverDiscs
) );

$newScores = self::getCollectionFromDb( "SELECT player_id, player_score FROM player", true );
self::notifyAllPlayers( "newScores", "", array(
"scores" => $newScores
) );
</pre>

... then we notify about all these changes. We are using for that 3 notifications (<code>playDisc</code>, <code>turnOverDiscs</code> and <code>newScores</code> that we are going to implement on client side later). Note that the description of the <code>playDisc</code> notification will be logged in the game log.

<pre>
// Then, go to the next state
$this->gamestate->nextState( 'playDisc' );
}
else
throw new BgaSystemException( "Impossible move" );
}
</pre>

... finally, we jump to the next game state if everything goes fine (<code>playDisc</code> is the name of a transition in the <code>playerTurn</code> game state description above which leads to state 11 which is <code>nextPlayer</code>).

To make the statistics work, we have to initialize them in <code>stats.json</code>:

<pre>
{
"player": {
"discPlayedOnCorner": {
"id": 10,
"name": "Discs played on a corner",
"type": "int"
},
"discPlayedOnBorder": {
"id": 11,
"name": "Discs played on a border",
"type": "int"
},
"discPlayedOnCenter": {
"id": 12,
"name": "Discs played on board center part",
"type": "int"
},
"turnedOver": {
"id": 13,
"name": "Number of discs turned over",
"type": "int"
}
}
}
</pre>

A last thing to do on the server side is to activate the next player when we enter the <code>nextPlayer</code> game state (in the <code>reversi.game.php</code> file, under "Game state reactions"):

<pre>
function stNextPlayer()
{
// Active next player
$player_id = self::activeNextPlayer();

// Check if both player has at least 1 discs, and if there are free squares to play
$player_to_discs = self::getCollectionFromDb( "SELECT board_player, COUNT( board_x )
FROM board
GROUP BY board_player", true );

if( ! isset( $player_to_discs[ null ] ) )
{
// Index 0 has not been set => there's no more free place on the board !
// => end of the game
$this->gamestate->nextState( 'endGame' );
return ;
}
else if( ! isset( $player_to_discs[ $player_id ] ) )
{
// Active player has no more disc on the board => he looses immediately
$this->gamestate->nextState( 'endGame' );
return ;
}

// Can this player play?

$possibleMoves = self::getPossibleMoves( $player_id );
if( count( $possibleMoves ) == 0 )
{

// This player can't play
// Can his opponent play ?
$opponent_id = self::getUniqueValueFromDb( "SELECT player_id FROM player WHERE player_id!='$player_id' " );
if( count( self::getPossibleMoves( $opponent_id ) ) == 0 )
{
// Nobody can move => end of the game
$this->gamestate->nextState( 'endGame' );
}
else
{
// => pass his turn
$this->gamestate->nextState( 'cantPlay' );
}
}
else
{
// This player can play. Give him some extra time
self::giveExtraTime( $player_id );
$this->gamestate->nextState( 'nextTurn' );
}

}
</pre>

Now, when we play a token, the rules are checked and the token appears in the database.

[[File:reversi9.jpg]]

Of course, as we don't manage notifications on client side, we need to press F5 after each move to see the changes on the board.

== Make the move appear automatically ==

Now, what we have to do is process the notifications sent by the server and make the move appear on the interface.

In our <code>setupNotifications</code> method in <code>reversi.js</code>, we register 2 methods for the 2 notifications we created at the previous step (<code>playDisc</code> and <code>turnOverDiscs</code>):

<pre>
dojo.subscribe( 'playDisc', this, "notif_playDisc" );
this.notifqueue.setSynchronous( 'playDisc', 500 );
dojo.subscribe( 'turnOverDiscs', this, "notif_turnOverDiscs" );
this.notifqueue.setSynchronous( 'turnOverDiscs', 1500 );
dojo.subscribe( 'newScores', this, "notif_newScores" );
this.notifqueue.setSynchronous( 'newScores', 500 );
</pre>

As you can see, we associate each of our 3 notifications with a method prefixed with <code>notif_</code>. We also define these notifications as "synchronous", with a duration in millisecond. It tells the user interface to wait some time after executing the notification, to let the animation end before starting the next notification. In our specific case, the animation will be the following:
* Make a disc slide from the player panel to its place on the board
* (wait 500ms)
* Make all turned over discs blink (and of course turned them over)
* (wait 1500ms)
* Update the player scores
* (wait 500ms)

The 2nd parameter in <code>dojo.subscribe</code> call (this) is the <code>context</code>, and will be passed in as a parameter to the specified method.

Let's have a look now on the <code>playDisc</code> notification handler method:

<pre>
notif_playDisc: function( notif )
{
// Remove current possible moves (makes the board more clear)
dojo.query( '.possibleMove' ).removeClass( 'possibleMove' );

this.addTokenOnBoard( notif.args.x, notif.args.y, notif.args.player_id );
},
</pre>

No surprise here, we re-used some existing stuff to:
* Remove the highlighted squares.
* Add a new disc on board, coming from player panel.

Now, here's the method that handles the <code>turnOverDiscs</code> notification:

<pre>
notif_turnOverDiscs: function( notif )
{
// Get the color of the player who is returning the discs
var targetColor = this.gamedatas.players[ notif.args.player_id ].color;

// Make these discs blink and set them to the specified color
for( var i in notif.args.turnedOver )
{
var token = notif.args.turnedOver[ i ];

// Make the token blink 2 times
var anim = dojo.fx.chain( [
dojo.fadeOut( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } ),
dojo.fadeOut( {
node: 'token_'+token.x+'_'+token.y,
onEnd: function( node ) {

// Remove any color class
dojo.removeClass( node, [ 'tokencolor_000000', 'tokencolor_ffffff' ] );
// ... and add the good one
dojo.addClass( node, 'tokencolor_'+targetColor );

}
} ),
dojo.fadeIn( { node: 'token_'+token.x+'_'+token.y } )

] ); // end of dojo.fx.chain

// ... and launch the animation
anim.play();
}
},
</pre>

The list of the discs to be turned over has been made available by our server side code in <code>notif.args.turnedOver</code> (see previous paragraph). We loop through all these discs, and create a complex animation using <code>dojo.Animation</code> for each of them. The complete documentation on dojo animations [http://dojotoolkit.org/documentation/tutorials/1.6/animation/ can be found here].

In few words: we create a chain of 4 animations to make the disc fade out, fade in, fade out again, and fade in again. At the end of the second fade out, we change the color of the disc. Finally, we launch the animation with <code>play()</code>.

And Also the notification to update the scores:

<pre>
notif_newScores: function( notif )
{
for( var player_id in notif.args.scores )
{
var newScore = notif.args.scores[ player_id ];
this.scoreCtrl[ player_id ].toValue( newScore );
}
},
</pre>

[[Category:Studio]]

Setting up BGA Development environment using VSCode

2024-04-11T20:38:22Z

NevinAF: Added the BGA-ts-template to the JS Intellisense section

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==

* Download and install vscode from https://code.visualstudio.com
* Download and install php (7.4) command line interface (for local tests and debugging)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===
The intellisense for JavaScript code is to '''use the [[BGA-ts-template]]'''. It offers a much cleaner initial file, clearer workflow, and nearly complete type and autofill support for whatever you may need.

<table>
<tr>
<td>[[File:Stripped base Typescript file.png|alt=Starting TS file with comments/template code removed|thumb|696x696px|Starting TS file with comments/template code removed]]</td>
<td>[[File:Typescript autofill.gif|alt=Typescript Autocomplete using BGA Type Safe Template|thumb|542x542px|Typescript Autocomplete using BGA Type Safe Template]] </td>
</tr>
</table>

If this does not interest you, you can also revert to the old ways of getting better intellisense:

- Because of dojo style class/method declarations most IDE won't be able to index main JavaScript file properly (i.e. go to definition of function and such).
If you manage to get it working in VS code, let us know how.

- There is a way to re-structure code to avoid using this style, but this is not for beginners. Do not use this on your first game!
https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Avoiding_code_in_dojo_declare_style

- There is also a complete example of a "dojo-less" project, it also includes a (incomplete) typescript definition file (.d.ts) for auto-completion of js BGA interfaces
https://github.com/elaskavaia/bga-dojoless

===PHP Intellisense===

If you don't do anything PHP will complain about undefined symbols from BGA framework (as well as from the material file).
To solve the warning about framework issues, you need a stubs for the BGA APIs:

*git clone git@github.com:elaskavaia/bga-sharedcode.git (you can also get and unzip it from the GitHub page)
** if that doesn't work, try git clone <nowiki>https://github.com/elaskavaia/bga-sharedcode.git</nowiki>
**you can do this in a terminal from VS Code - Terminal menu -> New Terminal
*add reference (include path) to bga-sharedcode/misc using settings of PHP extension, see example below

If you're using the Intelephense plugin, add this to global user settings (modify the path obviously)

"intelephense.environment.includePaths": [
"/home/victoria/git/bga-sharedcode/misc/"
],

To solve the warning about the material file class members

Option 1)
If you don't have too many class members you can define them, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

===Unit testing===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/victoria/php-composer
composer require --dev phpunit/phpunit ^9

Then add this path (e.x. /home/victoria/php-composer) to include paths as above

See more about unit testing in [[Testing by developer]]

== File Sync==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

*'''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

*'''Open VSCode on an empty folder''' that will be the local root of your project.

*Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store"
],
"syncOption": {
"skipCreate": false, # syncs new files
"delete": true # syncs deleted files
}
}
</pre>

===One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

=== Daily use===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.

=== Split settings for version control===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

==Code Formatter==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.19.1",
"prettier": "^2.7.1"
},
"prettier": {
"braceStyle": "1tbs"
}

== Code generators==
If you want to run code generators for example for typescript or scss you can install this extension:
*https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>

[[Category:Studio]]

File:Stripped base Typescript file.png

2024-04-11T20:27:37Z

NevinAF:

The main typescript file for the BGA Type Safe Template, with comments and noop code removed.

BGA Code Sharing

2024-04-11T20:08:06Z

NevinAF: Added the BGA Type safe template to this page

{{Studio_Framework_Navigation}}

This page is for listing of externally hosted bga projects, tools and resources, as well as internal project
intended for sharing

== Community shared components, pens, etc ==

{| class="wikitable"
|-
! NAME
! CODE LINK
! DESCRIPTION
|-
! colspan="3" | Dice models and animation
|-
| Die: 4 sided
| https://codepen.io/mrkiffie/pen/doVZgW ; https://codepen.io/VictoriaLa/pen/JjZNezr
| code pen
|-
| Die: 6 sided
| https://github.com/elaskavaia/bga-sharedcode ; https://codepen.io/VictoriaLa/pen/QWBBbwz
|
|-
| Die: 8 sided
| https://codepen.io/VictoriaLa/pen/YzMPeGq
| code pen
|-
| Die: 12 sided (dodecahedron)
| https://codepen.io/VictoriaLa/pen/xxLLxOP <nowiki/> https://codepen.io/hoursgoby/pen/GRwQzxo
| Code pen
|-
| Die: 20 sided
| https://codepen.io/vicentemundim/details/cenIh
| Code pen
|-
! colspan="3" | Moving object using CSS animation (mostly)
|-
| Phantom object move on oversurface
| https://codepen.io/VictoriaLa/pen/gORvdJo
| This technique creates clone of the object it moves it on another surface. It works well when parents that css transform applies such as scale and rotate
|-
| Move object directly using positioning
| https://codepen.io/VictoriaLa/pen/dyzgKVX
| This technique is modification of BGA framework method to allow mobile object not to have absolute position before or after the move (and uses css animation not dojo). Methods slideToObjectRelative, attachToNewObjectNoDestroy
|-
! colspan="3" | Responsive layout for game boards
|-
|Flex Layout
|https://codepen.io/VictoriaLa/pen/XWjJJgG
|Example on how to create flexible layout just by using css
|-
! colspan="3" | Algorithms
|-
|Hex grid
|tapestry,Tumbleweed,gaia project,Gold West
|
|-
|Shortest path on hex grid
|memoir 44
| Dijkstra
|-
|Largest area on hex grid
|tapestry, ...
|
|-
|Largest area on square grid
|king domino, ...
|
|-
|Tetris pieces
|patchwork, ...
|Matrix manupations to rotate, flip and fit tetris pieces
|-
|Line of sights on hex grid
|memoir 44
|Find intersecting hexes on a line between two cells
|-
! colspan="3" | Alternative implementations of BGA modules
|-
|Scrollmap with zoom
|https://github.com/yansnow78/bga_scrollmap
|you can find it in cacao an implementation in cacao (currently only changed in studio) . <nowiki>#</nowiki> improvements compare to scrollmap:
- add zoom capabilities

- add possibility to adjust pan delta to tile size when clicking on arrows

- allow zoom with scroll wheel. only allow zoom with wheel if alt or ctrl or shift are pressed by default. add possibility to select which key need to be pressed when zooming with wheel

- allow pan/scroll and pinch zoom on smartphone. only allow 2 fingers to start scrolling by default, one finger is for page scrolling

- make clickable area of buttons a bit bigger on smartphone

- improve animation between game board and player bards thanks to an animation_div

- add support to long click on buttons (continuous scroll or zoom or enlarge/reduce until button released)
|-
|Scrollmap Plus
|patchwork
|Implementation with some bugs fixed, improved drag support and ability to use only one direction (i.e. only horizontal like carousel). Found in modules/extscrollmap.js
|-
|Zoom
|[https://github.com/thoun/bga-zoom/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-zoom/demo/index.html Demo] (visible on Knarr, Azul, Abyss, ...)
|Allow the user to zoom on the game board. Include the controls to zoom, and handle the scale applied to the HTML element.
|-
|Cards
|[https://github.com/thoun/bga-cards/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-cards/demo/index.html Demo] (visible on Knarr, King of Tokyo, Abyss, ...)
|Alternative to BGA Stock component, using CSS transitions instead of dojo animations.
|-
|Jump to
|[https://github.com/thoun/bga-jump-to/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-jump-to/demo/index.html Demo] (visible on Knarr, Elawa)
|Add floating controls to quickly jump to a player's table
|-
|Help
|[https://github.com/thoun/bga-help/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-help/demo/index.html Demo] (visible on Knarr)
|Add floating help buttons at the bottom left corner of the screen
|-
|Dice
|[https://github.com/thoun/bga-dice/ Repo]<nowiki> | </nowiki>[https://thoun.github.io/bga-dice/demo/index.html Demo] (not used yet)
|Handle dice display and animation '''WORK IN PROGRESS''' Only d6 is started
|}

== Projects ==

Add the game name, a link to repository and nickname of the developer on bga (same as used for dev forum), and short description. See [[Tools_and_tips_of_BGA_Studio#Version_Control]] for some suggestions on how and where to publish your code externally. Also see the [https://github.com/topics/boardgamearena boardgamearena] topic on github.

'''Important notice about artwork on BGA Open Source projects: original hi-resolution images from publishers must not be published on the repositories. In addition, it is better to specify that the images derivated from publishers artwork are copyrighted and cannot be licensed under a free license like Creative Commons.
'''

{| class="wikitable"
|-
! NON-GAME PROJECTS
! CODE LINK
! DEVELOPER
! COMMENT
|-
| Shared Code (not a game)
| https://github.com/elaskavaia/bga-sharedcode
| Victoria_La
| Examples of various game components and PHP stubs of framework code to make IDE happy
|-
| Vanilla Typescipt template (not a game)
| https://github.com/elaskavaia/bga-dojoless
| Victoria_La
| Project template for typescript and using minimal dojo, good for vscode - type checking, auto-complete, navigation
|-
| BoardGameArena Workbench (not a game)
| https://github.com/danielholmes/bga-workbench
| Daniel Holmes (dhau)
|-
|BGA-boilerplate
|https://github.com/bga-devs/tisaac-boilerplate/
|Tisaac (and Vincentt ?)
|Main boilerplate with extended "basic" function and code structure
|-
|BGA Type Safe Template
|https://github.com/NevinAF/bga-ts-template
|NevinAF
|Full typing of all BGA Framework components.
|-
! GAME
! CODE LINK
! DEVELOPER
! COMMENT
|-
| 99 (Trick-taking Card Game)
| https://github.com/ekelly/bga-ninetynine
| QuasarDukeDev
|-
| Abandon All Artichokes
| https://github.com/0-wiz-0/bga-abandonallartichokes
| __wiz__, rojomojo
|-
| Assyria
| https://github.com/sebastien-prudhomme/bga-assyria
| daikinee
|-
| Aura
| https://github.com/micahstairs/bga-aura
| Micah Stairs (micahstairs)
|-
| Bandido
| https://github.com/opheliehb/BandidoBGA
| ophelopede & Harkle
|-
| The Battle for Hill 218
| https://github.com/danielholmes/battle-for-hill-218
| Daniel Holmes (dhau)
|-
| Bonbons
| https://github.com/AntonioSoler/bga-bonbons
| Morgalad
|-
|Big Monster
|https://github.com/nmatton/bigmonster
|nicotacotac
|-
| Canosa
| https://codeberg.org/halibut/Canosa
| junibegood
|-
| Coinche
| https://github.com/drasill/bga-coinche
| Draasill
|-
|Copenhagen
|https://github.com/JoeProgram/bga-copenhagen
|JoeProgram
|-
| Coup: City State
| https://github.com/quietmint/bga-coupcitystate
| quietmint
|-
| Dice Summoners
| https://github.com/eoincos/bga-dicesummoners
| eoincos
|-
| Dungeon Roll
| https://github.com/MartinGoulet/bga-dungeonroll
| MGoulet
|-
| Egyptian Ratscrew
| https://github.com/0BuRner/bga-egyptianratscrew
| 0BuRner
|-
| Eruption
| https://github.com/AndyKerrison/bga-eruption
| Andy_K
|-
| A Fistful Of Gold
| https://bitbucket.org/Joel_L/fistfulofgold
| Brainchild
|-
|Flip Freighters
|https://github.com/joesimpson/bga-flipfreighters
|joesimpson
|-
| Florenza: The Card Game
| https://github.com/alberto-bottarini/bga-florenza
| tarini
|-
| For-Ex
| https://github.com/Fnordistan/forex
| AmadanNaBriona
|-
| Get the MacGuffin
| https://github.com/mizutismask/bga-get-the-MacGuffin
| mizutismask
|-
| Hardback
| https://github.com/quietmint/bga-hardback
| quietmint
|-
| Hearts '''(Tutorial)'''
| https://github.com/elaskavaia/bga-heartsla
| Victoria_La
|-
| Homesteaders
| https://github.com/npatron/bga-homesteaders
| TheBoot
|-
| Incan Gold
| https://github.com/AntonioSoler/bga-incangold
| Morgalad
|-
| In the Year of the Dragon (10th Anniversary Edition)
| https://github.com/Fnordistan/ityotd
| AmadanNaBriona
|-
| Just Desserts
| https://github.com/mizutismask/bga-just-desserts
| mizutismask
|-
| The King's Guild
| https://github.com/AdamNovotny/BGG-KingsGuild
| A-dam
|-
| The Lady and the Tiger (Doors)
| https://github.com/Fnordistan/ladyandthetiger
| AmadanNaBriona
|-
| Mapmaker: The Gerrymandering Game
| https://github.com/gzhang01/bga-mapmaker
| gkz
|-
| Marco Polo
| https://github.com/rcitaliano/MarcoPolo
| rcitaliano
|-
| Nile
| https://github.com/AndyKerrison/bga-nile
| Andy_K
|-
| Noir: Killer vs Inspector
| https://bitbucket.org/chhuang76/bga_noirkvi
| ch huang
|-
| Penny Press
| https://github.com/AdamNovotny/bga-blooms
| A-dam
|-
| Perikles
| https://github.com/Fnordistan/perikles
| AmadanNaBriona
|-
| P.I.
| https://gitlab.com/fa81/bga-pi, https://github.com/hellp/bga-pi (mirror)
| Fabian Neumann (fa81)
|-
| President
| https://github.com/quaresma95/president
| quaresma95
|-
| Santorini
| https://github.com/AntonioSoler/bga-santorini
| Morgalad, quietmint, Tisaac
|-
| Tablut
| https://github.com/Lucas-C/tablut
| Lucas-C & ntaffore
|-
| Takara Island
| https://github.com/AntonioSoler/bga-takaraisland
| Morgalad
|-
| Taluva
| https://github.com/quietmint/bga-taluva
| Morgalad & quietmint
|-
| Teotihuacan: City of Gods
| https://github.com/Trompetenhut/bga-teotihuacan
| Trompetenhut
|-
| Texas 42 (domino game, still under development)
| https://github.com/ishermandom/bga-42
| Stardust Spikes, Jason Turner-Maier, Ilya Sherman
|-
| Tic Tac Match
| https://github.com/leocaseiro/bga-tictacmatch
| Leo Caseiro
|-
| Trick of the Rails
| https://github.com/Fnordistan/trickoftherails
| AmadanNaBriona
|-
| Uptown
| https://github.com/elliotkendall/bga-uptown
| SpottedShroom
|-
| Via Magica
| https://github.com/christopherburke/bga_viamagica
| CuriousTerran
|-
|}

== Projects on studio ==

Any developer can add themselves to a project as read-only from https://studio.boardgamearena.com/#!projects page (almost any project).

If it is not visible: a) it has no bgg id b) it is already published (use radio button to switch) c) it is an old game not developed on studio.

== Other useful resources ==

Moved to [[Tools_and_tips_of_BGA_Studio]]

[[Category:Studio]]

Using Typescript and Scss

2024-04-11T20:04:17Z

NevinAF: Make the sections purpose a bit more clear

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

== BGA Type Safe Template ==
If you are interested in all of the BGA Framework being typed for you, '''check out the [[BGA-ts-template]]'''. It will let you set up full typescript support and more with the fewest, easy to follow steps.
[[File:Typescript autofill.gif|alt=Typescript Autocomplete|center|thumb|734x734px|Typescript Autocomplete using BGA Type Safe Template]]'''The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.'''

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''

{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "tsc",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "tsc --watch",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"sass": "^1.32.6",
"typescript": "^4.1.3"
}
}

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

For Typescript compilation we also need to set up a <code>tsconfig.json</code> on the root folder.

'''tsconfig.json'''

{
"rootDir": ".",
"compilerOptions": {
"target": "es5",
"module": "none",
"lib": ["dom", "esnext"],
"sourceMap": false,
"typeRoots": ["src/types", "./types", "./node_modules/@types"],
"outFile": "YourGameName.js"
},
"files": [
"src/GameBody.ts",
"src/define.ts"
]
}

Note: it only works now with es5

If you want to split your code onto multiple files, just add them in the file list (order is important for dependencies, new subpart should go on top of the list). No need to import classes or types from one file to another. In fact, you can't with this configuration.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look [https://github.com/thoun/bga-ts-example here] for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/GameBody.ts'''

<pre>
// @ts-ignore
GameGui = (function () { // this hack required so we fake extend GameGui
function GameGui() {}
return GameGui;
})();

// Note: it does not really extend it in es6 way, you cannot call super you have to use dojo way
class GameBody extends GameGui {
constructor() {}

public setup(gamedatas: any) {
this.setupNotifications();
}
public onEnteringState(stateName: string, args: any) {}
public onLeavingState(stateName: string) {}
public onUpdateActionButtons(stateName: string, args: any) {}
public setupNotifications() {}
}
</pre>

To plug the class with BGA framework, we'll also create another file:

'''src/define.ts'''

define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock"
],
function (dojo, declare) {
return declare("bgagame.yourgamename", ebg.core.gamegui, new GameBody());
});
Copy <code>bgagame.yourgamename</code> from original JS to avoid name mistakes with letter case.

If you try to compile it you will be missing definitions of bunch of methods and variables for that we will add special ts type definition file .d.ts, this is not a complete version but you can get more complete from git projects below

'''src/types/bga-framework.d.ts'''
<pre>

declare var gameui: GameGui;
declare var g_replayFrom: number | undefined;
declare var g_gamethemeurl: string;
declare var g_themeurl: string;
declare var g_archive_mode: string;
declare function _(str: string): string;

declare const define;
declare const ebg;

declare class GameGui {
page_is_unloading: any;
game_name: string;
instantaneousMode: any;
player_id: string;
interface_min_width: number;
gamedatas: any;

isCurrentPlayerActive(): boolean;
addActionButton(id: string, label: string, callback: (event?: any) => void);
checkAction(action: any);
ajaxcall(url: string, args: object, bind: GameGui, resultHandler: (result: any) => void, allHandler: any);

setup(gamedatas: any): void;
onEnteringState(stateName: string, args: any): void;
onLeavingState(stateName: string ): void;
onUpdateActionButtons(stateName: string, args: any): void;
setupNotifications(): void;

onScriptError(msg: string, url?: string, linenumber?:number);
inherited(args: any);
}

</pre>

Above is barebone definition of gameui interface, you can find more complete one here
https://github.com/elaskavaia/bga-dojoless/blob/main/src/types/bga-framework.d.ts

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.
Original content same as original .css, i.e

@import url(../../../css/csslayer.css);

Your SCSS code can be splitted in multiple files, for example :

'''yourgamename.scss'''
@import 'gametable';

/* some classes */

'''_gametable.scss'''
/* _gametable related classes */

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continiously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup stanard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

=== Hint ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To add code completion on framework, dojo, stock, ... you'll need more type definition files. Feel free to copy them from [https://github.com/thoun/bga-ts-example this repo] and reference them at the top of files array, even before your subpart files.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless
* https://github.com/NevinAF/bga-ts-template

[[Category:Studio]]

Using Typescript and Scss

2024-04-11T20:02:44Z

NevinAF: Added the BGA Type Safe template redirect to the top of the page

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

== BGA Type Safe Template ==
If you are interested in all of the BGA Framework being typed for you, check out the [[BGA-ts-template]]. It will let you set up full typescript support and more with the fewest, easy to follow steps. The following document is geared towards setting up a custom project where you will be in charge of typing all components that you want to use.
[[File:Typescript autofill.gif|alt=Typescript Autocomplete|center|thumb|734x734px|Typescript Autocomplete]]

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''

{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "tsc",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "tsc --watch",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"sass": "^1.32.6",
"typescript": "^4.1.3"
}
}

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

For Typescript compilation we also need to set up a <code>tsconfig.json</code> on the root folder.

'''tsconfig.json'''

{
"rootDir": ".",
"compilerOptions": {
"target": "es5",
"module": "none",
"lib": ["dom", "esnext"],
"sourceMap": false,
"typeRoots": ["src/types", "./types", "./node_modules/@types"],
"outFile": "YourGameName.js"
},
"files": [
"src/GameBody.ts",
"src/define.ts"
]
}

Note: it only works now with es5

If you want to split your code onto multiple files, just add them in the file list (order is important for dependencies, new subpart should go on top of the list). No need to import classes or types from one file to another. In fact, you can't with this configuration.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look [https://github.com/thoun/bga-ts-example here] for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/GameBody.ts'''

<pre>
// @ts-ignore
GameGui = (function () { // this hack required so we fake extend GameGui
function GameGui() {}
return GameGui;
})();

// Note: it does not really extend it in es6 way, you cannot call super you have to use dojo way
class GameBody extends GameGui {
constructor() {}

public setup(gamedatas: any) {
this.setupNotifications();
}
public onEnteringState(stateName: string, args: any) {}
public onLeavingState(stateName: string) {}
public onUpdateActionButtons(stateName: string, args: any) {}
public setupNotifications() {}
}
</pre>

To plug the class with BGA framework, we'll also create another file:

'''src/define.ts'''

define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock"
],
function (dojo, declare) {
return declare("bgagame.yourgamename", ebg.core.gamegui, new GameBody());
});
Copy <code>bgagame.yourgamename</code> from original JS to avoid name mistakes with letter case.

If you try to compile it you will be missing definitions of bunch of methods and variables for that we will add special ts type definition file .d.ts, this is not a complete version but you can get more complete from git projects below

'''src/types/bga-framework.d.ts'''
<pre>

declare var gameui: GameGui;
declare var g_replayFrom: number | undefined;
declare var g_gamethemeurl: string;
declare var g_themeurl: string;
declare var g_archive_mode: string;
declare function _(str: string): string;

declare const define;
declare const ebg;

declare class GameGui {
page_is_unloading: any;
game_name: string;
instantaneousMode: any;
player_id: string;
interface_min_width: number;
gamedatas: any;

isCurrentPlayerActive(): boolean;
addActionButton(id: string, label: string, callback: (event?: any) => void);
checkAction(action: any);
ajaxcall(url: string, args: object, bind: GameGui, resultHandler: (result: any) => void, allHandler: any);

setup(gamedatas: any): void;
onEnteringState(stateName: string, args: any): void;
onLeavingState(stateName: string ): void;
onUpdateActionButtons(stateName: string, args: any): void;
setupNotifications(): void;

onScriptError(msg: string, url?: string, linenumber?:number);
inherited(args: any);
}

</pre>

Above is barebone definition of gameui interface, you can find more complete one here
https://github.com/elaskavaia/bga-dojoless/blob/main/src/types/bga-framework.d.ts

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.
Original content same as original .css, i.e

@import url(../../../css/csslayer.css);

Your SCSS code can be splitted in multiple files, for example :

'''yourgamename.scss'''
@import 'gametable';

/* some classes */

'''_gametable.scss'''
/* _gametable related classes */

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continiously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup stanard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

=== Hint ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To add code completion on framework, dojo, stock, ... you'll need more type definition files. Feel free to copy them from [https://github.com/thoun/bga-ts-example this repo] and reference them at the top of files array, even before your subpart files.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/elaskavaia/bga-dojoless
* https://github.com/NevinAF/bga-ts-template

[[Category:Studio]]

File:Typescript autofill.gif

2024-04-11T19:59:14Z

NevinAF:

A gif showing the bga type-safe template autofill in typescript

BGA Type Safe Template: Reversi

2024-04-11T19:21:02Z

NevinAF: Converted this page from the github using a slightly modified version of Pandoc.

BGA Type Safe Template: Tutorials

2024-04-11T19:16:55Z

NevinAF: Converted this page from the github using a slightly modified version of Pandoc.

Setting up BGA Development environment using VSCode

2024-04-04T00:33:41Z

NevinAF: /* Extensions */

Microsoft Visual Studio Code is light weight IDE/Editor. All desktops.

== Downloads ==

* Download and install vscode from https://code.visualstudio.com
* Download and install php (7.4) command line interface (for local tests and debugging)

== Extensions ==
Use [https://marketplace.visualstudio.com/items?itemName=NevinFoster.bga-extension-pack&ssr=false#overview BGA Extension Pack] to download all of the recommended extensions with one click.
* PHP Intelephense - https://marketplace.visualstudio.com/items?itemName=bmewburn.vscode-intelephense-client
* Or PHP IntelliSense - https://marketplace.visualstudio.com/items?itemName=zobo.php-intellisense
* PHP Debug - https://marketplace.visualstudio.com/items?itemName=xdebug.php-debug
* SQLTools - https://marketplace.visualstudio.com/items?itemName=mtxr.sqltools
* Prettier - code formatter - https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode
* SFTP (by Natizyskunk) - https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp

== Intellisense - Navigation/Auto-complete ==

=== JavaScript Intellisense ===

Because of dojo style class/method declarations most IDE won't be able to index main JavaScript file properly (i.e. go to definition of function and such).
If you manage to get it working in VS code, let us know how.

There is a way to re-structure code to avoid using this style, but this is not for beginners. Do not use this on your first game!
https://en.doc.boardgamearena.com/BGA_Studio_Cookbook#Avoiding_code_in_dojo_declare_style

There is also a complete example of a "dojo-less" project, it also includes a (incomplete) typescript definition file (.d.ts) for auto-completion of js BGA interfaces
https://github.com/elaskavaia/bga-dojoless

=== PHP Intellisense ===

If you don't do anything PHP will complain about undefined symbols from BGA framework (as well as from the material file).
To solve the warning about framework issues, you need a stubs for the BGA APIs:

* git clone git@github.com:elaskavaia/bga-sharedcode.git (you can also get and unzip it from the GitHub page)
** if that doesn't work, try git clone <nowiki>https://github.com/elaskavaia/bga-sharedcode.git</nowiki>
** you can do this in a terminal from VS Code - Terminal menu -> New Terminal
* add reference (include path) to bga-sharedcode/misc using settings of PHP extension, see example below

If you're using the Intelephense plugin, add this to global user settings (modify the path obviously)

"intelephense.environment.includePaths": [
"/home/victoria/git/bga-sharedcode/misc/"
],

To solve the warning about the material file class members

Option 1)
If you don't have too many class members you can define them, for example if I have $this->token_types = [...] in the material file I can define them in in the class of game.php

private $token_types;

Option 2)

Put this line in the settings.json if you using Intelliphense extension to ignore them:

"intelephense.diagnostics.undefinedProperties": false

=== Unit testing ===

If using phpunit, install it via composer somewhere in home directory, i.e.
cd /home/victoria/php-composer
composer require --dev phpunit/phpunit ^9

Then add this path (e.x. /home/victoria/php-composer) to include paths as above

See more about unit testing in [[Testing by developer]]

== File Sync ==
You can set up your sync using other methods, not related to vscode (such as rsync), if you want to do that see [[Tools_and_tips_of_BGA_Studio#File_Sync]] otherwise see below:

You might rely on your IDE to sync the files with the SFTP server. Each time you "save" a file with your modifications, the IDE will also submit it to the sFTP server. These are instructions for VS Code

* '''Install this extension''' https://marketplace.visualstudio.com/items?itemName=Natizyskunk.sftp (File->Preferences->Extensions ... type SFTP and make sure its by Natizyskunk)

* '''Open VSCode on an empty folder''' that will be the local root of your project.

* Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: config"''' - the edit will open with json config

* '''Update the json''' as below:

<pre>
{
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<your SFTP username>",
"password": "<your SFTP password>",
"remotePath": "/<your project name>/",
"uploadOnSave": true,
"ignore": [
".vscode",
".git",
".DS_Store"
],
"syncOption": {
"skipCreate": false, # syncs new files
"delete": true # syncs deleted files
}
}
</pre>

=== One time only - first sync ===

- Execute Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on Mac to open the command palette, and the type/run : '''"SFTP: Download Project"'''.

This will download all the files locally.

=== Daily use ===

You don't have to do anything else! Each time you modify/save a file in VSCode, it will upload it to the SFTP Server.

To force upload to a server, execute Ctrl+Shift+P -> '''"SFTP: Sync Local -> Remote"'''.

Note: the SFTP sync may fail with a permissions error when create or delete nested folders. To fix this, execute `chmod -R 755 <your directory name>` in your terminal, then force sync to remote.

=== Split settings for version control ===
If you want to commit this file to version control, use private key (upload ssh key https://studio.boardgamearena.com/controlpanel) instead and move user/password settings into vscode user settings

I.e. in user setting add this (have to edit settings.js manually, google for location its os specific)
<pre>
"remotefs.remote": {
"bgadev": {
"name": "BGA",
"host": "1.studio.boardgamearena.com",
"protocol": "sftp",
"port": 22,
"username": "<yourdevusername>",
"privateKeyPath": "~/.ssh/id_rsa",
},
}
</pre>
in project folder sftp.json (replace <yourproject> with project name)
<pre>
{
"remote": "bgadev",
"remotePath": "/<yourproject>/",
"uploadOnSave": true,
"ignore": [
".git"
],
"syncOption": {
"skipCreate": false,
"delete": true
},
"watcher": {
"files": "**/*.{js,css}",
"autoUpload": true,
"autoDelete": true
}
}
</pre>

Note: you don't need watcher section if you don't use code generators, but its needed if you use typescript, scss or similar code generator tools.

== Code Formatter ==
I think Prettier has better format, you can install Prettier plugin to do the formatting, for PHP add the following in package.json

"devDependencies": {
"@prettier/plugin-php": "^0.19.1",
"prettier": "^2.7.1"
},
"prettier": {
"braceStyle": "1tbs"
}

== Code generators ==
If you want to run code generators for example for typescript or scss you can install this extension:
* https://marketplace.visualstudio.com/items?itemName=emeraldwalk.RunOnSave

In settings.json add these (example only):
"emeraldwalk.runonsave": {
"commands": [
{
"match": ".*\\.ts$",
"isAsync": true,
"cmd": "npm run build:ts"
},
{
"match": ".*\\.scss$",
"isAsync": true,
"cmd": "npm run build:scss"
}
]
}

In this example <code>build:ts</code> and <code>build:scss</code> are scripts configured via package.json

Another example - you can run php script that will generate material.inc.php from misc/xxx_material.csv
{
"match": "misc/.*material\\.csv$",
"isAsync": true,
"cmd": "php7.4 ${env.HOME}/git/bga-sharedcode/misc/genmat.php ${file}"
}

== User templates ==

You can define user template to avoid writing boilerplate code, here is example of php template for states
(it is placed in global location php.json - you can open it from the gui File->Preferences->Configure User Snippets and type php

<pre>
{
"Single player state": {
"prefix": ["state", "playerstate"],

"body": [
"$LINE_COMMENT playerTurn${1:something}",
"${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'playerTurn${1:something}',",
"'description' => clienttranslate('\\${actplayer} must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'activeplayer',",
"'args'=>'arg_playerTurn${1:something}',",
"'action'=>'st_playerTurn${1:something}',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_PLAYER,",
"'loopback' => ${1/(.*)/STATE_PLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create single player state defition, use tab to fill template parameters"
},

"Multiple player state": {
"prefix": ["mstate", "multiplayerstate"],

"body": [
"$LINE_COMMENT mplayerTurn${1:something}",
"${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} => [",
"'name' => 'mplayerTurn${1:something}',",
"'description' => clienttranslate('Other players must ${1:something}'),",
"'descriptionmyturn' => clienttranslate('\\${you} must ${1:something}'),",
"'type' => 'multipleactiveplayer',",
"'args'=>'arg_mplayerTurn${1:something}',",
"'action'=>'stMakeEveryoneActive',",
"'possibleactions' => [ 'playCard', 'pass' ],",
"'transitions' => [",
"'next' => STATE_GAME_TURN_NEXT_MPLAYER,",
"'loopback' => ${1/(.*)/STATE_MPLAYER_TURN_${1:/upcase}/} ]",
"],"
],

"description": "Create multi player state defition, use tab to fill template parameters"
},
"Action in action.php": {
"prefix": ["action"],
"body": [
"public function ${1:actionName}() {",
"\tself::setAjaxMode();",
"\t\\$${2:arg} = self::getArg('${2:arg}', AT_posint, false, 0);",
"\t\\$this->game->action_${1:actionName}(\\$${2:arg});",
"\tself::ajaxResponse();",
"}"
]
},
"Player loop in game.php": {
"prefix": ["players"],
"body": [
"\\$players = \\$this->loadPlayersBasicInfos();",
"foreach (\\$players as \\$player_id => \\$player_info) {",
"${1}",
"}"
]
}

}
</pre>

[[Category:Studio]]

Using Typescript and Scss

2024-03-18T23:03:47Z

NevinAF: Added NevinAF ts template to the Referenced Projects

This page will help you set up your project to use Typescript client file and Scss style files, and automatically build Javascript (in ES5) files and CSS files so your project stay compatible to BGA framework requirements.
You can use only TS or only SCSS part if you want, they are not linked.

== Install and configure ==

=== Install dev stack ===
Install node/npm. Here is an example to activate auto-build in Visual Studio Code, if you use another tool I strongly recommend to find an equivalent so you don't have to launch build manually after each modification.

=== Configure package.json and tsconfig.json ===

Create a file named <code>package.json</code> on the root folder, not on the src folder.

'''package.json'''

{
"name": "yourgamename",
"version": "1.0.0",
"description": "",
"main": "YourGameName.js",
"scripts": {
"build:ts": "tsc",
"build:scss": "sass --no-source-map src/yourgamename.scss yourgamename.css",
"watch:ts": "tsc --watch",
"watch:scss": "sass --watch src/yourgamename.scss yourgamename.css",
"watch": "npm run watch:ts && npm run watch:scss",
"build": "npm run build:ts && npm run build:scss"
},
"author": "yourname",
"license": "MIT",
"devDependencies": {
"sass": "^1.32.6",
"typescript": "^4.1.3"
}
}

Note: if you not using scss - remove corresponding scripts and deps.

When package.json is created, run <code>npm i</code> on the root folder to install builders (will generate a node_modules folder).

For Typescript compilation we also need to set up a <code>tsconfig.json</code> on the root folder.

'''tsconfig.json'''

{
"rootDir": ".",
"compilerOptions": {
"target": "es5",
"module": "none",
"lib": ["dom", "esnext"],
"sourceMap": false,
"typeRoots": ["src/types", "./types", "./node_modules/@types"],
"outFile": "YourGameName.js"
},
"files": [
"src/GameBody.ts",
"src/define.ts"
]
}

Note: it only works now with es5

If you want to split your code onto multiple files, just add them in the file list (order is important for dependencies, new subpart should go on top of the list). No need to import classes or types from one file to another. In fact, you can't with this configuration.

== Create skeleton ==
When you create your game in BGA Studio, a JS and CSS file are generated. As we will overwrite them with autobuild. You can put the TS/SCSS files on a <code>src</code> folder to separate them from built files, but that's not mandatory.
Note to myself: check if 'src' dir will be svn version control, if not cannot really use it (even if duplicated in git).

=== Typescript file skeleton ===
Typescript example here have been stripped down of all comments for clarity.
Your TS code can be splitted in multiple files, you can have a look [https://github.com/thoun/bga-ts-example here] for inspiration.
To make this page concise, I removed comments and code samples. If it's your first game, well - don't do it if your first game - you won't be able to apply other code samples from docs, they all using dojo style and have to completely rewritten.

'''src/GameBody.ts'''

<pre>
// @ts-ignore
GameGui = (function () { // this hack required so we fake extend GameGui
function GameGui() {}
return GameGui;
})();

// Note: it does not really extend it in es6 way, you cannot call super you have to use dojo way
class GameBody extends GameGui {
constructor() {}

public setup(gamedatas: any) {
this.setupNotifications();
}
public onEnteringState(stateName: string, args: any) {}
public onLeavingState(stateName: string) {}
public onUpdateActionButtons(stateName: string, args: any) {}
public setupNotifications() {}
}
</pre>

To plug the class with BGA framework, we'll also create another file:

'''src/define.ts'''

define([
"dojo","dojo/_base/declare",
"ebg/core/gamegui",
"ebg/counter",
"ebg/stock"
],
function (dojo, declare) {
return declare("bgagame.yourgamename", ebg.core.gamegui, new GameBody());
});
Copy <code>bgagame.yourgamename</code> from original JS to avoid name mistakes with letter case.

If you try to compile it you will be missing definitions of bunch of methods and variables for that we will add special ts type definition file .d.ts, this is not a complete version but you can get more complete from git projects below

'''src/types/bga-framework.d.ts'''
<pre>

declare var gameui: GameGui;
declare var g_replayFrom: number | undefined;
declare var g_gamethemeurl: string;
declare var g_themeurl: string;
declare var g_archive_mode: string;
declare function _(str: string): string;

declare const define;
declare const ebg;

declare class GameGui {
page_is_unloading: any;
game_name: string;
instantaneousMode: any;
player_id: string;
interface_min_width: number;
gamedatas: any;

isCurrentPlayerActive(): boolean;
addActionButton(id: string, label: string, callback: (event?: any) => void);
checkAction(action: any);
ajaxcall(url: string, args: object, bind: GameGui, resultHandler: (result: any) => void, allHandler: any);

setup(gamedatas: any): void;
onEnteringState(stateName: string, args: any): void;
onLeavingState(stateName: string ): void;
onUpdateActionButtons(stateName: string, args: any): void;
setupNotifications(): void;

onScriptError(msg: string, url?: string, linenumber?:number);
inherited(args: any);
}

</pre>

Above is barebone definition of gameui interface, you can find more complete one here
https://github.com/elaskavaia/bga-dojoless/blob/main/src/types/bga-framework.d.ts

=== SCSS file ===
Nothing special here, just write classic SCSS (will be compiled by Dart scss) and name it '''src/yourgamename.scss'''.
Original content same as original .css, i.e

@import url(../../../css/csslayer.css);

Your SCSS code can be splitted in multiple files, for example :

'''yourgamename.scss'''
@import 'gametable';

/* some classes */

'''_gametable.scss'''
/* _gametable related classes */

== Auto build and auto upload ==

=== Auto build JS and CSS files ===

To build and watch (i.e. re-build continiously changed files) run in terminal:
npm run watch

Alternately you can make vscode to do it for you by installing Run on Save extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

Note: to build without watch
npm run build

=== Auto-upload generated files ===
You can setup stanard file sync or use vscode SFTP extension, see details in [[Setting_up_BGA_Development_environment_using_VSCode]]

=== Hint ===
Make sure <code>.vscode</code> and <code>node_modules</code> are in <code>.gitignore</code> if you commit your project somewhere.

=== Code completion ===
To add code completion on framework, dojo, stock, ... you'll need more type definition files. Feel free to copy them from [https://github.com/thoun/bga-ts-example this repo] and reference them at the top of files array, even before your subpart files.

== Referenced Projects ==

* https://github.com/thoun/bga-ts-example
* https://github.com/NevinAF/bga-ts-template
* https://github.com/elaskavaia/bga-dojoless

[[Category:Studio]]