Board Game Arena - User contributions [en]

Setting up BGA Development environment using VSCode

2024-08-26T13:25:36Z

P1ngouiin: Update SFTP port

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 (8.2) 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

* Another way to improve auto-complete and such is to use Typescript and SCSS, this is not for the beginners.
** Original wiki: https://en.doc.boardgamearena.com/Using_Typescript_and_Scss
** There is also 3rd party software that automates typescript template above: [[BGA Type Safe Template]]. It claims to offers a much cleaner initial file, clearer workflow, and nearly complete type and autofill support for whatever you may need.

===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": 2022,
"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": 2022,
"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]]

Studio

2024-08-09T10:04:19Z

P1ngouiin: /* Software Versions */

{{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)
* [[Options_and_preferences:_gameoptions.json,_gamepreferences.json|Game Options and Preferences]]
* [[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
** [[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
** [[BGA Type Safe Template]] - Setting up a fully typed project using typescript and more!
** [[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: 8.2
* 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]]